agents 0.24.0 → 0.26.0

package/dist/agent-tool-types.d.ts

@@ -1,36 +1,40 @@
 import {
-  $ as DetachedAgentToolConfig,
-  B as AgentToolInterruptedReason,
+  $ as ChatCapableAgentClass,
+  B as AgentToolFailure,
   F as AgentToolDisplayMetadata,
-  G as AgentToolRunInfo,
-  H as AgentToolMilestone,
+  G as AgentToolProgressSnapshot,
+  H as AgentToolLifecycleResult,
   I as AgentToolEvent,
-  J as AgentToolRunState,
-  K as AgentToolRunInspection,
-  L as AgentToolEventMessage,
+  J as AgentToolRunPart,
+  K as AgentToolRunInfo,
+  L as AgentToolEventDelivery,
   M as AGENT_TOOL_MILESTONE_PART,
   N as AGENT_TOOL_PROGRESS_PART,
   P as AgentToolChildAdapter,
-  Q as ChatCapableAgentClass,
-  R as AgentToolEventState,
-  U as AgentToolProgress,
-  V as AgentToolLifecycleResult,
-  W as AgentToolProgressSnapshot,
-  X as AgentToolStoredChunk,
-  Y as AgentToolRunStatus,
-  Z as AgentToolTerminalStatus,
-  et as DetachedRunAgentToolResult,
-  nt as RunAgentToolResult,
-  q as AgentToolRunPart,
-  tt as RunAgentToolOptions,
-  z as AgentToolFailure
-} from "./agent-routing-B2XLNMxq.js";
+  Q as AgentToolTerminalStatus,
+  R as AgentToolEventMessage,
+  U as AgentToolMilestone,
+  V as AgentToolInterruptedReason,
+  W as AgentToolProgress,
+  X as AgentToolRunStatus,
+  Y as AgentToolRunState,
+  Z as AgentToolStoredChunk,
+  at as isPositionlessAgentToolChunk,
+  et as DetachedAgentToolConfig,
+  it as isAgentToolLifecycleChunk,
+  nt as RunAgentToolOptions,
+  q as AgentToolRunInspection,
+  rt as RunAgentToolResult,
+  tt as DetachedRunAgentToolResult,
+  z as AgentToolEventState
+} from "./agent-routing-0DR0Tk2v.js";
 export {
   AGENT_TOOL_MILESTONE_PART,
   AGENT_TOOL_PROGRESS_PART,
   AgentToolChildAdapter,
   AgentToolDisplayMetadata,
   AgentToolEvent,
+  AgentToolEventDelivery,
   AgentToolEventMessage,
   AgentToolEventState,
   AgentToolFailure,
@@ -50,5 +54,7 @@ export {
   DetachedAgentToolConfig,
   DetachedRunAgentToolResult,
   RunAgentToolOptions,
-  RunAgentToolResult
+  RunAgentToolResult,
+  isAgentToolLifecycleChunk,
+  isPositionlessAgentToolChunk
 };

package/dist/agent-tool-types.js

@@ -14,7 +14,29 @@ const AGENT_TOOL_PROGRESS_PART = "data-agent-progress";
 * re-resolves milestone waiters. See `design/rfc-detached-agent-tools.md`.
 */
 const AGENT_TOOL_MILESTONE_PART = "data-agent-milestone";
+/**
+* Whether a chunk body is a progress or milestone frame. These are broadcast
+* but never written to the child's chunk store, so they have no stored-chunk
+* position and must not take part in stored-position numbering or dedupe.
+*/
+function isAgentToolLifecycleChunk(body) {
+	if (!body.includes("data-agent-progress") && !body.includes("data-agent-milestone")) return false;
+	try {
+		const type = JSON.parse(body)?.type;
+		return type === "data-agent-progress" || type === "data-agent-milestone";
+	} catch {
+		return false;
+	}
+}
+/**
+* Whether a forwarded chunk has no stored-chunk position: a progress or
+* milestone frame, or a chunk too large to store. Such chunks carry the next
+* stored position without consuming it.
+*/
+function isPositionlessAgentToolChunk(chunk) {
+	return chunk.unstoredId !== void 0 || isAgentToolLifecycleChunk(chunk.body);
+}
 //#endregion
-export { AGENT_TOOL_MILESTONE_PART, AGENT_TOOL_PROGRESS_PART };
+export { AGENT_TOOL_MILESTONE_PART, AGENT_TOOL_PROGRESS_PART, isAgentToolLifecycleChunk, isPositionlessAgentToolChunk };
 
 //# sourceMappingURL=agent-tool-types.js.map

package/dist/agent-tool-types.js.map

@@ -1 +1 @@
-{"version":3,"file":"agent-tool-types.js","names":[],"sources":["../src/agent-tool-types.ts"],"sourcesContent":["import type { Agent, SubAgentClass } from \"./index\";\n\nexport type AgentToolRunStatus =\n  | \"starting\"\n  | \"running\"\n  | \"completed\"\n  | \"error\"\n  | \"aborted\"\n  | \"interrupted\";\n\nexport type AgentToolTerminalStatus = Extract<\n  AgentToolRunStatus,\n  \"completed\" | \"error\" | \"aborted\" | \"interrupted\"\n>;\n\n/**\n * Machine-readable cause of an `interrupted` seal (#1630 follow-up). Lets a\n * caller branch on WHY a run was abandoned without parsing the human-readable\n * `error` prose, which is not a stable contract.\n *\n * - `no-progress` — the child went silent for a full no-progress window while\n *   the parent was tailing it (genuinely stalled / hung).\n * - `window-exceeded` — a finite `agentToolReattachMaxWindowMs` ceiling elapsed\n *   while the child was still non-terminal. Only fires when an integrator opts\n *   into a hard wall-clock cap (the default ceiling is `Infinity`).\n * - `not-tailable` — the child runtime cannot live-tail, so the parent could\n *   not re-attach to its stream to follow it to terminal.\n * - `inspect-timeout` — inspecting the child timed out during parent recovery.\n * - `inspect-failed` — inspecting the child failed during parent recovery.\n * - `recovery-deadline` — the overall parent-recovery deadline elapsed before\n *   this run could be reconciled.\n * - `budget-exceeded` — a detached run's absolute `maxBudgetMs` ceiling elapsed\n *   before it reached a terminal. The parent gave up watching and tore the\n *   child down. Like `window-exceeded` this is a soft seal: a child that\n *   completes anyway can still repair the run and re-fire the completion hook.\n */\nexport type AgentToolInterruptedReason =\n  | \"no-progress\"\n  | \"window-exceeded\"\n  | \"not-tailable\"\n  | \"inspect-timeout\"\n  | \"inspect-failed\"\n  | \"recovery-deadline\"\n  | \"budget-exceeded\";\n\n/**\n * Structured failure envelope an `agentTool()` returns when a sub-agent run\n * does not complete. Instead of an opaque error string the parent model would\n * parrot back to the user, the caller (or an orchestration harness) gets a\n * machine-readable signal:\n *\n * - `status` mirrors the underlying terminal status (`error` | `aborted` |\n *   `interrupted`).\n * - `retryable` is `true` only for a transient interruption — the child was\n *   reset or superseded by a deploy / parent recovery and never reached a\n *   logical outcome, so re-dispatching the same run is the right move. A\n *   genuine `error` or an intentional `aborted` is `false`.\n * - `error` stays human-readable for logs and UI.\n */\nexport type AgentToolFailure = {\n  ok: false;\n  status: Exclude<AgentToolTerminalStatus, \"completed\">;\n  error: string;\n  retryable: boolean;\n  /** Present only when `status` is `interrupted` — machine-readable cause. */\n  reason?: AgentToolInterruptedReason;\n  /**\n   * Present only when `status` is `interrupted`. `true` when the child facet was\n   * still non-terminal (running / advancing) at the moment the parent stopped\n   * waiting; `false` once the parent has torn the child down so it is no longer\n   * doing work. Lets a caller decide between re-dispatching vs. reconnecting.\n   */\n  childStillRunning?: boolean;\n};\n\nexport type AgentToolDisplayMetadata = {\n  name?: string;\n  icon?: string;\n} & Record<string, unknown>;\n\n/**\n * Reserved chunk type a sub-agent emits via `reportProgress` while it runs.\n * Rides the child's own UI-message stream as a **transient** data part, so it\n * re-broadcasts to the parent's clients (via the parent's tail) and surfaces in\n * `useAgentToolEvents` without persisting into the child's stored message parts.\n * See `design/rfc-detached-agent-tools.md` §\"Progress and milestone signaling\".\n */\nexport const AGENT_TOOL_PROGRESS_PART = \"data-agent-progress\";\n\n/**\n * Reserved chunk type a sub-agent emits via `reportProgress({ milestone })`.\n * Unlike the ephemeral progress part this rides the child's stream as a\n * **persisted** data part, so it survives eviction, replays on drill-in, and\n * re-resolves milestone waiters. See `design/rfc-detached-agent-tools.md`.\n */\nexport const AGENT_TOOL_MILESTONE_PART = \"data-agent-milestone\";\n\n/**\n * Ephemeral progress signal a running sub-agent emits with `reportProgress`. The\n * well-known fields drive generic UI (a bar + status line) with no per-app\n * convention; `data` is an app-specific escape hatch that is **live-only** by\n * default (not persisted) unless `reportProgress(p, { persist: true })`. Naming a\n * `milestone` promotes the signal to the **durable** tier: it persists as one row\n * per milestone, replays, and (with `data`) is retained.\n */\nexport type AgentToolProgress<T = unknown> = {\n  /** 0..1 — drives a progress bar. */\n  fraction?: number;\n  /** Human-readable status line, e.g. \"Ingested 40k/80k rows\". */\n  message?: string;\n  /** Coarse stage label, e.g. \"scaffolding\" | \"deploying\". */\n  phase?: string;\n  /**\n   * Present ⇒ a **durable** milestone: persisted, replayable, and surfaced as a\n   * distinct row in `AgentToolRunState.milestones` / `inspectAgentToolRun`. Use\n   * for named phase boundaries (\"schema-ready\", \"preview-ready\", \"deployed\").\n   */\n  milestone?: string;\n  /** App-specific payload; live-only for progress, persisted for milestones. */\n  data?: T;\n};\n\n/**\n * A durable milestone a sub-agent reached, projected onto `AgentToolRunState`\n * and `inspectAgentToolRun`. `sequence` is monotonic per run so replay/live\n * races dedupe on `(runId, sequence)`.\n */\nexport type AgentToolMilestone = {\n  name: string;\n  /** Monotonic per-run ordinal; dedupe key for replay vs live races. */\n  sequence: number;\n  /** Epoch ms the milestone was reached. */\n  at: number;\n  /** App-specific payload carried with the milestone (persisted). */\n  data?: unknown;\n};\n\n/**\n * Latest progress snapshot persisted on the child run row and surfaced through\n * `inspectAgentToolRun` + `AgentToolRunState`. Only the safe-to-inspect fields\n * are retained by default; `at` is the emit timestamp (drives the resetting\n * no-progress budget).\n */\nexport type AgentToolProgressSnapshot = {\n  fraction?: number;\n  message?: string;\n  phase?: string;\n  /**\n   * Set when this signal was a durable milestone (`reportProgress({ milestone })`).\n   * Lets an `onProgress` consumer branch on milestone vs. ephemeral progress.\n   */\n  milestone?: string;\n  /** Epoch ms of the latest signal. */\n  at: number;\n  /** Present only when the emitter opted into persisting `data`. */\n  data?: unknown;\n};\n\nexport type AgentToolRunInfo = {\n  runId: string;\n  parentToolCallId?: string;\n  agentType: string;\n  inputPreview?: unknown;\n  status: AgentToolRunStatus;\n  display?: AgentToolDisplayMetadata;\n  /**\n   * Caller-controlled `metadata.source` for chat-agent `detached.notify`\n   * completions. Present only for detached notify runs that supplied one.\n   */\n  notifySource?: string;\n  displayOrder: number;\n  startedAt: number;\n  completedAt?: number;\n};\n\nexport type AgentToolLifecycleResult = {\n  status: AgentToolTerminalStatus;\n  summary?: string;\n  error?: string;\n  /** Present only when `status` is `interrupted` — machine-readable cause. */\n  reason?: AgentToolInterruptedReason;\n  /**\n   * Present only when `status` is `interrupted`. Whether the child facet was\n   * still non-terminal when the parent stopped waiting (before any teardown).\n   */\n  childStillRunning?: boolean;\n};\n\n/**\n * Configuration for a detached (\"background\") agent-tool run. See\n * `design/rfc-detached-agent-tools.md`.\n *\n * Callbacks are referenced by **method name** on the dispatching agent (the same\n * durable, eviction-surviving pattern as `Agent.schedule`) — never closures,\n * which cannot be rehydrated after the Durable Object is evicted.\n *\n * `Self` is threaded from `runAgentTool(cls, options)` so the method names are\n * type-checked against the calling agent's own methods.\n */\nexport type DetachedAgentToolConfig<Self = Record<string, unknown>> = {\n  /**\n   * Method invoked once per terminal delivery. Branch on `result.status`:\n   * `\"completed\" | \"error\" | \"aborted\" | \"interrupted\"`. A budget give-up\n   * arrives as `status: \"interrupted\"` with `reason: \"budget-exceeded\"`; because\n   * `interrupted` is soft, a child that later completes can fire the hook again\n   * with `\"completed\"`, so a give-up never hides a late real result. Make the\n   * handler idempotent.\n   */\n  onFinish?: Extract<keyof Self, string>;\n  /**\n   * Absolute safety ceiling — a backstop against a child that runs forever. On\n   * expiry the parent gives up watching (delivers `onFinish` with\n   * `interrupted` / `budget-exceeded`) and tears the child down. Defaults to the\n   * parent-level `detachedMaxBudgetMs`.\n   */\n  maxBudgetMs?: number;\n  /**\n   * Per-run override of the resetting no-progress window (ms). Once the child\n   * emits its first `reportProgress`, the parent gives up if it then goes silent\n   * for this long (resets on each signal). Defaults to the parent-level\n   * `detachedNoProgressBudgetMs` (1h). `0`/`Infinity` disables it.\n   */\n  noProgressBudgetMs?: number;\n  /**\n   * Chat-agent convenience (`@cloudflare/think` / `AIChatAgent`): when the run\n   * finishes, inject a message into the chat so the model can react to the\n   * result, instead of you wiring `onFinish` by hand. Sugar that auto-targets\n   * the agent's `_cfDetachedNotifyFinish` hook; ignored on a base `Agent` that\n   * does not implement it, and ignored when `onFinish` is also set (an explicit\n   * `onFinish` wins). Pass `{ source }` to fit the injected message into your\n   * app's existing metadata taxonomy. Override `formatDetachedCompletion()` to\n   * customize the injected text.\n   */\n  notify?: boolean | { source?: string };\n  /**\n   * Chat-agent convenience: milestone names that, when the detached run reaches\n   * them, surface an idempotent synthetic message in the chat BEFORE the run\n   * finishes. Each `(runId, name)` fires at most once (idempotency-keyed),\n   * whether observed live or reconciled after eviction. Override the wording via\n   * `formatDetachedMilestone()`. Requires a chat host (`@cloudflare/think`); a\n   * no-op on a base `Agent`.\n   *\n   * Two delivery modes (the string-array shorthand defaults to `\"narrate\"`):\n   * - `\"narrate\"` (default) — inject a synthetic **assistant** message directly\n   *   (no inference): a cheap, honest status line (\"Found 2 sources…\") that does\n   *   not trigger a model turn. Best for pure progress narration.\n   * - `\"react\"` — inject a **user-role** turn so the model responds to the\n   *   milestone (steer, start dependent work, narrate with context). Costs a\n   *   model turn. Opt in for milestones the agent should *act on*.\n   */\n  onMilestones?: string[] | { names: string[]; mode?: \"react\" | \"narrate\" };\n};\n\nexport type RunAgentToolOptions<\n  Input = unknown,\n  Self = Record<string, unknown>\n> = {\n  input: Input;\n  runId?: string;\n  parentToolCallId?: string;\n  displayOrder?: number;\n  signal?: AbortSignal;\n  inputPreview?: unknown;\n  display?: AgentToolDisplayMetadata;\n  /**\n   * Run the sub-agent **detached**: dispatch it, let the current turn continue,\n   * and (optionally) get a durable callback when it finishes. `true` is\n   * fire-and-forget (observe via `agent-tool-event` frames + the global\n   * `onAgentToolFinish` hook); an object adds the targeted, eviction-surviving\n   * `onFinish` callback. A detached run does NOT inherit `options.signal` — it\n   * must outlive the spawning turn; cancel it explicitly via `cancelAgentTool`.\n   */\n  detached?: boolean | DetachedAgentToolConfig<Self>;\n};\n\n/**\n * Result of dispatching a detached run. Returns immediately after dispatch\n * rather than after completion.\n */\nexport type DetachedRunAgentToolResult = {\n  runId: string;\n  agentType: string;\n  /**\n   * `\"running\"` on a successful dispatch; `\"error\"` if dispatch itself failed\n   * (e.g. the `maxConcurrentAgentTools` cap was exceeded — rejected\n   * synchronously, no child started, no callback wired).\n   */\n  status: \"running\" | \"error\";\n  error?: string;\n};\n\nexport type RunAgentToolResult<Output = unknown> = {\n  runId: string;\n  agentType: string;\n  status: AgentToolTerminalStatus;\n  output?: Output;\n  summary?: string;\n  error?: string;\n  /**\n   * Present only when `status` is `interrupted` — a machine-readable cause so\n   * callers don't pattern-match the `error` prose (#1630 follow-up).\n   */\n  reason?: AgentToolInterruptedReason;\n  /**\n   * Present only when `status` is `interrupted`. `true` when the child facet was\n   * still non-terminal (running / advancing) at the moment the parent stopped\n   * waiting and before any teardown; `false` once the parent has torn the child\n   * down so it is no longer doing work.\n   */\n  childStillRunning?: boolean;\n};\n\nexport type ChatCapableAgentClass<T extends Agent = Agent> = SubAgentClass<T>;\n\nexport type AgentToolRunInspection<Output = unknown> = {\n  runId: string;\n  status: Exclude<AgentToolRunStatus, \"interrupted\">;\n  requestId?: string;\n  streamId?: string;\n  output?: Output;\n  summary?: string;\n  error?: string;\n  startedAt: number;\n  completedAt?: number;\n  /**\n   * Latest progress snapshot the child has persisted, so a rehydrated parent\n   * (recovery / backbone reconcile) can reconstruct \"where is this run\" and\n   * reset the resetting no-progress budget without having tailed the live\n   * stream. Absent until the child emits its first `reportProgress`.\n   */\n  progress?: AgentToolProgressSnapshot;\n  /**\n   * Durable milestones the child has persisted, ordered by `sequence`. Lets a\n   * rehydrated parent (recovery / backbone reconcile) replay milestone-gated\n   * work and milestone notifications without having observed the live stream.\n   */\n  milestones?: AgentToolMilestone[];\n};\n\nexport type AgentToolStoredChunk = {\n  sequence: number;\n  body: string;\n};\n\nexport type AgentToolChildAdapter<Input = unknown, Output = unknown> = {\n  startAgentToolRun(\n    input: Input,\n    options: { runId: string; signal?: AbortSignal }\n  ): Promise<AgentToolRunInspection<Output>>;\n  cancelAgentToolRun(runId: string, reason?: unknown): Promise<void>;\n  inspectAgentToolRun(\n    runId: string\n  ): Promise<AgentToolRunInspection<Output> | null>;\n  getAgentToolChunks(\n    runId: string,\n    options?: { afterSequence?: number }\n  ): Promise<AgentToolStoredChunk[]>;\n  tailAgentToolRun?(\n    runId: string,\n    options?: { afterSequence?: number; signal?: AbortSignal }\n  ): Promise<ReadableStream<AgentToolStoredChunk>>;\n};\n\nexport type AgentToolEvent =\n  | {\n      kind: \"started\";\n      runId: string;\n      agentType: string;\n      inputPreview?: unknown;\n      order: number;\n      display?: AgentToolDisplayMetadata;\n    }\n  | {\n      kind: \"chunk\";\n      runId: string;\n      body: string;\n    }\n  | {\n      kind: \"finished\";\n      runId: string;\n      summary: string;\n    }\n  | {\n      kind: \"error\";\n      runId: string;\n      error: string;\n    }\n  | {\n      kind: \"aborted\";\n      runId: string;\n      reason?: string;\n    }\n  | {\n      kind: \"interrupted\";\n      runId: string;\n      error: string;\n      /** Machine-readable cause of the interrupt (#1630 follow-up). */\n      reason?: AgentToolInterruptedReason;\n      /**\n       * Whether the child facet was still non-terminal when the parent stopped\n       * waiting (before any teardown). Lets a UI distinguish a still-running\n       * child from one the parent has torn down.\n       */\n      childStillRunning?: boolean;\n    };\n\nexport type AgentToolEventMessage = {\n  type: \"agent-tool-event\";\n  parentToolCallId?: string;\n  sequence: number;\n  replay?: true;\n  event: AgentToolEvent;\n};\n\nexport type AgentToolRunPart = { type: string };\n\nexport type AgentToolRunState<\n  Part extends AgentToolRunPart = AgentToolRunPart\n> = {\n  runId: string;\n  agentType: string;\n  parentToolCallId?: string;\n  inputPreview?: unknown;\n  order: number;\n  display?: AgentToolDisplayMetadata;\n  status: \"running\" | \"completed\" | \"error\" | \"aborted\" | \"interrupted\";\n  /**\n   * Message parts reconstructed from the child agent's streamed chunks.\n   *\n   * The default stays framework-neutral so importing `agents` does not require\n   * an AI SDK peer. AI SDK consumers can use\n   * `AgentToolRunState<UIMessage[\"parts\"][number]>` when they need its exact\n   * discriminated union.\n   */\n  parts: Part[];\n  summary?: string;\n  error?: string;\n  /**\n   * Present only when `status` is `interrupted` — machine-readable cause and\n   * whether the child is still running, mirrored from the wire event so a UI\n   * can render the reason without parsing `error` (#1630 follow-up).\n   */\n  reason?: AgentToolInterruptedReason;\n  childStillRunning?: boolean;\n  /**\n   * Latest progress snapshot, projected from the child's transient\n   * `data-agent-progress` signals so a UI can render a bar / ETA / phase label\n   * for a running (especially detached / background) run without drilling in.\n   */\n  progress?: AgentToolProgressSnapshot;\n  /**\n   * Durable milestones the run has reached, ordered by `sequence` (deduped\n   * across replay/live races). Drives milestone chips / a phase timeline.\n   */\n  milestones?: AgentToolMilestone[];\n  subAgent: { agent: string; name: string };\n};\n\nexport type AgentToolEventState<\n  Part extends AgentToolRunPart = AgentToolRunPart\n> = {\n  runsById: Record<string, AgentToolRunState<Part>>;\n  runsByToolCallId: Record<string, AgentToolRunState<Part>[]>;\n  unboundRuns: AgentToolRunState<Part>[];\n};\n"],"mappings":";;;;;;;;AAuFA,MAAa,2BAA2B;;;;;;;AAQxC,MAAa,4BAA4B"}
+{"version":3,"file":"agent-tool-types.js","names":[],"sources":["../src/agent-tool-types.ts"],"sourcesContent":["import type { Agent, SubAgentClass } from \"./index\";\n\nexport type AgentToolRunStatus =\n  | \"starting\"\n  | \"running\"\n  | \"completed\"\n  | \"error\"\n  | \"aborted\"\n  | \"interrupted\";\n\nexport type AgentToolTerminalStatus = Extract<\n  AgentToolRunStatus,\n  \"completed\" | \"error\" | \"aborted\" | \"interrupted\"\n>;\n\n/**\n * Machine-readable cause of an `interrupted` seal (#1630 follow-up). Lets a\n * caller branch on WHY a run was abandoned without parsing the human-readable\n * `error` prose, which is not a stable contract.\n *\n * - `no-progress` — the child went silent for a full no-progress window while\n *   the parent was tailing it (genuinely stalled / hung).\n * - `window-exceeded` — a finite `agentToolReattachMaxWindowMs` ceiling elapsed\n *   while the child was still non-terminal. Only fires when an integrator opts\n *   into a hard wall-clock cap (the default ceiling is `Infinity`).\n * - `not-tailable` — the child runtime cannot live-tail, so the parent could\n *   not re-attach to its stream to follow it to terminal.\n * - `inspect-timeout` — inspecting the child timed out during parent recovery.\n * - `inspect-failed` — inspecting the child failed during parent recovery.\n * - `recovery-deadline` — the overall parent-recovery deadline elapsed before\n *   this run could be reconciled.\n * - `budget-exceeded` — a detached run's absolute `maxBudgetMs` ceiling elapsed\n *   before it reached a terminal. The parent gave up watching and tore the\n *   child down. Like `window-exceeded` this is a soft seal: a child that\n *   completes anyway can still repair the run and re-fire the completion hook.\n */\nexport type AgentToolInterruptedReason =\n  | \"no-progress\"\n  | \"window-exceeded\"\n  | \"not-tailable\"\n  | \"inspect-timeout\"\n  | \"inspect-failed\"\n  | \"recovery-deadline\"\n  | \"budget-exceeded\";\n\n/**\n * Structured failure envelope an `agentTool()` returns when a sub-agent run\n * does not complete. Instead of an opaque error string the parent model would\n * parrot back to the user, the caller (or an orchestration harness) gets a\n * machine-readable signal:\n *\n * - `status` mirrors the underlying terminal status (`error` | `aborted` |\n *   `interrupted`).\n * - `retryable` is `true` only for a transient interruption — the child was\n *   reset or superseded by a deploy / parent recovery and never reached a\n *   logical outcome, so re-dispatching the same run is the right move. A\n *   genuine `error` or an intentional `aborted` is `false`.\n * - `error` stays human-readable for logs and UI.\n */\nexport type AgentToolFailure = {\n  ok: false;\n  status: Exclude<AgentToolTerminalStatus, \"completed\">;\n  error: string;\n  retryable: boolean;\n  /** Present only when `status` is `interrupted` — machine-readable cause. */\n  reason?: AgentToolInterruptedReason;\n  /**\n   * Present only when `status` is `interrupted`. `true` when the child facet was\n   * still non-terminal (running / advancing) at the moment the parent stopped\n   * waiting; `false` once the parent has torn the child down so it is no longer\n   * doing work. Lets a caller decide between re-dispatching vs. reconnecting.\n   */\n  childStillRunning?: boolean;\n};\n\nexport type AgentToolDisplayMetadata = {\n  name?: string;\n  icon?: string;\n} & Record<string, unknown>;\n\n/**\n * Reserved chunk type a sub-agent emits via `reportProgress` while it runs.\n * Rides the child's own UI-message stream as a **transient** data part, so it\n * re-broadcasts to the parent's clients (via the parent's tail) and surfaces in\n * `useAgentToolEvents` without persisting into the child's stored message parts.\n * See `design/rfc-detached-agent-tools.md` §\"Progress and milestone signaling\".\n */\nexport const AGENT_TOOL_PROGRESS_PART = \"data-agent-progress\";\n\n/**\n * Reserved chunk type a sub-agent emits via `reportProgress({ milestone })`.\n * Unlike the ephemeral progress part this rides the child's stream as a\n * **persisted** data part, so it survives eviction, replays on drill-in, and\n * re-resolves milestone waiters. See `design/rfc-detached-agent-tools.md`.\n */\nexport const AGENT_TOOL_MILESTONE_PART = \"data-agent-milestone\";\n\n/**\n * Whether a chunk body is a progress or milestone frame. These are broadcast\n * but never written to the child's chunk store, so they have no stored-chunk\n * position and must not take part in stored-position numbering or dedupe.\n */\nexport function isAgentToolLifecycleChunk(body: string): boolean {\n  if (\n    !body.includes(AGENT_TOOL_PROGRESS_PART) &&\n    !body.includes(AGENT_TOOL_MILESTONE_PART)\n  ) {\n    return false;\n  }\n  try {\n    const type = (JSON.parse(body) as { type?: unknown } | null)?.type;\n    return (\n      type === AGENT_TOOL_PROGRESS_PART || type === AGENT_TOOL_MILESTONE_PART\n    );\n  } catch {\n    return false;\n  }\n}\n\n/**\n * Whether a forwarded chunk has no stored-chunk position: a progress or\n * milestone frame, or a chunk too large to store. Such chunks carry the next\n * stored position without consuming it.\n */\nexport function isPositionlessAgentToolChunk(\n  chunk: AgentToolStoredChunk\n): boolean {\n  return (\n    chunk.unstoredId !== undefined || isAgentToolLifecycleChunk(chunk.body)\n  );\n}\n\n/**\n * Ephemeral progress signal a running sub-agent emits with `reportProgress`. The\n * well-known fields drive generic UI (a bar + status line) with no per-app\n * convention; `data` is an app-specific escape hatch that is **live-only** by\n * default (not persisted) unless `reportProgress(p, { persist: true })`. Naming a\n * `milestone` promotes the signal to the **durable** tier: it persists as one row\n * per milestone, replays, and (with `data`) is retained.\n */\nexport type AgentToolProgress<T = unknown> = {\n  /** 0..1 — drives a progress bar. */\n  fraction?: number;\n  /** Human-readable status line, e.g. \"Ingested 40k/80k rows\". */\n  message?: string;\n  /** Coarse stage label, e.g. \"scaffolding\" | \"deploying\". */\n  phase?: string;\n  /**\n   * Present ⇒ a **durable** milestone: persisted, replayable, and surfaced as a\n   * distinct row in `AgentToolRunState.milestones` / `inspectAgentToolRun`. Use\n   * for named phase boundaries (\"schema-ready\", \"preview-ready\", \"deployed\").\n   */\n  milestone?: string;\n  /** App-specific payload; live-only for progress, persisted for milestones. */\n  data?: T;\n};\n\n/**\n * A durable milestone a sub-agent reached, projected onto `AgentToolRunState`\n * and `inspectAgentToolRun`. `sequence` is monotonic per run so replay/live\n * races dedupe on `(runId, sequence)`.\n */\nexport type AgentToolMilestone = {\n  name: string;\n  /** Monotonic per-run ordinal; dedupe key for replay vs live races. */\n  sequence: number;\n  /** Epoch ms the milestone was reached. */\n  at: number;\n  /** App-specific payload carried with the milestone (persisted). */\n  data?: unknown;\n};\n\n/**\n * Latest progress snapshot persisted on the child run row and surfaced through\n * `inspectAgentToolRun` + `AgentToolRunState`. Only the safe-to-inspect fields\n * are retained by default; `at` is the emit timestamp (drives the resetting\n * no-progress budget).\n */\nexport type AgentToolProgressSnapshot = {\n  fraction?: number;\n  message?: string;\n  phase?: string;\n  /**\n   * Set when this signal was a durable milestone (`reportProgress({ milestone })`).\n   * Lets an `onProgress` consumer branch on milestone vs. ephemeral progress.\n   */\n  milestone?: string;\n  /** Epoch ms of the latest signal. */\n  at: number;\n  /** Present only when the emitter opted into persisting `data`. */\n  data?: unknown;\n};\n\nexport type AgentToolRunInfo = {\n  runId: string;\n  parentToolCallId?: string;\n  agentType: string;\n  inputPreview?: unknown;\n  status: AgentToolRunStatus;\n  display?: AgentToolDisplayMetadata;\n  /**\n   * Caller-controlled `metadata.source` for chat-agent `detached.notify`\n   * completions. Present only for detached notify runs that supplied one.\n   */\n  notifySource?: string;\n  displayOrder: number;\n  startedAt: number;\n  completedAt?: number;\n};\n\nexport type AgentToolLifecycleResult = {\n  status: AgentToolTerminalStatus;\n  summary?: string;\n  error?: string;\n  /** Present only when `status` is `interrupted` — machine-readable cause. */\n  reason?: AgentToolInterruptedReason;\n  /**\n   * Present only when `status` is `interrupted`. Whether the child facet was\n   * still non-terminal when the parent stopped waiting (before any teardown).\n   */\n  childStillRunning?: boolean;\n};\n\n/**\n * Configuration for a detached (\"background\") agent-tool run. See\n * `design/rfc-detached-agent-tools.md`.\n *\n * Callbacks are referenced by **method name** on the dispatching agent (the same\n * durable, eviction-surviving pattern as `Agent.schedule`) — never closures,\n * which cannot be rehydrated after the Durable Object is evicted.\n *\n * `Self` is threaded from `runAgentTool(cls, options)` so the method names are\n * type-checked against the calling agent's own methods.\n */\nexport type DetachedAgentToolConfig<Self = Record<string, unknown>> = {\n  /**\n   * Method invoked once per terminal delivery. Branch on `result.status`:\n   * `\"completed\" | \"error\" | \"aborted\" | \"interrupted\"`. A budget give-up\n   * arrives as `status: \"interrupted\"` with `reason: \"budget-exceeded\"`; because\n   * `interrupted` is soft, a child that later completes can fire the hook again\n   * with `\"completed\"`, so a give-up never hides a late real result. Make the\n   * handler idempotent.\n   */\n  onFinish?: Extract<keyof Self, string>;\n  /**\n   * Absolute safety ceiling — a backstop against a child that runs forever. On\n   * expiry the parent gives up watching (delivers `onFinish` with\n   * `interrupted` / `budget-exceeded`) and tears the child down. Defaults to the\n   * parent-level `detachedMaxBudgetMs`.\n   */\n  maxBudgetMs?: number;\n  /**\n   * Per-run override of the resetting no-progress window (ms). Once the child\n   * emits its first `reportProgress`, the parent gives up if it then goes silent\n   * for this long (resets on each signal). Defaults to the parent-level\n   * `detachedNoProgressBudgetMs` (1h). `0`/`Infinity` disables it.\n   */\n  noProgressBudgetMs?: number;\n  /**\n   * Chat-agent convenience (`@cloudflare/think` / `AIChatAgent`): when the run\n   * finishes, inject a message into the chat so the model can react to the\n   * result, instead of you wiring `onFinish` by hand. Sugar that auto-targets\n   * the agent's `_cfDetachedNotifyFinish` hook; ignored on a base `Agent` that\n   * does not implement it, and ignored when `onFinish` is also set (an explicit\n   * `onFinish` wins). Pass `{ source }` to fit the injected message into your\n   * app's existing metadata taxonomy. Override `formatDetachedCompletion()` to\n   * customize the injected text.\n   */\n  notify?: boolean | { source?: string };\n  /**\n   * Chat-agent convenience: milestone names that, when the detached run reaches\n   * them, surface an idempotent synthetic message in the chat BEFORE the run\n   * finishes. Each `(runId, name)` fires at most once (idempotency-keyed),\n   * whether observed live or reconciled after eviction. Override the wording via\n   * `formatDetachedMilestone()`. Requires a chat host (`@cloudflare/think`); a\n   * no-op on a base `Agent`.\n   *\n   * Two delivery modes (the string-array shorthand defaults to `\"narrate\"`):\n   * - `\"narrate\"` (default) — inject a synthetic **assistant** message directly\n   *   (no inference): a cheap, honest status line (\"Found 2 sources…\") that does\n   *   not trigger a model turn. Best for pure progress narration.\n   * - `\"react\"` — inject a **user-role** turn so the model responds to the\n   *   milestone (steer, start dependent work, narrate with context). Costs a\n   *   model turn. Opt in for milestones the agent should *act on*.\n   */\n  onMilestones?: string[] | { names: string[]; mode?: \"react\" | \"narrate\" };\n};\n\nexport type RunAgentToolOptions<\n  Input = unknown,\n  Self = Record<string, unknown>\n> = {\n  input: Input;\n  runId?: string;\n  parentToolCallId?: string;\n  displayOrder?: number;\n  signal?: AbortSignal;\n  inputPreview?: unknown;\n  display?: AgentToolDisplayMetadata;\n  /**\n   * Run the sub-agent **detached**: dispatch it, let the current turn continue,\n   * and (optionally) get a durable callback when it finishes. `true` is\n   * fire-and-forget (observe via `agent-tool-event` frames + the global\n   * `onAgentToolFinish` hook); an object adds the targeted, eviction-surviving\n   * `onFinish` callback. A detached run does NOT inherit `options.signal` — it\n   * must outlive the spawning turn; cancel it explicitly via `cancelAgentTool`.\n   */\n  detached?: boolean | DetachedAgentToolConfig<Self>;\n  /**\n   * Which child events reach the parent's clients. `\"full\"` (default) forwards\n   * every streamed chunk. `\"terminal\"` forwards only lifecycle events: started,\n   * progress and milestone frames, and the terminal event. The child still\n   * persists its whole stream, and the parent still tails it for completion,\n   * cancellation, progress and recovery. Use it for a headless parent with no\n   * client watching the child. Not supported with `detached`.\n   */\n  eventDelivery?: AgentToolEventDelivery;\n};\n\nexport type AgentToolEventDelivery = \"full\" | \"terminal\";\n\n/**\n * Result of dispatching a detached run. Returns immediately after dispatch\n * rather than after completion.\n */\nexport type DetachedRunAgentToolResult = {\n  runId: string;\n  agentType: string;\n  /**\n   * `\"running\"` on a successful dispatch; `\"error\"` if dispatch itself failed\n   * (e.g. the `maxConcurrentAgentTools` cap was exceeded — rejected\n   * synchronously, no child started, no callback wired).\n   */\n  status: \"running\" | \"error\";\n  error?: string;\n};\n\nexport type RunAgentToolResult<Output = unknown> = {\n  runId: string;\n  agentType: string;\n  status: AgentToolTerminalStatus;\n  output?: Output;\n  summary?: string;\n  error?: string;\n  /**\n   * Present only when `status` is `interrupted` — a machine-readable cause so\n   * callers don't pattern-match the `error` prose (#1630 follow-up).\n   */\n  reason?: AgentToolInterruptedReason;\n  /**\n   * Present only when `status` is `interrupted`. `true` when the child facet was\n   * still non-terminal (running / advancing) at the moment the parent stopped\n   * waiting and before any teardown; `false` once the parent has torn the child\n   * down so it is no longer doing work.\n   */\n  childStillRunning?: boolean;\n};\n\nexport type ChatCapableAgentClass<T extends Agent = Agent> = SubAgentClass<T>;\n\nexport type AgentToolRunInspection<Output = unknown> = {\n  runId: string;\n  status: Exclude<AgentToolRunStatus, \"interrupted\">;\n  requestId?: string;\n  streamId?: string;\n  output?: Output;\n  summary?: string;\n  error?: string;\n  startedAt: number;\n  completedAt?: number;\n  /**\n   * Latest progress snapshot the child has persisted, so a rehydrated parent\n   * (recovery / backbone reconcile) can reconstruct \"where is this run\" and\n   * reset the resetting no-progress budget without having tailed the live\n   * stream. Absent until the child emits its first `reportProgress`.\n   */\n  progress?: AgentToolProgressSnapshot;\n  /**\n   * Durable milestones the child has persisted, ordered by `sequence`. Lets a\n   * rehydrated parent (recovery / backbone reconcile) replay milestone-gated\n   * work and milestone notifications without having observed the live stream.\n   */\n  milestones?: AgentToolMilestone[];\n};\n\nexport type AgentToolStoredChunk = {\n  sequence: number;\n  body: string;\n  /**\n   * Set when the child broadcast this chunk but could not store it (it exceeds\n   * the stored-chunk size limit). The chunk is never replayed, so it carries\n   * the next stored position without consuming it and dedupes on this id.\n   */\n  unstoredId?: string;\n};\n\nexport type AgentToolChildAdapter<Input = unknown, Output = unknown> = {\n  startAgentToolRun(\n    input: Input,\n    options: {\n      runId: string;\n      signal?: AbortSignal;\n      /**\n       * `\"terminal\"` means no client is watching this run's chunks, so the\n       * child can skip broadcasting them.\n       */\n      eventDelivery?: AgentToolEventDelivery;\n    }\n  ): Promise<AgentToolRunInspection<Output>>;\n  cancelAgentToolRun(runId: string, reason?: unknown): Promise<void>;\n  inspectAgentToolRun(\n    runId: string,\n    options?: {\n      /**\n       * `false` reports the stored row as-is instead of first reconciling\n       * (and possibly sealing) a stale run. Defaults to `true`.\n       */\n      reconcile?: boolean;\n    }\n  ): Promise<AgentToolRunInspection<Output> | null>;\n  getAgentToolChunks(\n    runId: string,\n    options?: { afterSequence?: number }\n  ): Promise<AgentToolStoredChunk[]>;\n  tailAgentToolRun?(\n    runId: string,\n    options?: { afterSequence?: number; signal?: AbortSignal }\n  ): Promise<ReadableStream<AgentToolStoredChunk>>;\n};\n\nexport type AgentToolEvent =\n  | {\n      kind: \"started\";\n      runId: string;\n      agentType: string;\n      inputPreview?: unknown;\n      order: number;\n      display?: AgentToolDisplayMetadata;\n    }\n  | {\n      kind: \"chunk\";\n      runId: string;\n      body: string;\n      /** See {@link AgentToolStoredChunk.unstoredId}. */\n      unstoredId?: string;\n    }\n  | {\n      kind: \"finished\";\n      runId: string;\n      summary: string;\n    }\n  | {\n      kind: \"error\";\n      runId: string;\n      error: string;\n    }\n  | {\n      kind: \"aborted\";\n      runId: string;\n      reason?: string;\n    }\n  | {\n      kind: \"interrupted\";\n      runId: string;\n      error: string;\n      /** Machine-readable cause of the interrupt (#1630 follow-up). */\n      reason?: AgentToolInterruptedReason;\n      /**\n       * Whether the child facet was still non-terminal when the parent stopped\n       * waiting (before any teardown). Lets a UI distinguish a still-running\n       * child from one the parent has torn down.\n       */\n      childStillRunning?: boolean;\n    };\n\nexport type AgentToolEventMessage = {\n  type: \"agent-tool-event\";\n  parentToolCallId?: string;\n  sequence: number;\n  replay?: true;\n  event: AgentToolEvent;\n};\n\nexport type AgentToolRunPart = { type: string };\n\nexport type AgentToolRunState<\n  Part extends AgentToolRunPart = AgentToolRunPart\n> = {\n  runId: string;\n  agentType: string;\n  parentToolCallId?: string;\n  inputPreview?: unknown;\n  order: number;\n  display?: AgentToolDisplayMetadata;\n  status: \"running\" | \"completed\" | \"error\" | \"aborted\" | \"interrupted\";\n  /**\n   * Message parts reconstructed from the child agent's streamed chunks.\n   *\n   * The default stays framework-neutral so importing `agents` does not require\n   * an AI SDK peer. AI SDK consumers can use\n   * `AgentToolRunState<UIMessage[\"parts\"][number]>` when they need its exact\n   * discriminated union.\n   */\n  parts: Part[];\n  summary?: string;\n  error?: string;\n  /**\n   * Present only when `status` is `interrupted` — machine-readable cause and\n   * whether the child is still running, mirrored from the wire event so a UI\n   * can render the reason without parsing `error` (#1630 follow-up).\n   */\n  reason?: AgentToolInterruptedReason;\n  childStillRunning?: boolean;\n  /**\n   * Latest progress snapshot, projected from the child's transient\n   * `data-agent-progress` signals so a UI can render a bar / ETA / phase label\n   * for a running (especially detached / background) run without drilling in.\n   */\n  progress?: AgentToolProgressSnapshot;\n  /**\n   * Durable milestones the run has reached, ordered by `sequence` (deduped\n   * across replay/live races). Drives milestone chips / a phase timeline.\n   */\n  milestones?: AgentToolMilestone[];\n  subAgent: { agent: string; name: string };\n};\n\nexport type AgentToolEventState<\n  Part extends AgentToolRunPart = AgentToolRunPart\n> = {\n  runsById: Record<string, AgentToolRunState<Part>>;\n  runsByToolCallId: Record<string, AgentToolRunState<Part>[]>;\n  unboundRuns: AgentToolRunState<Part>[];\n};\n"],"mappings":";;;;;;;;AAuFA,MAAa,2BAA2B;;;;;;;AAQxC,MAAa,4BAA4B;;;;;;AAOzC,SAAgB,0BAA0B,MAAuB;CAC/D,IACE,CAAC,KAAK,SAAA,qBAAiC,KACvC,CAAC,KAAK,SAAA,sBAAkC,GAExC,OAAO;CAET,IAAI;EACF,MAAM,OAAQ,KAAK,MAAM,IAAI,CAAC,EAAgC;EAC9D,OACE,SAAA,yBAAqC,SAAA;CAEzC,QAAQ;EACN,OAAO;CACT;AACF;;;;;;AAOA,SAAgB,6BACd,OACS;CACT,OACE,MAAM,eAAe,KAAA,KAAa,0BAA0B,MAAM,IAAI;AAE1E"}

package/dist/{agent-tools-y7zLfw4Q.js → agent-tools-CdJC-8Dc.js}

@@ -1,5 +1,21 @@
-import { AGENT_TOOL_MILESTONE_PART, AGENT_TOOL_PROGRESS_PART } from "./agent-tool-types.js";
-import { t as applyChunkToParts } from "./message-builder-BymO4N_D.js";
+import { AGENT_TOOL_MILESTONE_PART, AGENT_TOOL_PROGRESS_PART, isAgentToolLifecycleChunk } from "./agent-tool-types.js";
+import { t as applyChunkToParts } from "./message-builder-DAl9AhHH.js";
+//#region src/chat/chunk-size.ts
+const textEncoder = new TextEncoder();
+/** Maximum serialized chunk body size before skipping storage (bytes). */
+const CHUNK_MAX_BYTES = 18e5;
+/** Byte size of a chunk body in its stored (JSON-escaped) encoding. */
+function storedChunkBytes(body) {
+	return textEncoder.encode(JSON.stringify(body)).byteLength;
+}
+/**
+* Whether `ResumableStream.storeChunk` skips storing this body: it is still
+* broadcast live, but absent from replay.
+*/
+function isChunkTooLargeToStore(body) {
+	return storedChunkBytes(body) > CHUNK_MAX_BYTES;
+}
+//#endregion
 //#region src/chat/agent-tools.ts
 /**
 * Pull a reserved `data-agent-progress` chunk (emitted by a running sub-agent's
@@ -91,6 +107,7 @@ var AgentToolProgressEmitter = class {
 		};
 		this.hooks.broadcast(requestId, JSON.stringify({
 			type: AGENT_TOOL_PROGRESS_PART,
+			id: crypto.randomUUID(),
 			transient: true,
 			data: wire
 		}));
@@ -250,6 +267,42 @@ function createAgentToolEventState() {
 		unboundRuns: []
 	};
 }
+/**
+* Identity of an agent-tool event for replay-vs-live dedupe. Ordinary chunks
+* key on the broadcast `sequence`, which is their stored-chunk position on
+* both the live and replay paths. Lifecycle events key on their content: a
+* reattached run can be interrupted again with a different reason, and the
+* reducer overwrites on lifecycle events, so re-applying one is harmless.
+* Milestones key on their own persisted sequence. Progress frames and chunks
+* too large to store reuse the next stored chunk's sequence without consuming
+* it and are never replayed, so they key on their own emitter-assigned id.
+*/
+function agentToolEventDedupeKey(message) {
+	const { event } = message;
+	let identity;
+	if (event.kind !== "chunk") identity = `event:${JSON.stringify(event)}`;
+	else if (event.unstoredId !== void 0) identity = `unstored:${event.unstoredId}`;
+	else {
+		let milestone;
+		let progressId;
+		let progress = false;
+		if (event.body.includes("data-agent-milestone") || event.body.includes("data-agent-progress")) try {
+			const parsed = JSON.parse(event.body);
+			milestone = readAgentToolMilestoneChunk(parsed);
+			progress = readAgentToolProgressChunk(parsed) !== void 0;
+			const id = parsed.id;
+			if (typeof id === "string") progressId = id;
+		} catch {
+			milestone = void 0;
+		}
+		identity = milestone ? `milestone:${milestone.sequence}` : progress ? progressId !== void 0 ? `progress:${progressId}` : `progress:${message.sequence}:${event.body}` : `seq:${message.sequence}`;
+	}
+	return [
+		message.parentToolCallId ?? "",
+		event.runId,
+		identity
+	].join("\0");
+}
 function applyAgentToolEvent(state, message) {
 	if (message.type !== "agent-tool-event") return state;
 	const runId = message.event.runId;
@@ -276,29 +329,39 @@ function applyAgentToolEvent(state, message) {
 * error capture never depends on tailer timing. A frame belongs to a run iff it
 * carries that run's turn request id, so concurrent runs can't cross-contaminate
 * each other's progress or error state.
+*
+* Returns the run id when the frame is one of that run's content chunks, so a
+* host can skip broadcasting chunks no client is watching.
 */
 function interceptAgentToolBroadcast(msg, hooks) {
-	if ((hooks.forwarders.size > 0 || hooks.liveSequences.size > 0) && typeof msg === "string") try {
+	if ((hooks.forwarders.size > 0 || hooks.liveSequences.size > 0 || (hooks.terminalOnlyRuns?.size ?? 0) > 0) && typeof msg === "string") try {
 		const parsed = JSON.parse(msg);
 		if (parsed.type === hooks.responseType && typeof parsed.id === "string") {
 			const runId = hooks.runForRequest(parsed.id);
 			if (runId !== null) {
-				if (parsed.error === true && typeof parsed.body === "string") hooks.lastErrors.set(runId, parsed.body);
-				else if (typeof parsed.body === "string" && parsed.body.length > 0) {
+				if (parsed.error === true && typeof parsed.body === "string") {
+					hooks.lastErrors.set(runId, parsed.body);
+					hooks.onError?.(runId, parsed.body);
+				} else if (typeof parsed.body === "string" && parsed.body.length > 0) {
 					const sequence = hooks.liveSequences.get(runId) ?? 0;
-					hooks.liveSequences.set(runId, sequence + 1);
+					const lifecycle = isAgentToolLifecycleChunk(parsed.body);
+					const unstored = !lifecycle && isChunkTooLargeToStore(parsed.body);
+					hooks.liveSequences.set(runId, lifecycle || unstored ? sequence : sequence + 1);
 					const chunk = {
 						sequence,
-						body: parsed.body
+						body: parsed.body,
+						...unstored ? { unstoredId: crypto.randomUUID() } : {}
 					};
 					const forwarders = hooks.forwarders.get(runId);
 					if (forwarders) for (const forward of forwarders) forward(chunk);
+					return runId;
 				}
 			}
 		}
 	} catch {}
+	return null;
 }
 //#endregion
-export { interceptAgentToolBroadcast as i, applyAgentToolEvent as n, createAgentToolEventState as r, AgentToolProgressEmitter as t };
+export { interceptAgentToolBroadcast as a, createAgentToolEventState as i, agentToolEventDedupeKey as n, CHUNK_MAX_BYTES as o, applyAgentToolEvent as r, storedChunkBytes as s, AgentToolProgressEmitter as t };
 
-//# sourceMappingURL=agent-tools-y7zLfw4Q.js.map
+//# sourceMappingURL=agent-tools-CdJC-8Dc.js.map

package/dist/agent-tools-CdJC-8Dc.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"agent-tools-CdJC-8Dc.js","names":[],"sources":["../src/chat/chunk-size.ts","../src/chat/agent-tools.ts"],"sourcesContent":["const textEncoder = new TextEncoder();\n\n/** Maximum serialized chunk body size before skipping storage (bytes). */\nexport const CHUNK_MAX_BYTES = 1_800_000;\n\n/** Byte size of a chunk body in its stored (JSON-escaped) encoding. */\nexport function storedChunkBytes(body: string): number {\n  return textEncoder.encode(JSON.stringify(body)).byteLength;\n}\n\n/**\n * Whether `ResumableStream.storeChunk` skips storing this body: it is still\n * broadcast live, but absent from replay.\n */\nexport function isChunkTooLargeToStore(body: string): boolean {\n  return storedChunkBytes(body) > CHUNK_MAX_BYTES;\n}\n","import { applyChunkToParts, type MessagePart } from \"./message-builder\";\nimport { isChunkTooLargeToStore } from \"./chunk-size\";\nimport {\n  AGENT_TOOL_MILESTONE_PART,\n  AGENT_TOOL_PROGRESS_PART,\n  isAgentToolLifecycleChunk,\n  isPositionlessAgentToolChunk\n} from \"../agent-tool-types\";\nimport type {\n  AgentToolEventMessage,\n  AgentToolEventState,\n  AgentToolMilestone,\n  AgentToolProgress,\n  AgentToolProgressSnapshot,\n  AgentToolRunPart,\n  AgentToolRunState,\n  AgentToolStoredChunk\n} from \"../agent-tool-types\";\n\n/**\n * Pull a reserved `data-agent-progress` chunk (emitted by a running sub-agent's\n * `reportProgress`) into a latest-wins snapshot. Returns `undefined` for any\n * other chunk so the caller keeps the prior snapshot.\n */\nfunction readAgentToolProgressChunk(\n  chunk: unknown\n): AgentToolProgressSnapshot | undefined {\n  if (\n    typeof chunk !== \"object\" ||\n    chunk === null ||\n    (chunk as { type?: unknown }).type !== AGENT_TOOL_PROGRESS_PART\n  ) {\n    return undefined;\n  }\n  const data = (chunk as { data?: AgentToolProgress }).data ?? {};\n  return {\n    ...(typeof data.fraction === \"number\" ? { fraction: data.fraction } : {}),\n    ...(typeof data.message === \"string\" ? { message: data.message } : {}),\n    ...(typeof data.phase === \"string\" ? { phase: data.phase } : {}),\n    ...(data.data !== undefined ? { data: data.data } : {}),\n    at: Date.now()\n  };\n}\n\n/**\n * Pull a reserved `data-agent-milestone` chunk into a durable milestone record,\n * or `undefined` for any other chunk. Milestones carry their own monotonic\n * `sequence` so the caller can dedupe replay-vs-live races.\n */\nfunction readAgentToolMilestoneChunk(\n  chunk: unknown\n): AgentToolMilestone | undefined {\n  if (\n    typeof chunk !== \"object\" ||\n    chunk === null ||\n    (chunk as { type?: unknown }).type !== AGENT_TOOL_MILESTONE_PART\n  ) {\n    return undefined;\n  }\n  const data = (chunk as { data?: Partial<AgentToolMilestone> }).data ?? {};\n  if (typeof data.name !== \"string\") return undefined;\n  return {\n    name: data.name,\n    sequence: typeof data.sequence === \"number\" ? data.sequence : 0,\n    at: typeof data.at === \"number\" ? data.at : Date.now(),\n    ...(data.data !== undefined ? { data: data.data } : {})\n  };\n}\n\n/**\n * Merge a milestone into a run's ordered milestone list, deduping on `sequence`\n * (idempotent across replay + live races) and keeping the list sorted.\n */\nfunction mergeMilestone(\n  existing: AgentToolMilestone[] | undefined,\n  milestone: AgentToolMilestone\n): AgentToolMilestone[] {\n  // Returns `existing` unchanged (same reference) when the milestone is a dup,\n  // so callers can identity-compare to detect a genuinely new milestone.\n  if (existing?.some((m) => m.sequence === milestone.sequence)) return existing;\n  const list = existing ? [...existing, milestone] : [milestone];\n  list.sort((a, b) => a.sequence - b.sequence);\n  return list;\n}\n\n/** Latest-wins coalescing window for `reportProgress` emits (per run). */\nconst AGENT_TOOL_PROGRESS_COALESCE_MS = 200;\n\nexport type AgentToolProgressEmitResult = \"emitted\" | \"coalesced\" | \"inactive\";\n\n/**\n * Host-injected seams the shared progress emitter needs. Keeps the per-host\n * `reportProgress` thin: Think / AIChatAgent supply how to resolve the active\n * agent-tool run, how to broadcast a chat-response frame, and how to persist the\n * latest snapshot on their own child-run table.\n */\nexport type AgentToolProgressEmitHooks = {\n  /** The agent-tool run currently executing in this turn, or null. */\n  resolveActiveRun: () => { runId: string; requestId: string } | null;\n  /** Broadcast a chat-response frame (id = requestId) to clients/tailers. */\n  broadcast: (requestId: string, chunkBody: string) => void;\n  /** Persist the latest snapshot + signal timestamp on the child run row. */\n  persistSnapshot: (\n    runId: string,\n    snapshot: {\n      fraction?: number;\n      message?: string;\n      phase?: string;\n      data?: unknown;\n    },\n    at: number\n  ) => void;\n  /**\n   * Persist a durable milestone row, bump the run's signal timestamp, and return\n   * the assigned monotonic per-run `sequence` (used to dedupe replay/live races).\n   */\n  persistMilestone: (\n    runId: string,\n    name: string,\n    data: unknown,\n    at: number\n  ) => number;\n};\n\n/**\n * Shared implementation of `reportProgress` for chat hosts. Builds the reserved\n * transient `data-agent-progress` wire frame, coalesces bursts to a bounded\n * cadence (latest-wins; a `fraction >= 1` \"done\" frame always flushes), and\n * persists a latest snapshot. `data` rides the live frame but is only persisted\n * when the caller opts in via `{ persist: true }`.\n */\nexport class AgentToolProgressEmitter {\n  private readonly _lastEmitAt = new Map<string, number>();\n\n  constructor(private readonly hooks: AgentToolProgressEmitHooks) {}\n\n  report(\n    progress: AgentToolProgress,\n    options?: { persist?: boolean }\n  ): AgentToolProgressEmitResult {\n    const active = this.hooks.resolveActiveRun();\n    if (!active) return \"inactive\";\n    const { runId, requestId } = active;\n    const now = Date.now();\n\n    // Durable milestone: never coalesced (each named boundary must land,\n    // persist, and replay). Rides the stream as a PERSISTED data part.\n    if (typeof progress.milestone === \"string\" && progress.milestone) {\n      this._lastEmitAt.set(runId, now);\n      const sequence = this.hooks.persistMilestone(\n        runId,\n        progress.milestone,\n        progress.data,\n        now\n      );\n      this.hooks.broadcast(\n        requestId,\n        JSON.stringify({\n          type: AGENT_TOOL_MILESTONE_PART,\n          data: {\n            name: progress.milestone,\n            sequence,\n            at: now,\n            ...(typeof progress.fraction === \"number\"\n              ? { fraction: progress.fraction }\n              : {}),\n            ...(typeof progress.message === \"string\"\n              ? { message: progress.message }\n              : {}),\n            ...(typeof progress.phase === \"string\"\n              ? { phase: progress.phase }\n              : {}),\n            ...(progress.data !== undefined ? { data: progress.data } : {})\n          }\n        })\n      );\n      return \"emitted\";\n    }\n\n    const last = this._lastEmitAt.get(runId) ?? 0;\n    const isDone =\n      typeof progress.fraction === \"number\" && progress.fraction >= 1;\n    if (now - last < AGENT_TOOL_PROGRESS_COALESCE_MS && !isDone) {\n      return \"coalesced\";\n    }\n    this._lastEmitAt.set(runId, now);\n\n    const wire: AgentToolProgress = {\n      ...(typeof progress.fraction === \"number\"\n        ? { fraction: progress.fraction }\n        : {}),\n      ...(typeof progress.message === \"string\"\n        ? { message: progress.message }\n        : {}),\n      ...(typeof progress.phase === \"string\" ? { phase: progress.phase } : {}),\n      ...(progress.data !== undefined ? { data: progress.data } : {})\n    };\n    // Identical payloads must not dedupe against each other on a client that\n    // keeps seen keys for its connection's lifetime, including across a child\n    // restart, so the id is unique rather than a per-instance counter.\n    this.hooks.broadcast(\n      requestId,\n      JSON.stringify({\n        type: AGENT_TOOL_PROGRESS_PART,\n        id: crypto.randomUUID(),\n        transient: true,\n        data: wire\n      })\n    );\n    this.hooks.persistSnapshot(\n      runId,\n      {\n        ...(typeof progress.fraction === \"number\"\n          ? { fraction: progress.fraction }\n          : {}),\n        ...(typeof progress.message === \"string\"\n          ? { message: progress.message }\n          : {}),\n        ...(typeof progress.phase === \"string\"\n          ? { phase: progress.phase }\n          : {}),\n        ...(options?.persist && progress.data !== undefined\n          ? { data: progress.data }\n          : {})\n      },\n      now\n    );\n    return \"emitted\";\n  }\n\n  /** Drop coalescing state for a settled run (called on terminal). */\n  forget(runId: string): void {\n    this._lastEmitAt.delete(runId);\n  }\n}\n\nfunction sortRuns<Part extends AgentToolRunPart>(\n  runs: AgentToolRunState<Part>[]\n): AgentToolRunState<Part>[] {\n  return [...runs].sort((a, b) => {\n    if (a.order !== b.order) return a.order - b.order;\n    return a.runId.localeCompare(b.runId);\n  });\n}\n\nfunction rebuildIndexes<Part extends AgentToolRunPart>(\n  runsById: Record<string, AgentToolRunState<Part>>\n): Pick<AgentToolEventState<Part>, \"runsByToolCallId\" | \"unboundRuns\"> {\n  const grouped: Record<string, AgentToolRunState<Part>[]> = {};\n  const unboundRuns: AgentToolRunState<Part>[] = [];\n  for (const run of Object.values(runsById)) {\n    if (run.parentToolCallId) {\n      grouped[run.parentToolCallId] = grouped[run.parentToolCallId] ?? [];\n      grouped[run.parentToolCallId].push(run);\n    } else {\n      unboundRuns.push(run);\n    }\n  }\n  for (const [toolCallId, runs] of Object.entries(grouped)) {\n    grouped[toolCallId] = sortRuns(runs);\n  }\n  return { runsByToolCallId: grouped, unboundRuns: sortRuns(unboundRuns) };\n}\n\nfunction emptyRun<Part extends AgentToolRunPart>(\n  message: AgentToolEventMessage\n): AgentToolRunState<Part> | undefined {\n  const { event } = message;\n  if (event.kind === \"started\") {\n    return {\n      runId: event.runId,\n      agentType: event.agentType,\n      parentToolCallId: message.parentToolCallId,\n      inputPreview: event.inputPreview,\n      order: event.order,\n      display: event.display,\n      status: \"running\",\n      parts: [],\n      subAgent: { agent: event.agentType, name: event.runId }\n    };\n  }\n  return undefined;\n}\n\nfunction applyToRun<Part extends AgentToolRunPart>(\n  prev: AgentToolRunState<Part> | undefined,\n  message: AgentToolEventMessage\n): AgentToolRunState<Part> | undefined {\n  const seeded = prev ?? emptyRun(message);\n  const { event } = message;\n\n  switch (event.kind) {\n    case \"started\":\n      if (\n        seeded?.status === \"completed\" ||\n        seeded?.status === \"error\" ||\n        seeded?.status === \"aborted\" ||\n        seeded?.status === \"interrupted\"\n      ) {\n        return seeded;\n      }\n      return {\n        ...seeded,\n        runId: event.runId,\n        agentType: event.agentType,\n        parentToolCallId: message.parentToolCallId,\n        inputPreview: event.inputPreview,\n        order: event.order,\n        display: event.display,\n        status: \"running\",\n        parts: seeded?.parts ?? [],\n        subAgent: { agent: event.agentType, name: event.runId }\n      };\n    case \"chunk\": {\n      if (!seeded) return undefined;\n      // `applyChunkToParts` mutates part objects in place (e.g.\n      // `lastTextPart.text += delta`). A shallow array copy (`[...seeded.parts]`)\n      // keeps the *element* references shared with the previous state, so those\n      // in-place mutations leak back into `prev`. React double-invokes setState\n      // updaters in StrictMode / dev hydration, replaying each chunk against the\n      // same (already-mutated) `prev` and doubling the text (#1835). Clone each\n      // part so the reducer stays pure — every mutation here is to a top-level\n      // field, so a per-part shallow copy is sufficient.\n      const parts = seeded.parts.map((part) => ({ ...part }) as Part);\n      let parsed: unknown;\n      try {\n        parsed = JSON.parse(event.body);\n        applyChunkToParts(\n          parts as MessagePart[],\n          parsed as Parameters<typeof applyChunkToParts>[1]\n        );\n      } catch {\n        return seeded;\n      }\n      // Project a reserved `data-agent-progress` part onto the run's latest\n      // progress snapshot so a tray can render a bar/phase without drilling in.\n      // The part is transient (not persisted into `parts`), so it is read here\n      // off the raw chunk rather than from the reduced parts array.\n      const progress = readAgentToolProgressChunk(parsed);\n      if (progress) {\n        return { ...seeded, parts, progress };\n      }\n      // Durable milestones land as a persisted `data-agent-milestone` part:\n      // append (deduped by sequence) to the run's milestone list, and reflect\n      // any progress fields the milestone carried onto the latest snapshot.\n      const milestone = readAgentToolMilestoneChunk(parsed);\n      if (milestone) {\n        const milestones = mergeMilestone(seeded.milestones, milestone);\n        // Only advance the snapshot for a genuinely new, not-older milestone, so\n        // a late replay of an earlier milestone never rolls `progress` backward.\n        const isNew = milestones !== seeded.milestones;\n        const notOlder =\n          seeded.progress === undefined || milestone.at >= seeded.progress.at;\n        if (!isNew || !notOlder) {\n          return { ...seeded, parts, milestones };\n        }\n        const data = (parsed as { data?: AgentToolProgress }).data ?? {};\n        const snapshot: AgentToolProgressSnapshot = {\n          ...(typeof data.fraction === \"number\"\n            ? { fraction: data.fraction }\n            : {}),\n          ...(typeof data.message === \"string\"\n            ? { message: data.message }\n            : {}),\n          ...(typeof data.phase === \"string\" ? { phase: data.phase } : {}),\n          milestone: milestone.name,\n          at: milestone.at\n        };\n        return { ...seeded, parts, progress: snapshot, milestones };\n      }\n      return { ...seeded, parts };\n    }\n    case \"finished\":\n      if (!seeded) return undefined;\n      return {\n        ...seeded,\n        status: \"completed\",\n        summary: event.summary,\n        error: undefined\n      };\n    case \"error\":\n      if (!seeded) return undefined;\n      return { ...seeded, status: \"error\", error: event.error };\n    case \"aborted\":\n      if (!seeded) return undefined;\n      return { ...seeded, status: \"aborted\", error: event.reason };\n    case \"interrupted\":\n      if (!seeded) return undefined;\n      return {\n        ...seeded,\n        status: \"interrupted\",\n        error: event.error,\n        reason: event.reason,\n        childStillRunning: event.childStillRunning\n      };\n  }\n}\n\nexport function createAgentToolEventState<\n  Part extends AgentToolRunPart = AgentToolRunPart\n>(): AgentToolEventState<Part> {\n  return {\n    runsById: {},\n    runsByToolCallId: {},\n    unboundRuns: []\n  };\n}\n\n/**\n * Identity of an agent-tool event for replay-vs-live dedupe. Ordinary chunks\n * key on the broadcast `sequence`, which is their stored-chunk position on\n * both the live and replay paths. Lifecycle events key on their content: a\n * reattached run can be interrupted again with a different reason, and the\n * reducer overwrites on lifecycle events, so re-applying one is harmless.\n * Milestones key on their own persisted sequence. Progress frames and chunks\n * too large to store reuse the next stored chunk's sequence without consuming\n * it and are never replayed, so they key on their own emitter-assigned id.\n */\nexport function agentToolEventDedupeKey(\n  message: AgentToolEventMessage\n): string {\n  const { event } = message;\n  let identity: string;\n  if (event.kind !== \"chunk\") {\n    identity = `event:${JSON.stringify(event)}`;\n  } else if (event.unstoredId !== undefined) {\n    identity = `unstored:${event.unstoredId}`;\n  } else {\n    let milestone: AgentToolMilestone | undefined;\n    let progressId: string | undefined;\n    let progress = false;\n    if (\n      event.body.includes(AGENT_TOOL_MILESTONE_PART) ||\n      event.body.includes(AGENT_TOOL_PROGRESS_PART)\n    ) {\n      try {\n        const parsed: unknown = JSON.parse(event.body);\n        milestone = readAgentToolMilestoneChunk(parsed);\n        progress = readAgentToolProgressChunk(parsed) !== undefined;\n        const id = (parsed as { id?: unknown }).id;\n        if (typeof id === \"string\") progressId = id;\n      } catch {\n        milestone = undefined;\n      }\n    }\n    identity = milestone\n      ? `milestone:${milestone.sequence}`\n      : progress\n        ? progressId !== undefined\n          ? `progress:${progressId}`\n          : `progress:${message.sequence}:${event.body}`\n        : `seq:${message.sequence}`;\n  }\n  return [message.parentToolCallId ?? \"\", event.runId, identity].join(\"\\0\");\n}\n\nexport function applyAgentToolEvent<\n  Part extends AgentToolRunPart = AgentToolRunPart\n>(\n  state: AgentToolEventState<Part>,\n  message: AgentToolEventMessage\n): AgentToolEventState<Part> {\n  if (message.type !== \"agent-tool-event\") return state;\n  const runId = message.event.runId;\n  const nextRun = applyToRun(state.runsById[runId], message);\n  if (!nextRun) return state;\n\n  const runsById = { ...state.runsById, [runId]: nextRun };\n  return { runsById, ...rebuildIndexes(runsById) };\n}\n\nexport { isPositionlessAgentToolChunk };\n\nexport type {\n  AgentToolEvent,\n  AgentToolEventMessage,\n  AgentToolEventState,\n  AgentToolRunPart,\n  AgentToolRunState\n} from \"../agent-tool-types\";\n\n/**\n * @internal Host substrate the {@link interceptAgentToolBroadcast} snoop reads,\n * abstracting the divergent per-host run-lookup and response-frame constant.\n */\nexport interface AgentToolBroadcastHooks {\n  /** Live tailers per run; iterated to forward each progress chunk. */\n  forwarders: Map<string, Set<(chunk: AgentToolStoredChunk) => void>>;\n  /**\n   * Per-run live counter of stored chunks; advanced even with no tailer\n   * attached, so a stored chunk's live sequence equals its stored chunk_index.\n   *\n   * Progress/milestone frames (`reportProgress`) ride the same\n   * `USE_CHAT_RESPONSE` wire type and are forwarded here, but persist\n   * out-of-band (progress snapshot / milestone rows) and have no store\n   * position. Neither do chunks too large to store (they carry an\n   * `unstoredId`). Both carry the next position WITHOUT consuming it, and\n   * tails emit them outside the stored-position high-water dedupe; counting\n   * them would push later stored chunks past their stored index, so a chunk\n   * stored and broadcast during a tail's drain would be emitted twice. A tail\n   * seeds a cold counter from the stored high-water before it attaches.\n   */\n  liveSequences: Map<string, number>;\n  /** Per-run last error body, captured for replay to a late-attaching tailer. */\n  lastErrors: Map<string, string>;\n  /**\n   * Called after a run's error body is captured, so the host can record it\n   * durably on the still-open run row (the in-memory {@link lastErrors} entry\n   * is lost if the DO is evicted before the run is finalized).\n   */\n  onError?: (runId: string, body: string) => void;\n  /** The host's use-chat-response wire type (`CHAT_MESSAGE_TYPES.USE_CHAT_RESPONSE`). */\n  responseType: string;\n  /** Resolve the agent-tool run that owns a turn request id, or null. */\n  runForRequest: (requestId: string) => string | null;\n  /**\n   * Runs whose chunks the host suppresses (`eventDelivery: \"terminal\"`). Keeps\n   * inspection on after a restart empties the other maps, so a recovered\n   * turn's chunks are still attributed and suppressed.\n   */\n  terminalOnlyRuns?: ReadonlySet<string>;\n}\n\n/**\n * Snoop a host's outgoing chat frames while any agent-tool run is in flight and\n * forward the owning run's streamed body to its live tailers (or capture its\n * error), without altering the frame — the caller still broadcasts it (#1575).\n *\n * Shared verbatim by `@cloudflare/ai-chat` and `@cloudflare/think`; the only\n * per-host variance (the response-frame type constant and the run-lookup, whose\n * SQL differs) is supplied via {@link AgentToolBroadcastHooks}. Inspection runs\n * for a run's whole lifecycle (live sequences exist even with no tailer), so\n * error capture never depends on tailer timing. A frame belongs to a run iff it\n * carries that run's turn request id, so concurrent runs can't cross-contaminate\n * each other's progress or error state.\n *\n * Returns the run id when the frame is one of that run's content chunks, so a\n * host can skip broadcasting chunks no client is watching.\n */\nexport function interceptAgentToolBroadcast(\n  msg: string | ArrayBuffer | ArrayBufferView,\n  hooks: AgentToolBroadcastHooks\n): string | null {\n  if (\n    (hooks.forwarders.size > 0 ||\n      hooks.liveSequences.size > 0 ||\n      (hooks.terminalOnlyRuns?.size ?? 0) > 0) &&\n    typeof msg === \"string\"\n  ) {\n    try {\n      const parsed = JSON.parse(msg) as {\n        type?: unknown;\n        body?: unknown;\n        error?: unknown;\n        id?: unknown;\n      };\n      if (parsed.type === hooks.responseType && typeof parsed.id === \"string\") {\n        const runId = hooks.runForRequest(parsed.id);\n        if (runId !== null) {\n          if (parsed.error === true && typeof parsed.body === \"string\") {\n            hooks.lastErrors.set(runId, parsed.body);\n            hooks.onError?.(runId, parsed.body);\n          } else if (\n            typeof parsed.body === \"string\" &&\n            parsed.body.length > 0\n          ) {\n            // Advance the live sequence even with no tailer attached so a tailer\n            // registering mid-run resumes at the right offset. Progress,\n            // milestone, and unstored frames carry the next position without\n            // consuming it.\n            const sequence = hooks.liveSequences.get(runId) ?? 0;\n            const lifecycle = isAgentToolLifecycleChunk(parsed.body);\n            const unstored = !lifecycle && isChunkTooLargeToStore(parsed.body);\n            hooks.liveSequences.set(\n              runId,\n              lifecycle || unstored ? sequence : sequence + 1\n            );\n            const chunk: AgentToolStoredChunk = {\n              sequence,\n              body: parsed.body,\n              ...(unstored ? { unstoredId: crypto.randomUUID() } : {})\n            };\n            const forwarders = hooks.forwarders.get(runId);\n            if (forwarders) {\n              for (const forward of forwarders) forward(chunk);\n            }\n            return runId;\n          }\n        }\n      }\n    } catch {\n      // Non-chat frames pass through unchanged.\n    }\n  }\n  return null;\n}\n"],"mappings":"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"}

package/dist/{agent-tools-Dj5Mzlw7.d.ts → agent-tools-YrATZJu2.d.ts}

@@ -1,10 +1,10 @@
 import {
-  L as AgentToolEventMessage,
-  R as AgentToolEventState,
-  U as AgentToolProgress,
-  X as AgentToolStoredChunk,
-  q as AgentToolRunPart
-} from "./agent-routing-B2XLNMxq.js";
+  J as AgentToolRunPart,
+  R as AgentToolEventMessage,
+  W as AgentToolProgress,
+  Z as AgentToolStoredChunk,
+  z as AgentToolEventState
+} from "./agent-routing-0DR0Tk2v.js";
 
 //#region src/chat/agent-tools.d.ts
 type AgentToolProgressEmitResult = "emitted" | "coalesced" | "inactive";
@@ -81,27 +81,38 @@ interface AgentToolBroadcastHooks {
   /** Live tailers per run; iterated to forward each progress chunk. */
   forwarders: Map<string, Set<(chunk: AgentToolStoredChunk) => void>>;
   /**
-   * Per-run forwarded-chunk counter; advanced even with no tailer attached.
+   * Per-run live counter of stored chunks; advanced even with no tailer
+   * attached, so a stored chunk's live sequence equals its stored chunk_index.
    *
-   * This is deliberately a SEPARATE counter from the resumable stream's stored
-   * chunk_index — do NOT try to "simplify" it away by sequencing off the store
-   * position. Not every forwarded frame is durably stored: progress/milestone
-   * frames (`reportProgress`) ride the same `USE_CHAT_RESPONSE` wire type and
-   * are snooped + forwarded here, but persist out-of-band (progress snapshot /
-   * milestone rows), so they have no store position. Sourcing the sequence from
-   * the store would give them a colliding position and the tail's high-water
-   * dedupe (`emit`) would silently drop them, breaking live progress/milestone
-   * delivery to the parent. This counter sequences stored AND non-stored frames
-   * on one monotonic line; the tail realigns it to the stored high-water on each
-   * (re)attach so a replay→live handoff stays gap/duplicate-free.
+   * Progress/milestone frames (`reportProgress`) ride the same
+   * `USE_CHAT_RESPONSE` wire type and are forwarded here, but persist
+   * out-of-band (progress snapshot / milestone rows) and have no store
+   * position. Neither do chunks too large to store (they carry an
+   * `unstoredId`). Both carry the next position WITHOUT consuming it, and
+   * tails emit them outside the stored-position high-water dedupe; counting
+   * them would push later stored chunks past their stored index, so a chunk
+   * stored and broadcast during a tail's drain would be emitted twice. A tail
+   * seeds a cold counter from the stored high-water before it attaches.
    */
   liveSequences: Map<string, number>;
   /** Per-run last error body, captured for replay to a late-attaching tailer. */
   lastErrors: Map<string, string>;
+  /**
+   * Called after a run's error body is captured, so the host can record it
+   * durably on the still-open run row (the in-memory {@link lastErrors} entry
+   * is lost if the DO is evicted before the run is finalized).
+   */
+  onError?: (runId: string, body: string) => void;
   /** The host's use-chat-response wire type (`CHAT_MESSAGE_TYPES.USE_CHAT_RESPONSE`). */
   responseType: string;
   /** Resolve the agent-tool run that owns a turn request id, or null. */
   runForRequest: (requestId: string) => string | null;
+  /**
+   * Runs whose chunks the host suppresses (`eventDelivery: "terminal"`). Keeps
+   * inspection on after a restart empties the other maps, so a recovered
+   * turn's chunks are still attributed and suppressed.
+   */
+  terminalOnlyRuns?: ReadonlySet<string>;
 }
 /**
  * Snoop a host's outgoing chat frames while any agent-tool run is in flight and
@@ -115,11 +126,14 @@ interface AgentToolBroadcastHooks {
  * error capture never depends on tailer timing. A frame belongs to a run iff it
  * carries that run's turn request id, so concurrent runs can't cross-contaminate
  * each other's progress or error state.
+ *
+ * Returns the run id when the frame is one of that run's content chunks, so a
+ * host can skip broadcasting chunks no client is watching.
  */
 declare function interceptAgentToolBroadcast(
   msg: string | ArrayBuffer | ArrayBufferView,
   hooks: AgentToolBroadcastHooks
-): void;
+): string | null;
 //#endregion
 export {
   applyAgentToolEvent as a,
@@ -130,4 +144,4 @@ export {
   interceptAgentToolBroadcast as s,
   AgentToolBroadcastHooks as t
 };
-//# sourceMappingURL=agent-tools-Dj5Mzlw7.d.ts.map
+//# sourceMappingURL=agent-tools-YrATZJu2.d.ts.map

package/dist/agent-tools.d.ts

@@ -1,25 +1,26 @@
 import {
-  $ as DetachedAgentToolConfig,
-  B as AgentToolInterruptedReason,
+  $ as ChatCapableAgentClass,
+  B as AgentToolFailure,
   F as AgentToolDisplayMetadata,
-  G as AgentToolRunInfo,
+  H as AgentToolLifecycleResult,
   I as AgentToolEvent,
-  J as AgentToolRunState,
-  K as AgentToolRunInspection,
-  L as AgentToolEventMessage,
+  J as AgentToolRunPart,
+  K as AgentToolRunInfo,
+  L as AgentToolEventDelivery,
   P as AgentToolChildAdapter,
-  Q as ChatCapableAgentClass,
-  R as AgentToolEventState,
-  V as AgentToolLifecycleResult,
-  X as AgentToolStoredChunk,
-  Y as AgentToolRunStatus,
-  Z as AgentToolTerminalStatus,
-  et as DetachedRunAgentToolResult,
-  nt as RunAgentToolResult,
-  q as AgentToolRunPart,
-  tt as RunAgentToolOptions,
-  z as AgentToolFailure
-} from "./agent-routing-B2XLNMxq.js";
+  Q as AgentToolTerminalStatus,
+  R as AgentToolEventMessage,
+  V as AgentToolInterruptedReason,
+  X as AgentToolRunStatus,
+  Y as AgentToolRunState,
+  Z as AgentToolStoredChunk,
+  et as DetachedAgentToolConfig,
+  nt as RunAgentToolOptions,
+  q as AgentToolRunInspection,
+  rt as RunAgentToolResult,
+  tt as DetachedRunAgentToolResult,
+  z as AgentToolEventState
+} from "./agent-routing-0DR0Tk2v.js";
 import { FlexibleSchema, InferSchema, Tool } from "ai";
 
 //#region src/agent-tools.d.ts
@@ -63,6 +64,7 @@ export {
   type AgentToolChildAdapter,
   type AgentToolDisplayMetadata,
   type AgentToolEvent,
+  type AgentToolEventDelivery,
   type AgentToolEventMessage,
   type AgentToolEventState,
   type AgentToolFactoryOptions,

package/dist/agent-tools.js.map

@@ -1 +1 @@
-{"version":3,"file":"agent-tools.js","names":["agentContext","createTool"],"sources":["../src/agent-tools.ts"],"sourcesContent":["import {\n  asSchema,\n  tool,\n  type FlexibleSchema,\n  type InferSchema,\n  type Tool\n} from \"ai\";\nimport { __DO_NOT_USE_WILL_BREAK__agentContext as agentContext } from \"./internal_context\";\nimport type {\n  ChatCapableAgentClass,\n  RunAgentToolOptions,\n  RunAgentToolResult,\n  AgentToolDisplayMetadata,\n  AgentToolFailure\n} from \"./agent-tool-types\";\n\ntype ParseSchema<Output = unknown> = {\n  parse(value: unknown): Output;\n};\n\ntype AgentToolOutputSchema<Output> =\n  | FlexibleSchema<Output>\n  | ParseSchema<Output>;\n\ntype AgentToolFactoryOptions<Output = unknown, Input = unknown> = {\n  description: string;\n  inputSchema: FlexibleSchema<Input>;\n  outputSchema?: AgentToolOutputSchema<Output>;\n  displayName?: string;\n  icon?: string;\n  display?: AgentToolDisplayMetadata;\n};\n\n// Capture the concrete schema type so the overload below can derive its input\n// with InferSchema. AgentToolFactoryOptions remains available for callers that\n// explicitly supply agentTool<Input, Output>() type arguments.\ntype InferredAgentToolFactoryOptions<\n  InputSchema extends FlexibleSchema,\n  Output\n> = Omit<AgentToolFactoryOptions<Output>, \"inputSchema\"> & {\n  inputSchema: InputSchema;\n};\n\ntype ToolExecutionOptions = {\n  toolCallId?: string;\n  abortSignal?: AbortSignal;\n};\n\ntype AgentToolRunner = {\n  runAgentTool<Input, Output>(\n    cls: ChatCapableAgentClass,\n    options: RunAgentToolOptions<Input>\n  ): Promise<RunAgentToolResult<Output>>;\n};\n\n/**\n * Preserve the existing Zod-style `.parse()` output-schema contract while\n * extending validation to the other formats supported by AI SDK FlexibleSchema.\n */\nasync function validateOutput<Output>(\n  schema: AgentToolOutputSchema<Output>,\n  value: unknown\n): Promise<Output> {\n  if (\n    typeof schema === \"object\" &&\n    schema !== null &&\n    \"parse\" in schema &&\n    typeof schema.parse === \"function\"\n  ) {\n    return schema.parse(value);\n  }\n\n  const validate = asSchema(schema as FlexibleSchema<Output>).validate;\n  if (!validate) {\n    throw new Error(\"agentTool outputSchema must provide runtime validation\");\n  }\n\n  const result = await validate(value);\n  if (!result.success) throw result.error;\n  return result.value;\n}\n\nfunction currentAgentToolRunner(): AgentToolRunner {\n  const agent = agentContext.getStore()?.agent;\n  if (\n    agent === null ||\n    typeof agent !== \"object\" ||\n    typeof (agent as { runAgentTool?: unknown }).runAgentTool !== \"function\"\n  ) {\n    throw new Error(\n      \"agentTool() can only run inside an Agent turn. Use it from getTools() on an Agent subclass.\"\n    );\n  }\n  return agent as AgentToolRunner;\n}\n\nfunction failure(\n  status: AgentToolFailure[\"status\"],\n  error: string,\n  retryable: boolean,\n  extra?: Pick<AgentToolFailure, \"reason\" | \"childStillRunning\">\n): AgentToolFailure {\n  return {\n    ok: false,\n    status,\n    error,\n    retryable,\n    ...(extra?.reason !== undefined ? { reason: extra.reason } : {}),\n    ...(extra?.childStillRunning !== undefined\n      ? { childStillRunning: extra.childStillRunning }\n      : {})\n  };\n}\n\n/**\n * Create an AI SDK tool that dispatches a chat-capable sub-agent through\n * `Agent.runAgentTool`.\n */\nexport function agentTool<InputSchema extends FlexibleSchema, Output = unknown>(\n  cls: ChatCapableAgentClass,\n  options: InferredAgentToolFactoryOptions<InputSchema, Output>\n): Tool<InferSchema<InputSchema>, string | Output | AgentToolFailure>;\n// Preserve existing callers that explicitly provide agentTool<Input, Output>().\nexport function agentTool<Input = unknown, Output = unknown>(\n  cls: ChatCapableAgentClass,\n  options: AgentToolFactoryOptions<Output, Input>\n): Tool<Input, string | Output | AgentToolFailure>;\nexport function agentTool<Input = unknown, Output = unknown>(\n  cls: ChatCapableAgentClass,\n  options: AgentToolFactoryOptions<Output, Input>\n): Tool<Input, string | Output | AgentToolFailure> {\n  const createTool = tool as unknown as <I, O>(config: {\n    description: string;\n    inputSchema: unknown;\n    execute: (input: I, options?: ToolExecutionOptions) => Promise<O>;\n  }) => Tool<I, O>;\n\n  return createTool<Input, string | Output | AgentToolFailure>({\n    description: options.description,\n    inputSchema: options.inputSchema,\n    execute: async (input: Input, executeOptions?: ToolExecutionOptions) => {\n      const display: AgentToolDisplayMetadata | undefined =\n        options.displayName || options.icon || options.display\n          ? {\n              ...options.display,\n              ...(options.displayName ? { name: options.displayName } : {}),\n              ...(options.icon ? { icon: options.icon } : {})\n            }\n          : undefined;\n\n      // Derive a STABLE runId from the tool call id (#1630). A tool call's id is\n      // preserved in the transcript, so when a parent turn is re-run by chat\n      // recovery after a deploy / eviction, the same `agentTool()` call resolves\n      // to the same runId — turning the re-issue into a duplicate that\n      // `runAgentTool` re-attaches to the still-running child, instead of a\n      // fresh `nanoid` that spawns a brand-new child and re-runs already-\n      // completed work (\"the agent went all the way back\"). Falls back to a\n      // fresh id only when there is no tool call id (rare; preserves prior\n      // behavior).\n      const runId = executeOptions?.toolCallId\n        ? `agent-tool:${executeOptions.toolCallId}`\n        : undefined;\n\n      const result = await currentAgentToolRunner().runAgentTool<Input, Output>(\n        cls,\n        {\n          input,\n          runId,\n          parentToolCallId: executeOptions?.toolCallId,\n          signal: executeOptions?.abortSignal,\n          display\n        }\n      );\n\n      if (result.status === \"completed\") {\n        if (options.outputSchema) {\n          if (result.output === undefined) {\n            return failure(\n              \"error\",\n              \"agent tool completed without structured output required by outputSchema\",\n              false\n            );\n          }\n          return validateOutput(options.outputSchema, result.output);\n        }\n        return result.summary ?? \"\";\n      }\n\n      if (result.status === \"aborted\") {\n        // Intentional cancellation (parent/user stopped the run) — not retryable.\n        return failure(\n          \"aborted\",\n          result.error ?? \"agent tool run was cancelled\",\n          false\n        );\n      }\n      if (result.status === \"interrupted\") {\n        // The child was reset/superseded by a deploy or parent recovery before\n        // it reached a logical outcome. Re-dispatching the run can succeed, so\n        // surface it as retryable rather than a terminal failure the parent\n        // would report to the user as final. `retryable` is intentionally COARSE\n        // (always true for `interrupted`); callers that want to distinguish a\n        // self-healing child from an exhausted one branch on `reason` /\n        // `childStillRunning` instead.\n        return failure(\n          \"interrupted\",\n          result.error ??\n            \"agent tool run was interrupted before it finished; it can be retried\",\n          true,\n          { reason: result.reason, childStillRunning: result.childStillRunning }\n        );\n      }\n      return failure(\"error\", result.error ?? \"agent tool run failed\", false);\n    }\n  });\n}\n\nexport type { AgentToolFactoryOptions };\nexport type {\n  AgentToolChildAdapter,\n  AgentToolDisplayMetadata,\n  AgentToolEvent,\n  AgentToolEventMessage,\n  AgentToolEventState,\n  AgentToolFailure,\n  AgentToolInterruptedReason,\n  AgentToolLifecycleResult,\n  AgentToolRunInfo,\n  AgentToolRunInspection,\n  AgentToolRunPart,\n  AgentToolRunState,\n  AgentToolRunStatus,\n  AgentToolStoredChunk,\n  AgentToolTerminalStatus,\n  ChatCapableAgentClass,\n  DetachedAgentToolConfig,\n  DetachedRunAgentToolResult,\n  RunAgentToolOptions,\n  RunAgentToolResult\n} from \"./agent-tool-types\";\n"],"mappings":";;;;;;;;AA2DA,eAAe,eACb,QACA,OACiB;CACjB,IACE,OAAO,WAAW,YAClB,WAAW,QACX,WAAW,UACX,OAAO,OAAO,UAAU,YAExB,OAAO,OAAO,MAAM,KAAK;CAG3B,MAAM,WAAW,SAAS,MAAgC,CAAC,CAAC;CAC5D,IAAI,CAAC,UACH,MAAM,IAAI,MAAM,wDAAwD;CAG1E,MAAM,SAAS,MAAM,SAAS,KAAK;CACnC,IAAI,CAAC,OAAO,SAAS,MAAM,OAAO;CAClC,OAAO,OAAO;AAChB;AAEA,SAAS,yBAA0C;CACjD,MAAM,QAAQA,sCAAa,SAAS,CAAC,EAAE;CACvC,IACE,UAAU,QACV,OAAO,UAAU,YACjB,OAAQ,MAAqC,iBAAiB,YAE9D,MAAM,IAAI,MACR,6FACF;CAEF,OAAO;AACT;AAEA,SAAS,QACP,QACA,OACA,WACA,OACkB;CAClB,OAAO;EACL,IAAI;EACJ;EACA;EACA;EACA,GAAI,OAAO,WAAW,KAAA,IAAY,EAAE,QAAQ,MAAM,OAAO,IAAI,CAAC;EAC9D,GAAI,OAAO,sBAAsB,KAAA,IAC7B,EAAE,mBAAmB,MAAM,kBAAkB,IAC7C,CAAC;CACP;AACF;AAeA,SAAgB,UACd,KACA,SACiD;CAOjD,OAAOC,KAAsD;EAC3D,aAAa,QAAQ;EACrB,aAAa,QAAQ;EACrB,SAAS,OAAO,OAAc,mBAA0C;GACtE,MAAM,UACJ,QAAQ,eAAe,QAAQ,QAAQ,QAAQ,UAC3C;IACE,GAAG,QAAQ;IACX,GAAI,QAAQ,cAAc,EAAE,MAAM,QAAQ,YAAY,IAAI,CAAC;IAC3D,GAAI,QAAQ,OAAO,EAAE,MAAM,QAAQ,KAAK,IAAI,CAAC;GAC/C,IACA,KAAA;GAWN,MAAM,QAAQ,gBAAgB,aAC1B,cAAc,eAAe,eAC7B,KAAA;GAEJ,MAAM,SAAS,MAAM,uBAAuB,CAAC,CAAC,aAC5C,KACA;IACE;IACA;IACA,kBAAkB,gBAAgB;IAClC,QAAQ,gBAAgB;IACxB;GACF,CACF;GAEA,IAAI,OAAO,WAAW,aAAa;IACjC,IAAI,QAAQ,cAAc;KACxB,IAAI,OAAO,WAAW,KAAA,GACpB,OAAO,QACL,SACA,2EACA,KACF;KAEF,OAAO,eAAe,QAAQ,cAAc,OAAO,MAAM;IAC3D;IACA,OAAO,OAAO,WAAW;GAC3B;GAEA,IAAI,OAAO,WAAW,WAEpB,OAAO,QACL,WACA,OAAO,SAAS,gCAChB,KACF;GAEF,IAAI,OAAO,WAAW,eAQpB,OAAO,QACL,eACA,OAAO,SACL,wEACF,MACA;IAAE,QAAQ,OAAO;IAAQ,mBAAmB,OAAO;GAAkB,CACvE;GAEF,OAAO,QAAQ,SAAS,OAAO,SAAS,yBAAyB,KAAK;EACxE;CACF,CAAC;AACH"}
+{"version":3,"file":"agent-tools.js","names":["agentContext","createTool"],"sources":["../src/agent-tools.ts"],"sourcesContent":["import {\n  asSchema,\n  tool,\n  type FlexibleSchema,\n  type InferSchema,\n  type Tool\n} from \"ai\";\nimport { __DO_NOT_USE_WILL_BREAK__agentContext as agentContext } from \"./internal_context\";\nimport type {\n  ChatCapableAgentClass,\n  RunAgentToolOptions,\n  RunAgentToolResult,\n  AgentToolDisplayMetadata,\n  AgentToolFailure\n} from \"./agent-tool-types\";\n\ntype ParseSchema<Output = unknown> = {\n  parse(value: unknown): Output;\n};\n\ntype AgentToolOutputSchema<Output> =\n  | FlexibleSchema<Output>\n  | ParseSchema<Output>;\n\ntype AgentToolFactoryOptions<Output = unknown, Input = unknown> = {\n  description: string;\n  inputSchema: FlexibleSchema<Input>;\n  outputSchema?: AgentToolOutputSchema<Output>;\n  displayName?: string;\n  icon?: string;\n  display?: AgentToolDisplayMetadata;\n};\n\n// Capture the concrete schema type so the overload below can derive its input\n// with InferSchema. AgentToolFactoryOptions remains available for callers that\n// explicitly supply agentTool<Input, Output>() type arguments.\ntype InferredAgentToolFactoryOptions<\n  InputSchema extends FlexibleSchema,\n  Output\n> = Omit<AgentToolFactoryOptions<Output>, \"inputSchema\"> & {\n  inputSchema: InputSchema;\n};\n\ntype ToolExecutionOptions = {\n  toolCallId?: string;\n  abortSignal?: AbortSignal;\n};\n\ntype AgentToolRunner = {\n  runAgentTool<Input, Output>(\n    cls: ChatCapableAgentClass,\n    options: RunAgentToolOptions<Input>\n  ): Promise<RunAgentToolResult<Output>>;\n};\n\n/**\n * Preserve the existing Zod-style `.parse()` output-schema contract while\n * extending validation to the other formats supported by AI SDK FlexibleSchema.\n */\nasync function validateOutput<Output>(\n  schema: AgentToolOutputSchema<Output>,\n  value: unknown\n): Promise<Output> {\n  if (\n    typeof schema === \"object\" &&\n    schema !== null &&\n    \"parse\" in schema &&\n    typeof schema.parse === \"function\"\n  ) {\n    return schema.parse(value);\n  }\n\n  const validate = asSchema(schema as FlexibleSchema<Output>).validate;\n  if (!validate) {\n    throw new Error(\"agentTool outputSchema must provide runtime validation\");\n  }\n\n  const result = await validate(value);\n  if (!result.success) throw result.error;\n  return result.value;\n}\n\nfunction currentAgentToolRunner(): AgentToolRunner {\n  const agent = agentContext.getStore()?.agent;\n  if (\n    agent === null ||\n    typeof agent !== \"object\" ||\n    typeof (agent as { runAgentTool?: unknown }).runAgentTool !== \"function\"\n  ) {\n    throw new Error(\n      \"agentTool() can only run inside an Agent turn. Use it from getTools() on an Agent subclass.\"\n    );\n  }\n  return agent as AgentToolRunner;\n}\n\nfunction failure(\n  status: AgentToolFailure[\"status\"],\n  error: string,\n  retryable: boolean,\n  extra?: Pick<AgentToolFailure, \"reason\" | \"childStillRunning\">\n): AgentToolFailure {\n  return {\n    ok: false,\n    status,\n    error,\n    retryable,\n    ...(extra?.reason !== undefined ? { reason: extra.reason } : {}),\n    ...(extra?.childStillRunning !== undefined\n      ? { childStillRunning: extra.childStillRunning }\n      : {})\n  };\n}\n\n/**\n * Create an AI SDK tool that dispatches a chat-capable sub-agent through\n * `Agent.runAgentTool`.\n */\nexport function agentTool<InputSchema extends FlexibleSchema, Output = unknown>(\n  cls: ChatCapableAgentClass,\n  options: InferredAgentToolFactoryOptions<InputSchema, Output>\n): Tool<InferSchema<InputSchema>, string | Output | AgentToolFailure>;\n// Preserve existing callers that explicitly provide agentTool<Input, Output>().\nexport function agentTool<Input = unknown, Output = unknown>(\n  cls: ChatCapableAgentClass,\n  options: AgentToolFactoryOptions<Output, Input>\n): Tool<Input, string | Output | AgentToolFailure>;\nexport function agentTool<Input = unknown, Output = unknown>(\n  cls: ChatCapableAgentClass,\n  options: AgentToolFactoryOptions<Output, Input>\n): Tool<Input, string | Output | AgentToolFailure> {\n  const createTool = tool as unknown as <I, O>(config: {\n    description: string;\n    inputSchema: unknown;\n    execute: (input: I, options?: ToolExecutionOptions) => Promise<O>;\n  }) => Tool<I, O>;\n\n  return createTool<Input, string | Output | AgentToolFailure>({\n    description: options.description,\n    inputSchema: options.inputSchema,\n    execute: async (input: Input, executeOptions?: ToolExecutionOptions) => {\n      const display: AgentToolDisplayMetadata | undefined =\n        options.displayName || options.icon || options.display\n          ? {\n              ...options.display,\n              ...(options.displayName ? { name: options.displayName } : {}),\n              ...(options.icon ? { icon: options.icon } : {})\n            }\n          : undefined;\n\n      // Derive a STABLE runId from the tool call id (#1630). A tool call's id is\n      // preserved in the transcript, so when a parent turn is re-run by chat\n      // recovery after a deploy / eviction, the same `agentTool()` call resolves\n      // to the same runId — turning the re-issue into a duplicate that\n      // `runAgentTool` re-attaches to the still-running child, instead of a\n      // fresh `nanoid` that spawns a brand-new child and re-runs already-\n      // completed work (\"the agent went all the way back\"). Falls back to a\n      // fresh id only when there is no tool call id (rare; preserves prior\n      // behavior).\n      const runId = executeOptions?.toolCallId\n        ? `agent-tool:${executeOptions.toolCallId}`\n        : undefined;\n\n      const result = await currentAgentToolRunner().runAgentTool<Input, Output>(\n        cls,\n        {\n          input,\n          runId,\n          parentToolCallId: executeOptions?.toolCallId,\n          signal: executeOptions?.abortSignal,\n          display\n        }\n      );\n\n      if (result.status === \"completed\") {\n        if (options.outputSchema) {\n          if (result.output === undefined) {\n            return failure(\n              \"error\",\n              \"agent tool completed without structured output required by outputSchema\",\n              false\n            );\n          }\n          return validateOutput(options.outputSchema, result.output);\n        }\n        return result.summary ?? \"\";\n      }\n\n      if (result.status === \"aborted\") {\n        // Intentional cancellation (parent/user stopped the run) — not retryable.\n        return failure(\n          \"aborted\",\n          result.error ?? \"agent tool run was cancelled\",\n          false\n        );\n      }\n      if (result.status === \"interrupted\") {\n        // The child was reset/superseded by a deploy or parent recovery before\n        // it reached a logical outcome. Re-dispatching the run can succeed, so\n        // surface it as retryable rather than a terminal failure the parent\n        // would report to the user as final. `retryable` is intentionally COARSE\n        // (always true for `interrupted`); callers that want to distinguish a\n        // self-healing child from an exhausted one branch on `reason` /\n        // `childStillRunning` instead.\n        return failure(\n          \"interrupted\",\n          result.error ??\n            \"agent tool run was interrupted before it finished; it can be retried\",\n          true,\n          { reason: result.reason, childStillRunning: result.childStillRunning }\n        );\n      }\n      return failure(\"error\", result.error ?? \"agent tool run failed\", false);\n    }\n  });\n}\n\nexport type { AgentToolFactoryOptions };\nexport type {\n  AgentToolChildAdapter,\n  AgentToolDisplayMetadata,\n  AgentToolEvent,\n  AgentToolEventDelivery,\n  AgentToolEventMessage,\n  AgentToolEventState,\n  AgentToolFailure,\n  AgentToolInterruptedReason,\n  AgentToolLifecycleResult,\n  AgentToolRunInfo,\n  AgentToolRunInspection,\n  AgentToolRunPart,\n  AgentToolRunState,\n  AgentToolRunStatus,\n  AgentToolStoredChunk,\n  AgentToolTerminalStatus,\n  ChatCapableAgentClass,\n  DetachedAgentToolConfig,\n  DetachedRunAgentToolResult,\n  RunAgentToolOptions,\n  RunAgentToolResult\n} from \"./agent-tool-types\";\n"],"mappings":";;;;;;;;AA2DA,eAAe,eACb,QACA,OACiB;CACjB,IACE,OAAO,WAAW,YAClB,WAAW,QACX,WAAW,UACX,OAAO,OAAO,UAAU,YAExB,OAAO,OAAO,MAAM,KAAK;CAG3B,MAAM,WAAW,SAAS,MAAgC,CAAC,CAAC;CAC5D,IAAI,CAAC,UACH,MAAM,IAAI,MAAM,wDAAwD;CAG1E,MAAM,SAAS,MAAM,SAAS,KAAK;CACnC,IAAI,CAAC,OAAO,SAAS,MAAM,OAAO;CAClC,OAAO,OAAO;AAChB;AAEA,SAAS,yBAA0C;CACjD,MAAM,QAAQA,sCAAa,SAAS,CAAC,EAAE;CACvC,IACE,UAAU,QACV,OAAO,UAAU,YACjB,OAAQ,MAAqC,iBAAiB,YAE9D,MAAM,IAAI,MACR,6FACF;CAEF,OAAO;AACT;AAEA,SAAS,QACP,QACA,OACA,WACA,OACkB;CAClB,OAAO;EACL,IAAI;EACJ;EACA;EACA;EACA,GAAI,OAAO,WAAW,KAAA,IAAY,EAAE,QAAQ,MAAM,OAAO,IAAI,CAAC;EAC9D,GAAI,OAAO,sBAAsB,KAAA,IAC7B,EAAE,mBAAmB,MAAM,kBAAkB,IAC7C,CAAC;CACP;AACF;AAeA,SAAgB,UACd,KACA,SACiD;CAOjD,OAAOC,KAAsD;EAC3D,aAAa,QAAQ;EACrB,aAAa,QAAQ;EACrB,SAAS,OAAO,OAAc,mBAA0C;GACtE,MAAM,UACJ,QAAQ,eAAe,QAAQ,QAAQ,QAAQ,UAC3C;IACE,GAAG,QAAQ;IACX,GAAI,QAAQ,cAAc,EAAE,MAAM,QAAQ,YAAY,IAAI,CAAC;IAC3D,GAAI,QAAQ,OAAO,EAAE,MAAM,QAAQ,KAAK,IAAI,CAAC;GAC/C,IACA,KAAA;GAWN,MAAM,QAAQ,gBAAgB,aAC1B,cAAc,eAAe,eAC7B,KAAA;GAEJ,MAAM,SAAS,MAAM,uBAAuB,CAAC,CAAC,aAC5C,KACA;IACE;IACA;IACA,kBAAkB,gBAAgB;IAClC,QAAQ,gBAAgB;IACxB;GACF,CACF;GAEA,IAAI,OAAO,WAAW,aAAa;IACjC,IAAI,QAAQ,cAAc;KACxB,IAAI,OAAO,WAAW,KAAA,GACpB,OAAO,QACL,SACA,2EACA,KACF;KAEF,OAAO,eAAe,QAAQ,cAAc,OAAO,MAAM;IAC3D;IACA,OAAO,OAAO,WAAW;GAC3B;GAEA,IAAI,OAAO,WAAW,WAEpB,OAAO,QACL,WACA,OAAO,SAAS,gCAChB,KACF;GAEF,IAAI,OAAO,WAAW,eAQpB,OAAO,QACL,eACA,OAAO,SACL,wEACF,MACA;IAAE,QAAQ,OAAO;IAAQ,mBAAmB,OAAO;GAAkB,CACvE;GAEF,OAAO,QAAQ,SAAS,OAAO,SAAS,yBAAyB,KAAK;EACxE;CACF,CAAC;AACH"}