agents 0.16.2 → 0.17.0

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

@@ -1,23 +1,33 @@
 import {
-  _ as RunAgentToolResult,
-  a as AgentToolEventState,
-  c as AgentToolLifecycleResult,
-  d as AgentToolRunState,
-  f as AgentToolRunStatus,
-  g as RunAgentToolOptions,
-  h as ChatCapableAgentClass,
-  i as AgentToolEventMessage,
-  l as AgentToolRunInfo,
-  m as AgentToolTerminalStatus,
-  n as AgentToolDisplayMetadata,
-  o as AgentToolFailure,
-  p as AgentToolStoredChunk,
-  r as AgentToolEvent,
-  s as AgentToolInterruptedReason,
-  t as AgentToolChildAdapter,
-  u as AgentToolRunInspection
-} from "./agent-tool-types-CTw3UJUP.js";
+  C as DetachedRunAgentToolResult,
+  S as DetachedAgentToolConfig,
+  T as RunAgentToolResult,
+  _ as AgentToolRunState,
+  a as AgentToolEvent,
+  b as AgentToolTerminalStatus,
+  c as AgentToolFailure,
+  d as AgentToolMilestone,
+  f as AgentToolProgress,
+  g as AgentToolRunPart,
+  h as AgentToolRunInspection,
+  i as AgentToolDisplayMetadata,
+  l as AgentToolInterruptedReason,
+  m as AgentToolRunInfo,
+  n as AGENT_TOOL_PROGRESS_PART,
+  o as AgentToolEventMessage,
+  p as AgentToolProgressSnapshot,
+  r as AgentToolChildAdapter,
+  s as AgentToolEventState,
+  t as AGENT_TOOL_MILESTONE_PART,
+  u as AgentToolLifecycleResult,
+  v as AgentToolRunStatus,
+  w as RunAgentToolOptions,
+  x as ChatCapableAgentClass,
+  y as AgentToolStoredChunk
+} from "./agent-tool-types-Cd1TZPfB.js";
 export {
+  AGENT_TOOL_MILESTONE_PART,
+  AGENT_TOOL_PROGRESS_PART,
   AgentToolChildAdapter,
   AgentToolDisplayMetadata,
   AgentToolEvent,
@@ -26,13 +36,19 @@ export {
   AgentToolFailure,
   AgentToolInterruptedReason,
   AgentToolLifecycleResult,
+  AgentToolMilestone,
+  AgentToolProgress,
+  AgentToolProgressSnapshot,
   AgentToolRunInfo,
   AgentToolRunInspection,
+  AgentToolRunPart,
   AgentToolRunState,
   AgentToolRunStatus,
   AgentToolStoredChunk,
   AgentToolTerminalStatus,
   ChatCapableAgentClass,
+  DetachedAgentToolConfig,
+  DetachedRunAgentToolResult,
   RunAgentToolOptions,
   RunAgentToolResult
 };

package/dist/agent-tool-types.js

@@ -1 +1,20 @@
-export {};
+//#region src/agent-tool-types.ts
+/**
+* Reserved chunk type a sub-agent emits via `reportProgress` while it runs.
+* Rides the child's own UI-message stream as a **transient** data part, so it
+* re-broadcasts to the parent's clients (via the parent's tail) and surfaces in
+* `useAgentToolEvents` without persisting into the child's stored message parts.
+* See `design/rfc-detached-agent-tools.md` §"Progress and milestone signaling".
+*/
+const AGENT_TOOL_PROGRESS_PART = "data-agent-progress";
+/**
+* Reserved chunk type a sub-agent emits via `reportProgress({ milestone })`.
+* Unlike the ephemeral progress part this rides the child's stream as a
+* **persisted** data part, so it survives eviction, replays on drill-in, and
+* re-resolves milestone waiters. See `design/rfc-detached-agent-tools.md`.
+*/
+const AGENT_TOOL_MILESTONE_PART = "data-agent-milestone";
+//#endregion
+export { AGENT_TOOL_MILESTONE_PART, AGENT_TOOL_PROGRESS_PART };
+
+//# sourceMappingURL=agent-tool-types.js.map

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

@@ -0,0 +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"}

package/dist/agent-tools-BXlsuX0d.js

@@ -0,0 +1,304 @@
+import { AGENT_TOOL_MILESTONE_PART, AGENT_TOOL_PROGRESS_PART } from "./agent-tool-types.js";
+import { t as applyChunkToParts } from "./message-builder-BymO4N_D.js";
+//#region src/chat/agent-tools.ts
+/**
+* Pull a reserved `data-agent-progress` chunk (emitted by a running sub-agent's
+* `reportProgress`) into a latest-wins snapshot. Returns `undefined` for any
+* other chunk so the caller keeps the prior snapshot.
+*/
+function readAgentToolProgressChunk(chunk) {
+	if (typeof chunk !== "object" || chunk === null || chunk.type !== "data-agent-progress") return;
+	const data = chunk.data ?? {};
+	return {
+		...typeof data.fraction === "number" ? { fraction: data.fraction } : {},
+		...typeof data.message === "string" ? { message: data.message } : {},
+		...typeof data.phase === "string" ? { phase: data.phase } : {},
+		...data.data !== void 0 ? { data: data.data } : {},
+		at: Date.now()
+	};
+}
+/**
+* Pull a reserved `data-agent-milestone` chunk into a durable milestone record,
+* or `undefined` for any other chunk. Milestones carry their own monotonic
+* `sequence` so the caller can dedupe replay-vs-live races.
+*/
+function readAgentToolMilestoneChunk(chunk) {
+	if (typeof chunk !== "object" || chunk === null || chunk.type !== "data-agent-milestone") return;
+	const data = chunk.data ?? {};
+	if (typeof data.name !== "string") return void 0;
+	return {
+		name: data.name,
+		sequence: typeof data.sequence === "number" ? data.sequence : 0,
+		at: typeof data.at === "number" ? data.at : Date.now(),
+		...data.data !== void 0 ? { data: data.data } : {}
+	};
+}
+/**
+* Merge a milestone into a run's ordered milestone list, deduping on `sequence`
+* (idempotent across replay + live races) and keeping the list sorted.
+*/
+function mergeMilestone(existing, milestone) {
+	if (existing?.some((m) => m.sequence === milestone.sequence)) return existing;
+	const list = existing ? [...existing, milestone] : [milestone];
+	list.sort((a, b) => a.sequence - b.sequence);
+	return list;
+}
+/** Latest-wins coalescing window for `reportProgress` emits (per run). */
+const AGENT_TOOL_PROGRESS_COALESCE_MS = 200;
+/**
+* Shared implementation of `reportProgress` for chat hosts. Builds the reserved
+* transient `data-agent-progress` wire frame, coalesces bursts to a bounded
+* cadence (latest-wins; a `fraction >= 1` "done" frame always flushes), and
+* persists a latest snapshot. `data` rides the live frame but is only persisted
+* when the caller opts in via `{ persist: true }`.
+*/
+var AgentToolProgressEmitter = class {
+	constructor(hooks) {
+		this.hooks = hooks;
+		this._lastEmitAt = /* @__PURE__ */ new Map();
+	}
+	report(progress, options) {
+		const active = this.hooks.resolveActiveRun();
+		if (!active) return "inactive";
+		const { runId, requestId } = active;
+		const now = Date.now();
+		if (typeof progress.milestone === "string" && progress.milestone) {
+			this._lastEmitAt.set(runId, now);
+			const sequence = this.hooks.persistMilestone(runId, progress.milestone, progress.data, now);
+			this.hooks.broadcast(requestId, JSON.stringify({
+				type: AGENT_TOOL_MILESTONE_PART,
+				data: {
+					name: progress.milestone,
+					sequence,
+					at: now,
+					...typeof progress.fraction === "number" ? { fraction: progress.fraction } : {},
+					...typeof progress.message === "string" ? { message: progress.message } : {},
+					...typeof progress.phase === "string" ? { phase: progress.phase } : {},
+					...progress.data !== void 0 ? { data: progress.data } : {}
+				}
+			}));
+			return "emitted";
+		}
+		const last = this._lastEmitAt.get(runId) ?? 0;
+		const isDone = typeof progress.fraction === "number" && progress.fraction >= 1;
+		if (now - last < AGENT_TOOL_PROGRESS_COALESCE_MS && !isDone) return "coalesced";
+		this._lastEmitAt.set(runId, now);
+		const wire = {
+			...typeof progress.fraction === "number" ? { fraction: progress.fraction } : {},
+			...typeof progress.message === "string" ? { message: progress.message } : {},
+			...typeof progress.phase === "string" ? { phase: progress.phase } : {},
+			...progress.data !== void 0 ? { data: progress.data } : {}
+		};
+		this.hooks.broadcast(requestId, JSON.stringify({
+			type: AGENT_TOOL_PROGRESS_PART,
+			transient: true,
+			data: wire
+		}));
+		this.hooks.persistSnapshot(runId, {
+			...typeof progress.fraction === "number" ? { fraction: progress.fraction } : {},
+			...typeof progress.message === "string" ? { message: progress.message } : {},
+			...typeof progress.phase === "string" ? { phase: progress.phase } : {},
+			...options?.persist && progress.data !== void 0 ? { data: progress.data } : {}
+		}, now);
+		return "emitted";
+	}
+	/** Drop coalescing state for a settled run (called on terminal). */
+	forget(runId) {
+		this._lastEmitAt.delete(runId);
+	}
+};
+function sortRuns(runs) {
+	return [...runs].sort((a, b) => {
+		if (a.order !== b.order) return a.order - b.order;
+		return a.runId.localeCompare(b.runId);
+	});
+}
+function rebuildIndexes(runsById) {
+	const grouped = {};
+	const unboundRuns = [];
+	for (const run of Object.values(runsById)) if (run.parentToolCallId) {
+		grouped[run.parentToolCallId] = grouped[run.parentToolCallId] ?? [];
+		grouped[run.parentToolCallId].push(run);
+	} else unboundRuns.push(run);
+	for (const [toolCallId, runs] of Object.entries(grouped)) grouped[toolCallId] = sortRuns(runs);
+	return {
+		runsByToolCallId: grouped,
+		unboundRuns: sortRuns(unboundRuns)
+	};
+}
+function emptyRun(message) {
+	const { event } = message;
+	if (event.kind === "started") return {
+		runId: event.runId,
+		agentType: event.agentType,
+		parentToolCallId: message.parentToolCallId,
+		inputPreview: event.inputPreview,
+		order: event.order,
+		display: event.display,
+		status: "running",
+		parts: [],
+		subAgent: {
+			agent: event.agentType,
+			name: event.runId
+		}
+	};
+}
+function applyToRun(prev, message) {
+	const seeded = prev ?? emptyRun(message);
+	const { event } = message;
+	switch (event.kind) {
+		case "started":
+			if (seeded?.status === "completed" || seeded?.status === "error" || seeded?.status === "aborted" || seeded?.status === "interrupted") return seeded;
+			return {
+				...seeded,
+				runId: event.runId,
+				agentType: event.agentType,
+				parentToolCallId: message.parentToolCallId,
+				inputPreview: event.inputPreview,
+				order: event.order,
+				display: event.display,
+				status: "running",
+				parts: seeded?.parts ?? [],
+				subAgent: {
+					agent: event.agentType,
+					name: event.runId
+				}
+			};
+		case "chunk": {
+			if (!seeded) return void 0;
+			const parts = [...seeded.parts];
+			let parsed;
+			try {
+				parsed = JSON.parse(event.body);
+				applyChunkToParts(parts, parsed);
+			} catch {
+				return seeded;
+			}
+			const progress = readAgentToolProgressChunk(parsed);
+			if (progress) return {
+				...seeded,
+				parts,
+				progress
+			};
+			const milestone = readAgentToolMilestoneChunk(parsed);
+			if (milestone) {
+				const milestones = mergeMilestone(seeded.milestones, milestone);
+				const isNew = milestones !== seeded.milestones;
+				const notOlder = seeded.progress === void 0 || milestone.at >= seeded.progress.at;
+				if (!isNew || !notOlder) return {
+					...seeded,
+					parts,
+					milestones
+				};
+				const data = parsed.data ?? {};
+				const snapshot = {
+					...typeof data.fraction === "number" ? { fraction: data.fraction } : {},
+					...typeof data.message === "string" ? { message: data.message } : {},
+					...typeof data.phase === "string" ? { phase: data.phase } : {},
+					milestone: milestone.name,
+					at: milestone.at
+				};
+				return {
+					...seeded,
+					parts,
+					progress: snapshot,
+					milestones
+				};
+			}
+			return {
+				...seeded,
+				parts
+			};
+		}
+		case "finished":
+			if (!seeded) return void 0;
+			return {
+				...seeded,
+				status: "completed",
+				summary: event.summary,
+				error: void 0
+			};
+		case "error":
+			if (!seeded) return void 0;
+			return {
+				...seeded,
+				status: "error",
+				error: event.error
+			};
+		case "aborted":
+			if (!seeded) return void 0;
+			return {
+				...seeded,
+				status: "aborted",
+				error: event.reason
+			};
+		case "interrupted":
+			if (!seeded) return void 0;
+			return {
+				...seeded,
+				status: "interrupted",
+				error: event.error,
+				reason: event.reason,
+				childStillRunning: event.childStillRunning
+			};
+	}
+}
+function createAgentToolEventState() {
+	return {
+		runsById: {},
+		runsByToolCallId: {},
+		unboundRuns: []
+	};
+}
+function applyAgentToolEvent(state, message) {
+	if (message.type !== "agent-tool-event") return state;
+	const runId = message.event.runId;
+	const nextRun = applyToRun(state.runsById[runId], message);
+	if (!nextRun) return state;
+	const runsById = {
+		...state.runsById,
+		[runId]: nextRun
+	};
+	return {
+		runsById,
+		...rebuildIndexes(runsById)
+	};
+}
+/**
+* Snoop a host's outgoing chat frames while any agent-tool run is in flight and
+* forward the owning run's streamed body to its live tailers (or capture its
+* error), without altering the frame — the caller still broadcasts it (#1575).
+*
+* Shared verbatim by `@cloudflare/ai-chat` and `@cloudflare/think`; the only
+* per-host variance (the response-frame type constant and the run-lookup, whose
+* SQL differs) is supplied via {@link AgentToolBroadcastHooks}. Inspection runs
+* for a run's whole lifecycle (live sequences exist even with no tailer), so
+* 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.
+*/
+function interceptAgentToolBroadcast(msg, hooks) {
+	if ((hooks.forwarders.size > 0 || hooks.liveSequences.size > 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) {
+					const sequence = hooks.liveSequences.get(runId) ?? 0;
+					hooks.liveSequences.set(runId, sequence + 1);
+					const chunk = {
+						sequence,
+						body: parsed.body
+					};
+					const forwarders = hooks.forwarders.get(runId);
+					if (forwarders) for (const forward of forwarders) forward(chunk);
+				}
+			}
+		}
+	} catch {}
+}
+//#endregion
+export { interceptAgentToolBroadcast as i, applyAgentToolEvent as n, createAgentToolEventState as r, AgentToolProgressEmitter as t };
+
+//# sourceMappingURL=agent-tools-BXlsuX0d.js.map

package/dist/agent-tools-BXlsuX0d.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"agent-tools-BXlsuX0d.js","names":[],"sources":["../src/chat/agent-tools.ts"],"sourcesContent":["import { applyChunkToParts, type MessagePart } from \"./message-builder\";\nimport {\n  AGENT_TOOL_MILESTONE_PART,\n  AGENT_TOOL_PROGRESS_PART\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    this.hooks.broadcast(\n      requestId,\n      JSON.stringify({\n        type: AGENT_TOOL_PROGRESS_PART,\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      const parts = [...seeded.parts];\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\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 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  /** Per-run forwarded-chunk counter; advanced even with no tailer attached. */\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  /** 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\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 */\nexport function interceptAgentToolBroadcast(\n  msg: string | ArrayBuffer | ArrayBufferView,\n  hooks: AgentToolBroadcastHooks\n): void {\n  if (\n    (hooks.forwarders.size > 0 || hooks.liveSequences.size > 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          } 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.\n            const sequence = hooks.liveSequences.get(runId) ?? 0;\n            hooks.liveSequences.set(runId, sequence + 1);\n            const chunk: AgentToolStoredChunk = { sequence, body: parsed.body };\n            const forwarders = hooks.forwarders.get(runId);\n            if (forwarders) {\n              for (const forward of forwarders) forward(chunk);\n            }\n          }\n        }\n      }\n    } catch {\n      // Non-chat frames pass through unchanged.\n    }\n  }\n}\n"],"mappings":"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"}

package/dist/agent-tools-_E8wxUIK.d.ts

@@ -0,0 +1,119 @@
+import {
+  f as AgentToolProgress,
+  g as AgentToolRunPart,
+  o as AgentToolEventMessage,
+  s as AgentToolEventState,
+  y as AgentToolStoredChunk
+} from "./agent-tool-types-Cd1TZPfB.js";
+
+//#region src/chat/agent-tools.d.ts
+type AgentToolProgressEmitResult = "emitted" | "coalesced" | "inactive";
+/**
+ * Host-injected seams the shared progress emitter needs. Keeps the per-host
+ * `reportProgress` thin: Think / AIChatAgent supply how to resolve the active
+ * agent-tool run, how to broadcast a chat-response frame, and how to persist the
+ * latest snapshot on their own child-run table.
+ */
+type AgentToolProgressEmitHooks = {
+  /** The agent-tool run currently executing in this turn, or null. */ resolveActiveRun: () => {
+    runId: string;
+    requestId: string;
+  } | null /** Broadcast a chat-response frame (id = requestId) to clients/tailers. */;
+  broadcast: (
+    requestId: string,
+    chunkBody: string
+  ) => void /** Persist the latest snapshot + signal timestamp on the child run row. */;
+  persistSnapshot: (
+    runId: string,
+    snapshot: {
+      fraction?: number;
+      message?: string;
+      phase?: string;
+      data?: unknown;
+    },
+    at: number
+  ) => void;
+  /**
+   * Persist a durable milestone row, bump the run's signal timestamp, and return
+   * the assigned monotonic per-run `sequence` (used to dedupe replay/live races).
+   */
+  persistMilestone: (
+    runId: string,
+    name: string,
+    data: unknown,
+    at: number
+  ) => number;
+};
+/**
+ * Shared implementation of `reportProgress` for chat hosts. Builds the reserved
+ * transient `data-agent-progress` wire frame, coalesces bursts to a bounded
+ * cadence (latest-wins; a `fraction >= 1` "done" frame always flushes), and
+ * persists a latest snapshot. `data` rides the live frame but is only persisted
+ * when the caller opts in via `{ persist: true }`.
+ */
+declare class AgentToolProgressEmitter {
+  private readonly hooks;
+  private readonly _lastEmitAt;
+  constructor(hooks: AgentToolProgressEmitHooks);
+  report(
+    progress: AgentToolProgress,
+    options?: {
+      persist?: boolean;
+    }
+  ): AgentToolProgressEmitResult;
+  /** Drop coalescing state for a settled run (called on terminal). */
+  forget(runId: string): void;
+}
+declare function createAgentToolEventState<
+  Part extends AgentToolRunPart = AgentToolRunPart
+>(): AgentToolEventState<Part>;
+declare function applyAgentToolEvent<
+  Part extends AgentToolRunPart = AgentToolRunPart
+>(
+  state: AgentToolEventState<Part>,
+  message: AgentToolEventMessage
+): AgentToolEventState<Part>;
+/**
+ * @internal Host substrate the {@link interceptAgentToolBroadcast} snoop reads,
+ * abstracting the divergent per-host run-lookup and response-frame constant.
+ */
+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. */
+  liveSequences: Map<string, number>;
+  /** Per-run last error body, captured for replay to a late-attaching tailer. */
+  lastErrors: Map<string, string>;
+  /** 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;
+}
+/**
+ * Snoop a host's outgoing chat frames while any agent-tool run is in flight and
+ * forward the owning run's streamed body to its live tailers (or capture its
+ * error), without altering the frame — the caller still broadcasts it (#1575).
+ *
+ * Shared verbatim by `@cloudflare/ai-chat` and `@cloudflare/think`; the only
+ * per-host variance (the response-frame type constant and the run-lookup, whose
+ * SQL differs) is supplied via {@link AgentToolBroadcastHooks}. Inspection runs
+ * for a run's whole lifecycle (live sequences exist even with no tailer), so
+ * 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.
+ */
+declare function interceptAgentToolBroadcast(
+  msg: string | ArrayBuffer | ArrayBufferView,
+  hooks: AgentToolBroadcastHooks
+): void;
+//#endregion
+export {
+  applyAgentToolEvent as a,
+  AgentToolProgressEmitter as i,
+  AgentToolProgressEmitHooks as n,
+  createAgentToolEventState as o,
+  AgentToolProgressEmitResult as r,
+  interceptAgentToolBroadcast as s,
+  AgentToolBroadcastHooks as t
+};
+//# sourceMappingURL=agent-tools-_E8wxUIK.d.ts.map