agent-accelerator 0.2.0 → 0.4.0

package/src/agent/loop.ts

@@ -2,7 +2,10 @@ import type { Provider, ProviderRequestOptions, ModelSpec } from "../types/model
 import type { ToolDefinition, ToolCallRecord, ToolResultRecord } from "../types/tool.ts";
 import type { TokenUsage } from "../types/core.ts";
 import type { AgentRunOptions } from "../types/agent.ts";
-import { AgentResponse, type SubAgentExecutionMetadata, type StreamEvent } from "../types/response.ts";
+import type { ContentPart } from "../types/message.ts";
+import { AgentResponse, normalizeFinishReason, type FinishReason, type SubAgentExecutionMetadata, type StreamEvent } from "../types/response.ts";
+import { priceUsage, reportUsageAnomaly, telemetryBus } from "../session/store.ts";
+export { telemetryBus };
 import { AssistantMessageEventStream } from "../streaming/event-stream.ts";
 import { AgentContext } from "./context.ts";
 import { toStandardToolDeclarations } from "../tools/tool.ts";
@@ -11,6 +14,12 @@ import { getModelFromCatalog, ensureModelCatalogFresh, validateModelThinking } f
 import { preprocessFilePartsForBypass } from "../utils/documents.ts";
 import { noteProviderTurn } from "../providers.ts";
 
+/** One mid-session steer request buffered while a run is active. */
+export interface SteerEntry {
+  prompt: string | ContentPart[];
+  options?: AgentRunOptions;
+}
+
 export interface AgentLoopConfig {
   agentName?: string;
   provider: Provider;
@@ -22,45 +31,309 @@ export interface AgentLoopConfig {
   maxTurns?: number;
   /** Convert `file` parts client-side for pdf-incapable models (see Agent flag). */
   bypassInputFileModality?: boolean;
+  /** Called after every turn for durable persistence checkpoints (never fails a turn). */
+  onProgress?: () => void;
+  /**
+   * Shared steer inbox for mid-session redirection. Entries are drained
+   * between turns (after the current provider/tool work finishes) and
+   * injected into the *current* turn — same response, same turn budget.
+   * Mutated in place by `agent.steer()` / `run(..., { enqueue: "steer" })`.
+   */
+  steerInbox?: SteerEntry[];
+  /** Called after steer entries are injected (streaming loops also push `steer_injected` events). */
+  onSteerInjected?: (injectedPrompts: string[]) => void;
 }
 
-export function computeCostFromPricing(usage: TokenUsage, spec?: ModelSpec): TokenUsage["cost"] {
-  if (usage.cost && usage.cost.totalCost !== undefined && usage.cost.totalCost > 0) {
-    return usage.cost;
+/** Short preview for `steer_injected` / `queued` event payloads (bounded, display-only). */
+function steerPreview(prompt: string | ContentPart[]): string {
+  if (typeof prompt === "string") return prompt.slice(0, 500);
+  try {
+    const texts = prompt
+      .filter((p) => (p as { type?: unknown }).type === "text")
+      .map((p) => (p as { text?: string }).text ?? "")
+      .join("\n");
+    return (texts || "[multipart]").slice(0, 500);
+  } catch {
+    return "[multipart]";
   }
-  if (!spec) return usage.cost;
+}
 
-  const costData = spec.cost || {};
-  const pricingData = spec.pricing || {};
-  const inputPrice = pricingData.inputPerMillion ?? costData.input ?? 0;
-  const outputPrice = pricingData.outputPerMillion ?? costData.output ?? 0;
-  const cacheReadPrice = pricingData.cacheReadPerMillion ?? costData.cache_read ?? 0;
-  const cacheWritePrice = pricingData.cacheWritePerMillion ?? costData.cache_write ?? 0;
+/**
+ * Drains pending steer entries into the conversation as new user messages.
+ * Returns display previews for events/telemetry. Never throws: invalid
+ * entries are skipped so one bad steer cannot fail the active turn.
+ */
+function drainSteerInbox(context: AgentContext, inbox?: SteerEntry[]): string[] {
+  if (!inbox || inbox.length === 0) return [];
+  const injected: string[] = [];
+  while (inbox.length > 0) {
+    const entry = inbox.shift()!;
+    try {
+      let prompt = entry.prompt as string | ContentPart[];
+      const opts = entry.options;
+      if (Array.isArray(prompt) && prompt.length === 0) continue;
+      if (opts?.additionalContext) {
+        const prefix = `[Additional Context]\n${opts.additionalContext}\n\n`;
+        if (typeof prompt === "string") prompt = prefix + prompt;
+        else prompt = [{ type: "text", text: prefix } as ContentPart, ...prompt];
+      }
+      context.addUserMessage(prompt);
+      injected.push(steerPreview(entry.prompt));
+    } catch {
+      continue;
+    }
+  }
+  return injected;
+}
 
-  if (inputPrice === 0 && outputPrice === 0 && cacheReadPrice === 0 && cacheWritePrice === 0) {
-    return usage.cost;
+function emitTurn(
+  runOptions: AgentRunOptions | undefined,
+  turn: { turns: number; text?: string; thinking?: string; toolCalls?: ToolCallRecord[]; toolResults?: ToolResultRecord[] }
+): void {
+  try {
+    runOptions?.onTurn?.({
+      turns: turn.turns,
+      text: turn.text,
+      thinking: turn.thinking,
+      toolCalls: turn.toolCalls?.map((c) => ({ id: c.id, name: c.name })),
+      toolResults: turn.toolResults?.map((r) => ({ id: r.id, name: r.name, isError: r.isError })),
+    });
+  } catch {}
+}
+
+function emitProgress(config: { onProgress?: () => void }): void {
+  try { config.onProgress?.(); } catch {}
+}
+
+/**
+ * Normalizes `maxTurns` to a safe positive integer (default Infinity).
+ * `0` means infinite (no limit), matching the `timeout: 0` convention.
+ * Prevents silent zero-turn runs from negative values (clamped to 1).
+ */
+function normalizeMaxTurns(value?: number): number {
+  if (value === undefined) return Infinity;
+  if (value === 0 || value === Infinity) return Infinity;
+  if (!Number.isFinite(value as number)) return Infinity;
+  return Math.max(1, Math.floor(value as number));
+}
+
+/**
+ * Warns when an agent run stops because `maxTurns` was exhausted while
+ * the model still wanted to call tools. Without this, the loop simply
+ * returns the last tool-turn text (often empty) with `finishReason:
+ * "tool_calls"`, which looks like success while dropping pending work.
+ */
+function warnMaxTurnsHit(agentName: string | undefined, maxTurns: number, pendingTools: string[]): void {
+  const who = agentName ? `"${agentName}"` : "Agent";
+  const tools = pendingTools.length > 0 ? ` Pending tool calls dropped: ${pendingTools.join(", ")}.` : "";
+  // Q-41: no console.* in library code — route via the telemetry bus
+  // (default no-op; CLIs attach a pretty logger via telemetryBus.onEvent).
+  try {
+    telemetryBus.emitWarning(
+      "agent.max_turns_truncated",
+      `[Agent Accelerator] "${who}" hit maxTurns (${maxTurns}) with unfinished tool calls.${tools} Increase maxTurns or split the task.`,
+      { agentName, maxTurns, pendingTools }
+    );
+  } catch {
+    // why: telemetry emission is observability-only and must never throw.
   }
+}
 
-  const cachedTokens = usage.cachedTokens ?? usage.cacheReadTokens ?? 0;
-  const nonCachedInputTokens = Math.max(0, (usage.inputTokens || 0) - cachedTokens);
-  const cacheWriteTokens = usage.cacheWriteTokens ?? 0;
-  const outputTokens = usage.outputTokens ?? 0;
+// ---------------------------------------------------------------------------
+// Q-19: tool-call/result pairing repair.
+// ---------------------------------------------------------------------------
 
-  const inputCost = (nonCachedInputTokens / 1_000_000) * inputPrice;
-  const cacheReadCost = (cachedTokens / 1_000_000) * cacheReadPrice;
-  const cacheWriteCost = (cacheWriteTokens / 1_000_000) * cacheWritePrice;
-  const outputCost = (outputTokens / 1_000_000) * outputPrice;
-  const totalCost = inputCost + cacheReadCost + cacheWriteCost + outputCost;
+/**
+ * Repairs orphaned tool call/result pairs before each provider request
+ * (Q-19). Providers reject a `tool_result` without its `tool_call` and
+ * vice versa; a prior abort or crash can leave such orphans in history.
+ * Synthesizes error results for orphan calls and drops orphan results.
+ */
+export function ensureToolPairing(context: AgentContext): void {
+  try {
+    const callIds = new Map<string, string>();
+    for (const m of context.messages) {
+      if ((m as any)?.role !== "assistant" || !Array.isArray((m as any).content)) continue;
+      for (const p of (m as any).content as Array<any>) {
+        if (p && p.type === "tool_call" && typeof p.id === "string" && p.id) {
+          if (!callIds.has(p.id)) callIds.set(p.id, typeof p.name === "string" ? p.name : "tool");
+        }
+      }
+    }
+    if (callIds.size === 0) {
+      // No calls: drop any stray tool results.
+      const hasOrphan = context.messages.some(
+        (m: any) => m?.role === "tool" && Array.isArray(m.content)
+      );
+      if (!hasOrphan) return;
+      context.messages = context.messages.filter((m: any) => m?.role !== "tool");
+      return;
+    }
+    const resultIds = new Set<string>();
+    for (const m of context.messages) {
+      if ((m as any)?.role !== "tool" || !Array.isArray((m as any).content)) continue;
+      for (const p of (m as any).content as Array<any>) {
+        if (p && p.type === "tool_result" && typeof p.id === "string" && p.id) {
+          resultIds.add(p.id);
+        }
+      }
+    }
+    const missing: ToolResultRecord[] = [];
+    for (const [id, name] of callIds) {
+      if (!resultIds.has(id)) {
+        missing.push({
+          id,
+          name,
+          result: `Error: orphan tool_call '${name}' (${id}) without a matching tool result (recovered by ensureToolPairing).`,
+          isError: true,
+          durationMs: 0,
+        });
+      }
+    }
+    if (missing.length > 0) {
+      try { context.addToolResults(missing); } catch {}
+      for (const r of missing) resultIds.add(r.id);
+    }
+    // Drop orphan results (result id never issued by the model).
+    const filtered = context.messages.filter((m: any) => {
+      if (m?.role !== "tool" || !Array.isArray(m.content)) return true;
+      const parts = m.content as Array<any>;
+      const keep = parts.filter((p) => p?.type !== "tool_result" || callIds.has(p.id));
+      if (keep.length === parts.length) return true;
+      if (keep.length === 0) return false;
+      try { (m as any).content = keep; } catch {}
+      return true;
+    });
+    context.messages = filtered as typeof context.messages;
+  } catch {}
+}
 
-  return {
-    inputCost,
-    outputCost,
-    cacheReadCost,
-    cacheWriteCost,
-    totalCost,
-  };
+// ---------------------------------------------------------------------------
+// Q-21/Q-22: abort + limits helpers.
+// ---------------------------------------------------------------------------
+
+export interface LoopLimits {
+  maxTurns?: number;
+  deadlineMs?: number;
+  maxToolCallsPerRun?: number;
+  requestTimeoutMs: number;
+  firstByteTimeoutMs: number;
+  streamIdleTimeoutMs: number;
+}
+
+/** Resolves `(config as any).limits` with Q-22 defaults (timeouts tolerate reasoning). */
+function resolveLoopLimits(config: AgentLoopConfig, fallbackMaxTurns: number): LoopLimits & { maxTurns: number; deadlineMs: number; maxToolCallsPerRun: number } {
+  const raw = ((config as unknown as { limits?: Record<string, unknown> }).limits ?? {}) as Record<string, unknown>;
+  const num = (v: unknown): number | undefined =>
+    typeof v === "number" && Number.isFinite(v) ? v : undefined;
+  let maxTurns = fallbackMaxTurns;
+  const limMax = num(raw.maxTurns);
+  if (limMax !== undefined) {
+    const normLim = normalizeMaxTurns(limMax);
+    maxTurns = Math.min(maxTurns, normLim);
+  }
+  const deadlineMs = num(raw.deadlineMs) ?? Infinity;
+  const maxToolCallsPerRun = num(raw.maxToolCallsPerRun) ?? Infinity;
+  const requestTimeoutMs = num(raw.requestTimeoutMs) ?? 300_000;
+  const firstByteTimeoutMs = num(raw.firstByteTimeoutMs) ?? 120_000;
+  const streamIdleTimeoutMs = num(raw.streamIdleTimeoutMs) ?? 300_000;
+  return { maxTurns, deadlineMs, maxToolCallsPerRun, requestTimeoutMs, firstByteTimeoutMs, streamIdleTimeoutMs };
 }
 
+function loopSessionId(config: AgentLoopConfig): string | undefined {
+  try {
+    return (
+      (config.runOptions as { sessionId?: string } | undefined)?.sessionId ||
+      (config.options as { sessionId?: string } | undefined)?.sessionId ||
+      (config.options as { cache?: { sessionId?: string } } | undefined)?.cache?.sessionId
+    );
+  } catch { return undefined; }
+}
+
+function makeAbortError(
+  partial: { usage: TokenUsage; turns: number; text?: string },
+  reason?: unknown
+): Error {
+  let base: Error;
+  if (reason instanceof Error && reason.name === "AbortError") base = reason;
+  else if (reason instanceof Error) base = new Error(reason.message || "Aborted");
+  else if (typeof reason === "string" && reason) base = new Error(reason);
+  else base = new Error("Aborted");
+  try { (base as { name: string }).name = "AbortError"; } catch {}
+  try { (base as unknown as { partial: unknown }).partial = partial; } catch {}
+  return base;
+}
+
+function throwIfAborted(
+  signal: AbortSignal | undefined,
+  partial: { usage: TokenUsage; turns: number; text?: string }
+): void {
+  if (signal?.aborted) {
+    throw makeAbortError(partial, (signal as unknown as { reason?: unknown })?.reason ?? new Error("Aborted"));
+  }
+}
+
+function checkDeadline(startTime: number, deadlineMs: number): void {
+  if (Number.isFinite(deadlineMs) && deadlineMs !== Infinity && Date.now() - startTime > deadlineMs) {
+    throw new Error(`[Agent Accelerator] Run deadline exceeded after ${deadlineMs}ms.`);
+  }
+}
+
+async function generateWithTimeout<T>(task: () => Promise<T>, timeoutMs: number): Promise<T> {
+  if (!Number.isFinite(timeoutMs) || timeoutMs <= 0 || timeoutMs === Infinity) return task();
+  let timer: ReturnType<typeof setTimeout> | undefined;
+  try {
+    const timeoutP = new Promise<never>((_, reject) => {
+      timer = setTimeout(() => {
+        const e = new Error(`[Agent Accelerator] Request timed out after ${timeoutMs}ms.`);
+        e.name = "TimeoutError";
+        reject(e);
+      }, timeoutMs);
+      try { (timer as unknown as { unref?: () => void }).unref?.(); } catch {}
+    });
+    return await Promise.race([task(), timeoutP]);
+  } finally {
+    if (timer) clearTimeout(timer);
+  }
+}
+
+/** Compat wrapper around the one cost model (`priceUsage` in session/store.ts, Q-36).
+ * Prefers provider-reported totals, else catalog pricing with integer
+ * micro-USD accumulation. Returns undefined when unknown (never a 0 object). */
+export function computeCostFromPricing(usage: TokenUsage, spec?: ModelSpec): TokenUsage["cost"] {
+  try {
+    if (usage.cost && usage.cost.totalCost !== undefined && usage.cost.totalCost > 0) {
+      return usage.cost;
+    }
+    if (!spec) return usage.cost;
+    const priced = priceUsage(usage, spec);
+    return priced
+      ? {
+          inputCost: priced.inputCost,
+          outputCost: priced.outputCost,
+          cacheReadCost: priced.cacheReadCost,
+          cacheWriteCost: priced.cacheWriteCost,
+          totalCost: priced.totalCost,
+        }
+      : usage.cost;
+  } catch {
+    // why: cost is observability-only — pricing failures must never break turns.
+    return usage.cost;
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Q-35: canonical usage accumulation (pure w.r.t. source).
+// Invariants (see assertUsageInvariants in session/store.ts):
+// - token counts are finite integers >= 0;
+// - cachedTokens/cacheReadTokens are a SUBSET of inputTokens (clamped below
+//   so no consumer observes >100% hit rates);
+// - thinkingTokens is a SUBSET of outputTokens when both are reported
+//   (reasoning is generated output; enforced in the test helper, documented
+//   here because providers vary on which side they omit).
+// This function never mutates `source` (Q-35): the priced cost is cloned
+// into a local before folding into the target.
+// ---------------------------------------------------------------------------
 function accumulateUsage(target: TokenUsage, source: TokenUsage, spec?: ModelSpec): void {
   target.inputTokens += source.inputTokens || 0;
   target.outputTokens += source.outputTokens || 0;
@@ -74,14 +347,25 @@ function accumulateUsage(target: TokenUsage, source: TokenUsage, spec?: ModelSpe
   // input. Some providers occasionally report cached > input on long chained
   // runs, which surfaces as >100% hit rates downstream. Clamp the aggregate
   // so no consumer can observe an impossible ratio.
-  target.cachedTokens = Math.min(target.cachedTokens ?? 0, target.inputTokens);
-  target.cacheReadTokens = Math.min(target.cacheReadTokens ?? 0, target.inputTokens);
-
-  const sourceCost = computeCostFromPricing(source, spec);
-  if (sourceCost) {
-    source.cost = sourceCost;
+  const preCached = target.cachedTokens ?? 0;
+  const preRead = target.cacheReadTokens ?? 0;
+  target.cachedTokens = Math.min(preCached, target.inputTokens);
+  target.cacheReadTokens = Math.min(preRead, target.inputTokens);
+  if ((target.cachedTokens ?? 0) < preCached || (target.cacheReadTokens ?? 0) < preRead) {
+    // Q-35: no console — report via the anomaly hook + telemetry bus.
+    reportUsageAnomaly({
+      type: "cache_clamp",
+      inputTokens: target.inputTokens,
+      cachedTokens: preCached,
+      cacheReadTokens: preRead,
+    });
   }
 
+  const priced = computeCostFromPricing(source, spec);
+  // Q-35: pure — read `source` only; never assign back to `source.cost`.
+  // Clone the priced cost so later target folds cannot alias source state.
+  const sourceCost = priced ? { ...priced } : undefined;
+
   if (sourceCost || target.cost) {
     target.cost = {
       inputCost: (target.cost?.inputCost ?? 0) + (sourceCost?.inputCost ?? 0),
@@ -131,6 +415,7 @@ async function executeToolCallsWithRepeatGuard(options: {
   agentName?: string;
   signal?: AbortSignal;
   sessionId?: string;
+  onSubagentEvent?: (event: { trackingId: string; delta?: string; thinkingDelta?: string; partialText?: string; partialThinking?: string }) => void;
 }): Promise<{ results: ToolResultRecord[]; fingerprints: Set<string> }> {
   const { toolCalls, previousFingerprints } = options;
   const currentFingerprints = new Set<string>();
@@ -163,6 +448,7 @@ async function executeToolCallsWithRepeatGuard(options: {
         parallel: true,
         signal: options.signal,
         sessionId: options.sessionId,
+        onSubagentEvent: options.onSubagentEvent,
       })
     : [];
   const byId = new Map<string, ToolResultRecord[]>();
@@ -202,21 +488,19 @@ export async function runAgentLoop(config: AgentLoopConfig): Promise<AgentRespon
     tools,
     options,
     runOptions,
-    maxTurns = 10,
+    maxTurns: rawMaxTurns = Infinity,
   } = config;
+  const fallbackMaxTurns = normalizeMaxTurns(rawMaxTurns);
+  const limits = resolveLoopLimits(config, fallbackMaxTurns);
+  const maxTurns = limits.maxTurns;
+  // Q-19: pre-run checkpoint for onFailure rollback.
+  const preRunCp = context.checkpoint();
+  const sessionIdForRollback = loopSessionId(config);
 
-  if (config.bypassInputFileModality) {
-    await preprocessFilePartsForBypass(config.context.messages, {
-      providerId: provider.id,
-      modelId,
-      signal: runOptions?.signal,
-    });
-  }
-
-  const standardTools = toStandardToolDeclarations(tools);
+  // Q-37: partial-run state hoisted outside try so the catch block can attach
+  // {usage,cost,turns,toolCalls,toolResults,text} to ANY thrown error.
   const startTime = Date.now();
-
-  let accumulatedUsage: TokenUsage = {
+  const accumulatedUsage: TokenUsage = {
     inputTokens: 0,
     outputTokens: 0,
     totalTokens: 0,
@@ -225,7 +509,6 @@ export async function runAgentLoop(config: AgentLoopConfig): Promise<AgentRespon
     cacheWriteTokens: 0,
     thinkingTokens: 0,
   };
-
   const allToolCalls: ToolCallRecord[] = [];
   const allToolResults: ToolResultRecord[] = [];
   const allSubagents: SubAgentExecutionMetadata[] = [];
@@ -233,7 +516,23 @@ export async function runAgentLoop(config: AgentLoopConfig): Promise<AgentRespon
   let turns = 0;
   let previousToolCallFingerprints = new Set<string>();
 
+  try {
+  if (config.bypassInputFileModality) {
+    await preprocessFilePartsForBypass(config.context.messages, {
+      providerId: provider.id,
+      modelId,
+      signal: runOptions?.signal,
+    });
+  }
+
+  const standardTools = toStandardToolDeclarations(tools);
+
   while (turns < maxTurns) {
+    // Q-21: fail fast on abort (throws AbortError with partial).
+    throwIfAborted(runOptions?.signal, { usage: accumulatedUsage, turns, text: finalResult?.text });
+    checkDeadline(startTime, limits.deadlineMs);
+    // Q-19: repair orphan tool pairs before every request.
+    ensureToolPairing(context);
     turns++;
 
     const spec = getModelFromCatalog(provider.id, modelId);
@@ -246,15 +545,33 @@ export async function runAgentLoop(config: AgentLoopConfig): Promise<AgentRespon
       tools: standardTools.length > 0 ? standardTools : undefined,
       signal: runOptions?.signal,
     };
+    // Q-22: per-request timeout pass-through (providers honor timeoutMs).
+    try {
+      if (Number.isFinite(limits.requestTimeoutMs) && limits.requestTimeoutMs !== Infinity) {
+        (providerOptions as unknown as { timeoutMs?: number }).timeoutMs = limits.requestTimeoutMs;
+      }
+    } catch {}
+    // Q-25-partial: google:{store:false} opt-out pass-through (provider
+    // already respects body.store===false for chaining).
+    try {
+      const gStore =
+        (runOptions as unknown as { googleStore?: unknown } | undefined)?.googleStore ??
+        (options as unknown as { googleStore?: unknown } | undefined)?.googleStore ??
+        (config as unknown as { googleStore?: unknown }).googleStore;
+      if (gStore === false) (providerOptions as unknown as { store?: boolean }).store = false;
+    } catch {}
 
-    const genResult = await provider.generate(
-      modelId,
-      {
-        systemPrompt: context.systemPrompt,
-        messages: context.messages,
-        cachedContentId: context.cachedContentId,
-      },
-      providerOptions
+    const genResult = await generateWithTimeout(
+      () => provider.generate(
+        modelId,
+        {
+          systemPrompt: context.systemPrompt,
+          messages: context.messages,
+          cachedContentId: context.cachedContentId,
+        },
+        providerOptions
+      ),
+      limits.requestTimeoutMs
     );
 
     finalResult = genResult;
@@ -265,15 +582,20 @@ export async function runAgentLoop(config: AgentLoopConfig): Promise<AgentRespon
       provider.id
     );
 
-    // Safety fallback: if no tool calls and text is empty, rescue answer from thinking
+    // Thinking is exposed via events/traces and onTurn (see shouldExposeThinking,
+    // default true). Promoting thinking to answer text is gated (Q-15, default
+    // OFF): without the explicit opt-in the run returns the provider's empty
+    // text with its finishReason instead of fabricating an answer from reasoning.
     if ((!genResult.text || genResult.text.trim() === "") && (!genResult.toolCalls || genResult.toolCalls.length === 0) && genResult.thinking) {
-      if (genResult.thinking.includes("</think>")) {
-        const parts = genResult.thinking.split(/<\/(?:think|thought)>/i);
-        genResult.thinking = parts[0]!.replace(/<(?:think|thought)>/i, "").trim() || undefined;
-        genResult.text = parts.slice(1).join("").trim();
-      } else {
-        genResult.text = genResult.thinking;
-        genResult.thinking = undefined;
+      if (shouldPromoteThinkingToAnswer(config, runOptions)) {
+        if (genResult.thinking.includes("</think>")) {
+          const parts = genResult.thinking.split(/<\/(?:think|thought)>/i);
+          genResult.thinking = parts[0]!.replace(/<(?:think|thought)>/i, "").trim() || undefined;
+          genResult.text = parts.slice(1).join("").trim();
+        } else {
+          genResult.text = genResult.thinking;
+          genResult.thinking = undefined;
+        }
       }
     }
 
@@ -287,13 +609,42 @@ export async function runAgentLoop(config: AgentLoopConfig): Promise<AgentRespon
       genResult.thoughtSignature
     );
 
-    // If no tool calls, generation is complete!
+    // Mid-session steer: if new queries arrived during this provider turn,
+    // inject them now. Tool turns still execute first (see below) so the
+    // current action finishes before redirection.
+    const noToolSteered = (!genResult.toolCalls || genResult.toolCalls.length === 0)
+      ? drainSteerInbox(context, config.steerInbox)
+      : [];
+
+    // If no tool calls, generation is complete — unless steered, in which
+    // case the injected message extends the SAME run (no new response).
     if (!genResult.toolCalls || genResult.toolCalls.length === 0) {
+      emitTurn(runOptions, { turns, text: genResult.text, thinking: genResult.thinking });
+      if (noToolSteered.length > 0) {
+        try { config.onSteerInjected?.(noToolSteered); } catch {}
+        if (config.bypassInputFileModality) {
+          await preprocessFilePartsForBypass(config.context.messages, {
+            providerId: provider.id,
+            modelId,
+            signal: runOptions?.signal,
+          });
+        }
+      }
+      emitProgress(config);
+      if (noToolSteered.length > 0) continue;
       break;
     }
 
     // Execute tool calls — always parallel (model-driven, bloatfree DX7)
+    // Q-21: check abort before tools (throws AbortError with partial).
+    throwIfAborted(runOptions?.signal, { usage: accumulatedUsage, turns, text: genResult.text });
     allToolCalls.push(...genResult.toolCalls);
+    // Q-22: per-run tool-call budget.
+    if (allToolCalls.length > limits.maxToolCallsPerRun) {
+      throw new Error(
+        `[Agent Accelerator] maxToolCallsPerRun exceeded (${allToolCalls.length} > ${limits.maxToolCallsPerRun}).`
+      );
+    }
     const guarded = await executeToolCallsWithRepeatGuard({
       tools,
       toolCalls: genResult.toolCalls,
@@ -325,8 +676,48 @@ export async function runAgentLoop(config: AgentLoopConfig): Promise<AgentRespon
 
     allToolResults.push(...sanitizedResults);
     context.addToolResults(sanitizedResults);
+    // Q-19: results are stored BEFORE the cancellation check so an abort
+    // never drops executed tool work from history.
+    throwIfAborted(runOptions?.signal, { usage: accumulatedUsage, turns, text: genResult.text });
+    emitTurn(runOptions, {
+      turns,
+      text: genResult.text,
+      thinking: genResult.thinking,
+      toolCalls: genResult.toolCalls,
+      toolResults: sanitizedResults,
+    });
+    // Steer drain AFTER tool results so call/result pairs stay adjacent.
+    // The next loop iteration sends the injected user message to the model
+    // within the same run (same usage/turn budget).
+    const toolSteered = drainSteerInbox(context, config.steerInbox);
+    if (toolSteered.length > 0) {
+      try { config.onSteerInjected?.(toolSteered); } catch {}
+      if (config.bypassInputFileModality) {
+        await preprocessFilePartsForBypass(config.context.messages, {
+          providerId: provider.id,
+          modelId,
+          signal: runOptions?.signal,
+        });
+      }
+    }
+    emitProgress(config);
+
+    // Q-21: abort always throws AbortError with partial attached (never
+    // silently breaks).
+    throwIfAborted(runOptions?.signal, { usage: accumulatedUsage, turns, text: finalResult?.text });
+  }
 
-    if (runOptions?.signal?.aborted) break;
+  // maxTurns exhausted while the model still requested tools: the tool
+  // results above were never sent back, so the run is truncated — surface
+  // it via finishReason + warning instead of silently returning.
+  const truncatedByMaxTurns =
+    turns >= maxTurns && !!finalResult?.toolCalls && finalResult.toolCalls.length > 0;
+  if (truncatedByMaxTurns) {
+    warnMaxTurnsHit(
+      agentName,
+      maxTurns,
+      finalResult.toolCalls.map((c: ToolCallRecord) => c.name)
+    );
   }
 
   return new AgentResponse({
@@ -340,11 +731,47 @@ export async function runAgentLoop(config: AgentLoopConfig): Promise<AgentRespon
     responseId: finalResult?.responseId,
     model: modelId,
     provider: provider.id,
-    finishReason: finalResult?.finishReason,
+    // Q-04: canonical finish reason + raw vendor passthrough.
+    ...canonicalFinishReason(finalResult?.finishReason, truncatedByMaxTurns),
     durationMs: Date.now() - startTime,
     raw: finalResult?.raw,
     turns,
   });
+  } catch (err) {
+    // Q-19: run-level onFailure rollback (default restores pre-run
+    // checkpoint; opt out with (config as any).onFailure === "keep").
+    // Aborts are excluded so partial history survives interruption.
+    const onFailure = (config as unknown as { onFailure?: unknown }).onFailure;
+    const isAbort =
+      (err as { name?: string } | null)?.name === "AbortError" ||
+      !!runOptions?.signal?.aborted;
+    if (onFailure !== "keep" && !isAbort) {
+      try { context.rollback(preRunCp, sessionIdForRollback); } catch {
+        // why: rollback is best-effort — the original error takes precedence.
+      }
+    }
+    // Q-21: ensure aborts surface as AbortError with partial attached.
+    if (isAbort && (err as { name?: string } | null)?.name !== "AbortError") {
+      throw makeAbortError(
+        { usage: { inputTokens: 0, outputTokens: 0, totalTokens: 0 }, turns: 0 },
+        err
+      );
+    }
+    // Q-37: every failure carries its partial progress for observability.
+    try {
+      (err as unknown as { partial?: unknown }).partial ??= {
+        usage: accumulatedUsage,
+        cost: accumulatedUsage.cost,
+        turns,
+        toolCalls: allToolCalls,
+        toolResults: allToolResults,
+        text: finalResult?.text,
+      };
+    } catch {
+      // why: partial attachment is observability-only and must never mask the error.
+    }
+    throw err;
+  }
 }
 
 /**
@@ -372,12 +799,40 @@ export function streamAgentLoop(config: AgentLoopConfig): AssistantMessageEventS
   linked.signal.addEventListener("abort", () => {
     try { currentInner?.cancel(); } catch {}
   });
-  const throwIfCancelled = () => {
-    if (linked.signal.aborted || outerStream.isCancelled())
-      throw Object.assign(new Error("Stream aborted"), { name: "AbortError" });
+  const throwIfCancelled = (partial?: { usage: TokenUsage; turns: number; text?: string }) => {
+    if (linked.signal.aborted || outerStream.isCancelled()) {
+      const fallback: TokenUsage = { inputTokens: 0, outputTokens: 0, totalTokens: 0 };
+      throw makeAbortError(
+        partial ?? { usage: fallback, turns: 0 },
+        (linked.signal as unknown as { reason?: unknown })?.reason ?? new Error("Stream aborted")
+      );
+    }
   };
 
+  // Q-19/Q-22: per-run checkpoint + limits for the streaming loop.
+  const streamPreCp = config.context.checkpoint();
+  const streamSessionId = loopSessionId(config);
+  const streamFallbackMax = normalizeMaxTurns((config as { maxTurns?: number }).maxTurns);
+  const streamLimits = resolveLoopLimits(config, streamFallbackMax);
+  const streamStartTime = startTime;
+
   (async () => {
+    // Hoisted for catch-block partial reporting (Q-21/Q-37).
+    let accumulatedUsage: TokenUsage = {
+      inputTokens: 0,
+      outputTokens: 0,
+      totalTokens: 0,
+      cachedTokens: 0,
+      cacheReadTokens: 0,
+      cacheWriteTokens: 0,
+      thinkingTokens: 0,
+    };
+    let lastResponse: AgentResponse | null = null;
+    let turns = 0;
+    // Q-37: tool progress hoisted so failures carry toolCalls/toolResults.
+    const allToolCalls: ToolCallRecord[] = [];
+    const allToolResults: ToolResultRecord[] = [];
+    const allSubagents: SubAgentExecutionMetadata[] = [];
     try {
       await ensureModelCatalogFresh();
       // Re-validate after refresh: Agent.stream() validates before the catalog
@@ -409,12 +864,13 @@ export function streamAgentLoop(config: AgentLoopConfig): AssistantMessageEventS
         tools,
         options,
         runOptions,
-        maxTurns = 10,
+        maxTurns: rawMaxTurns = Infinity,
       } = config;
+      const maxTurns = streamLimits.maxTurns;
 
       const standardTools = toStandardToolDeclarations(tools);
 
-      let accumulatedUsage: TokenUsage = {
+      accumulatedUsage = {
         inputTokens: 0,
         outputTokens: 0,
         totalTokens: 0,
@@ -424,15 +880,16 @@ export function streamAgentLoop(config: AgentLoopConfig): AssistantMessageEventS
         thinkingTokens: 0,
       };
 
-      const allToolCalls: ToolCallRecord[] = [];
-      const allToolResults: ToolResultRecord[] = [];
-      const allSubagents: SubAgentExecutionMetadata[] = [];
-      let lastResponse: AgentResponse | null = null;
-      let turns = 0;
+      // Q-37: allToolCalls/allToolResults/allSubagents are hoisted above (fresh
+      // per stream run); just reset turn counters here.
+      lastResponse = null;
+      turns = 0;
       let previousToolCallFingerprints = new Set<string>();
 
       while (turns < maxTurns) {
-        throwIfCancelled();
+        throwIfCancelled({ usage: accumulatedUsage, turns, text: lastResponse?.text });
+        checkDeadline(streamStartTime, streamLimits.deadlineMs);
+        ensureToolPairing(context);
         turns++;
 
         const spec2 = getModelFromCatalog(provider.id, modelId);
@@ -444,6 +901,18 @@ export function streamAgentLoop(config: AgentLoopConfig): AssistantMessageEventS
           tools: standardTools.length > 0 ? standardTools : undefined,
           signal: linked.signal,
         };
+        try {
+          if (Number.isFinite(streamLimits.requestTimeoutMs) && streamLimits.requestTimeoutMs !== Infinity) {
+            (providerOptions as unknown as { timeoutMs?: number }).timeoutMs = streamLimits.requestTimeoutMs;
+          }
+        } catch {}
+        try {
+          const gStore =
+            (runOptions as unknown as { googleStore?: unknown } | undefined)?.googleStore ??
+            (options as unknown as { googleStore?: unknown } | undefined)?.googleStore ??
+            (config as unknown as { googleStore?: unknown }).googleStore;
+          if (gStore === false) (providerOptions as unknown as { store?: boolean }).store = false;
+        } catch {}
 
         const innerStream = provider.stream(
           modelId,
@@ -456,16 +925,54 @@ export function streamAgentLoop(config: AgentLoopConfig): AssistantMessageEventS
         );
         currentInner = innerStream as AssistantMessageEventStream;
 
-        for await (const event of innerStream) {
-          throwIfCancelled();
-          if (event.type !== "done") {
-            outerStream.push(event);
+        // Q-22: first-byte + idle timeouts around SSE (tolerate reasoning).
+        // Implemented as races on the inner iterator so a hung provider
+        // surfaces as TimeoutError instead of hanging the run forever.
+        {
+          const it = (innerStream as AsyncIterable<StreamEvent>)[Symbol.asyncIterator]();
+          let first = true;
+          let doneIter = false;
+          while (!doneIter) {
+            const waitMs = first ? streamLimits.firstByteTimeoutMs : streamLimits.streamIdleTimeoutMs;
+            let timer: ReturnType<typeof setTimeout> | undefined;
+            const timeoutP =
+              Number.isFinite(waitMs) && waitMs !== Infinity && waitMs > 0
+                ? new Promise<never>((_, reject) => {
+                    timer = setTimeout(() => {
+                      const e = new Error(
+                        `[Agent Accelerator] Stream ${first ? "first-byte" : "idle"} timed out after ${waitMs}ms.`
+                      );
+                      e.name = "TimeoutError";
+                      reject(e);
+                    }, waitMs);
+                    try { (timer as unknown as { unref?: () => void }).unref?.(); } catch {}
+                  })
+                : null;
+            try {
+              const nextP = it.next();
+              const res = timeoutP ? await Promise.race([nextP, timeoutP]) : await nextP;
+              if (timer) clearTimeout(timer);
+              if (res.done) { doneIter = true; break; }
+              first = false;
+              throwIfCancelled({ usage: accumulatedUsage, turns, text: lastResponse?.text });
+              const event = res.value as StreamEvent;
+              if ((event as StreamEvent)?.type !== "done") {
+                outerStream.push(event);
+              }
+            } catch (e) {
+              if (timer) clearTimeout(timer);
+              // Timeout: cancel the hung inner stream before surfacing.
+              if ((e as Error)?.name === "TimeoutError") {
+                try { currentInner?.cancel(); } catch {}
+              }
+              throw e;
+            }
           }
         }
 
         const turnResponse = await innerStream.result();
         currentInner = null;
-        throwIfCancelled();
+        throwIfCancelled({ usage: accumulatedUsage, turns, text: (turnResponse as { text?: string })?.text });
         lastResponse = turnResponse;
         // Canonical session routing: lets adapters detect provider switches.
         noteProviderTurn(
@@ -473,15 +980,19 @@ export function streamAgentLoop(config: AgentLoopConfig): AssistantMessageEventS
           provider.id
         );
 
-        // Safety fallback: if no tool calls and text is empty, rescue answer from thinking
+        // Thinking stays on events/traces + onTurn (default exposed). Promoting
+        // it to answer text is gated (Q-15, default OFF): without the opt-in
+        // the turn keeps the provider's empty text and finishReason.
         if ((!turnResponse.text || turnResponse.text.trim() === "") && (!turnResponse.toolCalls || turnResponse.toolCalls.length === 0) && turnResponse.thinking) {
-          if (turnResponse.thinking.includes("</think>")) {
-            const parts = turnResponse.thinking.split(/<\/(?:think|thought)>/i);
-            (turnResponse as any).thinking = parts[0]!.replace(/<(?:think|thought)>/i, "").trim() || undefined;
-            (turnResponse as any).text = parts.slice(1).join("").trim();
-          } else {
-            (turnResponse as any).text = turnResponse.thinking;
-            (turnResponse as any).thinking = undefined;
+          if (shouldPromoteThinkingToAnswer(config, runOptions)) {
+            if (turnResponse.thinking.includes("</think>")) {
+              const parts = turnResponse.thinking.split(/<\/(?:think|thought)>/i);
+              (turnResponse as any).thinking = parts[0]!.replace(/<(?:think|thought)>/i, "").trim() || undefined;
+              (turnResponse as any).text = parts.slice(1).join("").trim();
+            } else {
+              (turnResponse as any).text = turnResponse.thinking;
+              (turnResponse as any).thinking = undefined;
+            }
           }
         }
 
@@ -494,11 +1005,41 @@ export function streamAgentLoop(config: AgentLoopConfig): AssistantMessageEventS
           turnResponse.thoughtSignature
         );
 
+        const noToolSteered = (!turnResponse.toolCalls || turnResponse.toolCalls.length === 0)
+          ? drainSteerInbox(context, config.steerInbox)
+          : [];
         if (!turnResponse.toolCalls || turnResponse.toolCalls.length === 0) {
+          emitTurn(runOptions, { turns, text: turnResponse.text, thinking: turnResponse.thinking });
+          if (noToolSteered.length > 0) {
+            for (const preview of noToolSteered) {
+              try {
+                outerStream.push({ type: "steer_injected", injectedPrompt: preview });
+              } catch {
+                // why: stream push never throws, but guard anyway to protect the loop.
+              }
+            }
+            try { config.onSteerInjected?.(noToolSteered); } catch {
+              // why: user callback — a throw must not fail the run.
+            }
+          }
+          emitProgress(config);
+          if (noToolSteered.length > 0) continue;
           break;
         }
 
+        throwIfCancelled({ usage: accumulatedUsage, turns, text: turnResponse.text });
         allToolCalls.push(...turnResponse.toolCalls);
+        if (allToolCalls.length > streamLimits.maxToolCallsPerRun) {
+          throw new Error(
+            `[Agent Accelerator] maxToolCallsPerRun exceeded (${allToolCalls.length} > ${streamLimits.maxToolCallsPerRun}).`
+          );
+        }
+        // Q-40: typed tool lifecycle for streaming consumers.
+        try {
+          outerStream.push({ type: "tool_start", toolCalls: turnResponse.toolCalls });
+        } catch {
+          // why: stream push never throws, but guard anyway to protect the loop.
+        }
         const guarded = await executeToolCallsWithRepeatGuard({
           tools,
           toolCalls: turnResponse.toolCalls,
@@ -506,8 +1047,21 @@ export function streamAgentLoop(config: AgentLoopConfig): AssistantMessageEventS
           agentName,
           signal: linked.signal,
           sessionId: runOptions?.sessionId || options?.sessionId || options?.cache?.sessionId,
+          onSubagentEvent: (ev) => {
+            try {
+              outerStream.push({
+                type: "subagent_delta",
+                subagentTrackingId: ev.trackingId,
+                delta: ev.delta,
+                thinkingDelta: ev.thinkingDelta,
+                partialText: ev.partialText,
+                partialThinking: ev.partialThinking,
+              });
+            } catch {
+              // why: stream push never throws; keep subagent progress flowing.
+            }
+          },
         });
-        throwIfCancelled();
         const results = guarded.results;
         previousToolCallFingerprints = guarded.fingerprints;
 
@@ -538,11 +1092,51 @@ export function streamAgentLoop(config: AgentLoopConfig): AssistantMessageEventS
             toolResult: res,
           });
         }
+        // Q-40: close the tool lifecycle opened by `tool_start` above.
+        try {
+          outerStream.push({ type: "tool_end", toolResults: sanitizedResults });
+        } catch {
+          // why: stream push never throws, but guard anyway to protect the loop.
+        }
 
+        // Q-19: store tool results BEFORE the cancellation check.
         allToolResults.push(...sanitizedResults);
         context.addToolResults(sanitizedResults);
+        throwIfCancelled({ usage: accumulatedUsage, turns, text: turnResponse.text });
+        emitTurn(runOptions, {
+          turns,
+          text: turnResponse.text,
+          thinking: turnResponse.thinking,
+          toolCalls: turnResponse.toolCalls,
+          toolResults: sanitizedResults,
+        });
+        const toolSteered = drainSteerInbox(context, config.steerInbox);
+        if (toolSteered.length > 0) {
+          for (const preview of toolSteered) {
+            try {
+              outerStream.push({ type: "steer_injected", injectedPrompt: preview });
+            } catch {
+              // why: stream push never throws, but guard anyway to protect the loop.
+            }
+          }
+          try { config.onSteerInjected?.(toolSteered); } catch {
+            // why: user callback — a throw must not fail the run.
+          }
+        }
+        emitProgress(config);
       }
 
+      const truncatedByMaxTurns =
+        turns >= maxTurns && !!lastResponse?.toolCalls && lastResponse.toolCalls.length > 0;
+      if (truncatedByMaxTurns) {
+        warnMaxTurnsHit(
+          agentName,
+          maxTurns,
+          lastResponse!.toolCalls.map((c) => c.name)
+        );
+      }
+      const truncatedFinish = canonicalFinishReason(lastResponse?.finishReason, truncatedByMaxTurns);
+
       const finalAgentResponse = new AgentResponse({
         text: lastResponse?.text || "",
         thinking: lastResponse?.thinking,
@@ -554,7 +1148,8 @@ export function streamAgentLoop(config: AgentLoopConfig): AssistantMessageEventS
         responseId: lastResponse?.responseId,
         model: modelId,
         provider: provider.id,
-        finishReason: lastResponse?.finishReason,
+        // Q-04: canonical finish reason + raw vendor passthrough.
+        ...truncatedFinish,
         durationMs: Date.now() - startTime,
         raw: lastResponse?.raw as any,
         turns,
@@ -564,7 +1159,8 @@ export function streamAgentLoop(config: AgentLoopConfig): AssistantMessageEventS
         type: "done",
         delta: "",
         usage: accumulatedUsage,
-        finishReason: lastResponse?.finishReason,
+        finishReason: truncatedFinish.finishReason ?? lastResponse?.finishReason,
+        rawFinishReason: truncatedFinish.rawFinishReason,
         responseId: lastResponse?.responseId,
       });
 
@@ -576,17 +1172,130 @@ export function streamAgentLoop(config: AgentLoopConfig): AssistantMessageEventS
         outerStream.isCancelled() ||
         (raw as any)?.name === "AbortError" ||
         /abort|cancell?ed/i.test(String((raw as any)?.message ?? raw));
-      outerStream.fail(
-        isAbort
-          ? Object.assign(raw.name === "AbortError" ? raw : new Error("Stream aborted"), { name: "AbortError" })
-          : raw
-      );
+      // Q-19: streaming onFailure rollback (same policy as runAgentLoop;
+      // aborts excluded so partial history survives).
+      try {
+        const onFailure = (config as unknown as { onFailure?: unknown }).onFailure;
+        if (onFailure !== "keep" && !isAbort) {
+          try { config.context.rollback(streamPreCp, streamSessionId); } catch {
+            // why: rollback is best-effort — the original error takes precedence.
+          }
+        }
+      } catch {
+        // why: rollback policy itself must never mask the original error.
+      }
+      // Q-37: every failure carries its partial progress for observability.
+      const partial = {
+        usage: accumulatedUsage,
+        cost: accumulatedUsage.cost,
+        turns,
+        toolCalls: allToolCalls,
+        toolResults: allToolResults,
+        text: lastResponse?.text,
+      };
+      // Q-21: aborts always surface as AbortError with partial attached.
+      if (isAbort) {
+        const abortErr =
+          raw.name === "AbortError" ? raw : makeAbortError(partial, raw);
+        try { (abortErr as unknown as { partial?: unknown }).partial ??= partial; } catch {
+          // why: partial attachment is observability-only and must never mask the error.
+        }
+        outerStream.fail(abortErr);
+      } else {
+        try { (raw as unknown as { partial?: unknown }).partial ??= partial; } catch {
+          // why: partial attachment is observability-only and must never mask the error.
+        }
+        outerStream.fail(raw);
+      }
     } finally {
-      try { currentInner?.cancel(); } catch {}
-      try { userSignal?.removeEventListener("abort", forwardUserAbort); } catch {}
-      try { removeOuterCancel(); } catch {}
+      try { currentInner?.cancel(); } catch {
+        // why: inner streams tolerate double-cancel; cleanup must not throw.
+      }
+      try { userSignal?.removeEventListener("abort", forwardUserAbort); } catch {
+        // why: listener removal is best-effort cleanup.
+      }
+      try { removeOuterCancel(); } catch {
+        // why: unsubscribe is best-effort cleanup.
+      }
     }
   })();
 
   return outerStream;
 }
+
+// ---------------------------------------------------------------------------
+// Q-15: single thinking-exposure policy + Q-04 canonical finish helper.
+// (Appended here to avoid conflicts with other loop sections.)
+// ---------------------------------------------------------------------------
+
+/**
+ * Single expose-thinking policy (Q-15).
+ * - Events/traces/onTurn always carry thinking separately (default true).
+ * - Promoting thinking to answer *text* is a separate opt-in
+ *   (`thinkingAsAnswerFallback`, default false) — see
+ *   `shouldPromoteThinkingToAnswer`.
+ *
+ * Reads `exposeThinking` from the loop config, run options, or provider
+ * options; any explicit `false` hides thinking from events/traces.
+ */
+export function shouldExposeThinking(config?: unknown): boolean {
+  try {
+    const c = config as {
+      exposeThinking?: unknown;
+      runOptions?: { exposeThinking?: unknown };
+      options?: { exposeThinking?: unknown };
+    } | null | undefined;
+    const v = c?.exposeThinking ?? c?.runOptions?.exposeThinking ?? c?.options?.exposeThinking;
+    if (v === undefined) return true;
+    return Boolean(v);
+  } catch {
+    // why: policy lookup is best-effort — default to exposing thinking.
+    return true;
+  }
+}
+
+/**
+ * Whether an empty-text turn may promote `thinking` to answer `text` (Q-15).
+ * Default false: the run returns the provider's empty text with its
+ * finishReason instead of fabricating an answer from reasoning. Opt in via
+ * `(runOptions as any).thinkingAsAnswerFallback === true` or
+ * `(config as any).thinkingAsAnswerFallback === true`.
+ */
+export function shouldPromoteThinkingToAnswer(config?: unknown, runOptions?: unknown): boolean {
+  try {
+    if ((runOptions as { thinkingAsAnswerFallback?: unknown } | null | undefined)?.thinkingAsAnswerFallback === true) {
+      return true;
+    }
+    const c = config as {
+      thinkingAsAnswerFallback?: unknown;
+      runOptions?: { thinkingAsAnswerFallback?: unknown };
+    } | null | undefined;
+    if (c?.thinkingAsAnswerFallback === true) return true;
+    if (c?.runOptions?.thinkingAsAnswerFallback === true) return true;
+    return false;
+  } catch {
+    // why: policy lookup is best-effort — default to NOT promoting thinking.
+    return false;
+  }
+}
+
+/**
+ * Canonicalizes a provider finish reason for AgentResponse (Q-04).
+ * When `truncated` (maxTurns exhausted with pending tools), forces
+ * `"max_turns"` and preserves the provider's reason in `rawFinishReason`.
+ * Otherwise delegates to `normalizeFinishReason` (unknown vendor strings map
+ * to `"error"` with the original in `rawFinishReason`).
+ */
+export function canonicalFinishReason(
+  providerReason: unknown,
+  truncated: boolean
+): { finishReason?: FinishReason; rawFinishReason?: string } {
+  if (truncated) {
+    if (typeof providerReason === "string" && providerReason && providerReason !== "max_turns") {
+      return { finishReason: "max_turns", rawFinishReason: providerReason };
+    }
+    return { finishReason: "max_turns" };
+  }
+  if (typeof providerReason !== "string" || providerReason === "") return {};
+  return normalizeFinishReason(providerReason);
+}