agent-accelerator 0.5.9 → 0.6.5

package/src/session/usage.ts

@@ -72,8 +72,17 @@ export function addTurn(totals: UsageTotals, usage: TokenUsage, priced: PricedCo
 
 /** Adds `other` into `into` (workers into a total). */
 export function mergeUsage(into: UsageTotals, other: UsageTotals): void {
-  for (const k of ["turns", "inputTokens", "cacheReadTokens", "cacheWriteTokens", "outputTokens", "thinkingTokens"] as const) into[k] += other[k];
-  for (const k of ["input", "output", "cacheRead", "cacheWrite", "total"] as const) into.costMicroUSD[k] += other.costMicroUSD[k];
+  for (const k of [
+    "turns",
+    "inputTokens",
+    "cacheReadTokens",
+    "cacheWriteTokens",
+    "outputTokens",
+    "thinkingTokens",
+  ] as const)
+    into[k] += other[k];
+  for (const k of ["input", "output", "cacheRead", "cacheWrite", "total"] as const)
+    into.costMicroUSD[k] += other.costMicroUSD[k];
   for (const k of ["provider", "catalog", "unpriced"] as const) into.turnsBy[k] += other.turnsBy[k];
 }
 
@@ -82,8 +91,17 @@ export function readUsage(saved: unknown): UsageTotals {
   const out = emptyUsage();
   const s = saved as Partial<UsageTotals> | null | undefined;
   if (!s || typeof s !== "object") return out;
-  for (const k of ["turns", "inputTokens", "cacheReadTokens", "cacheWriteTokens", "outputTokens", "thinkingTokens"] as const) out[k] = count(s[k]);
-  for (const k of ["input", "output", "cacheRead", "cacheWrite", "total"] as const) out.costMicroUSD[k] = count(s.costMicroUSD?.[k]);
+  for (const k of [
+    "turns",
+    "inputTokens",
+    "cacheReadTokens",
+    "cacheWriteTokens",
+    "outputTokens",
+    "thinkingTokens",
+  ] as const)
+    out[k] = count(s[k]);
+  for (const k of ["input", "output", "cacheRead", "cacheWrite", "total"] as const)
+    out.costMicroUSD[k] = count(s.costMicroUSD?.[k]);
   for (const k of ["provider", "catalog", "unpriced"] as const) out.turnsBy[k] = count(s.turnsBy?.[k]);
   return out;
 }
@@ -124,7 +142,14 @@ export interface UsageLine {
 /** Turns raw totals into a readable {@link UsageLine}. */
 export function usageLine(t: UsageTotals): UsageLine {
   const priced = t.turnsBy.provider + t.turnsBy.catalog;
-  const source: CostSource = priced === 0 ? "unknown" : t.turnsBy.provider > 0 && t.turnsBy.catalog > 0 ? "mixed" : t.turnsBy.provider > 0 ? "provider" : "catalog";
+  const source: CostSource =
+    priced === 0
+      ? "unknown"
+      : t.turnsBy.provider > 0 && t.turnsBy.catalog > 0
+        ? "mixed"
+        : t.turnsBy.provider > 0
+          ? "provider"
+          : "catalog";
   const usd = (micro: number): number => micro / 1_000_000;
   const c = t.costMicroUSD;
   return {
@@ -143,7 +168,16 @@ export function usageLine(t: UsageTotals): UsageLine {
       source,
       unpricedTurns: t.turnsBy.unpriced,
       totalUsd: priced === 0 ? null : usd(c.total),
-      ...(priced === 0 ? {} : { parts: { inputUsd: usd(c.input), outputUsd: usd(c.output), cacheReadUsd: usd(c.cacheRead), cacheWriteUsd: usd(c.cacheWrite) } }),
+      ...(priced === 0
+        ? {}
+        : {
+            parts: {
+              inputUsd: usd(c.input),
+              outputUsd: usd(c.output),
+              cacheReadUsd: usd(c.cacheRead),
+              cacheWriteUsd: usd(c.cacheWrite),
+            },
+          }),
     },
   };
 }
@@ -190,13 +224,28 @@ function sumTree(into: UsageTotals, nodes: UsageNode[]): void {
 
 // One node as a report line, children included; in: a usage node, out: UsageReport.workers.
 function nodeLine(n: UsageNode): WorkerUsage {
-  return { id: n.id, name: n.name, ...(n.role ? { role: n.role } : {}), model: n.model, status: n.status, ...usageLine(n.totals), workers: n.workers.map(nodeLine) };
+  return {
+    id: n.id,
+    name: n.name,
+    ...(n.role ? { role: n.role } : {}),
+    model: n.model,
+    status: n.status,
+    ...usageLine(n.totals),
+    workers: n.workers.map(nodeLine),
+  };
 }
 
 /** Builds the report from the agent's own totals and its worker tree. */
-export function buildUsageReport(own: { id: string; name: string; model: string; totals: UsageTotals }, workers: UsageNode[]): UsageReport {
+export function buildUsageReport(
+  own: { id: string; name: string; model: string; totals: UsageTotals },
+  workers: UsageNode[]
+): UsageReport {
   const total = emptyUsage();
   mergeUsage(total, own.totals);
   sumTree(total, workers);
-  return { agent: { id: own.id, name: own.name, model: own.model, ...usageLine(own.totals) }, workers: workers.map(nodeLine), total: usageLine(total) };
+  return {
+    agent: { id: own.id, name: own.name, model: own.model, ...usageLine(own.totals) },
+    workers: workers.map(nodeLine),
+    total: usageLine(total),
+  };
 }

package/src/streaming/architecture.md

@@ -1,11 +1,12 @@
 # src/streaming/
 
-| File | What it is |
-| :-- | :-- |
+| File              | What it is                                                                                                                                                                                                |
+| :---------------- | :-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
 | `event-stream.ts` | `AssistantMessageEventStream`: an async-iterable event stream with listeners (`on`/`off`), a `result()` promise, `cancel()` and bounded buffering. Providers produce it; the loop and `Agent` consume it. |
-| `sse-parser.ts` | `SSEParser`: incremental Server-Sent Events framing that survives events split across network chunks. Internal (not exported from the barrel). |
+| `sse-parser.ts`   | `SSEParser`: incremental Server-Sent Events framing that survives events split across network chunks. Internal (not exported from the barrel).                                                            |
 
 ## Invariants
+
 - The buffer holds at most 1000 events (oldest dropped, reported on the bus); an event over 1 MB is dropped. `{ buffer: false }` keeps none (for a caller that only wants `result()`).
 - `end()` without a response fails the stream instead of leaving `result()` hanging.
 - A cancel is recognised by the `AbortError` name only, never by message text.

package/src/streaming/event-stream.ts

@@ -1,5 +1,6 @@
 import type { StreamEvent, AgentResponse } from "../types/response.ts";
 import { telemetryBus } from "../telemetry.ts";
+import { ValidationError } from "../types/errors.ts";
 
 /** Listener invoked for a matching stream event type or `*`. */
 export type StreamEventListener = (event: StreamEvent) => void;
@@ -87,7 +88,9 @@ export class AssistantMessageEventStream implements AsyncIterable<StreamEvent> {
     this.includePartial = opts?.includePartial !== false;
     this.buffered = opts?.buffer !== false;
     this.maxBufferedEvents =
-      typeof opts?.maxBufferedEvents === "number" && Number.isFinite(opts.maxBufferedEvents) && opts.maxBufferedEvents > 0
+      typeof opts?.maxBufferedEvents === "number" &&
+      Number.isFinite(opts.maxBufferedEvents) &&
+      opts.maxBufferedEvents > 0
         ? Math.floor(opts.maxBufferedEvents)
         : MAX_BUFFERED_EVENTS;
     this.maxEventBytes =
@@ -131,12 +134,15 @@ export class AssistantMessageEventStream implements AsyncIterable<StreamEvent> {
     }
 
     if (out.type === "error") {
-      this.error = (out.error instanceof Error ? out.error : new Error(String(out.error))) ?? new Error("Unknown error in stream");
+      this.error =
+        (out.error instanceof Error ? out.error : new Error(String(out.error))) ?? new Error("Unknown error in stream");
       // Single error semantic: deliver the error event to listeners,
       // reject result(), mark finished, reject pending iterators, and queue
       // the error event so a late iterator observes it before failing.
       this.deliverToListeners(out);
-      try { this.rejectFinalResult(this.error); } catch {
+      try {
+        this.rejectFinalResult(this.error);
+      } catch {
         // why: rejecting an already-settled promise helper must not throw.
       }
       this.finished = true;
@@ -168,7 +174,9 @@ export class AssistantMessageEventStream implements AsyncIterable<StreamEvent> {
     const specificListeners = this.listeners.get(event.type);
     if (specificListeners) {
       for (const listener of specificListeners) {
-        try { listener(event); } catch (e) {
+        try {
+          listener(event);
+        } catch (e) {
           // why: one bad listener must not break the stream or other
           // listeners; capture the first exception for inspection instead.
           if (!this.listenerError) {
@@ -180,7 +188,9 @@ export class AssistantMessageEventStream implements AsyncIterable<StreamEvent> {
     const allListeners = this.listeners.get("*");
     if (allListeners) {
       for (const listener of allListeners) {
-        try { listener(event); } catch (e) {
+        try {
+          listener(event);
+        } catch (e) {
           // why: same as above — isolate wildcard-listener failures.
           if (!this.listenerError) {
             this.listenerError = e instanceof Error ? e : new Error(String(e));
@@ -216,7 +226,7 @@ export class AssistantMessageEventStream implements AsyncIterable<StreamEvent> {
       // Never hang result() — ending without a response is a
       // programming error, so fail loudly instead of leaving consumers
       // waiting forever.
-      this.fail(new Error("end() requires response"));
+      this.fail(new ValidationError("end() requires response"));
       return;
     }
     this.finished = true;
@@ -245,13 +255,17 @@ export class AssistantMessageEventStream implements AsyncIterable<StreamEvent> {
   /** Registers a callback invoked once on cancel(). Returns an unsubscribe fn. */
   onCancel(handler: () => void): () => void {
     if (this.cancelled) {
-      try { handler(); } catch {
+      try {
+        handler();
+      } catch {
         // why: a throwing cancel handler must not break the canceller.
       }
       return () => {};
     }
     this.cancelHandlers.add(handler);
-    return () => { this.cancelHandlers.delete(handler); };
+    return () => {
+      this.cancelHandlers.delete(handler);
+    };
   }
 
   /** Cancels the stream: stops background work and rejects result() with AbortError.
@@ -260,16 +274,16 @@ export class AssistantMessageEventStream implements AsyncIterable<StreamEvent> {
     if (this.finished || this.cancelled) return;
     this.cancelled = true;
     for (const h of [...this.cancelHandlers]) {
-      try { h(); } catch {
+      try {
+        h();
+      } catch {
         // why: isolate faulty cancel handlers so every handler still runs.
       }
     }
     this.cancelHandlers.clear();
     const err = reason instanceof Error ? reason : null;
     const abortErr: Error =
-      err && err.name === "AbortError"
-        ? err
-        : Object.assign(new Error("Stream aborted"), { name: "AbortError" });
+      err && err.name === "AbortError" ? err : Object.assign(new Error("Stream aborted"), { name: "AbortError" });
     this.fail(abortErr);
   }
 

package/src/telemetry.ts

@@ -35,7 +35,9 @@ export const telemetryBus: TelemetryBus = (() => {
   const listeners = new Set<TelemetryListener>();
   const deliver = (event: TelemetryEvent): void => {
     for (const l of [...listeners]) {
-      try { l(event); } catch {
+      try {
+        l(event);
+      } catch {
         // why: a faulty telemetry listener must not break the emitting run.
       }
     }
@@ -43,7 +45,9 @@ export const telemetryBus: TelemetryBus = (() => {
   return {
     onEvent(listener: TelemetryListener): () => void {
       listeners.add(listener);
-      return () => { listeners.delete(listener); };
+      return () => {
+        listeners.delete(listener);
+      };
     },
     emitWarning(code: string, message: string, data?: unknown): void {
       try {

package/src/tools/architecture.md

@@ -2,16 +2,18 @@
 
 Defining tools and running them.
 
-| File | What it is |
-| :-- | :-- |
-| `tool.ts` | `tool()` factory, name validation, `toStandardToolDeclarations`, option normalizers. |
-| `schema.ts` | Zod to JSON Schema, `$ref` resolution, `stripSchemaForGoogle`. |
-| `executor.ts` | `executeToolCalls`: validation, concurrency (8 global + per-tool), attempts, timeout, result cap, error scrubbing, `ctx.stop`, `tool.*` events, per-call logs. |
-| `subagent-result.ts` | The private-Symbol brand that marks a result as made by the SDK's delegation tools. |
+| File                 | What it is                                                                                                                                                                                               |
+| :------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `tool.ts`            | `tool()` factory, name validation, `toStandardToolDeclarations`, option normalizers.                                                                                                                     |
+| `schema.ts`          | Zod to JSON Schema, `$ref` resolution, `stripSchemaForGoogle`.                                                                                                                                           |
+| `executor.ts`        | `executeToolCalls`: validation, concurrency (8 global + per-tool), attempts, timeout, result cap, error scrubbing, `ctx.stop`, `tool.*` events, per-call logs.                                           |
+| `tool-content.ts`    | `toolContent([...])`: a branded (private Symbol) tool result of text and media. The executor turns it into `result` (text) plus `parts` (inline data URLs), so only a tool's own code can produce media. |
+| `subagent-result.ts` | The private-Symbol brand that marks a result as made by the SDK's delegation tools.                                                                                                                      |
 
 ## Invariants
+
 - Tool names match `^[a-zA-Z0-9_-]{1,64}$` and must not collide after normalization (checked in the `Agent` constructor).
-- One attempt by default; only idempotent tools retry transient failures; the timeout is best effort (`ctx.signal` is cooperative), and an uncooperative tool no longer holds an aborted run.
+- One attempt by default; only idempotent tools retry transient failures (what counts as transient is the one `isTransientError` in `utils/errors.ts`, shared with the provider retries); the timeout is best effort (`ctx.signal` is cooperative), and an uncooperative tool no longer holds an aborted run.
 - Results are capped by serialized size (default 20000 chars); nested error stacks and absolute paths are scrubbed. The telemetry bus gets full detail, the model gets the scrubbed text.
 - A truncated call (`{ __truncated_raw }`) never executes.
 - `ctx.stop(reason)` throws a private signal; the batch finishes, then the loop ends the run as `stopped`.

package/src/tools/executor.ts

@@ -1,12 +1,12 @@
-import type {
-  ToolDefinition,
-  ToolCallRecord,
-  ToolResultRecord,
-  ToolExecutionContext,
-} from "../types/tool.ts";
+import type { ToolDefinition, ToolCallRecord, ToolResultRecord, ToolExecutionContext } from "../types/tool.ts";
 import { toJsonSafe } from "../utils/serialization.ts";
 import { ConfigError } from "../types/errors.ts";
+import { isTransientError } from "../utils/errors.ts";
 import { isSubagentResult } from "./subagent-result.ts";
+import { isToolContent, type ToolContent } from "./tool-content.ts";
+import { normalizeMediaInput } from "../utils/media.ts";
+import type { ContentPart } from "../types/message.ts";
+import { DEFAULT_PROMPTS, fillPrompt, type Prompts } from "../prompts/prompts.ts";
 import { isTruncatedArguments } from "../types/tool.ts";
 import { telemetryBus } from "../telemetry.ts";
 import type { ToolLogWriter } from "../session/tool-log.ts";
@@ -18,12 +18,20 @@ export interface ExecuteToolsOptions {
   parallel?: boolean;
   signal?: AbortSignal;
   sessionId?: string;
+  /** The refusal texts shown to the model (`AgentConfig.prompts`); the shipped ones when unset. */
+  prompts?: Pick<Prompts, "toolTruncatedArguments" | "toolNotFound" | "toolSchemaError">;
   /** Called the moment EACH call finishes (before the whole batch does), so a caller can save a result before the next tool is done. Never throws into the run. */
   onResult?: (result: ToolResultRecord) => void;
   /** Opens the log file of one call (only when the Agent persists to a folder); the executor writes its steps into it and `ctx.log` writes through it. */
   openToolLog?: (call: ToolCallRecord, sessionId: string | undefined) => ToolLogWriter | undefined;
   /** Forwards live sub-agent deltas (realtime worker thinking/text) to the caller. */
-  onSubagentEvent?: (event: { trackingId: string; delta?: string; thinkingDelta?: string; partialText?: string; partialThinking?: string }) => void;
+  onSubagentEvent?: (event: {
+    trackingId: string;
+    delta?: string;
+    thinkingDelta?: string;
+    partialText?: string;
+    partialThinking?: string;
+  }) => void;
 }
 
 const DEFAULT_TOOL_CONCURRENCY = 8;
@@ -93,9 +101,7 @@ export function isTruncatedToolCall(call: ToolCallRecord): boolean {
  * same name (case/format-insensitive via {@link normalizeToolName}), which
  * would otherwise make model tool calls ambiguous.
  */
-export function assertNoToolCollisions(
-  tools: Record<string, ToolDefinition>
-): void {
+export function assertNoToolCollisions(tools: Record<string, ToolDefinition>): void {
   if (!tools) return;
   const seen = new Map<string, string>();
   for (const [key, definition] of Object.entries(tools)) {
@@ -232,10 +238,11 @@ export function shouldBlockRepeat(
  * machine-readable code lives at `(result as any).errorCode` while the human
  * prefix keeps plain-string consumers working.
  */
-export function makeRepeatBlockedResult(call: ToolCallRecord): ToolResultRecord {
-  const message =
-    `repeat_blocked: Tool '${call.name}' was called again with identical arguments. ` +
-    "The previous result is already available; reuse it or call the tool with different arguments.";
+export function makeRepeatBlockedResult(
+  call: ToolCallRecord,
+  template = DEFAULT_PROMPTS.toolRepeatBlocked
+): ToolResultRecord {
+  const message = fillPrompt(template, { tool: call.name });
   return {
     id: call.id,
     name: call.name,
@@ -296,9 +303,7 @@ function levenshtein(a: string, b: string): number {
     row[0] = i;
     for (let j = 1; j <= b.length; j++) {
       const current = row[j]!;
-      row[j] = a[i - 1] === b[j - 1]
-        ? previous
-        : Math.min(previous + 1, row[j - 1]! + 1, current + 1);
+      row[j] = a[i - 1] === b[j - 1] ? previous : Math.min(previous + 1, row[j - 1]! + 1, current + 1);
       previous = current;
     }
   }
@@ -339,10 +344,7 @@ function resolveTool(tools: Record<string, ToolDefinition>, requestedName: strin
 }
 
 /** Finds a tool definition by exact or case/format-insensitive name (no suggestion logic). */
-export function findToolDefinition(
-  tools: Record<string, ToolDefinition>,
-  name: string
-): ToolDefinition | undefined {
+export function findToolDefinition(tools: Record<string, ToolDefinition>, name: string): ToolDefinition | undefined {
   return resolveTool(tools, name).definition;
 }
 
@@ -401,21 +403,6 @@ class Semaphore {
   }
 }
 
-/**
- * True for retry-worthy failures: explicit opt-in flags (`transient` /
- * `retryable`), retryable HTTP statuses, or retryable network codes. Never
- * matches on message text — message content is untrusted and locale-fragile.
- */
-function isTransientError(error: any): boolean {
-  if (!error) return false;
-  if (error.transient === true || error.retryable === true) return true;
-  const status = Number(error.status ?? error.statusCode ?? error.response?.status);
-  if ([408, 425, 429, 500, 502, 503, 504].includes(status)) return true;
-  const code = String(error.code || "").toUpperCase();
-  if (["ECONNRESET", "ECONNREFUSED", "EAI_AGAIN", "ETIMEDOUT", "EPIPE", "UND_ERR_CONNECT_TIMEOUT"].includes(code)) return true;
-  return false;
-}
-
 // Waits the retry backoff, rejecting `Tool execution aborted` as soon as the run aborts; in: runSingle's retry loop, out: nothing.
 function waitForRetry(ms: number, signal?: AbortSignal): Promise<void> {
   if (ms <= 0) return Promise.resolve();
@@ -497,6 +484,36 @@ async function executeAttempt(
   }
 }
 
+// Turns a `toolContent` result into its text (what every provider sees) and its media as inline data URLs (what Google also sends); in: runSingle for a branded tool result, out: the result record's `result` and `parts`.
+async function resolveToolContent(
+  content: ToolContent,
+  charLimit: number
+): Promise<{ text: string; parts: ContentPart[] }> {
+  const texts: string[] = [];
+  const parts: ContentPart[] = [];
+  const kinds: string[] = [];
+  for (const raw of content.parts) {
+    const part = typeof raw === "string" ? ({ type: "text", text: raw } as const) : raw;
+    if (part.type === "text") {
+      texts.push(part.text);
+      continue;
+    }
+    const value = (part as unknown as Record<string, string | Uint8Array | ArrayBuffer>)[part.type]!;
+    const media = await normalizeMediaInput(value, (part as { mimeType?: string }).mimeType);
+    const filename = (part as { filename?: string }).filename;
+    parts.push({
+      type: part.type,
+      [part.type]: media.dataUrl,
+      mimeType: media.mimeType,
+      ...(filename ? { filename } : {}),
+      ...((part.type === "image" || part.type === "video") && part.resolution ? { resolution: part.resolution } : {}),
+    } as unknown as ContentPart);
+    kinds.push(media.mimeType);
+  }
+  const text = texts.join("\n") || (kinds.length > 0 ? `[media result: ${kinds.join(", ")}]` : "null");
+  return { text: truncateResultString(text, charLimit), parts };
+}
+
 /**
  * Executes one or more tool calls in parallel or sequence, handling errors safely
  */
@@ -505,10 +522,19 @@ async function executeAttempt(
  *
  * @example `const results = await executeToolCalls({ tools, toolCalls });`
  */
-export async function executeToolCalls(
-  options: ExecuteToolsOptions
-): Promise<ToolResultRecord[]> {
-  const { tools, toolCalls, agentName, parallel = true, signal, sessionId, onSubagentEvent, onResult, openToolLog } = options;
+export async function executeToolCalls(options: ExecuteToolsOptions): Promise<ToolResultRecord[]> {
+  const {
+    tools,
+    toolCalls,
+    agentName,
+    parallel = true,
+    signal,
+    sessionId,
+    onSubagentEvent,
+    onResult,
+    openToolLog,
+    prompts = DEFAULT_PROMPTS,
+  } = options;
   assertNoToolCollisions(tools);
   const globalSemaphore = new Semaphore(DEFAULT_TOOL_CONCURRENCY);
   const perToolSemaphores = new Map<string, Semaphore>();
@@ -516,9 +542,7 @@ export async function executeToolCalls(
   const getToolSemaphore = (name: string, definition: ToolDefinition): Semaphore => {
     const existing = perToolSemaphores.get(name);
     if (existing) return existing;
-    const configured = integerOption(
-      definition.maxConcurrency
-    );
+    const configured = integerOption(definition.maxConcurrency);
     const limit = configured && configured > 0 ? configured : DEFAULT_TOOL_CONCURRENCY;
     const semaphore = new Semaphore(limit);
     perToolSemaphores.set(name, semaphore);
@@ -548,9 +572,7 @@ export async function executeToolCalls(
       return {
         id: call.id,
         name: call.name,
-        result:
-          `Error: Tool '${call.name}' arguments are truncated or incomplete and could not be parsed. ` +
-          "Call the tool again with the complete JSON arguments. Do not explain the error, just retry the call.",
+        result: fillPrompt(prompts.toolTruncatedArguments, { tool: call.name }),
         isError: true,
         durationMs: elapsedMs(startTime),
       };
@@ -561,11 +583,11 @@ export async function executeToolCalls(
 
     if (!toolDef) {
       trace("call_blocked", "warn", { reason: "tool_not_found", suggestion: resolved.suggestion });
-      const suffix = resolved.suggestion ? ` Did you mean '${resolved.suggestion}'?` : "";
+      const suggestion = resolved.suggestion ? ` Did you mean '${resolved.suggestion}'?` : "";
       return {
         id: call.id,
         name: call.name,
-        result: `Error: Tool '${call.name}' not found.${suffix}`,
+        result: fillPrompt(prompts.toolNotFound, { tool: call.name, suggestion }),
         isError: true,
         durationMs: elapsedMs(startTime),
       };
@@ -578,7 +600,14 @@ export async function executeToolCalls(
     let stopReason: string | undefined;
     const stoppedResult = (): ToolResultRecord => {
       trace("call_stopped", "warn", { reason: stopReason, attempts, durationMs: elapsedMs(executionStartTime) });
-      return { id: call.id, name: resolved.name, result: stopReason, isError: false, stopped: true, durationMs: elapsedMs(executionStartTime) };
+      return {
+        id: call.id,
+        name: resolved.name,
+        result: stopReason,
+        isError: false,
+        stopped: true,
+        durationMs: elapsedMs(executionStartTime),
+      };
     };
 
     try {
@@ -599,7 +628,8 @@ export async function executeToolCalls(
           stopReason ??= String(reason);
           throw new ToolStopSignal();
         },
-        log: (message, data) => log?.write({ phase: "log", message, ...(data !== undefined ? { data: toJsonSafe(data) } : {}) }),
+        log: (message, data) =>
+          log?.write({ phase: "log", message, ...(data !== undefined ? { data: toJsonSafe(data) } : {}) }),
         emit: (event) => {
           if (event?.type === "progress") progress = event;
           trace(event?.type === "progress" ? "progress" : "event", "info", { event: capJson(event) });
@@ -620,18 +650,12 @@ export async function executeToolCalls(
               ? JSON.stringify(toolDef.parameters).slice(0, 800)
               : undefined;
           const detail = parseRes.error.message;
-          const hint = expectedParams
-            ? ` Expected parameters: ${expectedParams}.`
-            : "";
+          const expected = expectedParams ? ` Expected parameters: ${expectedParams}.` : "";
           trace("call_blocked", "warn", { reason: "schema_validation", detail: parseRes.error.message });
           return {
             id: call.id,
             name: call.name,
-            result:
-              `Schema validation error for tool '${call.name}': ${detail}` +
-              ` Received argument keys: [${receivedKeys}].` +
-              hint +
-              ` Fix the arguments and call the tool again with corrected JSON. Do not explain the error, just retry the call.`,
+            result: fillPrompt(prompts.toolSchemaError, { tool: call.name, detail, keys: receivedKeys, expected }),
             isError: true,
             durationMs: elapsedMs(startTime),
           };
@@ -648,7 +672,7 @@ export async function executeToolCalls(
       // Attempts run serially in the while loop below — never concurrently —
       // so a non-idempotent tool cannot execute twice at the same time.
       const isIdempotent = (toolDef as any).idempotent === true;
-      const maxAttempts = configuredTries && configuredTries > 0 ? configuredTries : (isIdempotent ? 3 : 1);
+      const maxAttempts = configuredTries && configuredTries > 0 ? configuredTries : isIdempotent ? 3 : 1;
       const timeoutMs = numericOption(toolDef.timeoutMs);
       // Telemetry starts when the tool body is about to run, excluding queue
       // wait and schema validation. Retries/backoff remain part of this call.
@@ -668,8 +692,16 @@ export async function executeToolCalls(
           if (stopReason !== undefined) throw err; // ctx.stop: not a failure, never retried
           timedOut = err?.toolTimeout === true;
           const willRetry =
-            isTransientError(err) && attempt < maxAttempts && !(err?.code === "ETIMEDOUT" && (!configuredTries || configuredTries <= 0));
-          trace("attempt_failed", "warn", { attempt, maxAttempts, willRetry, error: describeError(err), progress: capJson(progress) });
+            isTransientError(err) &&
+            attempt < maxAttempts &&
+            !(err?.code === "ETIMEDOUT" && (!configuredTries || configuredTries <= 0));
+          trace("attempt_failed", "warn", {
+            attempt,
+            maxAttempts,
+            willRetry,
+            error: describeError(err),
+            progress: capJson(progress),
+          });
           if (!isTransientError(err) || attempt >= maxAttempts) throw err;
           // A timeout is a deliberate per-attempt deadline, not a parent
           // cancellation (which rejects via the abort signal instead and is
@@ -692,6 +724,19 @@ export async function executeToolCalls(
       log?.write({ phase: "result", result: isSubagentResult(rawResult) ? rawResult.xml : toJsonSafe(rawResult) });
       const finishOk = (resultChars: number): void =>
         trace("call_succeeded", "info", { attempts: attempt, durationMs: elapsedMs(executionStartTime), resultChars });
+      // Text and media from `toolContent`: the text is the result, the media rides in `parts` (inline data, set only here).
+      if (isToolContent(rawResult)) {
+        const { text, parts } = await resolveToolContent(rawResult, resultCharLimit(toolDef));
+        finishOk(text.length);
+        return {
+          id: call.id,
+          name: resolved.name,
+          result: text,
+          ...(parts.length > 0 ? { parts } : {}),
+          isError: false,
+          durationMs: elapsedMs(executionStartTime),
+        };
+      }
       if (rawResult === undefined) {
         finishOk(4);
         return {
@@ -765,7 +810,9 @@ export async function executeToolCalls(
               error: {
                 name: err?.name,
                 ...(err?.code !== undefined ? { code: err.code } : {}),
-                ...(err?.status !== undefined || err?.statusCode !== undefined ? { status: err.status ?? err.statusCode } : {}),
+                ...(err?.status !== undefined || err?.statusCode !== undefined
+                  ? { status: err.status ?? err.statusCode }
+                  : {}),
               },
             }),
         attempts,

package/src/tools/schema.ts

@@ -65,7 +65,11 @@ export function zodToJsonSchema(schema: unknown): Record<string, unknown> {
  *
  * @example `const clean = cleanJsonSchema(rawSchema);`
  */
-export function cleanJsonSchema(schema: any, rootDefs?: Record<string, any>, seenRefs: Set<string> = new Set()): Record<string, unknown> {
+export function cleanJsonSchema(
+  schema: any,
+  rootDefs?: Record<string, any>,
+  seenRefs: Set<string> = new Set()
+): Record<string, unknown> {
   if (typeof schema !== "object" || schema === null) {
     return schema;
   }
@@ -115,7 +119,8 @@ export function cleanJsonSchema(schema: any, rootDefs?: Record<string, any>, see
   if (rest.anyOf) rest.anyOf = (rest.anyOf as any[]).map((v: any) => cleanJsonSchema(v, defs, seenRefs));
   if (rest.oneOf) rest.oneOf = (rest.oneOf as any[]).map((v: any) => cleanJsonSchema(v, defs, seenRefs));
   if (rest.allOf) rest.allOf = (rest.allOf as any[]).map((v: any) => cleanJsonSchema(v, defs, seenRefs));
-  if (rest.prefixItems) rest.prefixItems = (rest.prefixItems as any[]).map((v: any) => cleanJsonSchema(v, defs, seenRefs));
+  if (rest.prefixItems)
+    rest.prefixItems = (rest.prefixItems as any[]).map((v: any) => cleanJsonSchema(v, defs, seenRefs));
   // Recursively clean nested $ref inside properties that were not top-level
   for (const k of Object.keys(rest)) {
     if (rest[k] && typeof rest[k] === "object" && !Array.isArray(rest[k]) && (rest[k] as any).$ref) {
@@ -142,9 +147,7 @@ function extractZodObjectSchema(zodSchema: any): Record<string, unknown> {
 
   for (const [key, propSchema] of Object.entries(shape as Record<string, any>)) {
     const isOptional =
-      propSchema.isOptional?.() ||
-      propSchema._def?.typeName === "ZodOptional" ||
-      propSchema._def?.type === "optional";
+      propSchema.isOptional?.() || propSchema._def?.typeName === "ZodOptional" || propSchema._def?.type === "optional";
 
     if (!isOptional) {
       required.push(key);
@@ -169,7 +172,8 @@ function inferZodPropertyType(prop: any): Record<string, unknown> {
   const tn = String(typeName).toLowerCase();
 
   if (tn.includes("number") || tn === "zodnumber") return { type: "number", ...(description ? { description } : {}) };
-  if (tn.includes("boolean") || tn === "zodboolean") return { type: "boolean", ...(description ? { description } : {}) };
+  if (tn.includes("boolean") || tn === "zodboolean")
+    return { type: "boolean", ...(description ? { description } : {}) };
   if (tn.includes("integer")) return { type: "integer", ...(description ? { description } : {}) };
   if (tn.includes("enum") || tn === "zodenum") {
     const vals = unwrapped._def?.values || unwrapped._def?.entries || [];

package/src/tools/subagent-result.ts

@@ -49,7 +49,12 @@ export function normalizeSubagentMetadata(metas: unknown): SubAgentExecutionMeta
     if (!raw || typeof raw !== "object") continue;
     const m = raw as Record<string, unknown>;
     const u = (m.usage && typeof m.usage === "object" ? m.usage : {}) as Record<string, unknown>;
-    const usage = { ...u, inputTokens: num(u.inputTokens), outputTokens: num(u.outputTokens), totalTokens: num(u.totalTokens) };
+    const usage = {
+      ...u,
+      inputTokens: num(u.inputTokens),
+      outputTokens: num(u.outputTokens),
+      totalTokens: num(u.totalTokens),
+    };
     out.push({
       ...(m as unknown as SubAgentExecutionMetadata),
       model: typeof m.model === "string" ? m.model : "unknown",