agent-accelerator 0.4.0 → 0.4.5

package/src/providers/openrouter.ts

@@ -52,11 +52,14 @@ import {
   redactedHeaders,
   readErrorPayload,
   incompleteStreamError,
+  hasTruncatedToolArguments,
   combinedSignal,
   timeoutFor,
+  hasAuthHeader,
+  clampToolCallId,
 } from "./shared.ts";
 import { createGenericModelSpec } from "../models/catalog.ts";
-import { getModelFromCatalog, getModelsForProvider } from "../models/catalog.ts";
+import { getModelFromCatalog, getModelsForProvider, modelSupportsStructuredOutput } from "../models/catalog.ts";
 import {
   mapThinkingLevelToOpenRouterChat,
   mapServiceTierToOpenRouter,
@@ -64,6 +67,10 @@ import {
   mapToolChoiceToOpenRouterChat,
   noteProviderTurn,
   parseStreamedToolArguments,
+  mapOutputToOpenRouterChat,
+  normalizeStructuredOutput,
+  augmentSystemPromptWithStructuredOutput,
+  emitProviderWarning,
 } from "../providers.ts";
 
 // ---------------------------------------------------------------------------
@@ -102,6 +109,7 @@ interface ChatRequestBody {
   service_tier?: string;
   session_id?: string;
   plugins?: Array<{ id: string }>;
+  response_format?: { type: "json_schema"; json_schema: { name: string; schema: Record<string, unknown>; strict: boolean; description?: string } };
   stream?: boolean;
   [k: string]: unknown;
 }
@@ -193,7 +201,10 @@ function resolveBaseUrl(options?: ProviderRequestOptions): string {
 }
 
 function resolveApiKey(options?: ProviderRequestOptions): string | undefined {
-  return options?.apiKey || getApiKey("openrouter", undefined, options?.env);
+  const key = getApiKey("openrouter", options?.apiKey, options?.env);
+  if (key) return key;
+  if (hasAuthHeader(options?.headers)) return "unused";
+  return undefined;
 }
 
 /**
@@ -352,11 +363,17 @@ async function fullHistoryMessages(context: ProviderContext): Promise<{
     messages.push({ role: "system", content: context.systemPrompt });
   }
   let hasFiles = false;
+  let lastRole: string | null = "system";
   for (const m of context.messages) {
     if (m.role === "system") continue;
     if (m.role === "user") {
+      // 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." });
+      }
       if (typeof m.content === "string") {
-        if (m.content) messages.push({ role: "user", content: m.content });
+        if (m.content) { messages.push({ role: "user", content: m.content }); lastRole = "user"; }
       } else {
         const { blocks, fileUrls, hasFiles: hf } = await contentPartsToBlocks(m.content);
         if (hf) hasFiles = true;
@@ -364,7 +381,7 @@ async function fullHistoryMessages(context: ProviderContext): Promise<{
         for (const url of fileUrls) {
           blocks.push({ type: "text", text: url });
         }
-        if (blocks.length > 0) messages.push({ role: "user", content: blocks });
+        if (blocks.length > 0) { messages.push({ role: "user", content: blocks }); lastRole = "user"; }
       }
     } else if (m.role === "assistant") {
       if (typeof m.content === "string") {
@@ -378,7 +395,7 @@ async function fullHistoryMessages(context: ProviderContext): Promise<{
       for (const part of m.content) {
         if (part.type === "tool_call") {
           calls.push({
-            id: part.callId || part.id,
+            id: clampToolCallId(part.callId || part.id),
             type: "function",
             function: { name: part.name, arguments: JSON.stringify(part.arguments || {}) },
           });
@@ -388,20 +405,25 @@ async function fullHistoryMessages(context: ProviderContext): Promise<{
         // Prior-turn reasoning is NOT resent: chat history is messages +
         // tool calls only (documented decision; avoids strict-route 400s).
       }
+      // Skip empty assistant turns (no text + no tool calls): strict
+      // routes reject them, and they carry no signal (pi drop rule).
+      if (texts.length === 0 && calls.length === 0) continue;
       messages.push({
         role: "assistant",
         content: texts.length > 0 ? texts.join("\n") : null,
         ...(calls.length > 0 ? { tool_calls: calls } : {}),
       });
+      lastRole = "assistant";
     } else if (m.role === "tool") {
       if (typeof m.content === "string") {
         const queue = (m.name && idsByName.get(m.name)) || [];
         messages.push({
           role: "tool",
-          tool_call_id: queue.shift() || newToolCallId(),
+          tool_call_id: clampToolCallId(queue.shift() || newToolCallId()),
           content: m.content,
           name: m.name,
         });
+        lastRole = "tool";
         continue;
       }
       if (!Array.isArray(m.content)) continue;
@@ -409,10 +431,11 @@ async function fullHistoryMessages(context: ProviderContext): Promise<{
         if (part.type === "tool_result") {
           messages.push({
             role: "tool",
-            tool_call_id: pairing.get(part.id) || part.id,
+            tool_call_id: clampToolCallId(pairing.get(part.id) || part.id),
             content: resultToOutput(part.result),
             name: part.name,
           });
+          lastRole = "tool";
         }
       }
     }
@@ -490,7 +513,7 @@ function parseResponse(
   for (const tc of message?.tool_calls ?? []) {
     const args = parseArguments(tc.function?.arguments);
     toolCalls.push({
-      id: tc.id || newToolCallId(),
+      id: tc.id && !tc.id.includes("|") && tc.id.length <= 40 ? tc.id : clampToolCallId(tc.id || newToolCallId()),
       name: tc.function?.name || "unknown",
       arguments: args,
       rawArguments:
@@ -559,7 +582,33 @@ export class OpenRouterChatCompletionsProvider implements Provider {
     const serviceTier = mapServiceTierToOpenRouter(options?.serviceTier);
     applyCacheForOpenRouter(options?.cache, `openrouter/${modelId}`);
 
-    const { messages, hasFiles } = await fullHistoryMessages(context);
+    // Structured outputs: native `response_format` when supported, else
+    // emulated via system-prompt instruction + client validation (catalog
+    // `structured_output: false` models would 400 on the wire shape).
+    let effectiveContext = context;
+    let outputEmulated = false;
+    let outputSpec: import("../types/model.ts").StructuredOutputSpec | undefined;
+    try {
+      outputSpec = normalizeStructuredOutput(options?.output ?? (options as { outputSchema?: unknown })?.outputSchema);
+    } catch {
+      // why: invalid output shapes fail fast at Agent construction/loop validation.
+      outputSpec = undefined;
+    }
+    if (outputSpec && !modelSupportsStructuredOutput("openrouter", modelId)) {
+      outputEmulated = true;
+      effectiveContext = {
+        ...context,
+        systemPrompt: augmentSystemPromptWithStructuredOutput(context.systemPrompt, outputSpec),
+      };
+      emitProviderWarning({
+        provider: "openrouter",
+        capability: "structured output",
+        requested: `${outputSpec.name} (openrouter/${modelId})`,
+        reason: "the catalog reports structured_output: false for this model, so native response_format is unsupported.",
+        fallback: "emulated JSON instruction + client validation (no response_format is sent)",
+      });
+    }
+    const { messages, hasFiles } = await fullHistoryMessages(effectiveContext);
     const body: ChatRequestBody = {
       model: modelId,
       messages,
@@ -573,12 +622,23 @@ export class OpenRouterChatCompletionsProvider implements Provider {
     if (toolChoice !== undefined) body.tool_choice = toolChoice;
     if (effort) body.reasoning = { effort };
     if (serviceTier) body.service_tier = serviceTier;
+    // Structured outputs: Chat Completions `response_format{type:json_schema,json_schema}`.
+    // Skipped when emulated (unsupported model): instruction already in messages.
+    if (outputSpec && !outputEmulated) {
+      try {
+        const mapped = mapOutputToOpenRouterChat(outputSpec);
+        if (mapped) body.response_format = mapped.response_format;
+      } catch {
+        // why: invalid output shapes fail fast at Agent construction/loop validation.
+      }
+    }
     // PDF ingestion is a documented plugin, not a message shape: enable it
     // only when file parts are present (never by default).
     if (hasFiles) body.plugins = [{ id: "file-parser" }];
-    // No temperature/top_p/max_tokens/stop/response_format/user/seed knobs
+    // No temperature/top_p/max_tokens/stop/user/seed knobs
     // (no canonical options exist; omitting also keeps provider cache keys
-    // stable). No store/previous_response_id/conversation: they do not exist
+    // stable). `response_format` above is the sole structured-output exception.
+    // No store/previous_response_id/conversation: they do not exist
     // on this endpoint.
     // Session affinity: top-level `session_id` is the documented sticky-routing
     // key on Chat Completions (prompt-caching guide) and takes precedence over
@@ -608,7 +668,7 @@ export class OpenRouterChatCompletionsProvider implements Provider {
       if (INTERNAL_HEADERS.has(k.toLowerCase())) delete headers[k];
     }
     setHeaderCaseInsensitive(headers, "Content-Type", "application/json");
-    setHeaderCaseInsensitive(headers, "Authorization", `Bearer ${apiKey}`);
+    if (apiKey !== "unused") setHeaderCaseInsensitive(headers, "Authorization", `Bearer ${apiKey}`);
     return { method: "POST", headers, body: JSON.stringify(body), signal };
   }
 
@@ -641,14 +701,21 @@ export class OpenRouterChatCompletionsProvider implements Provider {
     modelId: string
   ): void {
     if (status >= 200 && status < 300) return;
-    const { message, code, errorType } = readErrorPayload(bodyText);
-    const err: Record<string, unknown> & Error = new Error(message) as Record<string, unknown> & Error;
+    const { message, code, errorType, raw } = readErrorPayload(bodyText);
+    const hint =
+      status === 401
+        ? " Check OPENROUTER_API_KEY (no quotes/spaces, correct provider) and that the key is loaded (bun --env-file=.env.local)."
+        : "";
+    const fullMessage = `${message}${hint}`;
+    const err: Record<string, unknown> & Error = new Error(fullMessage) as Record<string, unknown> & Error;
     (err as Record<string, unknown>)["statusCode"] = status;
     (err as Record<string, unknown>)["status"] = status;
     (err as Record<string, unknown>)["responseBody"] = bodyText.slice(0, 500);
     (err as Record<string, unknown>)["url"] = url.split("?")[0];
+    (err as Record<string, unknown>)["data"] = { error: { message: fullMessage } };
     if (code !== undefined) (err as Record<string, unknown>)["code"] = code;
     if (errorType) (err as Record<string, unknown>)["errorType"] = errorType;
+    if (raw) (err as Record<string, unknown>)["raw"] = raw;
     throw toConciseProviderError(err, "openrouter", modelId);
   }
 
@@ -995,7 +1062,7 @@ export class OpenRouterChatCompletionsProvider implements Provider {
         for (const c of calls.values()) {
           const args = parseStreamedToolArguments(c.startArgs, c.deltaArgs);
           const record: ToolCallRecord = {
-            id: c.id || newToolCallId(),
+            id: c.id && !c.id.includes("|") && c.id.length <= 40 ? c.id : clampToolCallId(c.id || newToolCallId()),
             name: c.name,
             arguments: args,
             rawArguments: c.startArgs + c.deltaArgs,
@@ -1027,6 +1094,13 @@ export class OpenRouterChatCompletionsProvider implements Provider {
           eventStream.fail(incompleteStreamError("openrouter", clean));
           return;
         }
+        // Refuse unfinished tool calls whose args never parsed (output_item.done
+        // never arrived): truncated `{raw}` must not reach the executor (pi
+        // api/openai-responses-shared.ts:766 rule). Non-SSE mocks preserve legacy.
+        if (!hasTerminal && toolCalls.some((c) => hasTruncatedToolArguments(c.arguments)) && isSSEPayload) {
+          eventStream.fail(incompleteStreamError("openrouter", clean));
+          return;
+        }
 
         const cleanThinking = cleanThinkingEarly;
         const finalResponse = new AgentResponse({

package/src/providers/shared.ts

@@ -44,25 +44,30 @@ export function redactedHeaders(headers: Record<string, string>): Record<string,
 }
 
 /**
- * Extracts `{ message, code, errorType }` from a non-2xx JSON body. Handles
- * OpenAI `type`, OpenRouter `metadata.error_type`, and Google `status` code
- * shapes; unknown bodies degrade to a 300-char slice.
+ * Extracts `{ message, code, errorType, raw }` from a non-2xx JSON body. Handles
+ * OpenAI `type`, OpenRouter `metadata.error_type` + `metadata.raw`, and Google
+ * `status` code shapes; unknown bodies degrade to a 300-char slice.
  */
 export function readErrorPayload(
   bodyText: string
-): { message: string; code?: string | number; errorType?: string } {
+): { message: string; code?: string | number; errorType?: string; raw?: string } {
   try {
     const parsed: unknown = JSON.parse(bodyText);
     const first = Array.isArray(parsed) ? parsed[0] : parsed;
-    const err = (first as { error?: { message?: string; code?: string | number; type?: string; status?: string | number; metadata?: { error_type?: string } } })?.error;
+    const err = (first as { error?: { message?: string; code?: string | number; type?: string; status?: string | number; metadata?: { error_type?: string; raw?: unknown } } })?.error;
     if (err && typeof err.message === "string") {
       const code = err.code ?? err.status;
       const errorType =
         err.type ?? err.metadata?.error_type ?? (first as { error_type?: string })?.error_type;
+      const rawCandidate =
+        (err as { metadata?: { raw?: unknown } }).metadata?.raw ??
+        (first as { metadata?: { raw?: unknown } })?.metadata?.raw;
+      const raw = typeof rawCandidate === "string" && rawCandidate.trim() ? rawCandidate.trim().slice(0, 500) : undefined;
       return {
         message: err.message,
         ...(code !== undefined ? { code } : {}),
         ...(typeof errorType === "string" ? { errorType } : {}),
+        ...(raw ? { raw } : {}),
       };
     }
     return { message: bodyText.slice(0, 300) };
@@ -130,3 +135,56 @@ export function newToolCallId(prefix = "call"): string {
   } catch {}
   return `${prefix}_${Math.random().toString(36).slice(2, 10)}`;
 }
+
+/**
+ * True when custom headers already carry auth (proxy/Copilot flows).
+ * Case-insensitive, non-empty `Authorization` or `cf-aig-authorization`.
+ * Callers return `"unused"` instead of throwing missing-key.
+ */
+export function hasAuthHeader(headers: Record<string, string> | undefined): boolean {
+  if (!headers) return false;
+  for (const [k, v] of Object.entries(headers)) {
+    const lower = k.toLowerCase();
+    if ((lower === "authorization" || lower === "cf-aig-authorization") && typeof v === "string" && v.trim().length > 0) {
+      return true;
+    }
+  }
+  return false;
+}
+
+/** True for truncated streamed tool args (`{ raw }` marker from `parseStreamedToolArguments`). */
+export function hasTruncatedToolArguments(args: unknown): boolean {
+  if (!args || typeof args !== "object" || Array.isArray(args)) return false;
+  const keys = Object.keys(args as Record<string, unknown>);
+  return keys.length === 1 && keys[0] === "raw" && typeof (args as Record<string, unknown>).raw === "string";
+}
+
+/** Short hash for tool-ID clamping (FNV-1a, 8 hex chars, no deps). */
+export function shortHashId(value: string): string {
+  let h = 0x811c9dc5;
+  for (let i = 0; i < value.length; i++) {
+    h ^= value.charCodeAt(i);
+    h = Math.imul(h, 0x01000193);
+  }
+  return (h >>> 0).toString(16).padStart(8, "0");
+}
+
+/**
+ * Clamps a tool-call ID to the 40-char OpenAI limit (pi `api/openai-completions.ts:1194`).
+ * Pipe IDs (`callId|itemId`) become `callId_itemHash`; overlong IDs truncate
+ * with hash suffix. Plain IDs pass through (truncated if needed).
+ */
+export function clampToolCallId(id: string): string {
+  const clean = String(id ?? "").replace(/[^a-zA-Z0-9_-]/g, "_");
+  if (!clean.includes("|")) {
+    return clean.length > 40 ? clean.slice(0, 40) : clean || "call_unknown";
+  }
+  const sep = clean.indexOf("|");
+  const callId = clean.slice(0, sep).replace(/_+$/, "") || "call";
+  const itemId = clean.slice(sep + 1).replace(/_+$/, "");
+  const combined = itemId ? `${callId}_${itemId}` : callId;
+  if (combined.length <= 40) return combined;
+  const hash = shortHashId(id).slice(0, 8);
+  const prefix = callId.slice(0, Math.max(1, 40 - hash.length - 1));
+  return `${prefix}_${hash}`;
+}

package/src/providers.ts

@@ -10,6 +10,9 @@
  * redesigning this abstraction — only new per-provider mappers/adapters.
  */
 import type { CacheConfig, ServiceTier, ThinkingLevel } from "./types/core.ts";
+import type { StructuredOutputSpec } from "./types/model.ts";
+import { zodToJsonSchema } from "./tools/schema.ts";
+import { ValidationError } from "./types/errors.ts";
 
 /** Classification of a canonical capability on a given provider. */
 export type ProviderCapabilityStatus =
@@ -357,17 +360,17 @@ export function mapServiceTierToOpenAI(tier: ServiceTier | undefined): "flex" |
 
 /**
  * Applies canonical cache config for OpenAI. Session affinity flows via
- * `prompt_cache_key` (handled by the adapter); explicit retention control
- * lives in `prompt_cache_options` (gpt-5.6+ explicit breakpoints) which is
- * out of scope for the most-important subset, so retention/cachedContentId
- * are UNSUPPORTED: warn and drop. `prompt_cache_retention` is deprecated.
+ * `prompt_cache_key` (handled by the adapter); `long` retention maps to
+ * `prompt_cache_retention: "24h"` when the catalog supports it (handled by
+ * the adapter, pi `api/openai-responses.ts:97` rule). Other explicit
+ * retention modes and `cachedContentId` are UNSUPPORTED: warn and drop.
  */
 export function applyCacheForOpenAI(
   cache: CacheConfig | undefined,
   modelRef: string
 ): void {
   if (!cache) return;
-  if (cache.retention && cache.retention !== "implicit") {
+  if (cache.retention && cache.retention !== "implicit" && cache.retention !== "long") {
     emitProviderWarning({
       provider: "openai",
       capability: "cache retention",
@@ -489,3 +492,251 @@ export function parseStreamedToolArguments(startText: string, deltaText: string)
   }
   return { raw: startText + deltaText };
 }
+
+// ---------------------------------------------------------------------------
+// Structured outputs (canonical, pure, no I/O)
+// ---------------------------------------------------------------------------
+
+function isZodLike(value: unknown): boolean {
+  if (!value || typeof value !== "object") return false;
+  const v = value as Record<string, unknown>;
+  return (
+    typeof v["safeParse"] === "function" ||
+    typeof v["parse"] === "function" ||
+    "_def" in v ||
+    "~standard" in v
+  );
+}
+
+function looksLikeJsonSchema(value: unknown): boolean {
+  if (!isPlainObject(value)) return false;
+  const v = value as Record<string, unknown>;
+  return (
+    typeof v["type"] === "string" ||
+    isPlainObject(v["properties"]) ||
+    Array.isArray(v["anyOf"]) ||
+    Array.isArray(v["oneOf"]) ||
+    Array.isArray(v["allOf"]) ||
+    typeof v["$schema"] === "string" ||
+    isPlainObject(v["$defs"]) ||
+    isPlainObject(v["definitions"])
+  );
+}
+
+function sanitizeOutputName(raw: unknown): string {
+  const base = typeof raw === "string" && raw.trim() ? raw.trim() : "structured_output";
+  const cleaned = base.replace(/[^a-zA-Z0-9_-]/g, "_").slice(0, 64) || "structured_output";
+  return cleaned;
+}
+
+function schemaToJsonSchema(schema: unknown, what: string): Record<string, unknown> {
+  if (isZodLike(schema)) {
+    try {
+      const converted = zodToJsonSchema(schema);
+      if (isPlainObject(converted)) return converted;
+    } catch {
+      // fall through to error below
+    }
+  }
+  if (isPlainObject(schema)) return schema as Record<string, unknown>;
+  throw new ValidationError(
+    `[Agent Accelerator] Invalid structured output ${what}: expected a Zod schema, a JSON Schema object, or { name, schema, strict }.`
+  );
+}
+
+/**
+ * Normalizes `AgentConfig.output` into a provider-agnostic spec.
+ *
+ * Accepts a Zod schema, a JSON Schema object, or an explicit
+ * `{ name?, description?, schema, strict? }` wrapper. Returns `undefined`
+ * when no output was requested. Throws `ValidationError` for invalid shapes.
+ *
+ * @example `normalizeStructuredOutput(z.object({ city: z.string() }))`
+ */
+export function normalizeStructuredOutput(output: unknown): StructuredOutputSpec | undefined {
+  if (output === undefined || output === null) return undefined;
+  if (isPlainObject(output) && "schema" in (output as Record<string, unknown>)) {
+    const rec = output as Record<string, unknown>;
+    const schema = schemaToJsonSchema(rec["schema"], "`output.schema`");
+    return {
+      name: sanitizeOutputName(rec["name"]),
+      schema,
+      strict: typeof rec["strict"] === "boolean" ? (rec["strict"] as boolean) : true,
+      ...(typeof rec["description"] === "string" && (rec["description"] as string).trim()
+        ? { description: (rec["description"] as string).trim() }
+        : {}),
+    };
+  }
+  if (isZodLike(output) || looksLikeJsonSchema(output)) {
+    return {
+      name: "structured_output",
+      schema: schemaToJsonSchema(output, "`output`"),
+      strict: true,
+    };
+  }
+  throw new ValidationError(
+    "[Agent Accelerator] Invalid structured output: expected a Zod schema, a JSON Schema object, or { name, schema, strict }."
+  );
+}
+
+/**
+ * Extracts the original Zod validator from a canonical output option, when
+ * present (bare Zod schema or `{ schema: Zod }`). Used by the loop for
+ * post-parse validation; `undefined` means JSON-parse only.
+ */
+export function extractOutputValidator(output: unknown): { safeParse: (v: unknown) => { success: boolean; data?: unknown; error?: { message: string } } } | undefined {
+  if (!output) return undefined;
+  if (isZodLike(output) && typeof (output as { safeParse?: unknown }).safeParse === "function") {
+    return output as { safeParse: (v: unknown) => { success: boolean; data?: unknown; error?: { message: string } } };
+  }
+  if (isPlainObject(output) && isZodLike((output as Record<string, unknown>)["schema"])) {
+    const inner = (output as Record<string, unknown>)["schema"] as { safeParse?: unknown };
+    if (typeof inner.safeParse === "function") {
+      return inner as { safeParse: (v: unknown) => { success: boolean; data?: unknown; error?: { message: string } } };
+    }
+  }
+  return undefined;
+}
+
+function stripCodeFences(text: string): string {
+  const trimmed = text.trim();
+  const fenced = trimmed.match(/^```(?:json)?\s*\n([\s\S]*?)\n```\s*$/i);
+  if (fenced && typeof fenced[1] === "string") return fenced[1].trim();
+  return trimmed;
+}
+
+/**
+ * Parses and validates a final answer against a canonical output option.
+ * Strips markdown fences, requires valid JSON, then applies the Zod validator
+ * when the original option carried one. Throws `ValidationError` on mismatch.
+ *
+ * @example `parseStructuredOutput('{"city":"Paris"}', z.object({ city: z.string() }))`
+ */
+export function parseStructuredOutput(text: string, output: unknown): unknown {
+  const cleaned = stripCodeFences(typeof text === "string" ? text : String(text ?? ""));
+  if (!cleaned) {
+    throw new ValidationError(
+      "[Agent Accelerator] Structured output validation failed: model returned empty text, expected JSON matching the output schema."
+    );
+  }
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(cleaned);
+  } catch {
+    throw new ValidationError(
+      `[Agent Accelerator] Structured output validation failed: model text is not valid JSON (${cleaned.slice(0, 120)}).`
+    );
+  }
+  const validator = extractOutputValidator(output);
+  if (validator) {
+    const res = validator.safeParse(parsed);
+    if (!res.success) {
+      const detail = res.error?.message ? ` ${res.error.message}`.slice(0, 500) : "";
+      throw new ValidationError(
+        `[Agent Accelerator] Structured output validation failed: JSON does not match the output schema.${detail}`
+      );
+    }
+    return res.data ?? parsed;
+  }
+  return parsed;
+}
+
+/**
+ * Maps a normalized spec onto OpenAI Responses `text.format`.
+ * `{ type: json_schema, name, schema, strict }` (docs: responses/create).
+ */
+export function mapOutputToOpenAI(
+  spec: StructuredOutputSpec | undefined
+): { format: { type: "json_schema"; name: string; schema: Record<string, unknown>; strict: boolean; description?: string } } | undefined {
+  if (!spec) return undefined;
+  return {
+    format: {
+      type: "json_schema",
+      name: spec.name,
+      schema: spec.schema,
+      strict: spec.strict ?? true,
+      ...(spec.description ? { description: spec.description } : {}),
+    },
+  };
+}
+
+/**
+ * Maps a normalized spec onto Google Interactions `response_format`.
+ * `{ type: text, mime_type: application/json, schema }` (docs: structured-output).
+ */
+export function mapOutputToGoogle(
+  spec: StructuredOutputSpec | undefined
+): { responseFormat: { type: "text"; mime_type: "application/json"; schema: Record<string, unknown> } } | undefined {
+  if (!spec) return undefined;
+  return {
+    responseFormat: {
+      type: "text",
+      mime_type: "application/json",
+      schema: spec.schema,
+    },
+  };
+}
+
+/** Chat Completions `response_format` wire shape (OpenRouter + compat). */
+export type ChatCompletionsResponseFormat =
+  | { type: "json_schema"; json_schema: { name: string; schema: Record<string, unknown>; strict: boolean; description?: string } };
+
+/**
+ * Maps a normalized spec onto Chat Completions `response_format`.
+ * `{ type: json_schema, json_schema: { name, schema, strict } }`
+ * (docs: openai completions/create, openrouter parameters).
+ */
+export function mapOutputToOpenRouterChat(
+  spec: StructuredOutputSpec | undefined
+): { response_format: ChatCompletionsResponseFormat } | undefined {
+  if (!spec) return undefined;
+  return {
+    response_format: {
+      type: "json_schema",
+      json_schema: {
+        name: spec.name,
+        schema: spec.schema,
+        strict: spec.strict ?? true,
+        ...(spec.description ? { description: spec.description } : {}),
+      },
+    },
+  };
+}
+
+/**
+ * Maps a normalized spec onto generic compat Chat Completions
+ * `response_format` (same standard shape as OpenRouter Chat).
+ */
+export function mapOutputToCompatChat(
+  spec: StructuredOutputSpec | undefined
+): { response_format: ChatCompletionsResponseFormat } | undefined {
+  return mapOutputToOpenRouterChat(spec);
+}
+
+/**
+ * Builds the emulated structured-output instruction for models without
+ * native `response_format` support (catalog `structured_output: false`).
+ * Appended to the system prompt so the model still targets JSON; the loop
+ * still validates into `AgentResponse.parsed`.
+ *
+ * @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)}`;
+}
+
+/**
+ * Returns a system prompt with the emulated structured-output instruction
+ * appended (stable per Agent since `output` is agent-level, so prefix-cache
+ * affinity is preserved). No-op when spec is undefined.
+ */
+export function augmentSystemPromptWithStructuredOutput(
+  systemPrompt: string | undefined,
+  spec: StructuredOutputSpec | undefined
+): string | undefined {
+  if (!spec) return systemPrompt;
+  const instruction = `[Structured Output]\n${buildStructuredOutputInstruction(spec)}`;
+  if (!systemPrompt) return instruction;
+  if (systemPrompt.includes("[Structured Output]")) return systemPrompt;
+  return `${systemPrompt}\n\n${instruction}`;
+}

package/src/session/store.ts

@@ -1098,19 +1098,28 @@ export type PricedCost = NonNullable<TokenUsage["cost"]> & {
 };
 
 /**
- * Service-tier price multipliers (Q-36). ESTIMATES, not vendor guarantees:
- * `flex` batches trade latency for ~0.5x price, `priority` reserves capacity
- * at ~1.5x. Standard/default is 1.0. Documented as estimates because vendors
- * do not publish exact tier multipliers in the catalog.
+ * Service-tier price multipliers (Q-36). Aligned with pi
+ * (`api/openai-responses.ts:387`): `flex` trades latency for ~0.5x price,
+ * `priority`/`fast` reserve capacity at ~2x (`2.5x` for `gpt-5.5`).
+ * Standard/default is 1.0. Estimates because vendors do not publish exact
+ * tier multipliers in the catalog.
  */
 const SERVICE_TIER_MULTIPLIERS: Record<string, number> = {
   flex: 0.5,
-  priority: 1.5,
+  priority: 2,
+  fast: 2,
 };
 
-function serviceTierMultiplier(serviceTier?: string): { multiplier: number; tier?: string } {
+function serviceTierMultiplier(serviceTier?: string, modelId?: string): { multiplier: number; tier?: string } {
   if (!serviceTier) return { multiplier: 1 };
-  const m = SERVICE_TIER_MULTIPLIERS[serviceTier.toLowerCase()];
+  const lower = serviceTier.toLowerCase();
+  if (lower === "priority" || lower === "fast") {
+    if (typeof modelId === "string" && modelId.includes("gpt-5.5")) {
+      return { multiplier: 2.5, tier: serviceTier };
+    }
+    return { multiplier: 2, tier: serviceTier };
+  }
+  const m = SERVICE_TIER_MULTIPLIERS[lower];
   return m !== undefined ? { multiplier: m, tier: serviceTier } : { multiplier: 1, tier: serviceTier };
 }
 
@@ -1190,7 +1199,7 @@ function resolveEffectivePricing(
 export function priceUsage(
   usage: TokenUsage,
   spec?: ModelSpec,
-  opts?: { serviceTier?: ServiceTier | string }
+  opts?: { serviceTier?: ServiceTier | string; modelId?: string }
 ): PricedCost | undefined {
   const reported = usage?.cost;
   if (reported && typeof reported.totalCost === "number" && reported.totalCost > 0) {
@@ -1233,7 +1242,7 @@ export function priceUsage(
   if (!pricing.input && !pricing.output && !pricing.cacheRead && !pricing.cacheWrite && !pricing.audio) {
     return undefined;
   }
-  const { multiplier, tier: serviceTier } = serviceTierMultiplier(opts?.serviceTier);
+  const { multiplier, tier: serviceTier } = serviceTierMultiplier(opts?.serviceTier, opts?.modelId ?? spec?.id);
   const nonCachedInput = Math.max(0, inputTokens - cachedTokens);
   // Integer micro-USD accumulation: microUSD = tokens * pricePerMillion
   // ($P per 1M tokens == $P/1e6 per token == P micro-USD per token).