​

Analysis runtime

​

run(...) — await the result

const result = await api.runtime.analysis.run({
  purpose: "topic-detection",
  systemPrompt: "Return a compact JSON object with the topic and confidence.",
  input: event.cleanUserMessage.content,
  responseFormat: "json",
  timeoutMs: 10_000,
});

if (result.status === "ok" && result.json) {
  return {
    contribution: {
      systemPrompt: `Detected topic: ${JSON.stringify(result.json)}`,
    },
  };
}

​

enqueue(...) — fire and forget

api.runtime.analysis.enqueue(
  {
    purpose: "memory-extraction",
    systemPrompt: "Extract durable user facts as JSON.",
    input: event.cleanUserMessage.content,
    responseFormat: "json",
    timeoutMs: 30_000,
  },
  async (result) => {
    if (result.status === "ok") {
      await saveFacts(result.json);
    }
  },
);

​

Parameters

​

Prompt role mapping

​

Correlation metadata

​

Result

​

Memory tools in analysis

await api.runtime.analysis.run({
  purpose: "memory-recall",
  systemPrompt: "Find relevant durable memories. Return concise bullets.",
  input: event.cleanUserMessage.content,
  sessionKey: event.sessionKey,
  toolsAllow: ["memory_search", "memory_get"],
});

​

Lanes, admission, and bounds

• Analysis runs use a dedicated command lane, so awaited hook-time analysis does not queue behind the active user turn. The lane runs one analysis at a time.
• Background (enqueue) analysis is queued behind a small per-plugin cap. It yields to awaited work, and returns accepted: false with reason: "queue-full" when that plugin is saturated.
• If background analysis is already running, a new awaited run(...) is rejected immediately rather than waiting behind the job.
• Both run(...) and enqueue(...) validate params synchronously before claiming the lane or a quota. Invalid requests (empty purpose, empty input, a provider without a model, or a tool outside the allow-list) are rejected immediately — run(...) returns status: "rejected"; enqueue(...) returns accepted: false with reason: "invalid".

​

Constraints to keep in mind

• Analysis runs do not rewrite the raw user message. To affect the active turn, contribute context through normal hook returns (for example a PromptContribution from context.collect).
• Analysis is text-only in v1: prompt text that looks like a local image path is not auto-loaded.
• Provider overrides must include both provider and model — a provider-only override is rejected so a plugin cannot accidentally pair one provider with another’s default model id.
• Transient analysis runs skip workspace cwd changes, skill environment overrides, sandbox startup, bootstrap context loading, and global hook dispatch. The transcript uses a transient internal session key and is not synced back to session storage.
• Keep prompts narrow, set a timeout, and prefer enqueue(...) for work that updates plugin-owned state for future turns. Completion callbacks still run inside the plugin host process — keep them bounded.

​

What’s next

• Plugin SDK reference
• Hooks — where context.collect and the other lifecycle hooks live
• Agent signals