bazis 0.138.0 → 0.140.0

package/core/agent/internal/AgentExecutionDriver.ts

@@ -4,13 +4,15 @@ import type { ServiceProvider } from "../../di";
 import { getGeneratedOpenApiMetadata } from "../../http/OpenApi/generatedOpenApiRegistry";
 import { redactSensitive, redactSensitiveText } from "../../../library/redaction";
 import type { Logger } from "../../kernel/logging/Logger";
-import { AgentModelTimeoutError, AgentRuntimeError } from "../errors";
+import { AgentModelContextOverflowError, AgentModelTimeoutError, AgentModelUnavailableError, AgentRuntimeError } from "../errors";
 import { validateAgentJsonSchema } from "./AgentJsonSchema";
 import type { AgentDefinition, AgentRegistry } from "../AgentRegistry";
 import {
+  ApproximateAgentContextTokenEstimator,
   DefaultAgentContextBuilder,
   mergeAgentContextLimits,
   normalizeAgentContextLimits,
+  type AgentContext,
   type AgentContextBuilder,
   type AgentContextLimits,
 } from "../AgentContextBuilder";
@@ -46,13 +48,74 @@ import {
   type AgentToolError,
   type AgentToolContract,
   type AgentToolResult,
+  type AgentUsage,
   type JsonObject,
   type JsonValue,
 } from "../semantic";
 
-const DEFAULT_MAX_STEPS = 8;
+const DEFAULT_MAX_STEPS = 30;
 const DEFAULT_MAX_TOOL_CALLS_PER_STEP = 16;
 const DEFAULT_MODEL_TIMEOUT_MS = 60_000;
+const DEFAULT_MODEL_ATTEMPTS = 3;
+const DEFAULT_MODEL_RETRY_DELAY_MS = 500;
+const DEFAULT_MODEL_RETRY_MAX_DELAY_MS = 20_000;
+const DEFAULT_MAX_OUTPUT_CONTINUATIONS = 3;
+const DEFAULT_MAX_OUTPUT_REPAIRS = 2;
+const DEFAULT_MAX_PARALLEL_TOOL_CALLS = 8;
+
+/** `message.metadata.runtime` of the messages the runtime writes itself. */
+const RUNTIME_CONTINUE = "continue-output";
+const RUNTIME_REPAIR = "repair-output";
+const CONTINUE_TEXT = "Your previous message was cut off by the output limit. Continue exactly where it stopped: do not repeat, apologize or summarize what is already written.";
+
+/** How a model request that the provider could not serve right now is repeated. */
+export interface AgentModelRetryPolicy {
+  /** How many times one model request is sent, the first one included. 3 by default; 1 turns repeats off. */
+  readonly maxAttempts?: number;
+  /** The wait before the second attempt, doubled before each next one. 500 ms by default. */
+  readonly delayMs?: number;
+  /** The longest single wait, a provider's `Retry-After` included. 20 seconds by default. */
+  readonly maxDelayMs?: number;
+}
+
+/** `message.metadata.runtime` of the message that stands for the compacted part of a dialog. */
+const RUNTIME_SUMMARY = "summary";
+/** Compaction starts at this share of the model's context window, leaving room for the answer. */
+const COMPACTION_WINDOW_SHARE = 0.8;
+const SUMMARY_PREFIX = "Summary of the earlier part of this conversation (the original messages were replaced by it):";
+const SUMMARY_INSTRUCTIONS = [
+  "You summarize a conversation between a user and an AI assistant that uses tools, so that the assistant can continue the work without the original messages.",
+  "Keep everything needed to continue:",
+  "1. What the user asked for and wants: every request, in the user's own words where the wording matters.",
+  "2. Facts, names, identifiers, numbers and results obtained from tools that may be needed later.",
+  "3. What has been done and decided, and why.",
+  "4. What is in progress and what remains to be done.",
+  "5. Constraints, preferences and corrections the user gave.",
+  "Write plainly, in the language of the conversation. Do not invent anything, do not address the user, do not call tools. Output only the summary.",
+].join("\n");
+
+/** When and how the older part of a long dialog is replaced by a summary. */
+export interface AgentCompactionOptions {
+  /**
+   * The dialog size, in tokens, above which the older part is summarized.
+   * By default 80% of the model's context window, when the LLM connector
+   * states it (`contextTokens`); without both, only a provider's refusal of a
+   * request as too long starts compaction.
+   */
+  readonly maxTokens?: number;
+  /** How much of the newest dialog stays as written, in tokens. A quarter of `maxTokens` by default. */
+  readonly keepTokens?: number;
+  /** The model profile that writes the summary; the run's own by default. */
+  readonly modelProfile?: string;
+  /** Instructions for the summary instead of the built-in ones. */
+  readonly instructions?: string;
+}
+
+interface ModelRetrySettings {
+  readonly maxAttempts: number;
+  readonly delayMs: number;
+  readonly maxDelayMs: number;
+}
 
 export type AgentRuntimeStatus = "completed" | "failed";
 
@@ -78,6 +141,33 @@ export interface AgentRuntimeOptions {
   readonly modelProfile?: string;
   /** Provider-call timeout. Defaults to 60 seconds; 0 explicitly disables it. */
   readonly timeoutMs?: number;
+  /** The deadline of a whole run: every model call, Tool call and wait. No deadline by default. */
+  readonly runTimeoutMs?: number;
+  /** Repeats of a model request the provider could not serve right now (429, 5xx, a broken connection). */
+  readonly modelRetry?: AgentModelRetryPolicy;
+  /**
+   * How many times the model is asked to go on when the output limit cut its
+   * text answer (`finishReason: "length"`). 3 by default; 0 fails the run at once.
+   */
+  readonly maxOutputContinuations?: number;
+  /**
+   * How many times the model is asked to correct a structured answer that is
+   * not valid JSON or does not match the schema. 2 by default; 0 fails the run at once.
+   */
+  readonly maxOutputRepairs?: number;
+  /**
+   * How many Tools of one model step run at the same time. Only Tools with
+   * `sideEffect: "none"` or `"read"` standing next to each other run together;
+   * `write` and `external` always run one by one, in the order the model wrote
+   * them. 8 by default; 1 runs every Tool one by one.
+   */
+  readonly maxParallelToolCalls?: number;
+  /**
+   * Compaction of a long dialog: its older part is replaced by a summary the
+   * model writes, the newest messages stay as written. On by default;
+   * `false` turns it off, and a dialog that does not fit then fails the run.
+   */
+  readonly compaction?: AgentCompactionOptions | false;
   readonly contextBuilder?: AgentContextBuilder;
   readonly contextLimits?: AgentContextLimits;
   /**
@@ -93,6 +183,8 @@ export interface AgentRuntimeOptions {
  */
 export interface AgentExecutionDriverOptions extends AgentRuntimeOptions {
   readonly toolExecutorOptions?: AgentToolExecutorOptions;
+  /** Real tokens per estimated token, by model profile: one map for every run of a runtime. */
+  readonly tokenScales?: Map<string, number>;
 }
 
 export interface AgentRuntimeInvokeOptions {
@@ -109,6 +201,10 @@ export interface AgentRuntimeInvokeOptions {
   readonly temperature?: number;
   /** Per-provider-call timeout override; 0 explicitly disables it. */
   readonly timeoutMs?: number;
+  /** The deadline of this whole run instead of the runtime's; 0 explicitly disables it. */
+  readonly runTimeoutMs?: number;
+  /** Compaction settings of this run over the runtime's; `false` keeps the dialog as written. */
+  readonly compaction?: AgentCompactionOptions | false;
   readonly contextLimits?: AgentContextLimits;
   readonly signal?: AbortSignal;
   readonly toolExecution?: AgentRuntimeToolExecutionOptions;
@@ -127,6 +223,14 @@ export interface AgentRuntimeResult {
   readonly finalMessage?: AgentMessage;
   /** Validated structured value when `output` requested JSON. */
   readonly output?: JsonValue;
+  /** The sum over every model call of the run, summaries included, when the provider reports usage. */
+  readonly usage?: AgentUsage;
+  /**
+   * How many times the older part of the dialog was replaced by a summary
+   * during this run. `messages` then start with the summary, a user message
+   * with `metadata.runtime: "summary"`, not with the original dialog.
+   */
+  readonly compactions?: number;
   readonly error?: AgentToolError;
   readonly metadata: JsonObject;
 }
@@ -138,6 +242,15 @@ type PreparedAgentPlan = {
   readonly maxSteps: number;
   readonly maxToolCallsPerStep: number;
   readonly timeoutMs: number | undefined;
+  readonly runTimeoutMs: number | undefined;
+  readonly modelRetry: ModelRetrySettings;
+  readonly maxOutputContinuations: number;
+  readonly maxOutputRepairs: number;
+  readonly maxParallelToolCalls: number;
+  /** `undefined`: the dialog is never compacted. */
+  readonly compaction: AgentCompactionOptions | undefined;
+  /** What the run did besides its steps; filled while it runs. */
+  readonly side: { readonly usage: AgentUsage[]; compactions: number };
   readonly modelProfile: string | undefined;
   readonly contextLimits: AgentContextLimits | undefined;
   readonly messages: AgentMessage[];
@@ -403,6 +516,7 @@ function normalizeProviderResponse(value: unknown): AgentModelResponse {
       id: call.id as string,
       name: call.name as string,
       input: call.input,
+      inputError: call.inputError as string | undefined,
       metadata: call.metadata,
     });
   });
@@ -424,6 +538,146 @@ function runtimeError(code: string, message: string, details?: JsonValue): Agent
   });
 }
 
+/** The sum of what the provider reported for every model call. */
+function totalUsage(usages: readonly (AgentUsage | undefined)[]): AgentUsage | undefined {
+  const total: { inputTokens?: number; outputTokens?: number; totalTokens?: number; cacheReadTokens?: number; cacheWriteTokens?: number; reasoningTokens?: number; latencyMs?: number } = {};
+  let amount: number | undefined;
+  let currency: string | undefined;
+  let mixedCurrency = false;
+  let reported = false;
+  for (const usage of usages) {
+    if (usage === undefined) continue;
+    reported = true;
+    for (const field of ["inputTokens", "outputTokens", "totalTokens", "cacheReadTokens", "cacheWriteTokens", "reasoningTokens", "latencyMs"] as const) {
+      if (usage[field] !== undefined) total[field] = (total[field] ?? 0) + usage[field];
+    }
+    if (usage.cost !== undefined) {
+      if (currency !== undefined && currency !== usage.cost.currency) mixedCurrency = true;
+      currency = usage.cost.currency;
+      amount = (amount ?? 0) + usage.cost.amount;
+    }
+  }
+  if (!reported) return undefined;
+  return Object.freeze({
+    ...total,
+    ...(amount !== undefined && currency !== undefined && !mixedCurrency ? { cost: Object.freeze({ amount, currency }) } : {}),
+  });
+}
+
+/** The drafts at the end of a dialog that the runtime asked the model to continue or correct. */
+function runtimeChain(messages: readonly AgentMessage[]): { readonly start: number; readonly drafts: readonly AgentMessage[]; readonly continues: number; readonly repairs: number } {
+  let start = messages.length;
+  let continues = 0;
+  let repairs = 0;
+  const drafts: AgentMessage[] = [];
+  while (start >= 2) {
+    const ask = messages[start - 1]!;
+    const draft = messages[start - 2]!;
+    const kind = ask.role === "user" ? ask.metadata.runtime : undefined;
+    if ((kind !== RUNTIME_CONTINUE && kind !== RUNTIME_REPAIR) || draft.role !== "assistant" || draft.content.some((part) => part.kind === "tool-call")) break;
+    drafts.unshift(draft);
+    if (kind === RUNTIME_CONTINUE) continues += 1;
+    else repairs += 1;
+    start -= 2;
+  }
+  return { start, drafts, continues, repairs };
+}
+
+/** An answer in words: text, with or without the reasoning that led to it. */
+function isTextOnly(message: AgentMessage): boolean {
+  return message.content.every((part) => part.kind === "text" || part.kind === "reasoning");
+}
+
+/**
+ * A message without its reasoning parts. A provider ties reasoning to the
+ * dialog it was written in, so it is dropped wherever the runtime rewrites
+ * that dialog; the words and Tool calls stay.
+ */
+function withoutReasoning(message: AgentMessage): AgentMessage {
+  if (!message.content.some((part) => part.kind === "reasoning")) return message;
+  const content = message.content.filter((part) => part.kind !== "reasoning");
+  if (content.length === 0) return message;
+  return agentMessage(message.role, content, { id: message.id, name: message.name, toolCallId: message.toolCallId, createdAtUnixMs: message.createdAtUnixMs, metadata: message.metadata });
+}
+
+/** One answer out of the pieces the output limit cut it into. */
+function joinedAnswer(pieces: readonly AgentMessage[]): AgentMessage {
+  const last = pieces[pieces.length - 1]!;
+  const text = pieces.map((piece) => piece.content.map((part) => part.kind === "text" ? part.text : "").join("")).join("");
+  return agentMessage("assistant", text, { id: last.id, name: last.name, createdAtUnixMs: last.createdAtUnixMs, metadata: last.metadata });
+}
+
+function repairRequest(error: AgentToolError): string {
+  const details = error.details;
+  const issues = details !== undefined && details !== null && typeof details === "object" && !Array.isArray(details) ? (details as JsonObject).issues : undefined;
+  const listed = issues === undefined ? "" : ` Issues: ${JSON.stringify(issues).slice(0, 2_000)}.`;
+  return `Your answer was not accepted: ${error.message}${listed} Reply again with the corrected JSON only, without any other text.`;
+}
+
+function isInlineData(uri: string): boolean {
+  return uri.startsWith("data:");
+}
+
+function clip(text: string, maxChars: number): string {
+  return text.length <= maxChars ? text : `${text.slice(0, maxChars)}… [${text.length - maxChars} more characters]`;
+}
+
+/** A dialog as plain text for the model that writes its summary. */
+function renderDialog(messages: readonly AgentMessage[], maxChars: number): string {
+  const lines: string[] = [];
+  for (const message of messages) {
+    const speaker = message.metadata.runtime === RUNTIME_SUMMARY ? "Earlier summary" : message.role === "user" ? "User" : message.role === "assistant" ? "Assistant" : message.role === "tool" ? "Tool" : "Instructions";
+    for (const part of message.content) {
+      switch (part.kind) {
+        case "text": lines.push(`${speaker}: ${clip(part.text, 8_000)}`); break;
+        case "data": lines.push(`${speaker} (data${part.name === undefined ? "" : ` "${part.name}"`}): ${clip(JSON.stringify(part.value), 4_000)}`); break;
+        case "image": lines.push(`${speaker}: [image${isInlineData(part.uri) ? "" : ` ${clip(part.uri, 200)}`}]`); break;
+        case "file": lines.push(`${speaker}: [file ${part.name ?? (isInlineData(part.uri) ? "" : clip(part.uri, 200))}]`); break;
+        // Reasoning is the model's own working; the summary is written from what was said and done.
+        case "reasoning": break;
+        case "tool-call": lines.push(`Assistant called ${part.call.name}: ${clip(JSON.stringify(part.call.input), 2_000)}`); break;
+        case "tool-result": lines.push(`Result of ${part.result.name} (${part.result.status}): ${clip(JSON.stringify(part.result.status === "success" ? part.result.output : part.result.error), 4_000)}`); break;
+      }
+    }
+  }
+  const text = lines.join("\n");
+  // The end of the part being summarized matters most: it is what the dialog continues from.
+  return text.length <= maxChars ? text : `[The beginning of the conversation is omitted.]\n${text.slice(text.length - maxChars)}`;
+}
+
+/**
+ * Where the dialog is cut: messages before the index are summarized, the rest
+ * stay as written. A Tool call is never separated from its results.
+ * `undefined` when there is nothing worth summarizing.
+ */
+function compactionCut(messages: readonly AgentMessage[], tokens: readonly number[], keepTokens: number): number | undefined {
+  let cut = messages.length;
+  let kept = 0;
+  while (cut > 0 && kept + tokens[cut - 1]! <= keepTokens) {
+    kept += tokens[cut - 1]!;
+    cut -= 1;
+  }
+  // The kept part starts with a question or an answer, never with a Tool result.
+  while (cut < messages.length && messages[cut]!.role === "tool") cut += 1;
+  if (cut >= messages.length) {
+    // The newest exchange alone is larger than what may be kept: it stays whole anyway.
+    cut = messages.length - 1;
+    while (cut > 0 && messages[cut]!.role === "tool") cut -= 1;
+  }
+  return cut >= 2 ? cut : undefined;
+}
+
+/** Waits unless the run is cancelled first; resolves `false` when it was. */
+function pause(ms: number, signal: AbortSignal | undefined): Promise<boolean> {
+  if (signal?.aborted) return Promise.resolve(false);
+  if (ms <= 0) return Promise.resolve(true);
+  return new Promise<boolean>((resolve) => {
+    const onAbort = (): void => { clearTimeout(timer); resolve(false); };
+    const timer = setTimeout(() => { signal?.removeEventListener("abort", onAbort); resolve(true); }, ms);
+    signal?.addEventListener("abort", onAbort, { once: true });
+  });
+}
+
 function runtimeResult(options: {
   readonly invocationId: string;
   readonly agentName: string;
@@ -437,6 +691,7 @@ function runtimeResult(options: {
   readonly error?: AgentToolError;
   readonly metadata: JsonObject;
 }): AgentRuntimeResult {
+  const usage = totalUsage(options.responses.map((response) => response.usage));
   return Object.freeze({
     invocationId: options.invocationId,
     agentName: options.agentName,
@@ -447,6 +702,7 @@ function runtimeResult(options: {
     toolResults: Object.freeze([...options.toolResults]),
     ...(options.finalMessage !== undefined ? { finalMessage: options.finalMessage } : {}),
     ...(options.output !== undefined ? { output: options.output } : {}),
+    ...(usage !== undefined ? { usage } : {}),
     ...(options.error !== undefined ? { error: options.error } : {}),
     metadata: options.metadata,
   });
@@ -508,12 +764,33 @@ function attachAbortForwarding(source: AbortSignal | undefined, target: AbortCon
   return () => source.removeEventListener("abort", abort);
 }
 
+/** The size of a whole dialog as the context builder counted it, dropped messages included. */
+function contextTokens(context: AgentContext): number {
+  return context.trace.reduce((sum, entry) => sum + entry.tokens, 0);
+}
+
+const fallbackEstimator = new ApproximateAgentContextTokenEstimator();
+
+/** Tokens of every dialog message: the builder's own count, or an estimate for a builder that keeps no such trace. */
+function messageTokens(messages: readonly AgentMessage[], context: AgentContext, tokenScale: number): readonly number[] {
+  const counted = context.trace.filter((entry) => entry.section.startsWith("conversation["));
+  if (counted.length === messages.length) return counted.map((entry) => entry.tokens);
+  return messages.map((message) => Math.ceil(fallbackEstimator.estimateMessage(message) * tokenScale));
+}
+
 export class AgentExecutionDriver {
   private readonly toolExecutor: AgentToolExecutor;
   private readonly defaultMaxSteps: number;
   private readonly defaultMaxToolCallsPerStep: number;
   private readonly defaultModelProfile?: string;
   readonly defaultTimeoutMs?: number;
+  private readonly defaultRunTimeoutMs?: number;
+  private readonly modelRetry: ModelRetrySettings;
+  private readonly maxOutputContinuations: number;
+  private readonly maxOutputRepairs: number;
+  private readonly maxParallelToolCalls: number;
+  private readonly compaction: AgentCompactionOptions | undefined;
+  private readonly tokenScales: Map<string, number>;
   private readonly defaultContextLimits?: AgentContextLimits;
   private readonly contextBuilder: AgentContextBuilder;
   private readonly logger?: Logger;
@@ -527,6 +804,24 @@ export class AgentExecutionDriver {
     assertPositiveInteger(options.maxSteps, "AgentRuntime.maxSteps");
     assertPositiveInteger(options.maxToolCallsPerStep, "AgentRuntime.maxToolCallsPerStep");
     assertNonNegativeInteger(options.timeoutMs, "AgentRuntime.timeoutMs");
+    assertNonNegativeInteger(options.runTimeoutMs, "AgentRuntime.runTimeoutMs");
+    assertPositiveInteger(options.modelRetry?.maxAttempts, "AgentRuntime.modelRetry.maxAttempts");
+    assertNonNegativeInteger(options.modelRetry?.delayMs, "AgentRuntime.modelRetry.delayMs");
+    assertNonNegativeInteger(options.modelRetry?.maxDelayMs, "AgentRuntime.modelRetry.maxDelayMs");
+    assertNonNegativeInteger(options.maxOutputContinuations, "AgentRuntime.maxOutputContinuations");
+    assertNonNegativeInteger(options.maxOutputRepairs, "AgentRuntime.maxOutputRepairs");
+    assertPositiveInteger(options.maxParallelToolCalls, "AgentRuntime.maxParallelToolCalls");
+    this.defaultRunTimeoutMs = options.runTimeoutMs === 0 ? undefined : options.runTimeoutMs;
+    this.modelRetry = Object.freeze({
+      maxAttempts: options.modelRetry?.maxAttempts ?? DEFAULT_MODEL_ATTEMPTS,
+      delayMs: options.modelRetry?.delayMs ?? DEFAULT_MODEL_RETRY_DELAY_MS,
+      maxDelayMs: options.modelRetry?.maxDelayMs ?? DEFAULT_MODEL_RETRY_MAX_DELAY_MS,
+    });
+    this.maxOutputContinuations = options.maxOutputContinuations ?? DEFAULT_MAX_OUTPUT_CONTINUATIONS;
+    this.maxOutputRepairs = options.maxOutputRepairs ?? DEFAULT_MAX_OUTPUT_REPAIRS;
+    this.maxParallelToolCalls = options.maxParallelToolCalls ?? DEFAULT_MAX_PARALLEL_TOOL_CALLS;
+    this.compaction = this.compactionSettings(options.compaction, "AgentRuntime.compaction") ?? (options.compaction === false ? undefined : Object.freeze({}));
+    this.tokenScales = options.tokenScales ?? new Map<string, number>();
     this.defaultMaxSteps = options.maxSteps ?? DEFAULT_MAX_STEPS;
     this.defaultMaxToolCallsPerStep = options.maxToolCallsPerStep ?? DEFAULT_MAX_TOOL_CALLS_PER_STEP;
     this.defaultModelProfile = optionalText(options.modelProfile, "AgentRuntime.modelProfile");
@@ -667,6 +962,15 @@ export class AgentExecutionDriver {
       maxSteps,
       maxToolCallsPerStep,
       timeoutMs: providerTimeoutMs,
+      // A Session owns its run deadline and runs Tools one by one behind its durable boundary.
+      runTimeoutMs: undefined,
+      modelRetry: this.modelRetry,
+      maxOutputContinuations: this.maxOutputContinuations,
+      maxOutputRepairs: this.maxOutputRepairs,
+      maxParallelToolCalls: 1,
+      // A Session keeps its dialog as written: a checkpoint ties it to the recorded responses.
+      compaction: undefined,
+      side: { usage: [], compactions: 0 },
       modelProfile,
       contextLimits,
       messages: [...checkpoint.messages],
@@ -691,6 +995,8 @@ export class AgentExecutionDriver {
     let maxSteps: number;
     let maxToolCallsPerStep: number;
     let timeoutMs: number | undefined;
+    let runTimeoutMs: number | undefined;
+    let compaction: AgentCompactionOptions | undefined;
     let modelProfile: string | undefined;
     let contextLimits: AgentContextLimits | undefined;
     try {
@@ -698,6 +1004,12 @@ export class AgentExecutionDriver {
       assertPositiveInteger(options.maxSteps, "agentRuntime.maxSteps");
       assertPositiveInteger(options.maxToolCallsPerStep, "agentRuntime.maxToolCallsPerStep");
       assertNonNegativeInteger(options.timeoutMs, "agentRuntime.timeoutMs");
+      assertNonNegativeInteger(options.runTimeoutMs, "agentRuntime.runTimeoutMs");
+      runTimeoutMs = options.runTimeoutMs === 0 ? undefined : options.runTimeoutMs ?? this.defaultRunTimeoutMs;
+      const ownCompaction = this.compactionSettings(options.compaction, "agentRuntime.compaction");
+      compaction = options.compaction === false ? undefined
+        : ownCompaction === undefined ? this.compaction
+        : Object.freeze({ ...(this.compaction ?? {}), ...ownCompaction });
       maxSteps = options.maxSteps ?? this.defaultMaxSteps;
       maxToolCallsPerStep = options.maxToolCallsPerStep ?? this.defaultMaxToolCallsPerStep;
       timeoutMs = options.timeoutMs === 0 ? undefined : options.timeoutMs ?? this.defaultTimeoutMs;
@@ -733,6 +1045,13 @@ export class AgentExecutionDriver {
         maxSteps,
         maxToolCallsPerStep,
         timeoutMs,
+        runTimeoutMs,
+        modelRetry: this.modelRetry,
+        maxOutputContinuations: this.maxOutputContinuations,
+        maxOutputRepairs: this.maxOutputRepairs,
+        maxParallelToolCalls: this.maxParallelToolCalls,
+        compaction,
+        side: { usage: [], compactions: 0 },
         modelProfile,
         contextLimits,
         messages,
@@ -791,6 +1110,14 @@ export class AgentExecutionDriver {
       }
     };
     const terminal = (state: TState, result: AgentRuntimeResult): EngineOutcome<TState> => ({ kind: "terminal", state, result });
+    // A dialog is compacted at most once before a step and once after a refusal of that step.
+    const canCompact = !session && plan.compaction !== undefined;
+    let sizeCheckedAtStep = 0;
+    let overflowHandledAtStep = 0;
+    const withMessages = (messages: readonly AgentMessage[]): TState => bridge.evolve(checkpoint, {
+      phase: checkpoint.phase, steps: checkpoint.steps, messages, responses: checkpoint.responses, toolResults: checkpoint.toolResults,
+      seenToolCallIds: checkpoint.seenToolCallIds, pendingToolBatch: undefined, terminal: undefined,
+    });
 
     for (;;) {
       if (session && signal?.aborted) return suspend("aborted");
@@ -800,6 +1127,42 @@ export class AgentExecutionDriver {
         const pending = checkpoint.pendingToolBatch!;
         const response = checkpoint.responses[pending.responseIndex]!;
         const call = response.toolCalls[pending.nextToolIndex]!;
+        const together = session ? [] : this.readTogether(plan, response.toolCalls, pending.nextToolIndex);
+        if (together.length > 1) {
+          const results = await Promise.all(together.map((item) => this.toolExecutor.execute(item.call, {
+            ...plan.executorToolOptions,
+            agentName: plan.agent.name,
+            invocationId: plan.invocationId,
+            metadata: plan.metadata,
+            signal,
+            idempotencyKey: item.idempotencyKey,
+          })));
+          const unknown = results.findIndex((result) => result.error?.code?.endsWith("_OUTCOME_UNKNOWN") === true);
+          const nextToolIndex = pending.nextToolIndex + together.length;
+          const finished = nextToolIndex === response.toolCalls.length;
+          const candidate = bridge.evolve(checkpoint, {
+            phase: unknown >= 0 ? "terminal" : finished ? "ready-model" : "pending-tools",
+            steps: checkpoint.steps,
+            // Results stand in the order the model wrote the calls, whichever finished first.
+            messages: [...checkpoint.messages, ...results.map((result, index) => agentMessage("tool", agentToolResultPart(result), {
+              toolCallId: together[index]!.call.id, metadata: { toolName: together[index]!.call.name },
+            }))],
+            responses: checkpoint.responses,
+            toolResults: [...checkpoint.toolResults, ...results],
+            seenToolCallIds: checkpoint.seenToolCallIds,
+            pendingToolBatch: finished ? undefined : { ...pending, nextToolIndex },
+            terminal: unknown >= 0 ? {
+              status: "failed",
+              error: runtimeError("AGENT_TOOL_OUTCOME_UNKNOWN", `Tool "${together[unknown]!.call.name}" finished with an unknown retry-safe side-effect outcome; automatic model continuation is blocked.`, {
+                callId: together[unknown]!.call.id, toolName: together[unknown]!.call.name, idempotencyKey: together[unknown]!.idempotencyKey, toolErrorCode: results[unknown]!.error?.code ?? null,
+              }),
+            } : undefined,
+          });
+          const stopped = await committedControl(candidate);
+          if (stopped !== undefined) return stopped;
+          if (candidate.phase === "terminal") return terminal(candidate, this.resultFromCheckpoint(plan, candidate));
+          continue;
+        }
         let idempotencyKey: string;
         try {
           idempotencyKey = !session
@@ -873,8 +1236,22 @@ export class AgentExecutionDriver {
       const readyControl = await control(checkpoint);
       if (readyControl !== undefined) return readyControl;
       let modelRequest: AgentModelRequest;
+      let context: AgentContext;
+      const tokenScale = this.tokenScales.get(plan.modelProfile ?? "") ?? 1;
+      const build = (): AgentContext => this.contextBuilder.build({ invocationId: plan.invocationId, agent: plan.agent, messages: checkpoint.messages, metadata: plan.metadata, limits: plan.contextLimits, tokenScale });
       try {
-        const context = this.contextBuilder.build({ invocationId: plan.invocationId, agent: plan.agent, messages: checkpoint.messages, metadata: plan.metadata, limits: plan.contextLimits });
+        context = build();
+        if (canCompact && sizeCheckedAtStep !== step) {
+          sizeCheckedAtStep = step;
+          const maxTokens = this.compactionThreshold(plan);
+          if (maxTokens !== undefined && contextTokens(context) > maxTokens) {
+            const compacted = await this.compact(plan, checkpoint.messages, context, tokenScale, plan.compaction!.keepTokens ?? Math.floor(maxTokens / 4), "size", signal);
+            if (compacted !== undefined) {
+              checkpoint = withMessages(compacted);
+              context = build();
+            }
+          }
+        }
         modelRequest = agentModelRequest({
           invocationId: plan.invocationId, messages: context.messages, tools: plan.tools,
           output: this.providerOutputContract(plan.options.output),
@@ -896,9 +1273,18 @@ export class AgentExecutionDriver {
       } catch {
         return suspend("before-model-rejected");
       }
-      const response = await this.completeModel(modelRequest, plan.agent.name, plan.modelProfile, plan.metadata, signal, plan.timeoutMs,
+      const response = await this.completeModel(modelRequest, plan.agent.name, plan.modelProfile, plan.metadata, signal, plan.timeoutMs, plan.modelRetry,
         plan.options.onTextDelta ? text => plan.options.onTextDelta!(Object.freeze({ step, text })) : undefined);
       if (!response.ok) {
+        // The provider says the request is too long: the dialog is compacted and the step is asked again.
+        if (response.cause instanceof AgentModelContextOverflowError && canCompact && overflowHandledAtStep !== step) {
+          overflowHandledAtStep = step;
+          const compacted = await this.compact(plan, checkpoint.messages, context, tokenScale, plan.compaction!.keepTokens ?? Math.floor(contextTokens(context) / 4), "overflow", signal);
+          if (compacted !== undefined) {
+            checkpoint = withMessages(compacted);
+            continue;
+          }
+        }
         const candidate = bridge.evolve(checkpoint, {
           phase: "terminal", steps: step, messages: checkpoint.messages, responses: checkpoint.responses, toolResults: checkpoint.toolResults,
           seenToolCallIds: checkpoint.seenToolCallIds, pendingToolBatch: undefined, terminal: { status: "failed", error: response.error },
@@ -907,6 +1293,7 @@ export class AgentExecutionDriver {
         const stopped = await committedControl(candidate);
         return stopped ?? terminal(candidate, this.resultFromCheckpoint(plan, candidate));
       }
+      this.learnTokenScale(plan.modelProfile, tokenScale, context, response.value);
       const candidate = await this.modelCandidate(plan, checkpoint, step, response.value, bridge);
       try { await boundary.afterModelSettlement(checkpoint, candidate.state, step, { response: response.value }); } catch { throw bridge.boundaryError(checkpoint); }
       const stopped = await committedControl(candidate.state);
@@ -947,14 +1334,39 @@ export class AgentExecutionDriver {
       const state = bridge.evolve(checkpoint, { phase: "pending-tools", steps: step, messages: [...checkpoint.messages, assistant], responses: [...checkpoint.responses, response], toolResults: checkpoint.toolResults, seenToolCallIds: [...seen], pendingToolBatch: { step, responseIndex: checkpoint.responses.length, assistantMessageIndex: checkpoint.messages.length, nextToolIndex: 0 }, terminal: undefined });
       return { state };
     }
-    const messages = message === undefined ? checkpoint.messages : [...checkpoint.messages, message];
+    // No tool calls: a model response always carries a message then.
+    const answer = message!;
+    const chain = runtimeChain(checkpoint.messages);
+    const responses = [...checkpoint.responses, response];
+    const json = plan.options.output?.mode === "json";
+    /** The draft stays in the dialog with the runtime's request, and the model is called again. */
+    const askAgain = (kind: string, text: string): { readonly state: TState } => ({ state: bridge.evolve(checkpoint, {
+      phase: "ready-model", steps: step,
+      messages: [...checkpoint.messages, answer, agentMessage("user", text, { metadata: { runtime: kind } })],
+      responses, toolResults: checkpoint.toolResults, seenToolCallIds: checkpoint.seenToolCallIds, pendingToolBatch: undefined, terminal: undefined,
+    }) });
+    const mayAskAgain = step < plan.maxSteps;
+    if (response.finishReason === "length" && !json && isTextOnly(answer) && mayAskAgain && chain.continues < plan.maxOutputContinuations) {
+      return askAgain(RUNTIME_CONTINUE, CONTINUE_TEXT);
+    }
+    // The finished dialog keeps one answer: the pieces joined, without rejected drafts and the runtime's requests.
+    const finalMessage = !json && chain.continues > 0 && chain.repairs === 0 && isTextOnly(answer) && chain.drafts.every(isTextOnly)
+      ? joinedAnswer([...chain.drafts, answer])
+      // Drafts are dropped from the dialog, so the answer's reasoning no longer matches it.
+      : chain.drafts.length > 0 ? withoutReasoning(answer) : answer;
+    const messages = [...checkpoint.messages.slice(0, chain.start), finalMessage];
     let result: AgentRuntimeResult;
-    if (response.finishReason !== "stop" || message === undefined) {
-      result = runtimeResult({ invocationId: plan.invocationId, agentName: plan.agent.name, status: "failed", steps: step, messages, responses: [...checkpoint.responses, response], toolResults: checkpoint.toolResults, finalMessage: message, metadata: plan.metadata,
+    if (response.finishReason !== "stop") {
+      result = runtimeResult({ invocationId: plan.invocationId, agentName: plan.agent.name, status: "failed", steps: step, messages, responses, toolResults: checkpoint.toolResults, finalMessage, metadata: plan.metadata,
         error: runtimeError("AGENT_PROVIDER_STOPPED", `Model provider stopped with finishReason "${response.finishReason}".`) });
     } else {
-      result = runtimeResult({ invocationId: plan.invocationId, agentName: plan.agent.name, status: "completed", steps: step, messages, responses: [...checkpoint.responses, response], toolResults: checkpoint.toolResults, finalMessage: message, metadata: plan.metadata });
-      if (plan.options.output?.mode === "json") result = this.validateExplicitOutput(result, plan.options.output);
+      result = runtimeResult({ invocationId: plan.invocationId, agentName: plan.agent.name, status: "completed", steps: step, messages, responses, toolResults: checkpoint.toolResults, finalMessage, metadata: plan.metadata });
+      if (plan.options.output?.mode === "json") {
+        result = this.validateExplicitOutput(result, plan.options.output);
+        if (result.error?.code === "AGENT_OUTPUT_INVALID" && mayAskAgain && chain.repairs < plan.maxOutputRepairs) {
+          return askAgain(RUNTIME_REPAIR, repairRequest(result.error));
+        }
+      }
     }
     const state = bridge.evolve(checkpoint, { phase: "terminal", steps: step, messages: result.messages, responses: result.responses, toolResults: result.toolResults, seenToolCallIds: checkpoint.seenToolCallIds, pendingToolBatch: undefined,
       terminal: result.status === "completed" ? { status: "completed", finalMessage: result.finalMessage, output: result.output } : { status: "failed", finalMessage: result.finalMessage, error: result.error! } });
@@ -992,21 +1404,152 @@ export class AgentExecutionDriver {
       boundaryError() { return new AgentRuntimeError("in-memory execution boundary rejected a transition."); },
     };
     const resolvedPlan = { ...plan, modelProfile: plan.modelProfile ?? plan.agent.modelProfile ?? this.defaultModelProfile };
-    const outcome = await this.drivePhaseEngine(resolvedPlan, initial, inMemoryBoundary, plan.options.signal, inMemoryBridge, false);
-    if (outcome.kind === "terminal") return outcome.result;
-    throw new AgentRuntimeError("in-memory execution cannot suspend.");
+    if (plan.runTimeoutMs === undefined) {
+      const outcome = await this.drivePhaseEngine(resolvedPlan, initial, inMemoryBoundary, plan.options.signal, inMemoryBridge, false);
+      if (outcome.kind === "terminal") return this.withSideWork(outcome.result, plan);
+      throw new AgentRuntimeError("in-memory execution cannot suspend.");
+    }
+    // The run deadline cancels whatever is in flight, like the caller's signal does.
+    const deadline = new AbortController();
+    const detach = attachAbortForwarding(plan.options.signal, deadline);
+    let expired = false;
+    const timer = setTimeout(() => { expired = true; deadline.abort(); }, plan.runTimeoutMs);
+    try {
+      const outcome = await this.drivePhaseEngine(resolvedPlan, initial, inMemoryBoundary, deadline.signal, inMemoryBridge, false);
+      if (outcome.kind !== "terminal") throw new AgentRuntimeError("in-memory execution cannot suspend.");
+      return this.withSideWork(expired && outcome.result.error?.code === "AGENT_ABORTED"
+        ? this.failedResult(outcome.result, runtimeError("AGENT_RUN_TIMEOUT", `Agent "${plan.agent.name}" did not finish within runTimeoutMs (${plan.runTimeoutMs}).`, { runTimeoutMs: plan.runTimeoutMs }))
+        : outcome.result, plan);
+    } finally {
+      clearTimeout(timer);
+      detach?.();
+    }
+  }
+
+  /** Adds to a result what the run did besides its steps: summaries and their usage. */
+  private withSideWork(result: AgentRuntimeResult, plan: PreparedAgentPlan): AgentRuntimeResult {
+    if (plan.side.compactions === 0) return result;
+    const usage = totalUsage([result.usage, ...plan.side.usage]);
+    return Object.freeze({ ...result, ...(usage === undefined ? {} : { usage }), compactions: plan.side.compactions });
+  }
+
+  private compactionSettings(value: AgentCompactionOptions | false | undefined, field: string): AgentCompactionOptions | undefined {
+    if (value === undefined || value === false) return undefined;
+    assertPositiveInteger(value.maxTokens, `${field}.maxTokens`);
+    assertPositiveInteger(value.keepTokens, `${field}.keepTokens`);
+    const modelProfile = optionalText(value.modelProfile, `${field}.modelProfile`);
+    const instructions = optionalText(value.instructions, `${field}.instructions`);
+    return Object.freeze({
+      ...(value.maxTokens === undefined ? {} : { maxTokens: value.maxTokens }),
+      ...(value.keepTokens === undefined ? {} : { keepTokens: value.keepTokens }),
+      ...(modelProfile === undefined ? {} : { modelProfile }),
+      ...(instructions === undefined ? {} : { instructions }),
+    });
+  }
+
+  /** The dialog size that starts compaction, when it is set or the model's window is known. */
+  private compactionThreshold(plan: PreparedAgentPlan): number | undefined {
+    if (plan.compaction?.maxTokens !== undefined) return plan.compaction.maxTokens;
+    let window: number | undefined;
+    try { window = this.modelProvider.contextTokens?.(plan.modelProfile); } catch { window = undefined; }
+    return typeof window === "number" && Number.isFinite(window) && window > 0 ? Math.floor(window * COMPACTION_WINDOW_SHARE) : undefined;
+  }
+
+  /**
+   * Replaces the older part of a dialog with a summary the model writes.
+   * `undefined` when there is nothing to summarize or the summary failed: the
+   * dialog then stays as it is.
+   */
+  private async compact(
+    plan: PreparedAgentPlan, messages: readonly AgentMessage[], context: AgentContext, tokenScale: number, keepTokens: number,
+    reason: "size" | "overflow", signal: AbortSignal | undefined,
+  ): Promise<readonly AgentMessage[] | undefined> {
+    const tokens = messageTokens(messages, context, tokenScale);
+    const cut = compactionCut(messages, tokens, keepTokens);
+    if (cut === undefined) return undefined;
+    const settings = plan.compaction!;
+    const modelProfile = settings.modelProfile ?? plan.modelProfile;
+    const before = tokens.reduce((sum, value) => sum + value, 0);
+    const summarized = tokens.slice(0, cut).reduce((sum, value) => sum + value, 0);
+    try {
+      const request = agentModelRequest({
+        invocationId: plan.invocationId,
+        messages: [
+          agentMessage("system", settings.instructions ?? SUMMARY_INSTRUCTIONS),
+          // Plain text, so the request needs neither the Tools nor a valid tool-call order.
+          agentMessage("user", `<conversation>\n${renderDialog(messages.slice(0, cut), Math.max(20_000, summarized * 4))}\n</conversation>\n\nWrite the summary of the conversation above.`),
+        ],
+        modelProfile,
+        metadata: { ...plan.metadata, agentName: plan.agent.name, purpose: "compaction", modelProfile: modelProfile ?? null },
+      });
+      const response = await this.completeModel(request, plan.agent.name, modelProfile, plan.metadata, signal, plan.timeoutMs, plan.modelRetry);
+      if (!response.ok) {
+        if (response.error.code !== "AGENT_ABORTED") this.logger?.warn("Agent context was not compacted", { agent: plan.agent.name, invocationId: plan.invocationId, reason, code: response.error.code });
+        return undefined;
+      }
+      if (response.value.usage !== undefined) plan.side.usage.push(response.value.usage);
+      const summary = (response.value.message?.content ?? []).map((part) => part.kind === "text" ? part.text : "").join("").trim();
+      if (summary.length === 0 || response.value.toolCalls.length > 0) {
+        this.logger?.warn("Agent context was not compacted", { agent: plan.agent.name, invocationId: plan.invocationId, reason, code: "AGENT_SUMMARY_EMPTY" });
+        return undefined;
+      }
+      plan.side.compactions += 1;
+      this.logger?.info("Agent context compacted", { agent: plan.agent.name, invocationId: plan.invocationId, reason, messages: cut, tokensBefore: before, tokensSummarized: summarized });
+      return Object.freeze([
+        agentMessage("user", `${SUMMARY_PREFIX}\n\n${summary}`, { metadata: { runtime: RUNTIME_SUMMARY, messages: cut } }),
+        // The kept messages were reasoned about with the whole dialog in front of the model.
+        ...messages.slice(cut).map(withoutReasoning),
+      ]);
+    } catch (error) {
+      this.logger?.warn("Agent context was not compacted", { agent: plan.agent.name, invocationId: plan.invocationId, reason, error: redactSensitive(error) });
+      return undefined;
+    }
+  }
+
+  /** Remembers how many real tokens an estimated one is for a model, from the usage it reported. */
+  private learnTokenScale(modelProfile: string | undefined, usedScale: number, context: AgentContext, response: AgentModelResponse): void {
+    const reported = response.usage?.inputTokens;
+    const counted = context.metadata.tokenCount;
+    if (typeof reported !== "number" || reported <= 0 || typeof counted !== "number" || counted <= 0) return;
+    const measured = Math.min(6, Math.max(0.5, reported / (counted / usedScale)));
+    const key = modelProfile ?? "";
+    const known = this.tokenScales.get(key);
+    // Half-way to the new measurement: one unusual request does not swing the estimate.
+    this.tokenScales.set(key, known === undefined ? measured : (known + measured) / 2);
+  }
+
+  /**
+   * The calls from `from` on that may run at the same time: Tools that change
+   * nothing, standing next to each other. One call, or a call that changes
+   * something, runs alone through the ordinary path.
+   */
+  private readTogether(plan: PreparedAgentPlan, calls: readonly AgentModelResponse["toolCalls"][number][], from: number): readonly { readonly call: AgentModelResponse["toolCalls"][number]; readonly idempotencyKey: string }[] {
+    const together: { call: AgentModelResponse["toolCalls"][number]; idempotencyKey: string }[] = [];
+    for (let index = from; index < calls.length && together.length < plan.maxParallelToolCalls; index += 1) {
+      const call = calls[index]!;
+      const sideEffect = plan.agent.tools.find((tool) => tool.metadata.name === call.name)?.metadata.sideEffect;
+      if (sideEffect !== "none" && sideEffect !== "read") break;
+      try {
+        together.push({ call, idempotencyKey: this.toolIdempotencyKey(plan.options.toolExecution, { invocationId: plan.invocationId, agentName: plan.agent.name, call }) });
+      } catch {
+        // A wrong idempotency setting is reported by the ordinary one-call path.
+        break;
+      }
+    }
+    return together;
   }
   private parseJsonOutput(message: AgentMessage | undefined): unknown {
     if (message === undefined) {
       throw new AgentRuntimeError("Model response does not contain a final message.");
     }
-    if (message.content.length === 1 && message.content[0]?.kind === "data") {
-      return message.content[0].value;
+    const content = message.content.filter((part) => part.kind !== "reasoning");
+    if (content.length === 1 && content[0]?.kind === "data") {
+      return content[0].value;
     }
-    if (!message.content.every((part) => part.kind === "text")) {
+    if (!content.every((part) => part.kind === "text")) {
       throw new AgentRuntimeError("JSON output must contain only text or one data part.");
     }
-    const text = message.content.map((part) => part.kind === "text" ? part.text : "").join("\n").trim();
+    const text = content.map((part) => part.kind === "text" ? part.text : "").join("\n").trim();
     if (text.length === 0) {
       throw new AgentRuntimeError("JSON output is empty.");
     }
@@ -1099,6 +1642,7 @@ export class AgentExecutionDriver {
     return agentOutputContract({ ...output, schema: agentJsonSchema(output.schema.name, inlineGeneratedSchema(generated, schemas), { strict: output.schema.strict }) });
   }
 
+  /** One model request, repeated while the provider cannot serve it right now. */
   private async completeModel(
     request: AgentModelRequest,
     agentName: string,
@@ -1106,11 +1650,42 @@ export class AgentExecutionDriver {
     metadata: JsonObject,
     sourceSignal: AbortSignal | undefined,
     timeoutMs: number | undefined,
+    retry: ModelRetrySettings,
     onTextDelta?: (text: string) => void,
-  ): Promise<{ readonly ok: true; readonly value: AgentModelResponse } | { readonly ok: false; readonly error: AgentToolError }> {
+  ): Promise<{ readonly ok: true; readonly value: AgentModelResponse } | { readonly ok: false; readonly error: AgentToolError; readonly cause?: unknown }> {
+    for (let attempt = 1; ; attempt += 1) {
+      const outcome = await this.completeModelOnce(request, agentName, modelProfile, metadata, sourceSignal, timeoutMs, onTextDelta);
+      if (outcome.ok) return outcome;
+      // Text already shown to the user is not followed by a second answer.
+      const repeat = outcome.cause instanceof AgentModelUnavailableError && attempt < retry.maxAttempts && !outcome.textEmitted && sourceSignal?.aborted !== true;
+      if (!repeat) {
+        if (outcome.error.code !== "AGENT_ABORTED" && !outcome.logged) {
+          this.logger?.error("Agent model call failed", { agent: agentName, invocationId: request.invocationId, code: outcome.error.code, ...(attempt > 1 ? { attempts: attempt } : {}), error: redactSensitive(outcome.cause) });
+        }
+        return { ok: false, error: outcome.error, cause: outcome.cause };
+      }
+      const asked = (outcome.cause as AgentModelUnavailableError).retryAfterMs ?? 0;
+      const delayMs = Math.min(retry.maxDelayMs, Math.max(asked, retry.delayMs * 2 ** (attempt - 1)));
+      this.logger?.warn("Agent model call failed, repeating", { agent: agentName, invocationId: request.invocationId, attempt, maxAttempts: retry.maxAttempts, delayMs, error: redactSensitive(outcome.cause) });
+      if (!await pause(delayMs, sourceSignal)) {
+        return { ok: false, error: runtimeError("AGENT_ABORTED", "Agent runtime invocation was aborted.") };
+      }
+    }
+  }
+
+  private async completeModelOnce(
+    request: AgentModelRequest,
+    agentName: string,
+    modelProfile: string | undefined,
+    metadata: JsonObject,
+    sourceSignal: AbortSignal | undefined,
+    timeoutMs: number | undefined,
+    onTextDelta?: (text: string) => void,
+  ): Promise<{ readonly ok: true; readonly value: AgentModelResponse } | { readonly ok: false; readonly error: AgentToolError; readonly cause: unknown; readonly textEmitted: boolean; readonly logged: boolean }> {
     const abortController = new AbortController();
     const detach = attachAbortForwarding(sourceSignal, abortController);
     let acceptingText = true;
+    let textEmitted = false;
     const context: AgentModelProviderContext = Object.freeze({
       invocationId: request.invocationId,
       agentName,
@@ -1120,7 +1695,7 @@ export class AgentExecutionDriver {
       ...(onTextDelta ? { onTextDelta: (text: string) => {
         if (!acceptingText || abortController.signal.aborted) return;
         if (typeof text !== "string") throw new AgentRuntimeError("Model text delta must be a string.");
-        if (text) onTextDelta(text);
+        if (text) { textEmitted = true; onTextDelta(text); }
       } } : {}),
     });
 
@@ -1139,7 +1714,7 @@ export class AgentExecutionDriver {
       } catch (error) {
         this.logger?.error("Agent model call failed", { agent: agentName, invocationId: request.invocationId, code: "AGENT_PROVIDER_RESPONSE_INVALID", error: redactSensitive(error) });
         return {
-          ok: false,
+          ok: false, cause: error, textEmitted, logged: true,
           error: runtimeError("AGENT_PROVIDER_RESPONSE_INVALID", `Model provider returned an invalid response: ${errorMessageOf(error)}`),
         };
       }
@@ -1148,11 +1723,10 @@ export class AgentExecutionDriver {
         ? "AGENT_PROVIDER_TIMEOUT"
         : error instanceof AgentRuntimeAbortError
           ? "AGENT_ABORTED"
-          : "AGENT_PROVIDER_FAILED";
-      if (code !== "AGENT_ABORTED") {
-        this.logger?.error("Agent model call failed", { agent: agentName, invocationId: request.invocationId, code, error: redactSensitive(error) });
-      }
-      return { ok: false, error: runtimeError(code, errorMessageOf(error)) };
+          : error instanceof AgentModelContextOverflowError
+            ? "AGENT_CONTEXT_OVERFLOW"
+            : "AGENT_PROVIDER_FAILED";
+      return { ok: false, cause: error, textEmitted, logged: false, error: runtimeError(code, errorMessageOf(error)) };
     } finally {
       acceptingText = false;
       detach?.();