agents 0.13.3 → 0.14.1

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-BAJWu8s4.js";
 import {
   n as createAgentToolEventState,
   t as applyAgentToolEvent
-} from "../agent-tools-Bg5ilERh.js";
+} from "../agent-tools-0R6KEert.js";
 import { JSONSchema7, Tool, ToolSet, UIMessage } from "ai";
 import { Connection } from "agents";
 
@@ -51,6 +51,29 @@ type StreamChunkData = {
   messageMetadata?: unknown;
   [key: string]: unknown;
 };
+/**
+ * Coerce a tool part's `input` into a provider-acceptable object.
+ *
+ * The Anthropic Messages API requires `tool_use.input` to be a JSON **object** —
+ * `null`, `undefined`, `""`, a raw string, **or an array** are all rejected with
+ * `tool_use.input: Input should be an object` (verified empirically against the
+ * live API: `{}` → 200, but `""`, `[]`, and `[{...}]` all → 400). A streamed
+ * tool call that finishes with no `input_json_delta` events (the model called
+ * the tool with no args), or whose input surfaces as a stringified JSON blob,
+ * can persist one of these shapes — and because it lives in durable storage, the
+ * session is then wedged across reconnects, redeploys, and DO evictions.
+ * Enforcing the invariant at the write boundary (and as a read-side repair
+ * backstop) keeps the transcript valid.
+ *
+ * - A plain (non-array) object is returned untouched (`changed: false`).
+ * - A string that parses to a plain object is parsed.
+ * - Everything else (`null`, `undefined`, `""`, arrays, primitives, non-object
+ *   or unparseable JSON) collapses to `{}`.
+ */
+declare function normalizeToolInput(raw: unknown): {
+  input: unknown;
+  changed: boolean;
+};
 /**
  * Applies a stream chunk to a mutable parts array, building up the message
  * incrementally. Returns true if the chunk was handled, false if it was
@@ -334,7 +357,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 +396,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 +721,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 +735,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 +747,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 +783,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 +797,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 +912,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 +1080,7 @@ type ChatFiberSnapshot<Kind extends string = string> = {
   kind: Kind;
   version: 1;
   requestId: string;
+  recoveryRootRequestId?: string;
   continuation: boolean;
   latestMessageId?: string;
   latestMessageRole?: string;
@@ -956,6 +1092,7 @@ type ChatFiberSnapshot<Kind extends string = string> = {
 declare function createChatFiberSnapshot<Kind extends string>({
   kind,
   requestId,
+  recoveryRootRequestId,
   continuation,
   messages,
   lastBody,
@@ -963,6 +1100,7 @@ declare function createChatFiberSnapshot<Kind extends string>({
 }: {
   kind: Kind;
   requestId: string;
+  recoveryRootRequestId?: string;
   continuation: boolean;
   messages: UIMessage[];
   lastBody?: Record<string, unknown>;
@@ -994,7 +1132,9 @@ export {
   CHAT_MESSAGE_TYPES,
   type ChatFiberSnapshot,
   type ChatProtocolEvent,
+  type ChatRecoveryConfig,
   type ChatRecoveryContext,
+  type ChatRecoveryExhaustedContext,
   type ChatRecoveryOptions,
   type ChatResponseResult,
   type ChunkAction,
@@ -1010,6 +1150,7 @@ export {
   type MessageParts,
   type NormalizedMessageConcurrency,
   ROW_MAX_BYTES,
+  type ResolvedChatRecoveryConfig,
   ResumableStream,
   type SaveMessagesOptions,
   type SaveMessagesResult,
@@ -1031,8 +1172,10 @@ export {
   createAgentToolEventState,
   createChatFiberSnapshot,
   createToolsFromClientSchemas,
+  crossMessageToolResultUpdate,
   enforceRowSizeLimit,
   isReplayChunk,
+  normalizeToolInput,
   parseProtocolMessage,
   reconcileMessages,
   resolveToolMergeId,

package/dist/chat/index.js

@@ -1,5 +1,5 @@
-import { i as isReplayChunk, n as createAgentToolEventState, r as applyChunkToParts, t as applyAgentToolEvent } from "../agent-tools-BAdX1vdI.js";
-import { t as truncateToolOutput } from "../tool-output-truncation-CH-khbZ3.js";
+import { a as normalizeToolInput, i as isReplayChunk, n as createAgentToolEventState, r as applyChunkToParts, t as applyAgentToolEvent } from "../agent-tools-DYrkT-Kx.js";
+import { t as truncateToolOutput } from "../tool-output-truncation-CNnnGZQ3.js";
 import { jsonSchema, tool } from "ai";
 import { nanoid } from "nanoid";
 //#region src/chat/sanitize.ts
@@ -520,7 +520,8 @@ const CHAT_MESSAGE_TYPES = {
 	STREAM_RESUME_NONE: "cf_agent_stream_resume_none",
 	TOOL_RESULT: "cf_agent_tool_result",
 	TOOL_APPROVAL: "cf_agent_tool_approval",
-	MESSAGE_UPDATED: "cf_agent_message_updated"
+	MESSAGE_UPDATED: "cf_agent_message_updated",
+	CHAT_RECOVERING: "cf_agent_chat_recovering"
 };
 //#endregion
 //#region src/chat/resumable-stream.ts
@@ -969,6 +970,22 @@ var ContinuationState = class {
 		this.activeConnectionId = null;
 	}
 	/**
+	* Mark a connection as no longer available without canceling the
+	* continuation it initiated.
+	*/
+	releaseConnection(connectionId) {
+		this.awaitingConnections.delete(connectionId);
+		if (this.pending?.connectionId === connectionId) this.pending = {
+			...this.pending,
+			connectionId: null
+		};
+		if (this.deferred?.connectionId === connectionId) this.deferred = {
+			...this.deferred,
+			connectionId: null
+		};
+		if (this.activeConnectionId === connectionId) this.activeConnectionId = null;
+	}
+	/**
 	* Send STREAM_RESUME_NONE to all connections waiting for a
 	* continuation stream to start, then clear the map.
 	*/
@@ -1019,7 +1036,7 @@ var ContinuationState = class {
 			prerequisite: d.prerequisite,
 			pastCoalesce: false
 		};
-		this.awaitingConnections.set(d.connectionId, d.connection);
+		if (d.connectionId !== null) this.awaitingConnections.set(d.connectionId, d.connection);
 		return this.pending;
 	}
 };
@@ -1172,6 +1189,60 @@ function toolResultUpdate(toolCallId, output, overrideState, errorText) {
 	};
 }
 /**
+* 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`).
+*/
+function crossMessageToolResultUpdate(toolCallId, updateType, output, errorText, preliminary) {
+	return {
+		toolCallId,
+		matchStates: [
+			"input-streaming",
+			"input-available",
+			"approval-requested",
+			"approval-responded",
+			"output-available",
+			"output-error",
+			"output-denied"
+		],
+		apply: (part) => {
+			if (part.state === "output-available" || part.state === "output-error" || part.state === "output-denied") return part;
+			if (updateType === "output-error") return {
+				...part,
+				state: "output-error",
+				errorText: errorText ?? "Tool execution failed"
+			};
+			return {
+				...part,
+				state: "output-available",
+				output,
+				preliminary: preliminary ?? false
+			};
+		}
+	};
+}
+/**
 * Build an update descriptor for applying a tool approval.
 *
 * Matches parts in `input-available` or `approval-requested` state.
@@ -1311,23 +1382,35 @@ function assistantContentKey(message, sanitize) {
 	return JSON.stringify(sanitized.parts);
 }
 function mergeServerToolOutputs(incoming, serverMessages) {
-	const serverToolOutputs = /* @__PURE__ */ new Map();
+	const serverResolvedParts = /* @__PURE__ */ new Map();
 	for (const msg of serverMessages) {
 		if (msg.role !== "assistant") continue;
-		for (const part of msg.parts) if ("toolCallId" in part && "state" in part && part.state === "output-available" && "output" in part) serverToolOutputs.set(part.toolCallId, part.output);
+		for (const part of msg.parts) {
+			const record = part;
+			if ("toolCallId" in record && "state" in record && (record.state === "output-available" || record.state === "output-error" || record.state === "output-denied")) serverResolvedParts.set(record.toolCallId, record);
+		}
 	}
-	if (serverToolOutputs.size === 0) return incoming;
+	if (serverResolvedParts.size === 0) return incoming;
 	return incoming.map((msg) => {
 		if (msg.role !== "assistant") return msg;
 		let hasChanges = false;
 		const updatedParts = msg.parts.map((part) => {
-			if ("toolCallId" in part && "state" in part && (part.state === "input-available" || part.state === "approval-requested" || part.state === "approval-responded") && serverToolOutputs.has(part.toolCallId)) {
+			const record = part;
+			if ("toolCallId" in record && "state" in record && (record.state === "input-available" || record.state === "approval-requested" || record.state === "approval-responded") && serverResolvedParts.has(record.toolCallId)) {
 				hasChanges = true;
-				return {
+				const server = serverResolvedParts.get(record.toolCallId);
+				const merged = {
 					...part,
-					state: "output-available",
-					output: serverToolOutputs.get(part.toolCallId)
+					state: server.state
 				};
+				if (server.state === "output-available") {
+					if ("output" in server) merged.output = server.output;
+				} else if (server.state === "output-error") {
+					if ("errorText" in server) merged.errorText = server.errorText;
+				} else if (server.state === "output-denied") {
+					if ("approval" in server) merged.approval = server.approval;
+				}
+				return merged;
 			}
 			return part;
 		});
@@ -1379,7 +1462,7 @@ function findMessageByToolCallId(messages, toolCallId) {
 }
 //#endregion
 //#region src/chat/recovery.ts
-function createChatFiberSnapshot({ kind, requestId, continuation, messages, lastBody, lastClientTools }) {
+function createChatFiberSnapshot({ kind, requestId, recoveryRootRequestId, continuation, messages, lastBody, lastClientTools }) {
 	const latestMessage = messages.length > 0 ? messages[messages.length - 1] : void 0;
 	let latestUser;
 	for (let index = messages.length - 1; index >= 0; index--) if (messages[index].role === "user") {
@@ -1390,6 +1473,7 @@ function createChatFiberSnapshot({ kind, requestId, continuation, messages, last
 		kind,
 		version: 1,
 		requestId,
+		recoveryRootRequestId,
 		continuation,
 		latestMessageId: latestMessage?.id,
 		latestMessageRole: latestMessage?.role,
@@ -1427,6 +1511,6 @@ function unwrapChatFiberSnapshot(key, value, expectedKind) {
 	};
 }
 //#endregion
-export { AbortRegistry, CHAT_MESSAGE_TYPES, ContinuationState, ROW_MAX_BYTES, ResumableStream, StreamAccumulator, SubmitConcurrencyController, TurnQueue, applyAgentToolEvent, applyChunkToParts, applyToolUpdate, assistantContentKey, transition as broadcastTransition, byteLength, createAgentToolEventState, createChatFiberSnapshot, createToolsFromClientSchemas, enforceRowSizeLimit, isReplayChunk, parseProtocolMessage, reconcileMessages, resolveToolMergeId, sanitizeMessage, toolApprovalUpdate, toolResultUpdate, unwrapChatFiberSnapshot, wrapChatFiberSnapshot };
+export { AbortRegistry, CHAT_MESSAGE_TYPES, ContinuationState, ROW_MAX_BYTES, ResumableStream, StreamAccumulator, SubmitConcurrencyController, TurnQueue, applyAgentToolEvent, applyChunkToParts, applyToolUpdate, assistantContentKey, transition as broadcastTransition, byteLength, createAgentToolEventState, createChatFiberSnapshot, createToolsFromClientSchemas, crossMessageToolResultUpdate, enforceRowSizeLimit, isReplayChunk, normalizeToolInput, parseProtocolMessage, reconcileMessages, resolveToolMergeId, sanitizeMessage, toolApprovalUpdate, toolResultUpdate, unwrapChatFiberSnapshot, wrapChatFiberSnapshot };
 
 //# sourceMappingURL=index.js.map