Runtime exports

This is your primary React-facing export. It returns install state, enabled state, settings, prompt state, status indicators, and helper actions such as enable, disable, or settings updates.

The authoring guide explicitly calls out that useExtension() returns ExtensionState.

Use this to publish function-calling tool definitions. The tool schema should describe the arguments clearly and stay stable enough that the model can learn when to use it.

Tool execution stays local to the browser runtime. The host namespaces tool names before the model sees them, so your module-level tool names only need to be stable within the extension itself.

Each tool may include an optional displayLabels sibling field (alongside type and function) with pending, success, and error strings. The chat UI uses these for the tool-call card — e.g. "Sending photo…" while running and "Sent you a photo" on success. The field is stripped before tools are sent to the model, so it cannot affect model behaviour. When omitted the card falls back to a Title-Cased tool name.

The handler receives the tool name, parsed arguments, and a runtime context with APIs for prompt instructions, variables, chat state, persona data, memories, media, and UI.

Return the tool result you want the model to see. Throw only for real errors or unknown tools; do not use exceptions as normal control flow.

This is the steady-state prompt policy hook from the markdown guide. It is the right place for extension-owned ambient guidance such as style defaults, image rules, or follow-up instructions that should be present before tool selection.

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.',
    },
  ];
}

export async function onAfterAssistantMessage(ctx) {
  const disposition = await ctx.runtime.variables.get('disposition', {
    scope: 'persona',
    defaultValue: { score: 0 },
  });

  const nextScore = Number((disposition.value as any)?.score || 0)
    + (ctx.assistantText?.includes('good girl') ? 1 : 0);

  await ctx.runtime.variables.set('disposition', { score: nextScore }, {
    scope: 'persona',
    visibility: 'private',
  });
}

Use these for setup or teardown tied to persona enablement, not per-message logic. They return a promise and do not contribute prompt text directly.

Return { content } to rewrite the outgoing message. Return { blocked: true, message } to stop the send and surface a message to the user.

Return nothing when the extension only wants to observe.

Return { tools } to replace the tool list for the round, or { promptContributions } to add request-time instructions.

This is the dynamic counterpart to getPromptContributions().

Use these when you need telemetry, follow-up state updates, or post-tool prompt logic that depends on what the model chose and what the tool returned.

onAfterAssistantChunk is for streaming-time observation. onAfterAssistantMessage is the better place for end-of-turn bookkeeping such as memory writes or variable updates.

Toy extensions should pair this hook with manifest.supportsEmergencyStop = true.

The host only dispatches the stop event to enabled toy extensions that both declare support and are currently active or connected.

The recommended default is to stop output immediately while keeping the underlying connection intact unless your hardware or safety model requires a harder reset.

Available on both the surface runtime (panel, footer, settings) and the lifecycle runtime inside hooks. Integration extensions that want to halt toy output in response to user state (e.g. arousal-state cumming or spent transitions) should call this directly instead of writing to a variable and hoping the LLM intercepts it.

Resolves to { ok, stoppedCount, error? }. stoppedCount is the number of toy extensions that successfully completed their stop hook.