agent-accelerator 0.6.0 → 0.6.6

package/src/providers/openai.ts

@@ -91,6 +91,8 @@ import {
   augmentSystemPromptWithStructuredOutput,
   emitProviderWarning,
   warnIgnoredMediaResolution,
+  warnIgnoredVideoProcessing,
+  warnIgnoredToolMedia,
 } from "../providers.ts";
 
 // ---------------------------------------------------------------------------
@@ -551,6 +553,8 @@ export class OpenAIResponsesProvider implements Provider {
     // `12h` maps to `prompt_cache_retention: "24h"`; everything else stays on implicit prompt_cache_key affinity.
     const cache = resolveCache("openai", options?.cache, ["implicit", "12h"], `openai/${modelId}`);
     warnIgnoredMediaResolution("openai", context.messages, `openai/${modelId}`);
+    warnIgnoredVideoProcessing("openai", context.messages, `openai/${modelId}`);
+    warnIgnoredToolMedia("openai", context.messages, `openai/${modelId}`);
 
     // Structured outputs: native `text.format` when supported, else emulated
     // via instructions (catalog `structured_output: false` would 400).
@@ -564,7 +568,11 @@ export class OpenAIResponsesProvider implements Provider {
     }
     if (outputSpec && !modelSupportsStructuredOutput("openai", modelId)) {
       outputEmulated = true;
-      effectiveSystemPrompt = augmentSystemPromptWithStructuredOutput(context.systemPrompt, outputSpec);
+      effectiveSystemPrompt = augmentSystemPromptWithStructuredOutput(
+        context.systemPrompt,
+        outputSpec,
+        options?.prompts?.structuredOutput
+      );
       emitProviderWarning({
         provider: "openai",
         capability: "structured output",
@@ -586,9 +594,7 @@ export class OpenAIResponsesProvider implements Provider {
     if (effectiveSystemPrompt) body.instructions = effectiveSystemPrompt;
     const aiTools = toOpenAITools(tools);
     if (aiTools) body.tools = aiTools;
-    const toolChoice = mapToolChoiceToOpenAI(
-      options?.toolChoice as "auto" | "none" | "required" | { type: "function"; function: { name: string } } | undefined
-    );
+    const toolChoice = mapToolChoiceToOpenAI(options?.toolChoice);
     if (toolChoice !== undefined) body.tool_choice = toolChoice;
     if (effort) body.reasoning = { effort };
     if (serviceTier) body.service_tier = serviceTier;

package/src/providers/openrouter.ts

@@ -6,7 +6,7 @@
  * never in the canonical layer (`src/providers.ts`).
  *
  * Wire contract: `references/testings/openrouter/CONTRACT.md` (docs + live
- * captures on `stealth/space-bunny-alpha`, 2026-09-24). Capability matrix:
+ * captures, 2026-09-24). Capability matrix:
  * `references/testings/openrouter/CAPABILITY-MATRIX.md`.
  *
  * This is the STABLE transport. The beta Responses skin
@@ -24,9 +24,10 @@
  * - IDs are provider-generated (`gen-…` generations, `call_…`/uuid tool ids)
  *   and echoed verbatim (`tool_call_id`). The `call_${random}` fallback in
  *   parsers is a local canonical correlation id only; it is never sent.
- * - Prior-turn reasoning is NOT resent (chat history is messages + tool
- *   calls only). This matches the Responses adapter behavior and avoids 400s
- *   on strict routes; documented in the capability matrix.
+ * - Prior-turn reasoning is resent as `reasoning_details` exactly as returned (kept on the assistant message as
+ *   `providerSteps`), which tool turns need (reasoning-tokens.md, "Preserving Reasoning"). Plain `reasoning` text alone is
+ *   never resent. Parsed-PDF `file` annotations ride the same way and go back as `annotations`, so the router does not parse
+ *   the same PDF again (pdf-inputs.md, "Skip Parsing Costs").
  */
 import type {
   Provider,
@@ -47,6 +48,7 @@ import { normalizeMediaInput } from "../utils/media.ts";
 import { safeStringify } from "../utils/serialization.ts";
 import { toConciseProviderError, assertModalitiesSupported } from "../utils/errors.ts";
 import { ConfigError, isAbortError } from "../types/errors.ts";
+import { DEFAULT_PROMPTS } from "../prompts/prompts.ts";
 import {
   newToolCallId,
   redactedHeaders,
@@ -84,6 +86,8 @@ import {
   augmentSystemPromptWithStructuredOutput,
   emitProviderWarning,
   warnIgnoredMediaResolution,
+  warnIgnoredVideoProcessing,
+  warnIgnoredToolMedia,
 } from "../providers.ts";
 
 // ---------------------------------------------------------------------------
@@ -108,6 +112,8 @@ type ChatMessage =
         type: "function";
         function: { name: string; arguments: string };
       }>;
+      reasoning_details?: unknown[];
+      annotations?: unknown[];
       name?: string;
     }
   | { role: "tool"; content: string; tool_call_id: string; name?: string }
@@ -118,7 +124,10 @@ interface ChatRequestBody {
   messages: ChatMessage[];
   tools?: Array<Record<string, unknown>>;
   tool_choice?: string | { type: "function"; function: { name: string } };
-  reasoning?: { effort: string };
+  reasoning?: { effort?: string; exclude?: boolean };
+  provider?: Record<string, unknown>;
+  parallel_tool_calls?: boolean;
+  user?: string;
   service_tier?: string;
   session_id?: string;
   cache_control?: { type: "ephemeral"; ttl: "5m" | "1h" };
@@ -135,8 +144,13 @@ interface ChatUsage {
   prompt_tokens?: number;
   completion_tokens?: number;
   total_tokens?: number;
-  prompt_tokens_details?: { cached_tokens?: number; cache_write_tokens?: number };
-  completion_tokens_details?: { reasoning_tokens?: number };
+  prompt_tokens_details?: {
+    cached_tokens?: number;
+    cache_write_tokens?: number;
+    audio_tokens?: number;
+    video_tokens?: number;
+  };
+  completion_tokens_details?: { reasoning_tokens?: number; audio_tokens?: number; image_tokens?: number };
   cost?: number;
   [k: string]: unknown;
 }
@@ -188,6 +202,71 @@ function midStreamStatus(code: unknown, errorType: unknown): number | undefined
   return typeof errorType === "string" ? RETRYABLE_ERROR_TYPE_STATUS[errorType] : undefined;
 }
 
+// OpenRouter options that come from env vars, never from AgentConfig (provider routing, `parallel_tool_calls`, `reasoning.exclude`, `user`). A per-Agent `env` wins over the process env; nothing is sent when no variable is set; a bad value is a ConfigError before any network call. NOT supported on purpose (the owner does not want them for now): `reasoning.max_tokens` and `trace`; in: buildBody, out: the extra body fields.
+const ROUTING_LISTS = { OPENROUTER_ORDER: "order", OPENROUTER_ONLY: "only", OPENROUTER_IGNORE: "ignore" } as const;
+const ROUTING_FLAGS = {
+  OPENROUTER_ALLOW_FALLBACKS: "allow_fallbacks",
+  OPENROUTER_REQUIRE_PARAMETERS: "require_parameters",
+  OPENROUTER_ZDR: "zdr",
+} as const;
+function openRouterEnvOptions(options?: ProviderRequestOptions): {
+  provider?: Record<string, unknown>;
+  parallel_tool_calls?: boolean;
+  reasoning_exclude?: boolean;
+  user?: string;
+} {
+  const read = (name: string): string | undefined => {
+    const own = options?.env?.[name]?.trim();
+    return own ? own : getEnv(name);
+  };
+  const bad = (name: string, value: string, expected: string): never => {
+    throw new ConfigError(`[Agent Accelerator] Invalid ${name} ${JSON.stringify(value)}: expected ${expected}.`);
+  };
+  const flag = (name: string): boolean | undefined => {
+    const v = read(name);
+    if (v === undefined) return undefined;
+    const t = v.toLowerCase();
+    if (t === "true" || t === "1") return true;
+    if (t === "false" || t === "0") return false;
+    return bad(name, v, "true or false");
+  };
+  const provider: Record<string, unknown> = {};
+  for (const [name, field] of Object.entries(ROUTING_LISTS)) {
+    const v = read(name);
+    if (v === undefined) continue;
+    const list = v
+      .split(",")
+      .map((x) => x.trim())
+      .filter(Boolean);
+    if (list.length === 0) bad(name, v, "a comma-separated list of provider slugs");
+    provider[field] = list;
+  }
+  for (const [name, field] of Object.entries(ROUTING_FLAGS)) {
+    const v = flag(name);
+    if (v !== undefined) provider[field] = v;
+  }
+  const collection = read("OPENROUTER_DATA_COLLECTION");
+  if (collection !== undefined) {
+    if (collection !== "allow" && collection !== "deny") bad("OPENROUTER_DATA_COLLECTION", collection, "allow or deny");
+    provider["data_collection"] = collection;
+  }
+  const sort = read("OPENROUTER_SORT");
+  if (sort !== undefined) {
+    if (sort !== "price" && sort !== "throughput" && sort !== "latency")
+      bad("OPENROUTER_SORT", sort, "price, throughput or latency");
+    provider["sort"] = sort;
+  }
+  const parallel = flag("OPENROUTER_PARALLEL_TOOL_CALLS");
+  const exclude = flag("OPENROUTER_REASONING_EXCLUDE");
+  const user = read("OPENROUTER_USER");
+  return {
+    ...(Object.keys(provider).length > 0 ? { provider } : {}),
+    ...(parallel !== undefined ? { parallel_tool_calls: parallel } : {}),
+    ...(exclude !== undefined ? { reasoning_exclude: exclude } : {}),
+    ...(user ? { user } : {}),
+  };
+}
+
 // Canonical tool declarations as Chat Completions function tools; in: options.tools, out: request `tools`.
 function toOpenRouterTools(tools?: StandardToolDeclaration[]): Array<Record<string, unknown>> | undefined {
   if (!tools || tools.length === 0) return undefined;
@@ -311,6 +390,48 @@ async function contentPartsToBlocks(parts: ContentPart[]): Promise<ChatContentPa
   return blocks;
 }
 
+// Folds one streamed `reasoning_details` chunk into the turn's blocks: chunks with the same index (else id) are one block whose text, summary, data and signature are concatenated or filled in, in order; in: the stream handler, out: the blocks replayed on the next request.
+function mergeReasoningDetails(blocks: Array<Record<string, unknown>>, chunk: unknown): void {
+  if (!chunk || typeof chunk !== "object" || Array.isArray(chunk)) return;
+  const c = chunk as Record<string, unknown>;
+  const same = blocks.find((b) =>
+    typeof c["index"] === "number" ? b["index"] === c["index"] : c["id"] != null && b["id"] === c["id"]
+  );
+  if (!same) {
+    blocks.push({ ...c });
+    return;
+  }
+  for (const [k, v] of Object.entries(c)) {
+    if (v === null || v === undefined) continue;
+    if ((k === "text" || k === "summary" || k === "data") && typeof v === "string" && typeof same[k] === "string")
+      same[k] = (same[k] as string) + v;
+    else same[k] = v;
+  }
+}
+
+// Adds a streamed `file` annotation (a parsed PDF) once per `file.hash`; in: the stream handler, out: the annotations replayed on the next request.
+function mergeAnnotation(blocks: Array<Record<string, unknown>>, chunk: unknown): void {
+  if (!chunk || typeof chunk !== "object" || (chunk as { type?: unknown }).type !== "file") return;
+  const hash = (chunk as { file?: { hash?: unknown } }).file?.hash;
+  if (typeof hash === "string" && blocks.some((b) => (b as { file?: { hash?: unknown } }).file?.hash === hash)) return;
+  blocks.push(chunk as Record<string, unknown>);
+}
+
+// The reasoning blocks and the parsed-PDF annotations of an assistant turn as OpenRouter returned them (both live in `providerSteps`, told apart by `type: "file"`); in: a stored assistant message, out: fullHistoryMessages.
+function storedReplay(m: { providerSteps?: { provider: string; steps: unknown[] } }): {
+  reasoning_details?: unknown[];
+  annotations?: unknown[];
+} {
+  if (m.providerSteps?.provider !== "openrouter") return {};
+  const isFile = (x: unknown): boolean => (x as { type?: unknown } | null)?.type === "file";
+  const annotations = m.providerSteps.steps.filter(isFile);
+  const details = m.providerSteps.steps.filter((x) => !isFile(x));
+  return {
+    ...(details.length > 0 ? { reasoning_details: details } : {}),
+    ...(annotations.length > 0 ? { annotations } : {}),
+  };
+}
+
 // A tool result as the text of a tool message; in: fullHistoryMessages, out: a string.
 function resultToOutput(result: unknown): string {
   if (typeof result === "string") return result;
@@ -323,7 +444,10 @@ function resultToOutput(result: unknown): string {
  * carries everything. Assistant items carry no provider `id`/`status`
  * requirements (unlike the discontinued Responses skin).
  */
-async function fullHistoryMessages(context: ProviderContext): Promise<ChatMessage[]> {
+async function fullHistoryMessages(
+  context: ProviderContext,
+  bridge = DEFAULT_PROMPTS.toolBridge
+): Promise<ChatMessage[]> {
   // Map assistant tool_call ids so tool results pair even though the
   // executor keys results by the call id.
   const pairing = new Map<string, string>();
@@ -354,7 +478,7 @@ async function fullHistoryMessages(context: ProviderContext): Promise<ChatMessag
       // Strict routes reject `user` directly after `tool`: bridge with a
       // synthetic assistant turn (pi api/openai-completions.ts:1233).
       if (lastRole === "tool") {
-        messages.push({ role: "assistant", content: "I have processed the tool results." });
+        messages.push({ role: "assistant", content: bridge });
       }
       if (typeof m.content === "string") {
         if (m.content) {
@@ -369,9 +493,10 @@ async function fullHistoryMessages(context: ProviderContext): Promise<ChatMessag
         }
       }
     } else if (m.role === "assistant") {
+      const replay = storedReplay(m);
       if (typeof m.content === "string") {
         if (m.content) {
-          messages.push({ role: "assistant", content: m.content });
+          messages.push({ role: "assistant", content: m.content, ...replay });
         }
         continue;
       }
@@ -387,8 +512,7 @@ async function fullHistoryMessages(context: ProviderContext): Promise<ChatMessag
         } else if (part.type === "text" && part.text) {
           texts.push(part.text);
         }
-        // Prior-turn reasoning is NOT resent: chat history is messages +
-        // tool calls only (documented decision; avoids strict-route 400s).
+        // Reasoning is not rebuilt from text: the stored `reasoning_details` blocks are replayed verbatim below.
       }
       // Skip empty assistant turns (no text + no tool calls): strict
       // routes reject them, and they carry no signal (pi drop rule).
@@ -397,6 +521,7 @@ async function fullHistoryMessages(context: ProviderContext): Promise<ChatMessag
         role: "assistant",
         content: texts.length > 0 ? texts.join("\n") : null,
         ...(calls.length > 0 ? { tool_calls: calls } : {}),
+        ...replay,
       });
       lastRole = "assistant";
     } else if (m.role === "tool") {
@@ -448,6 +573,25 @@ function mapUsage(raw?: ChatUsage): TokenUsage {
     cacheWriteTokens: raw?.prompt_tokens_details?.cache_write_tokens ?? 0,
     thinkingTokens: raw?.completion_tokens_details?.reasoning_tokens ?? 0,
   };
+  // Media tokens are listed only when the provider reported more than zero of them.
+  const count = (n: unknown): number | undefined =>
+    typeof n === "number" && Number.isFinite(n) && n > 0 ? n : undefined;
+  const inDet = {
+    audioTokens: count(raw?.prompt_tokens_details?.audio_tokens),
+    videoTokens: count(raw?.prompt_tokens_details?.video_tokens),
+  };
+  const outDet = {
+    audioTokens: count(raw?.completion_tokens_details?.audio_tokens),
+    imageTokens: count(raw?.completion_tokens_details?.image_tokens),
+  };
+  const keep = (d: Record<string, number | undefined>): Record<string, number> | undefined => {
+    const kept = Object.fromEntries(Object.entries(d).filter(([, v]) => v !== undefined)) as Record<string, number>;
+    return Object.keys(kept).length > 0 ? kept : undefined;
+  };
+  const inKept = keep(inDet);
+  const outKept = keep(outDet);
+  if (inKept) usage.inputDetails = inKept;
+  if (outKept) usage.outputDetails = outKept;
   if (typeof raw?.cost === "number" && raw.cost >= 0) {
     // an explicit 0 (a free model, a response-cache hit) is a known cost, not a missing one
     usage.cost = { totalCost: raw.cost };
@@ -502,6 +646,8 @@ export class OpenRouterChatCompletionsProvider implements Provider {
       `openrouter/${modelId}`
     );
     warnIgnoredMediaResolution("openrouter", context.messages, `openrouter/${modelId}`, ["video"]);
+    warnIgnoredVideoProcessing("openrouter", context.messages, `openrouter/${modelId}`);
+    warnIgnoredToolMedia("openrouter", context.messages, `openrouter/${modelId}`);
 
     // Structured outputs: native `response_format` when supported, else
     // emulated via system-prompt instruction + client validation (catalog
@@ -519,7 +665,11 @@ export class OpenRouterChatCompletionsProvider implements Provider {
       outputEmulated = true;
       effectiveContext = {
         ...context,
-        systemPrompt: augmentSystemPromptWithStructuredOutput(context.systemPrompt, outputSpec),
+        systemPrompt: augmentSystemPromptWithStructuredOutput(
+          context.systemPrompt,
+          outputSpec,
+          options?.prompts?.structuredOutput
+        ),
       };
       emitProviderWarning({
         provider: "openrouter",
@@ -530,7 +680,7 @@ export class OpenRouterChatCompletionsProvider implements Provider {
         fallback: "emulated JSON instruction + client validation (no response_format is sent)",
       });
     }
-    const messages = await fullHistoryMessages(effectiveContext);
+    const messages = await fullHistoryMessages(effectiveContext, options?.prompts?.toolBridge);
     const body: ChatRequestBody = {
       model: modelId,
       messages,
@@ -538,11 +688,17 @@ export class OpenRouterChatCompletionsProvider implements Provider {
     };
     const orTools = toOpenRouterTools(tools);
     if (orTools) body.tools = orTools;
-    const toolChoice = mapToolChoiceToOpenRouterChat(
-      options?.toolChoice as "auto" | "none" | "required" | { type: "function"; function: { name: string } } | undefined
-    );
+    const toolChoice = mapToolChoiceToOpenRouterChat(options?.toolChoice);
     if (toolChoice !== undefined) body.tool_choice = toolChoice;
-    if (effort) body.reasoning = { effort };
+    const env = openRouterEnvOptions(options);
+    if (effort || env.reasoning_exclude !== undefined)
+      body.reasoning = {
+        ...(effort ? { effort } : {}),
+        ...(env.reasoning_exclude !== undefined ? { exclude: env.reasoning_exclude } : {}),
+      };
+    if (env.provider) body.provider = env.provider;
+    if (env.parallel_tool_calls !== undefined && orTools) body.parallel_tool_calls = env.parallel_tool_calls;
+    if (env.user) body.user = env.user;
     if (serviceTier) body.service_tier = serviceTier;
     if (cache === "5m" || cache === "1h") body.cache_control = { type: "ephemeral", ttl: cache };
     // Documented Chat Completions generation controls (only those the caller set).
@@ -653,6 +809,7 @@ export class OpenRouterChatCompletionsProvider implements Provider {
         provider: "openrouter",
         raw: res.raw,
         durationMs: res.durationMs,
+        providerSteps: res.providerSteps,
       };
     } catch (err) {
       // A stream reports its own generic abort; the caller's reason (`interrupt(new Error("..."))`) is what the run should carry.
@@ -748,6 +905,10 @@ export class OpenRouterChatCompletionsProvider implements Provider {
         // Index of the most recent tool-call delta: unindexed chunks continue
         // it (falling back to calls.size would fork a phantom call per chunk).
         let lastToolIndex = 0;
+        // The turn's reasoning blocks exactly as returned, replayed on the next request (tool turns need them).
+        const reasoningBlocks: Array<Record<string, unknown>> = [];
+        // Parsed PDFs (`file` annotations) of the turn: sent back so OpenRouter does not parse the same file again.
+        const annotationBlocks: Array<Record<string, unknown>> = [];
         let usage: TokenUsage = { inputTokens: 0, outputTokens: 0, totalTokens: 0 };
         let finishReason = "stop";
         let sawFinishReason = false;
@@ -812,6 +973,7 @@ export class OpenRouterChatCompletionsProvider implements Provider {
           const details = delta["reasoning_details"];
           if (Array.isArray(details)) {
             for (const block of details) {
+              mergeReasoningDetails(reasoningBlocks, block);
               const t = (block as { text?: string })?.text;
               if (typeof t === "string" && t) {
                 thinking += t;
@@ -833,6 +995,8 @@ export class OpenRouterChatCompletionsProvider implements Provider {
               partialThinking: thinking,
             });
           }
+          if (Array.isArray(delta["annotations"]))
+            for (const a of delta["annotations"]) mergeAnnotation(annotationBlocks, a);
           // Tool-call deltas accumulate per choice index.
           const deltaCalls = delta["tool_calls"];
           if (Array.isArray(deltaCalls)) {
@@ -942,6 +1106,9 @@ export class OpenRouterChatCompletionsProvider implements Provider {
             response: { ...responseMeta, body: completedBody, badFrames } as unknown as ProviderRawData["response"],
           },
           durationMs: Date.now() - startTime,
+          ...(reasoningBlocks.length + annotationBlocks.length > 0
+            ? { providerSteps: { provider: "openrouter", steps: [...reasoningBlocks, ...annotationBlocks] } }
+            : {}),
         });
         eventStream.push({ type: "done", delta: "", usage, finishReason, responseId });
         eventStream.end(finalResponse);

package/src/providers.ts

@@ -16,6 +16,7 @@ import { zodToJsonSchema } from "./tools/schema.ts";
 import { ValidationError } from "./types/errors.ts";
 import { TRUNCATED_ARGS_KEY } from "./types/tool.ts";
 import { telemetryBus } from "./telemetry.ts";
+import { DEFAULT_PROMPTS, fillPrompt } from "./prompts/prompts.ts";
 
 /** Classification of a canonical capability on a given provider. */
 export type ProviderCapabilityStatus = "NATIVE" | "TRANSLATED" | "AUTOMATIC" | "EMULATED" | "UNSUPPORTED";
@@ -232,6 +233,47 @@ export function warnIgnoredMediaResolution(
   });
 }
 
+/** Warns once per provider/model that a video's `processing` mode is ignored (only Google has one); in: an adapter's request messages, out: telemetry bus only. */
+export function warnIgnoredVideoProcessing(provider: string, messages: Message[], modelRef: string): void {
+  const used = messages.some(
+    (m) => Array.isArray(m.content) && m.content.some((p) => p.type === "video" && p.processing)
+  );
+  if (!used) return;
+  emitProviderWarning({
+    provider,
+    capability: "video processing",
+    requested: modelRef,
+    reason: "only Google reads a video in a chosen processing mode (static or agentic).",
+    fallback: "the provider's default video handling",
+  });
+}
+
+/** Warns once per provider/model that media a tool returned with `toolContent` is not sent (only Google takes media inside a function result); the model still gets the tool's text; in: an adapter's request messages, out: telemetry bus only. */
+export function warnIgnoredToolMedia(provider: string, messages: Message[], modelRef: string): void {
+  const used = messages.some(
+    (m) => Array.isArray(m.content) && m.content.some((p) => p.type === "tool_result" && p.parts && p.parts.length > 0)
+  );
+  if (!used) return;
+  emitProviderWarning({
+    provider,
+    capability: "media in tool results",
+    requested: modelRef,
+    reason: "only Google accepts images, audio, video or files inside a function result.",
+    fallback: "the tool's text only (the media is not sent)",
+  });
+}
+
+// Warns once that the `validated` tool choice (Google only) is dropped and the provider default (auto) is used; in: the OpenRouter and OpenAI tool-choice mappers (compat goes through the OpenAI one), out: a provider_warning on the bus.
+function warnValidatedToolChoice(provider: string): void {
+  emitProviderWarning({
+    provider,
+    capability: "tool choice",
+    requested: "validated",
+    reason: "only Google has a validated tool-choice mode.",
+    fallback: "automatic tool choice",
+  });
+}
+
 /** OpenRouter Chat Completions `tool_choice` wire values. */
 export type OpenRouterChatToolChoice = "auto" | "none" | "required" | { type: "function"; function: { name: string } };
 
@@ -243,9 +285,10 @@ export type OpenRouterChatToolChoice = "auto" | "none" | "required" | { type: "f
  * (`{type:function,name}`): completions nests the name under `function`.
  */
 export function mapToolChoiceToOpenRouterChat(
-  choice: "auto" | "none" | "required" | { type: "function"; function: { name: string } } | undefined
+  choice: "auto" | "none" | "required" | "validated" | { type: "function"; function: { name: string } } | undefined
 ): OpenRouterChatToolChoice | undefined {
   if (!choice || choice === "auto") return undefined;
+  if (choice === "validated") return (warnValidatedToolChoice("openrouter"), undefined);
   if (choice === "none" || choice === "required") return choice;
   const name = choice.function?.name;
   if (name) return { type: "function", function: { name } };
@@ -292,9 +335,11 @@ export type OpenAIToolChoice = "auto" | "none" | "required" | { type: "function"
  * variants are out of scope and never emitted.
  */
 export function mapToolChoiceToOpenAI(
-  choice: "auto" | "none" | "required" | { type: "function"; function: { name: string } } | undefined
+  choice: "auto" | "none" | "required" | "validated" | { type: "function"; function: { name: string } } | undefined,
+  provider = "openai"
 ): OpenAIToolChoice | undefined {
   if (!choice || choice === "auto") return undefined;
+  if (choice === "validated") return (warnValidatedToolChoice(provider), undefined);
   if (choice === "none" || choice === "required") return choice;
   const name = choice.function?.name;
   if (name) return { type: "function", name };
@@ -302,7 +347,7 @@ export function mapToolChoiceToOpenAI(
 }
 
 /** Normalized tool-choice mode shared by provider adapters. */
-export type CanonicalToolChoiceMode = "auto" | "any" | "none";
+export type CanonicalToolChoiceMode = "auto" | "any" | "none" | "validated";
 
 /**
  * Normalizes canonical toolChoice into a provider-neutral mode + optional
@@ -310,13 +355,14 @@ export type CanonicalToolChoiceMode = "auto" | "any" | "none";
  * `{ allowed_tools: { mode, tools? } }` in its own adapter.
  */
 export function normalizeToolChoice(
-  choice: "auto" | "none" | "required" | { type: "function"; function: { name: string } } | undefined,
+  choice: "auto" | "none" | "required" | "validated" | { type: "function"; function: { name: string } } | undefined,
   availableToolNames: string[]
 ): { mode: CanonicalToolChoiceMode; tools?: string[] } | undefined {
   if (!choice) return undefined;
   if (typeof choice === "string") {
     if (choice === "auto") return undefined; // server default
     if (choice === "none") return { mode: "none" };
+    if (choice === "validated") return { mode: "validated" };
     if (choice === "required") {
       return availableToolNames.length > 0 ? { mode: "any", tools: availableToolNames } : { mode: "any" };
     }
@@ -654,8 +700,11 @@ export function mapOutputToCompatChat(
  *
  * @example `augmentSystemPromptWithStructuredOutput(sys, spec)`
  */
-export function buildStructuredOutputInstruction(spec: StructuredOutputSpec): string {
-  return `Return ONLY valid JSON matching this JSON Schema, with no markdown fences, no commentary, no extra text.\nSchema: ${JSON.stringify(spec.schema)}`;
+export function buildStructuredOutputInstruction(
+  spec: StructuredOutputSpec,
+  template = DEFAULT_PROMPTS.structuredOutput
+): string {
+  return fillPrompt(template, { schema: JSON.stringify(spec.schema) });
 }
 
 /**
@@ -665,11 +714,12 @@ export function buildStructuredOutputInstruction(spec: StructuredOutputSpec): st
  */
 export function augmentSystemPromptWithStructuredOutput(
   systemPrompt: string | undefined,
-  spec: StructuredOutputSpec | undefined
+  spec: StructuredOutputSpec | undefined,
+  template?: string
 ): string | undefined {
   if (!spec) return systemPrompt;
-  const instruction = `[Structured Output]\n${buildStructuredOutputInstruction(spec)}`;
+  const instruction = `[Structured Output]\n${buildStructuredOutputInstruction(spec, template)}`;
   if (!systemPrompt) return instruction;
-  if (systemPrompt.includes("[Structured Output]")) return systemPrompt;
+  if (systemPrompt.includes(instruction)) return systemPrompt;
   return `${systemPrompt}\n\n${instruction}`;
 }

package/src/scheduler/architecture.md

@@ -2,19 +2,19 @@
 
 Scheduled actions: a worker that runs later (once or repeating) and saves its answer to a file. Off unless `dynamicSubagents.allowScheduledActions` is set.
 
-| File                               | What it is                                                                                                                                                                                                                                                                    |
-| :--------------------------------- | :---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `scheduler.ts`                     | One `Scheduler` per home folder: a 1 s unref'd clock that runs only while something is pending, startup sweep, dead-owner recovery, heartbeats, cook/deliver state machine, and the public functions (`createScheduledAction`, `list/update/run/skip/deleteScheduledAction`). |
-| `store.ts`                         | Disk layer under `<home>/scheduled/`: `<id>/task.json`, `<id>/delivery.json`, run files, one short mutex per action; validation of records.                                                                                                                                   |
-| `time.ts`                          | Pure `DD:HH:MM` and local-clock maths. No timezone, DST or `Intl`; `now` is always passed in.                                                                                                                                                                                 |
-| `tool.ts` + `scheduled-actions.md` | The model-facing `scheduled_actions` tool and `get_datetime`; the `.md` is the tool description.                                                                                                                                                                              |
+| File           | What it is                                                                                                                                                                                                                                                                                                                                                                                                     |
+| :------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `scheduler.ts` | One `Scheduler` per home folder: a 1 s unref'd clock that runs only while something is pending, startup sweep, dead-owner recovery, heartbeats, cook/deliver state machine, the functions behind the API (`createScheduledAction`, `list/update/run/skip/deleteScheduledAction`, not exported from the barrel) and `ScheduledActions`, the class behind `agent.scheduled` that binds them to the agent's home. |
+| `store.ts`     | Disk layer under `<home>/scheduled/`: `<id>/task.json`, `<id>/delivery.json`, run files, one short mutex per action; validation of records.                                                                                                                                                                                                                                                                    |
+| `time.ts`      | Pure `DD:HH:MM` and local-clock maths. No timezone, DST or `Intl`; `now` is always passed in.                                                                                                                                                                                                                                                                                                                  |
+| `tool.ts`      | The model-facing `scheduled_actions` tool and `get_datetime`; its description is the `scheduledActionsTool` prompt (`../prompts/scheduled-actions-tool.md`).                                                                                                                                                                                                                                                   |
 
 ## Invariants
 
 - The files are the truth: every write re-reads first and goes through the durable writer. The file format is a stable public contract: see `docs/scheduled-action-files.md` and add a changelog row for any change.
 - Write order when a run ends: run file, then `<id>/delivery.json`, then `<id>/task.json`. A crash in between is repaired by the dead-owner recovery (`recoverCooking`, at start and every 15 s): the delivery is rebuilt from the run file, or the run is marked `missed` when no run file exists.
 - `startCook` advances the next times BEFORE the run starts; a run still cooking when the next is due is skipped, never stacked.
-- Runs are fresh stateless workers built by `buildDynamicWorkerConfig`; their spending guardrail is `workerBudget` only.
+- Runs are fresh stateless workers built by `buildDynamicWorkerConfig`; their spending guardrail is `dynamicSubagents.scheduledActionBudget` only (never `workerBudget`, `budget` or `usageLimit`).
 - The Agent registry holds `WeakRef`s by name: keep every Agent that owns actions referenced, or its runs become `missed`.
 - Several processes may share a home: scheduled actions take no home lock, only the short per-action mutex (`<id>/.mutex`); the one-process lock is on session folders only. Ownership: a process only starts, delivers or recovers actions whose Agent it registered. An action nobody here owns is left alone until its delivery time passed with no run started, then marked `missed` (`no_agent`).
 - Exactly once: a scheduled start re-checks under the action's mutex that it is still `waiting` and due; `markMissed` only changes the state the caller saw; a delivery is emitted only by the process that removed its entry from `delivery.json`.

package/src/scheduler/scheduler.ts

@@ -1052,3 +1052,43 @@ export function deleteScheduledAction(
 ): Promise<DeleteResult> {
   return schedulerFor(opts).delete(id, { force: opts?.force, purge: opts?.purge });
 }
+
+/**
+ * The scheduled-action API of one Agent (`agent.scheduled`): every method works on that agent's home folder, so an Agent
+ * with its own `home` never needs `{ home }` passed. `create` needs `dynamicSubagents.allowScheduledActions` (else a
+ * `ConfigError`). `list`, `update`, `run`, `skip` and `delete` work on every action in the home, as the model's
+ * `scheduled_actions` tool does; `run` needs the action's creating Agent alive in this process.
+ */
+export class ScheduledActions {
+  constructor(private readonly agent: Agent) {}
+
+  /** Schedules a new action under this agent. Returns the saved record; throws one `ValidationError` listing every problem. */
+  create(input: ScheduledActionInput): ScheduledActionRecord {
+    return createScheduledAction(this.agent, input);
+  }
+
+  /** Every action in this agent's home with its full metadata and state, plus a `running` flag. */
+  list(): Array<ScheduledActionRecord & { running: boolean }> {
+    return listScheduledActions({ home: this.agent.home });
+  }
+
+  /** Changes instructions, task, tools, timeout, role or any schedule field of action `id` (refused for a schedule change while it cooks). */
+  update(id: string, patch: ScheduledActionPatch): ScheduledActionRecord {
+    return updateScheduledAction(id, patch, { home: this.agent.home });
+  }
+
+  /** Runs action `id` now, outside its schedule (also resolves a missed run). */
+  run(id: string): ScheduledActionRecord {
+    return runScheduledAction(id, { home: this.agent.home });
+  }
+
+  /** Ignores a missed run of `id` and waits for the next scheduled time (a one-shot becomes `done`). */
+  skip(id: string): ScheduledActionRecord {
+    return skipScheduledAction(id, { home: this.agent.home });
+  }
+
+  /** Deletes action `id` for good. While it is cooking nothing changes unless `force: true`; `purge: true` also deletes its past run files. */
+  delete(id: string, opts?: { force?: boolean; purge?: boolean }): Promise<DeleteResult> {
+    return deleteScheduledAction(id, { home: this.agent.home, ...opts });
+  }
+}