agents 0.13.3 → 0.14.0

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

@@ -1,26 +1,28 @@
 import {
   a as AgentToolEventState,
-  c as AgentToolRunInspection,
-  d as AgentToolStoredChunk,
-  f as AgentToolTerminalStatus,
-  h as RunAgentToolResult,
+  c as AgentToolRunInfo,
+  d as AgentToolRunStatus,
+  f as AgentToolStoredChunk,
+  g as RunAgentToolResult,
+  h as RunAgentToolOptions,
   i as AgentToolEventMessage,
-  l as AgentToolRunState,
-  m as RunAgentToolOptions,
+  l as AgentToolRunInspection,
+  m as ChatCapableAgentClass,
   n as AgentToolDisplayMetadata,
-  o as AgentToolLifecycleResult,
-  p as ChatCapableAgentClass,
+  o as AgentToolFailure,
+  p as AgentToolTerminalStatus,
   r as AgentToolEvent,
-  s as AgentToolRunInfo,
+  s as AgentToolLifecycleResult,
   t as AgentToolChildAdapter,
-  u as AgentToolRunStatus
-} from "./agent-tool-types-l98LCbBl.js";
+  u as AgentToolRunState
+} from "./agent-tool-types-LInzZfLo.js";
 export {
   AgentToolChildAdapter,
   AgentToolDisplayMetadata,
   AgentToolEvent,
   AgentToolEventMessage,
   AgentToolEventState,
+  AgentToolFailure,
   AgentToolLifecycleResult,
   AgentToolRunInfo,
   AgentToolRunInspection,

package/dist/{agent-tools-Bg5ilERh.d.ts → agent-tools-BE9xosUG.d.ts}

@@ -1,7 +1,7 @@
 import {
   a as AgentToolEventState,
   i as AgentToolEventMessage
-} from "./agent-tool-types-l98LCbBl.js";
+} from "./agent-tool-types-LInzZfLo.js";
 
 //#region src/chat/agent-tools.d.ts
 declare function createAgentToolEventState(): AgentToolEventState;
@@ -11,4 +11,4 @@ declare function applyAgentToolEvent(
 ): AgentToolEventState;
 //#endregion
 export { createAgentToolEventState as n, applyAgentToolEvent as t };
-//# sourceMappingURL=agent-tools-Bg5ilERh.d.ts.map
+//# sourceMappingURL=agent-tools-BE9xosUG.d.ts.map

package/dist/agent-tools.d.ts

@@ -1,20 +1,21 @@
 import {
   a as AgentToolEventState,
-  c as AgentToolRunInspection,
-  d as AgentToolStoredChunk,
-  f as AgentToolTerminalStatus,
-  h as RunAgentToolResult,
+  c as AgentToolRunInfo,
+  d as AgentToolRunStatus,
+  f as AgentToolStoredChunk,
+  g as RunAgentToolResult,
+  h as RunAgentToolOptions,
   i as AgentToolEventMessage,
-  l as AgentToolRunState,
-  m as RunAgentToolOptions,
+  l as AgentToolRunInspection,
+  m as ChatCapableAgentClass,
   n as AgentToolDisplayMetadata,
-  o as AgentToolLifecycleResult,
-  p as ChatCapableAgentClass,
+  o as AgentToolFailure,
+  p as AgentToolTerminalStatus,
   r as AgentToolEvent,
-  s as AgentToolRunInfo,
+  s as AgentToolLifecycleResult,
   t as AgentToolChildAdapter,
-  u as AgentToolRunStatus
-} from "./agent-tool-types-l98LCbBl.js";
+  u as AgentToolRunState
+} from "./agent-tool-types-LInzZfLo.js";
 import { Tool } from "ai";
 
 //#region src/agent-tools.d.ts
@@ -36,15 +37,7 @@ type AgentToolFactoryOptions<Output = unknown> = {
 declare function agentTool<Input = unknown, Output = unknown>(
   cls: ChatCapableAgentClass,
   options: AgentToolFactoryOptions<Output>
-): Tool<
-  Input,
-  | string
-  | Output
-  | {
-      ok: false;
-      error: string;
-    }
->;
+): Tool<Input, string | Output | AgentToolFailure>;
 //#endregion
 export {
   type AgentToolChildAdapter,
@@ -53,6 +46,7 @@ export {
   type AgentToolEventMessage,
   type AgentToolEventState,
   type AgentToolFactoryOptions,
+  type AgentToolFailure,
   type AgentToolLifecycleResult,
   type AgentToolRunInfo,
   type AgentToolRunInspection,

package/dist/agent-tools.js

@@ -6,10 +6,12 @@ function currentAgentToolRunner() {
 	if (agent === null || typeof agent !== "object" || typeof agent.runAgentTool !== "function") throw new Error("agentTool() can only run inside an Agent turn. Use it from getTools() on an Agent subclass.");
 	return agent;
 }
-function failure(error) {
+function failure(status, error, retryable) {
 	return {
 		ok: false,
-		error
+		status,
+		error,
+		retryable
 	};
 }
 /**
@@ -26,22 +28,24 @@ function agentTool(cls, options) {
 				...options.displayName ? { name: options.displayName } : {},
 				...options.icon ? { icon: options.icon } : {}
 			} : void 0;
+			const runId = executeOptions?.toolCallId ? `agent-tool:${executeOptions.toolCallId}` : void 0;
 			const result = await currentAgentToolRunner().runAgentTool(cls, {
 				input,
+				runId,
 				parentToolCallId: executeOptions?.toolCallId,
 				signal: executeOptions?.abortSignal,
 				display
 			});
 			if (result.status === "completed") {
 				if (options.outputSchema) {
-					if (result.output === void 0) return failure("agent tool completed without structured output required by outputSchema");
+					if (result.output === void 0) return failure("error", "agent tool completed without structured output required by outputSchema", false);
 					return options.outputSchema.parse(result.output);
 				}
 				return result.summary ?? "";
 			}
-			if (result.status === "aborted") return failure("agent tool run was cancelled");
-			if (result.status === "interrupted") return failure("agent tool run was interrupted; no recoverable output");
-			return failure(result.error ?? "agent tool run failed");
+			if (result.status === "aborted") return failure("aborted", result.error ?? "agent tool run was cancelled", false);
+			if (result.status === "interrupted") return failure("interrupted", result.error ?? "agent tool run was interrupted before it finished; it can be retried", true);
+			return failure("error", result.error ?? "agent tool run failed", false);
 		}
 	});
 }

package/dist/agent-tools.js.map

@@ -1 +1 @@
-{"version":3,"file":"agent-tools.js","names":["agentContext","createTool"],"sources":["../src/agent-tools.ts"],"sourcesContent":["import { tool, type Tool } 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} from \"./agent-tool-types\";\n\ntype SchemaLike<T = unknown> = {\n  parse(value: unknown): T;\n};\n\ntype AgentToolFactoryOptions<Output = unknown> = {\n  description: string;\n  inputSchema: unknown;\n  outputSchema?: SchemaLike<Output>;\n  displayName?: string;\n  icon?: string;\n  display?: AgentToolDisplayMetadata;\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\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(error: string): { ok: false; error: string } {\n  return { ok: false, error };\n}\n\n/**\n * Create an AI SDK tool that dispatches a chat-capable sub-agent through\n * `Agent.runAgentTool`.\n */\nexport function agentTool<Input = unknown, Output = unknown>(\n  cls: ChatCapableAgentClass,\n  options: AgentToolFactoryOptions<Output>\n): Tool<Input, string | Output | { ok: false; error: string }> {\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 | { ok: false; error: string }>({\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      const result = await currentAgentToolRunner().runAgentTool<Input, Output>(\n        cls,\n        {\n          input,\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              \"agent tool completed without structured output required by outputSchema\"\n            );\n          }\n          return options.outputSchema.parse(result.output);\n        }\n        return result.summary ?? \"\";\n      }\n\n      if (result.status === \"aborted\") {\n        return failure(\"agent tool run was cancelled\");\n      }\n      if (result.status === \"interrupted\") {\n        return failure(\"agent tool run was interrupted; no recoverable output\");\n      }\n      return failure(result.error ?? \"agent tool run failed\");\n    }\n  });\n}\n\nexport type { AgentToolFactoryOptions };\nexport type {\n  AgentToolChildAdapter,\n  AgentToolDisplayMetadata,\n  AgentToolEvent,\n  AgentToolEventMessage,\n  AgentToolEventState,\n  AgentToolLifecycleResult,\n  AgentToolRunInfo,\n  AgentToolRunInspection,\n  AgentToolRunState,\n  AgentToolRunStatus,\n  AgentToolStoredChunk,\n  AgentToolTerminalStatus,\n  ChatCapableAgentClass,\n  RunAgentToolOptions,\n  RunAgentToolResult\n} from \"./agent-tool-types\";\n"],"mappings":";;;AAkCA,SAAS,yBAA0C;CACjD,MAAM,QAAQA,sCAAa,SAAS,GAAG;CACvC,IACE,UAAU,QACV,OAAO,UAAU,YACjB,OAAQ,MAAqC,iBAAiB,YAE9D,MAAM,IAAI,MACR,6FACF;CAEF,OAAO;AACT;AAEA,SAAS,QAAQ,OAA6C;CAC5D,OAAO;EAAE,IAAI;EAAO;CAAM;AAC5B;;;;;AAMA,SAAgB,UACd,KACA,SAC6D;CAO7D,OAAOC,KAAkE;EACvE,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;GAEN,MAAM,SAAS,MAAM,uBAAuB,EAAE,aAC5C,KACA;IACE;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,yEACF;KAEF,OAAO,QAAQ,aAAa,MAAM,OAAO,MAAM;IACjD;IACA,OAAO,OAAO,WAAW;GAC3B;GAEA,IAAI,OAAO,WAAW,WACpB,OAAO,QAAQ,8BAA8B;GAE/C,IAAI,OAAO,WAAW,eACpB,OAAO,QAAQ,uDAAuD;GAExE,OAAO,QAAQ,OAAO,SAAS,uBAAuB;EACxD;CACF,CAAC;AACH"}
+{"version":3,"file":"agent-tools.js","names":["agentContext","createTool"],"sources":["../src/agent-tools.ts"],"sourcesContent":["import { tool, type Tool } 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 SchemaLike<T = unknown> = {\n  parse(value: unknown): T;\n};\n\ntype AgentToolFactoryOptions<Output = unknown> = {\n  description: string;\n  inputSchema: unknown;\n  outputSchema?: SchemaLike<Output>;\n  displayName?: string;\n  icon?: string;\n  display?: AgentToolDisplayMetadata;\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\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): AgentToolFailure {\n  return { ok: false, status, error, retryable };\n}\n\n/**\n * Create an AI SDK tool that dispatches a chat-capable sub-agent through\n * `Agent.runAgentTool`.\n */\nexport function agentTool<Input = unknown, Output = unknown>(\n  cls: ChatCapableAgentClass,\n  options: AgentToolFactoryOptions<Output>\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 options.outputSchema.parse(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.\n        return failure(\n          \"interrupted\",\n          result.error ??\n            \"agent tool run was interrupted before it finished; it can be retried\",\n          true\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  AgentToolLifecycleResult,\n  AgentToolRunInfo,\n  AgentToolRunInspection,\n  AgentToolRunState,\n  AgentToolRunStatus,\n  AgentToolStoredChunk,\n  AgentToolTerminalStatus,\n  ChatCapableAgentClass,\n  RunAgentToolOptions,\n  RunAgentToolResult\n} from \"./agent-tool-types\";\n"],"mappings":";;;AAmCA,SAAS,yBAA0C;CACjD,MAAM,QAAQA,sCAAa,SAAS,GAAG;CACvC,IACE,UAAU,QACV,OAAO,UAAU,YACjB,OAAQ,MAAqC,iBAAiB,YAE9D,MAAM,IAAI,MACR,6FACF;CAEF,OAAO;AACT;AAEA,SAAS,QACP,QACA,OACA,WACkB;CAClB,OAAO;EAAE,IAAI;EAAO;EAAQ;EAAO;CAAU;AAC/C;;;;;AAMA,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,EAAE,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,QAAQ,aAAa,MAAM,OAAO,MAAM;IACjD;IACA,OAAO,OAAO,WAAW;GAC3B;GAEA,IAAI,OAAO,WAAW,WAEpB,OAAO,QACL,WACA,OAAO,SAAS,gCAChB,KACF;GAEF,IAAI,OAAO,WAAW,eAKpB,OAAO,QACL,eACA,OAAO,SACL,wEACF,IACF;GAEF,OAAO,QAAQ,SAAS,OAAO,SAAS,yBAAyB,KAAK;EACxE;CACF,CAAC;AACH"}

package/dist/browser/ai.d.ts

@@ -1,4 +1,4 @@
-import { t as BrowserToolsOptions } from "../shared-Cvj92byG.js";
+import { t as BrowserToolsOptions } from "../shared-CpY1FLvm.js";
 import { ToolSet } from "ai";
 
 //#region src/browser/ai.d.ts

package/dist/browser/ai.js

@@ -1,4 +1,4 @@
-import { n as SEARCH_DESCRIPTION, r as createBrowserToolHandlers, t as EXECUTE_DESCRIPTION } from "../shared-CiKaIK4h.js";
+import { n as SEARCH_DESCRIPTION, r as createBrowserToolHandlers, t as EXECUTE_DESCRIPTION } from "../shared-DdOn6sp4.js";
 import { tool } from "ai";
 import { z } from "zod";
 //#region src/browser/ai.ts

package/dist/browser/index.d.ts

@@ -4,7 +4,7 @@ import {
   n as EXECUTE_DESCRIPTION,
   r as SEARCH_DESCRIPTION,
   t as BrowserToolsOptions
-} from "../shared-Cvj92byG.js";
+} from "../shared-CpY1FLvm.js";
 
 //#region src/browser/cdp-session.d.ts
 interface DebugEntry {

package/dist/browser/index.js

@@ -1,2 +1,2 @@
-import { a as connectBrowser, i as CdpSession, n as SEARCH_DESCRIPTION, o as connectUrl, r as createBrowserToolHandlers, t as EXECUTE_DESCRIPTION } from "../shared-CiKaIK4h.js";
+import { a as connectBrowser, i as CdpSession, n as SEARCH_DESCRIPTION, o as connectUrl, r as createBrowserToolHandlers, t as EXECUTE_DESCRIPTION } from "../shared-DdOn6sp4.js";
 export { CdpSession, EXECUTE_DESCRIPTION, SEARCH_DESCRIPTION, connectBrowser, connectUrl, createBrowserToolHandlers };

package/dist/browser/tanstack-ai.d.ts

@@ -1,4 +1,4 @@
-import { t as BrowserToolsOptions } from "../shared-Cvj92byG.js";
+import { t as BrowserToolsOptions } from "../shared-CpY1FLvm.js";
 import { ServerTool } from "@tanstack/ai";
 
 //#region src/browser/tanstack-ai.d.ts

package/dist/browser/tanstack-ai.js

@@ -1,4 +1,4 @@
-import { n as SEARCH_DESCRIPTION, r as createBrowserToolHandlers, t as EXECUTE_DESCRIPTION } from "../shared-CiKaIK4h.js";
+import { n as SEARCH_DESCRIPTION, r as createBrowserToolHandlers, t as EXECUTE_DESCRIPTION } from "../shared-DdOn6sp4.js";
 import { z } from "zod";
 import { toolDefinition } from "@tanstack/ai";
 //#region src/browser/tanstack-ai.ts

package/dist/chat/index.d.ts

@@ -1,13 +1,13 @@
 import {
   a as AgentToolEventState,
   i as AgentToolEventMessage,
-  l as AgentToolRunState,
-  r as AgentToolEvent
-} from "../agent-tool-types-l98LCbBl.js";
+  r as AgentToolEvent,
+  u as AgentToolRunState
+} from "../agent-tool-types-LInzZfLo.js";
 import {
   n as createAgentToolEventState,
   t as applyAgentToolEvent
-} from "../agent-tools-Bg5ilERh.js";
+} from "../agent-tools-BE9xosUG.js";
 import { JSONSchema7, Tool, ToolSet, UIMessage } from "ai";
 import { Connection } from "agents";
 
@@ -334,7 +334,21 @@ type SaveMessagesResult = {
  * stream is detected after DO restart.
  */
 type ChatRecoveryContext = {
-  /** Stream ID from the interrupted stream. */ streamId: string /** Request ID from the interrupted stream. */;
+  /** Stable identifier for this recovery incident. */ incidentId: string;
+  /**
+   * Stable request ID for the whole continuation chain (the recovery "root").
+   * Unlike `requestId` — which changes on every chained continuation — this is
+   * constant for the lifetime of the incident, so it's the right key for
+   * per-incident budget tracking or fresh-incident detection without
+   * re-deriving identity from message IDs.
+   */
+  recoveryRootRequestId: string /** Attempt number for this recovery incident, starting at 1. */;
+  attempt: number /** Maximum attempts before the framework terminalizes recovery. */;
+  maxAttempts: number /** Whether this recovery is retrying an unanswered user turn or continuing a partial assistant turn. */;
+  recoveryKind:
+    | "retry"
+    | "continue" /** Stream ID from the interrupted stream. */;
+  streamId: string /** Request ID from the interrupted stream. */;
   requestId: string /** Partial text extracted from stored chunks. */;
   partialText: string /** Partial message parts reconstructed from chunks. */;
   partialParts: MessagePart[] /** Checkpoint data from `this.stash()` during the interrupted stream. */;
@@ -359,6 +373,59 @@ type ChatRecoveryOptions = {
   /** Save the partial response from stored chunks. Default: true. */ persist?: boolean /** Schedule a continuation via `continueLastTurn()`. Default: true. */;
   continue?: boolean;
 };
+/**
+ * Context passed when framework-owned chat recovery exhausts its retry budget.
+ *
+ * Carries enough to render/persist a user-facing terminal banner without
+ * re-deriving anything: the `terminalMessage` that was shown, the
+ * `recoveryRootRequestId` (stable incident identity), and the partial the turn
+ * produced before it was given up on.
+ */
+type ChatRecoveryExhaustedContext = Pick<
+  ChatRecoveryContext,
+  | "incidentId"
+  | "requestId"
+  | "recoveryRootRequestId"
+  | "attempt"
+  | "maxAttempts"
+  | "recoveryKind"
+  | "streamId"
+  | "createdAt"
+  | "partialText"
+  | "partialParts"
+> & {
+  /**
+   * Why recovery stopped. One of:
+   * - `max_attempts_exceeded` — the per-incident attempt budget was spent.
+   * - `no_progress_timeout` — no forward progress within the no-progress window.
+   * - `max_recovery_window_exceeded` — the absolute incident-age ceiling was hit.
+   * - `stable_timeout` — a recovery attempt kept timing out waiting for the
+   *   isolate to reach stable state until the budget drained (extreme churn).
+   *
+   * Treat this as an open string: new reasons may be added.
+   */
+  reason: string /** The terminal message shown to the user (from the `chatRecovery` config). */;
+  terminalMessage: string;
+};
+/**
+ * Configuration for durable chat recovery. `true` uses these defaults:
+ * `maxAttempts: 6`, `stableTimeoutMs: 10_000`, and a generic terminal message.
+ */
+type ChatRecoveryConfig =
+  | boolean
+  | {
+      maxAttempts?: number;
+      stableTimeoutMs?: number;
+      terminalMessage?: string;
+      onExhausted?(ctx: ChatRecoveryExhaustedContext): void | Promise<void>;
+    };
+type ResolvedChatRecoveryConfig = {
+  enabled: boolean;
+  maxAttempts: number;
+  stableTimeoutMs: number;
+  terminalMessage: string;
+  onExhausted?: (ctx: ChatRecoveryExhaustedContext) => void | Promise<void>;
+};
 /**
  * Controls how overlapping user submit requests behave while another
  * chat turn is already active or queued.
@@ -631,6 +698,7 @@ declare const CHAT_MESSAGE_TYPES: {
   readonly TOOL_RESULT: "cf_agent_tool_result";
   readonly TOOL_APPROVAL: "cf_agent_tool_approval";
   readonly MESSAGE_UPDATED: "cf_agent_message_updated";
+  readonly CHAT_RECOVERING: "cf_agent_chat_recovering";
 };
 //#endregion
 //#region src/chat/continuation-state.d.ts
@@ -644,9 +712,11 @@ interface ContinuationConnection {
   readonly id: string;
   send(message: string): void;
 }
-interface ContinuationPending {
-  connection: ContinuationConnection;
-  connectionId: string;
+interface ContinuationPending<
+  TConnection extends ContinuationConnection = ContinuationConnection
+> {
+  connection: TConnection;
+  connectionId: string | null;
   requestId: string;
   clientTools?: ClientToolSchema[];
   body?: Record<string, unknown>;
@@ -654,24 +724,33 @@ interface ContinuationPending {
   prerequisite: Promise<boolean> | null;
   pastCoalesce: boolean;
 }
-interface ContinuationDeferred {
-  connection: ContinuationConnection;
-  connectionId: string;
+interface ContinuationDeferred<
+  TConnection extends ContinuationConnection = ContinuationConnection
+> {
+  connection: TConnection;
+  connectionId: string | null;
   clientTools?: ClientToolSchema[];
   body?: Record<string, unknown>;
   errorPrefix: string;
   prerequisite: Promise<boolean> | null;
 }
-declare class ContinuationState {
-  pending: ContinuationPending | null;
-  deferred: ContinuationDeferred | null;
+declare class ContinuationState<
+  TConnection extends ContinuationConnection = ContinuationConnection
+> {
+  pending: ContinuationPending<TConnection> | null;
+  deferred: ContinuationDeferred<TConnection> | null;
   activeRequestId: string | null;
   activeConnectionId: string | null;
-  awaitingConnections: Map<string, ContinuationConnection>;
+  awaitingConnections: Map<string, TConnection>;
   /** Clear pending state and awaiting connections (without sending RESUME_NONE). */
   clearPending(): void;
   clearDeferred(): void;
   clearAll(): void;
+  /**
+   * Mark a connection as no longer available without canceling the
+   * continuation it initiated.
+   */
+  releaseConnection(connectionId: string): void;
   /**
    * Send STREAM_RESUME_NONE to all connections waiting for a
    * continuation stream to start, then clear the map.
@@ -681,9 +760,7 @@ declare class ContinuationState {
    * Flush awaiting connections by notifying each one via the provided
    * callback (typically sends STREAM_RESUMING), then clear.
    */
-  flushAwaitingConnections(
-    notify: (conn: ContinuationConnection) => void
-  ): void;
+  flushAwaitingConnections(notify: (conn: TConnection) => void): void;
   /**
    * Transition pending → active. Called when the continuation stream
    * actually starts. Moves request/connection IDs to active slots,
@@ -697,7 +774,9 @@ declare class ContinuationState {
    * Returns the new pending state (so the host can enqueue the turn),
    * or null if there was nothing deferred.
    */
-  activateDeferred(generateRequestId: () => string): ContinuationPending | null;
+  activateDeferred(
+    generateRequestId: () => string
+  ): ContinuationPending<TConnection> | null;
 }
 //#endregion
 //#region src/chat/abort-registry.d.ts
@@ -810,6 +889,39 @@ declare function toolResultUpdate(
   overrideState?: "output-error",
   errorText?: string
 ): ToolPartUpdate;
+/**
+ * Build an update descriptor for a terminal tool result that belongs to a
+ * tool part in a *different* (earlier) assistant message than the one
+ * currently being streamed.
+ *
+ * This is the "cross-message" case: an approved server tool executes during a
+ * continuation stream, but its tool part lives in the assistant message that
+ * originally requested it. `StreamAccumulator` surfaces this as a
+ * `cross-message-tool-update` action because the accumulator only owns the
+ * current turn's new content and cannot mutate a part from a prior message.
+ *
+ * Compared to {@link toolResultUpdate} this builder is deliberately more
+ * defensive, mirroring the equivalent fallback in `@cloudflare/ai-chat`:
+ *
+ * - It matches the broad set of pre-terminal **and** terminal states, so a
+ *   provider that replays the entire prior tool round-trip during a
+ *   continuation (notably the OpenAI Responses API — issue #1404) still
+ *   resolves to the same part instead of silently missing it.
+ * - It is **first-write-wins**: a chunk arriving for a tool that already holds
+ *   a terminal result is treated as a replay and the existing output is never
+ *   overwritten. In that case `apply` returns the *same part reference*, which
+ *   callers use as an idempotent-no-op signal to skip the durable write and a
+ *   redundant `MESSAGE_UPDATED` broadcast.
+ * - It preserves a streamed `preliminary` flag when one is present, otherwise
+ *   marks the result final (`preliminary: false`).
+ */
+declare function crossMessageToolResultUpdate(
+  toolCallId: string,
+  updateType: "output-available" | "output-error",
+  output?: unknown,
+  errorText?: string,
+  preliminary?: boolean
+): ToolPartUpdate;
 /**
  * Build an update descriptor for applying a tool approval.
  *
@@ -945,6 +1057,7 @@ type ChatFiberSnapshot<Kind extends string = string> = {
   kind: Kind;
   version: 1;
   requestId: string;
+  recoveryRootRequestId?: string;
   continuation: boolean;
   latestMessageId?: string;
   latestMessageRole?: string;
@@ -956,6 +1069,7 @@ type ChatFiberSnapshot<Kind extends string = string> = {
 declare function createChatFiberSnapshot<Kind extends string>({
   kind,
   requestId,
+  recoveryRootRequestId,
   continuation,
   messages,
   lastBody,
@@ -963,6 +1077,7 @@ declare function createChatFiberSnapshot<Kind extends string>({
 }: {
   kind: Kind;
   requestId: string;
+  recoveryRootRequestId?: string;
   continuation: boolean;
   messages: UIMessage[];
   lastBody?: Record<string, unknown>;
@@ -994,7 +1109,9 @@ export {
   CHAT_MESSAGE_TYPES,
   type ChatFiberSnapshot,
   type ChatProtocolEvent,
+  type ChatRecoveryConfig,
   type ChatRecoveryContext,
+  type ChatRecoveryExhaustedContext,
   type ChatRecoveryOptions,
   type ChatResponseResult,
   type ChunkAction,
@@ -1010,6 +1127,7 @@ export {
   type MessageParts,
   type NormalizedMessageConcurrency,
   ROW_MAX_BYTES,
+  type ResolvedChatRecoveryConfig,
   ResumableStream,
   type SaveMessagesOptions,
   type SaveMessagesResult,
@@ -1031,6 +1149,7 @@ export {
   createAgentToolEventState,
   createChatFiberSnapshot,
   createToolsFromClientSchemas,
+  crossMessageToolResultUpdate,
   enforceRowSizeLimit,
   isReplayChunk,
   parseProtocolMessage,