Developer Guide

Prompt contributions

Prompt contributions are the public runtime mechanism for ambient instruction blocks. This page turns the authoring guide's prompt-contribution section into a reference for fields, placement rules, and usage patterns.

✦

Prefer prompt contributions for extension-owned policy and “when or why” guidance. Use prompt state, variables, or the chat itself for large dynamic state.

Contribution shape

A prompt contribution is a small object inserted into the current request. The authoring guide keeps the shape intentionally small so extensions can add policy without taking over the whole prompt assembly process.

Ambient contribution export

getPromptContributions(ctx)

Return an array of contribution objects that should be present even before the model chooses a tool.

This is the base export for steady-state guidance. It is the right place for rules that should travel with the extension whenever it is enabled for the active persona.

export function getPromptContributions() {
  return [
    {
      placement: 'system_pre',
      priority: 10,
      text: 'When a visual beat would help, create an image near the end of the turn.',
    },
    {
      placement: 'tool_guidance',
      priority: 20,
      text: 'If an image tool succeeds, keep the reply text short and acknowledge the image once.',
    },
  ];
}

export async function onBeforeLLMRequest() {
  return {
    promptContributions: [
      {
        placement: 'system_post',
        priority: 30,
        text: 'If you emitted an image, do not narrate camera mechanics.',
      },
    ],
  };
}

Required field

placement

Controls where the runtime inserts the contribution into the assembled prompt.

The current public placement values are:

system_pre for early system guidance
persona_post for guidance that should land after persona text
tool_guidance for instructions closely related to tool behavior
system_post for late system guidance

Optional field

priority

Lower numbers sort earlier within the same placement.

Use priority only when ordering matters between contributions that share a placement. Smaller numbers run earlier, so they should hold the more foundational guidance.

Required field

text

The instruction block inserted into the current request.

Keep the text focused and durable. Prompt contributions work best for concise policy, style, or follow-up instructions instead of large runtime dumps.

Placement guide

The markdown guide names the available placements but does not force one style of usage. In practice, placement choice should match how long the rule should survive and what it is trying to influence.

Good fit

Default image or tool policy.

Extension-owned style guidance.

Short “when or why” instructions.

Poor fit

Large structured state that belongs in promptState or variables.

Replacing the whole turn with extension-authored prompt text.

Per-message history that already exists in chat context.

Usage patterns

The runtime offers both steady-state and request-time contribution paths. Choose the one that matches whether the guidance is always-on or specific to the current round.

Request-time additions

onBeforeLLMRequest(ctx)

Return promptContributions from the lifecycle hook when the guidance depends on the current request.

This is the dynamic companion to getPromptContributions(). Use it when the instruction depends on current message content, current tools, or the outcome of earlier runtime work in the same round.

Choose the right channel

Prompt contributions vs promptState

Use prompt contributions for guidance. Use promptState for app-rendered structured state.

If the runtime data needs to be rendered consistently as current toys, player info, or other structured state, it belongs in promptState.

If the extension wants to express policy, tone, tool follow-up rules, or decision guidance, use prompt contributions instead.

Avoid duplication

Prompt contributions vs chat content

Do not repeat things in prompt contributions that already belong in the visible conversation.

Prompt contributions are hidden runtime instructions. They should complement the visible chat, not mirror it line-for-line.