agents 0.16.2 → 0.17.1

package/dist/chat/index.d.ts

@@ -1,14 +1,25 @@
 import {
-  a as AgentToolEventState,
-  d as AgentToolRunState,
-  i as AgentToolEventMessage,
-  r as AgentToolEvent
-} from "../agent-tool-types-CTw3UJUP.js";
+  U as FiberRecoveryContext,
+  _ as AgentToolRunState,
+  a as AgentToolEvent,
+  o as AgentToolEventMessage,
+  s as AgentToolEventState
+} from "../agent-tool-types-CNyE1iz_.js";
 import {
-  n as createAgentToolEventState,
-  t as applyAgentToolEvent
-} from "../agent-tools-DZhI5F6Q.js";
-import { JSONSchema7, Tool, ToolSet, UIMessage } from "ai";
+  n as ClientToolSchema,
+  r as createToolsFromClientSchemas,
+  t as ClientToolExecutor
+} from "../client-tools-aIBO0Fk7.js";
+import {
+  a as applyAgentToolEvent,
+  i as AgentToolProgressEmitter,
+  n as AgentToolProgressEmitHooks,
+  o as createAgentToolEventState,
+  r as AgentToolProgressEmitResult,
+  s as interceptAgentToolBroadcast,
+  t as AgentToolBroadcastHooks
+} from "../agent-tools-CSnyGvJ2.js";
+import { JSONSchema7, UIMessage } from "ai";
 import { Connection } from "agents";
 
 //#region src/chat/message-builder.d.ts
@@ -39,7 +50,8 @@ type StreamChunkData = {
   state?: string;
   errorText?: string /** When true, the output is preliminary (may be updated by a later chunk) */;
   preliminary?: boolean /** Approval ID for tools with needsApproval */;
-  approvalId?: string;
+  approvalId?: string /** Optional framework-specific metadata for the approval request. */;
+  approvalDescriptor?: unknown;
   providerMetadata?: Record<
     string,
     unknown
@@ -119,6 +131,20 @@ declare function applyChunkToParts(
  * - `tool-input-available` for a `toolCallId` whose existing part is no
  *   longer `input-streaming` (i.e. has already advanced to `input-available`
  *   or any terminal state).
+ * - `tool-output-denied` for a `toolCallId` whose existing part is already
+ *   settled (`output-available` / `output-error` / `output-denied`) or
+ *   user-approved (`approval-responded`). A continuation that re-validates
+ *   the transcript can re-emit a denial for an approval the SDK now deems
+ *   unneeded; `applyChunkToParts` already drops it server-side, and this stops
+ *   it reaching the client (where the in-place `updateToolPart` would flip the
+ *   part to `output-denied`) and the replay buffer. Mirrors the
+ *   first-write-wins guard in `applyChunkToParts`.
+ * - `tool-approval-request` for a `toolCallId` whose existing part is already
+ *   `approval-responded` or settled. A continuation replaying a prior tool
+ *   round-trip can re-emit the approval request; left unfiltered it would
+ *   revert an already-approved tool back to `approval-requested` on the client
+ *   (re-showing Approve/Reject) and replay that regression on reconnect. Same
+ *   pattern and rationale as `tool-output-denied`.
  */
 declare function isReplayChunk(
   parts: MessagePart[],
@@ -138,15 +164,30 @@ declare function byteLength(s: string): number;
  * 2. Filters truly empty reasoning parts (no text, no remaining providerMetadata)
  */
 declare function sanitizeMessage(message: UIMessage): UIMessage;
+/** Optional hooks for {@link enforceRowSizeLimit}. */
+interface EnforceRowSizeLimitOptions {
+  /**
+   * Optional logger invoked when a message has to be compacted/truncated. The
+   * package supplies its own log prefix (log prefixes stay package-specific).
+   */
+  warn?: (message: string) => void;
+}
 /**
  * Enforce SQLite row size limits by compacting tool outputs and text parts
- * when a serialized message exceeds the safety threshold (1.8MB).
+ * when a serialized message exceeds the safety threshold (1.8MB). Shared by
+ * `@cloudflare/ai-chat` and `@cloudflare/think` so both compact identically.
  *
  * Compaction strategy:
- * 1. Compact tool outputs over 1KB while preserving structured output shape
- * 2. If still too big, truncate text parts from oldest to newest
+ * 1. Compact tool outputs over 1KB with {@link truncateToolOutput}, preserving
+ *    the structured output shape, and annotate `metadata.compactedToolOutputs`
+ *    with the compacted tool-call IDs.
+ * 2. If still too big, truncate text parts from oldest to newest, annotating
+ *    `metadata.compactedTextParts` with the truncated part indices.
  */
-declare function enforceRowSizeLimit(message: UIMessage): UIMessage;
+declare function enforceRowSizeLimit(
+  message: UIMessage,
+  options?: EnforceRowSizeLimitOptions
+): UIMessage;
 //#endregion
 //#region src/chat/stream-accumulator.d.ts
 interface StreamAccumulatorOptions {
@@ -266,52 +307,18 @@ declare class TurnQueue {
   private _decrementCount;
 }
 //#endregion
-//#region src/chat/client-tools.d.ts
-/**
- * Wire-format tool schema sent from the client.
- * Uses `parameters` (JSONSchema7) rather than AI SDK's `inputSchema`
- * because Zod schemas cannot be serialized over the wire.
- */
-type ClientToolSchema = {
-  /** Unique name for the tool */ name: string /** Human-readable description of what the tool does */;
-  description?: Tool["description"] /** JSON Schema defining the tool's input parameters */;
-  parameters?: JSONSchema7;
-};
+//#region src/chat/lifecycle.d.ts
 /**
- * Executes a client-defined tool and returns its output.
- *
- * Used for the RPC path (e.g. a parent agent delegating to a Think sub-agent)
- * where the caller can run the client tools itself, rather than the
- * browser/WebSocket path where results are sent back asynchronously.
+ * An advisory, open-ended hint that an action records during a turn to
+ * influence how the final reply is delivered without changing the model-visible
+ * tool output. The base type is intentionally open; channels/voice surfaces
+ * narrow it to the shapes they understand and ignore the rest.
+ * `@cloudflare/think` exports a richer named union for `ctx.attachReply`'s
+ * parameter; this base is what rides on `ChatResponseResult`.
  */
-type ClientToolExecutor = (call: {
-  /** The name of the client tool the model called. */ toolName: string /** The model-generated input for the tool call. */;
-  input: unknown /** The AI SDK tool-call id for the invocation. */;
-  toolCallId: string;
-}) => unknown | Promise<unknown>;
-/**
- * Converts client tool schemas to AI SDK tool format.
- *
- * By default these tools have no `execute` function — when the AI model calls
- * them, the tool call is sent back to the client for execution.
- *
- * When `options.execute` is provided, each tool is built WITH an `execute` that
- * delegates to it. This is used by the RPC path (e.g. a parent agent driving a
- * Think sub-agent) so the model's client-tool call is resolved inline within
- * the same turn.
- *
- * @param clientTools - Array of tool schemas from the client
- * @param options - Optional `execute` delegate to run the tools inline
- * @returns Record of AI SDK tools that can be spread into your tools object
- */
-declare function createToolsFromClientSchemas(
-  clientTools?: ClientToolSchema[],
-  options?: {
-    execute?: ClientToolExecutor;
-  }
-): ToolSet;
-//#endregion
-//#region src/chat/lifecycle.d.ts
+type ReplyAttachment = {
+  type: string;
+} & Record<string, unknown>;
 /**
  * Result passed to the `onChatResponse` lifecycle hook after a chat
  * turn completes.
@@ -325,6 +332,11 @@ type ChatResponseResult = {
     | "error"
     | "aborted" /** Error message when `status` is `"error"`. */;
   error?: string;
+  /**
+   * Advisory reply attachments recorded during the turn (best-effort,
+   * producing-attempt only — not re-applied on a ledger replay).
+   */
+  attachments?: ReplyAttachment[];
 };
 /**
  * Options accepted by programmatic entry points that drive a chat turn
@@ -445,6 +457,9 @@ type ChatRecoveryExhaustedContext = Pick<
    * - `work_budget_exceeded` — the turn kept producing content but exceeded the
    *   configured `maxRecoveryWork` runaway-loop budget.
    * - `recovery_aborted` — the caller's `shouldKeepRecovering` hook returned `false`.
+   * - `out_of_memory` — recovery attempts kept hitting a Durable Object
+   *   memory-limit reset (the isolate exceeded its 128 MB limit) until the
+   *   tight `maxOomRetries` budget drained (#1825).
    * - `stable_timeout` — a recovery attempt kept timing out waiting for the
    *   isolate to reach stable state until the budget drained (extreme churn).
    * - `max_recovery_window_exceeded` — DEPRECATED. The old absolute incident-age
@@ -482,7 +497,7 @@ type ChatRecoveryProgressContext = {
 /**
  * Configuration for durable chat recovery. `true` uses these defaults:
  * `maxAttempts: 10`, `stableTimeoutMs: 10_000`, `noProgressTimeoutMs: 300_000`
- * (5 min), `maxRecoveryWork: Infinity`, and a generic terminal message.
+ * (5 min), `maxRecoveryWork: 1000`, and a generic terminal message.
  *
  * **Apply this as a class field or in the constructor — never assign it in
  * `onStart()`.** On every wake the SDK evaluates recovery budgets (and may seal
@@ -510,12 +525,31 @@ type ChatRecoveryConfig =
       /**
        * Runaway-loop guard. Maximum recovery WORK — produced content/tool units
        * since the incident began — before a still-progressing turn is sealed
-       * with `reason="work_budget_exceeded"`. Defaults to `Infinity` (no cap):
-       * the SDK never terminates a progressing turn on its own. Set a finite
-       * value (or use `shouldKeepRecovering`) to bound a loop that keeps
-       * emitting content but never converges.
+       * with `reason="work_budget_exceeded"`. Defaults to `1000`: a generous
+       * backstop that bounds wasted re-run cost when a turn keeps emitting a
+       * little content but never converges (e.g. an isolate that OOMs mid-stream
+       * on every recovery — #1825 — which otherwise resets the attempt cap and
+       * no-progress window forever). Work only accrues from the first
+       * interruption until the turn completes, so a normal interrupted turn
+       * never approaches it. A very long agentic turn under heavy interruption
+       * that legitimately needs more can raise this (or set `Infinity` to
+       * disable the framework cap and bound the runaway via `shouldKeepRecovering`
+       * instead).
        */
       maxRecoveryWork?: number;
+      /**
+       * Tight retry budget for the specific case of a Durable Object isolate
+       * exceeding its memory limit and being reset mid-turn. An OOM is usually
+       * deterministic (the turn's working set no longer fits in 128 MB), so
+       * re-running re-OOMs; but a single OOM can be a transient spike, so
+       * recovery retries this many times before sealing with
+       * `reason="out_of_memory"`. Counts only attempts that ended in an OOM (not
+       * total attempts), so a turn interrupted by deploys is unaffected.
+       * Defaults to `3`. Set `0` to seal on the first OOM. Much tighter than
+       * `maxRecoveryWork` because an OOM is attributable and each re-run is
+       * expensive (it re-runs the model).
+       */
+      maxOomRetries?: number;
       /**
        * Caller policy consulted on each recovery attempt from the second
        * onward — it is NOT called on the first detection (the attempt that
@@ -543,6 +577,7 @@ type ResolvedChatRecoveryConfig = {
   terminalMessage: string;
   noProgressTimeoutMs: number;
   maxRecoveryWork: number;
+  maxOomRetries: number;
   shouldKeepRecovering?: (
     ctx: ChatRecoveryProgressContext
   ) => boolean | Promise<boolean>;
@@ -669,6 +704,18 @@ declare function transition(
 ): TransitionResult;
 //#endregion
 //#region src/chat/resumable-stream.d.ts
+/**
+ * How far ahead (seconds) to schedule the resumable-stream buffer cleanup
+ * alarm. Set to the short completion-grace window ({@link COMPLETED_RETENTION_MS},
+ * 10m) so a finished buffer is reclaimed promptly. The re-arm-while-reclaimable
+ * loop (see {@link cleanupStreamBuffers}) revisits any longer-lived rows — e.g.
+ * an abandoned in-flight buffer on its 1h window — by waking again each interval
+ * until they age out, then stops. Driving cleanup from an alarm (rather than
+ * only piggybacking on the next stream completion) ensures idle/one-off chat
+ * DOs still reclaim their buffers without waking forever (#1706). Shared by
+ * `AIChatAgent` and `Think`.
+ */
+declare const STREAM_CLEANUP_DELAY_SECONDS: number;
 /**
  * Minimal SQL interface matching Agent's this.sql tagged template.
  * Allows ResumableStream to work with the Agent's SQLite without
@@ -890,6 +937,22 @@ declare class ResumableStream {
    */
   insertChunkAt(streamId: string, body: string, ageMs: number): void;
 }
+/**
+ * The buffer-cleanup alarm body: sweep aged stream buffers, then re-arm only
+ * while rows remain so a fully-swept DO stops waking itself. `rearm` schedules
+ * the next sweep — it MUST schedule a non-idempotent alarm, because this runs
+ * INSIDE the currently-executing one-shot schedule row, which `alarm()` deletes
+ * only after it returns; an idempotent reschedule would dedup onto that row and
+ * be deleted with it, so the re-arm would silently never fire and buffers that
+ * survived this sweep (e.g. a younger turn) would go uncollected. A fresh
+ * delayed row survives the deletion. Shared by `AIChatAgent` and `Think`.
+ *
+ * `@internal`
+ */
+declare function cleanupStreamBuffers(
+  stream: Pick<ResumableStream, "cleanup" | "hasReclaimableStreams">,
+  rearm: () => Promise<void>
+): Promise<void>;
 //#endregion
 //#region src/chat/sql-batch.d.ts
 /**
@@ -934,23 +997,208 @@ declare const CHAT_MESSAGE_TYPES: {
   readonly STREAM_RESUME_ACK: "cf_agent_stream_resume_ack";
   readonly STREAM_RESUME_REQUEST: "cf_agent_stream_resume_request";
   readonly STREAM_RESUME_NONE: "cf_agent_stream_resume_none";
+  readonly STREAM_PENDING: "cf_agent_stream_pending";
   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
+//#region src/chat/wire-types.d.ts
 /**
- * Minimal connection interface for sending WebSocket messages.
- * Matches the Connection type from agents without importing it.
- * Uses a permissive send signature so Connection (which extends
- * WebSocket with its own send overload) is structurally assignable.
+ * Enum for message types to improve type safety and maintainability
  */
-interface ContinuationConnection {
+declare enum MessageType {
+  CF_AGENT_CHAT_MESSAGES = "cf_agent_chat_messages",
+  CF_AGENT_USE_CHAT_REQUEST = "cf_agent_use_chat_request",
+  CF_AGENT_USE_CHAT_RESPONSE = "cf_agent_use_chat_response",
+  CF_AGENT_CHAT_CLEAR = "cf_agent_chat_clear",
+  CF_AGENT_CHAT_REQUEST_CANCEL = "cf_agent_chat_request_cancel",
+  /** Sent by server when client connects and there's an active stream to resume */
+  CF_AGENT_STREAM_RESUMING = "cf_agent_stream_resuming",
+  /** Sent by client to acknowledge stream resuming notification and request chunks */
+  CF_AGENT_STREAM_RESUME_ACK = "cf_agent_stream_resume_ack",
+  /** Sent by client after message handler is ready, requesting stream resume check */
+  CF_AGENT_STREAM_RESUME_REQUEST = "cf_agent_stream_resume_request",
+  /** Sent by server when client requests resume but no active stream exists */
+  CF_AGENT_STREAM_RESUME_NONE = "cf_agent_stream_resume_none",
+  /**
+   * Sent by server when a turn is accepted but its resumable stream has not
+   * started yet (queued / debouncing / waiting on MCP / async setup). Tells a
+   * reconnecting client to keep waiting rather than resolve its resume probe to
+   * "no stream". Resolved by a later `CF_AGENT_STREAM_RESUMING` (stream started)
+   * or `CF_AGENT_STREAM_RESUME_NONE` (settled without streaming). See #1784.
+   */
+  CF_AGENT_STREAM_PENDING = "cf_agent_stream_pending",
+  /** Client sends tool result to server (for client-side tools) */
+  CF_AGENT_TOOL_RESULT = "cf_agent_tool_result",
+  /** Server notifies client that a message was updated (e.g., tool result applied) */
+  CF_AGENT_MESSAGE_UPDATED = "cf_agent_message_updated",
+  /** Client sends tool approval response to server (for tools with needsApproval) */
+  CF_AGENT_TOOL_APPROVAL = "cf_agent_tool_approval",
+  /**
+   * Server→client progress hint: a durable chat turn is being recovered
+   * (interrupted by a deploy/eviction or a stream-stall watchdog abort and now
+   * resuming). Sent when a recovery continuation is scheduled and cleared on
+   * every terminal outcome. (`@cloudflare/think` also replays it on connect;
+   * `@cloudflare/ai-chat` broadcasts the live signal only — see #1645.)
+   * Backward-compatible — clients that don't understand it ignore it. See #1620.
+   */
+  CF_AGENT_CHAT_RECOVERING = "cf_agent_chat_recovering"
+}
+/**
+ * Types of messages sent from the Agent to clients
+ */
+type OutgoingMessage<ChatMessage extends UIMessage = UIMessage> =
+  | {
+      /** Indicates this message is a command to clear chat history */ type: MessageType.CF_AGENT_CHAT_CLEAR;
+    }
+  | {
+      /** Indicates this message contains updated chat messages */ type: MessageType.CF_AGENT_CHAT_MESSAGES /** Array of chat messages */;
+      messages: readonly ChatMessage[];
+    }
+  | {
+      /** Indicates this message is a response to a chat request */ type: MessageType.CF_AGENT_USE_CHAT_RESPONSE /** Unique ID of the request this response corresponds to */;
+      id: string /** Content body of the response */;
+      body: string /** Whether this is the final chunk of the response */;
+      done: boolean /** Whether this response contains an error */;
+      error?: boolean /** Whether this is a continuation (append to last assistant message) */;
+      continuation?: boolean /** Whether this chunk is being replayed from storage (stream resumption) */;
+      replay?: boolean /** Signals that replay of stored chunks is complete (stream is still active) */;
+      replayComplete?: boolean;
+    }
+  | {
+      /** Indicates the server is resuming an active stream */ type: MessageType.CF_AGENT_STREAM_RESUMING /** The request ID of the stream being resumed */;
+      id: string;
+    }
+  | {
+      /** Server notifies client that a message was updated (e.g., tool result applied) */ type: MessageType.CF_AGENT_MESSAGE_UPDATED /** The updated message */;
+      message: ChatMessage;
+    }
+  | {
+      /** Server responds to resume request when no active stream exists */ type: MessageType.CF_AGENT_STREAM_RESUME_NONE;
+    }
+  | {
+      /**
+       * Server signals an accepted turn whose resumable stream has not started
+       * yet — the client should keep waiting for `STREAM_RESUMING` (or a later
+       * `STREAM_RESUME_NONE`) rather than give up. See #1784.
+       */
+      type: MessageType.CF_AGENT_STREAM_PENDING /** The accepted request id, when known. */;
+      id?: string;
+    }
+  | {
+      /**
+       * Progress hint: a durable chat turn is being recovered (`recovering:
+       * true`) or recovery has resolved (`recovering: false`). Purely advisory;
+       * a client renders a "recovering…" indicator while true.
+       */
+      type: MessageType.CF_AGENT_CHAT_RECOVERING /** Whether recovery is in progress (true) or has resolved (false). */;
+      recovering: boolean /** The recovery-root request id of the turn being recovered, if known. */;
+      id?: string;
+    };
+/**
+ * Types of messages sent from clients to the Agent
+ */
+type IncomingMessage<ChatMessage extends UIMessage = UIMessage> =
+  | {
+      /** Indicates this message is a command to clear chat history */ type: MessageType.CF_AGENT_CHAT_CLEAR;
+    }
+  | {
+      /** Indicates this message is a request to the chat API */ type: MessageType.CF_AGENT_USE_CHAT_REQUEST /** Unique ID for this request */;
+      id: string /** Request initialization options */;
+      init: Pick<
+        RequestInit,
+        | "method"
+        | "keepalive"
+        | "headers"
+        | "body"
+        | "redirect"
+        | "integrity"
+        | "credentials"
+        | "mode"
+        | "referrer"
+        | "referrerPolicy"
+        | "window"
+      >;
+    }
+  | {
+      /** Indicates this message contains updated chat messages */ type: MessageType.CF_AGENT_CHAT_MESSAGES /** Array of chat messages */;
+      messages: ChatMessage[];
+    }
+  | {
+      /** Indicates the user wants to stop generation of this message */ type: MessageType.CF_AGENT_CHAT_REQUEST_CANCEL;
+      id: string;
+    }
+  | {
+      /** Client acknowledges stream resuming notification and is ready to receive chunks */ type: MessageType.CF_AGENT_STREAM_RESUME_ACK /** The request ID of the stream being resumed */;
+      id: string;
+    }
+  | {
+      /** Client requests stream resume check after message handler is registered */ type: MessageType.CF_AGENT_STREAM_RESUME_REQUEST;
+    }
+  | {
+      /** Client sends tool result to server (for client-side tools) */ type: MessageType.CF_AGENT_TOOL_RESULT /** The tool call ID this result is for */;
+      toolCallId: string /** The name of the tool */;
+      toolName: string /** The output from the tool execution */;
+      output: unknown /** Override the tool part state (e.g. "output-error" for custom denial) */;
+      state?:
+        | "output-available"
+        | "output-error" /** Error message when state is "output-error" */;
+      errorText?: string /** Whether server should auto-continue the conversation after applying result */;
+      autoContinue?: boolean /** Client tool schemas for continuation (client is source of truth) */;
+      clientTools?: Array<{
+        name: string;
+        description?: string;
+        parameters?: JSONSchema7;
+      }>;
+    }
+  | {
+      /** Client sends tool approval response to server (for tools with needsApproval) */ type: MessageType.CF_AGENT_TOOL_APPROVAL /** The tool call ID this approval is for */;
+      toolCallId: string /** Whether the tool execution was approved */;
+      approved: boolean /** Whether server should auto-continue the conversation after applying approval */;
+      autoContinue?: boolean;
+    };
+//#endregion
+//#region src/chat/connection.d.ts
+/**
+ * Connection I/O — shared WebSocket send guard for chat agents.
+ *
+ * `@internal` — sibling-package support for `@cloudflare/ai-chat` and
+ * `@cloudflare/think`, not a public API. See
+ * `design/rfc-chat-recovery-foundation.md`.
+ *
+ * Both packages (and `continuation-state`) hand-maintained byte-identical
+ * copies of `sendIfOpen` / `isWebSocketClosedSendError`; this is the single
+ * shared implementation.
+ */
+/**
+ * Minimal connection interface for sending WebSocket messages. Matches the
+ * `Connection` type from `agents` without importing it: `Connection` extends
+ * `WebSocket` with its own `send` overload, so it is structurally assignable.
+ */
+interface ChatConnection {
   readonly id: string;
   send(message: string): void;
 }
+/**
+ * Send a message on a connection, swallowing the specific
+ * "send after close" error a racing disconnect produces. Returns `true` if the
+ * send went out, `false` if the socket was already closed. Any other error
+ * rethrows.
+ */
+declare function sendIfOpen(
+  connection: ChatConnection,
+  message: string
+): boolean;
+//#endregion
+//#region src/chat/continuation-state.d.ts
+/**
+ * Minimal connection interface for sending WebSocket messages. Alias of the
+ * shared {@link ChatConnection} — kept as a named export for back-compat with
+ * existing `ContinuationConnection` consumers.
+ */
+type ContinuationConnection = ChatConnection;
 interface ContinuationPending<
   TConnection extends ContinuationConnection = ContinuationConnection
 > {
@@ -1018,6 +1266,197 @@ declare class ContinuationState<
   ): ContinuationPending<TConnection> | null;
 }
 //#endregion
+//#region src/chat/pre-stream-turns.d.ts
+declare class PreStreamTurns<
+  TConnection extends ChatConnection = ChatConnection
+> {
+  /**
+   * Accepted-but-not-yet-streamed request ids. A turn enters on `begin()` and
+   * leaves on `settle()`; the set being non-empty means "pre-stream work is in
+   * flight", which gates parking and the eventual `resume_none` release.
+   */
+  private readonly _accepted;
+  /** Connections parked waiting for a stream to start. */
+  readonly awaitingConnections: Map<string, TConnection>;
+  /** The most recently accepted pre-stream request id (for the keep-waiting frame). */
+  private _latestRequestId;
+  /** Mark a freshly-accepted turn as in flight (pre-stream). */
+  begin(requestId: string): void;
+  /**
+   * Mark an accepted turn as settled. Returns `true` when no accepted turn
+   * remains in flight (the caller should release parked connections if no
+   * stream is active).
+   */
+  settle(requestId: string): boolean;
+  /** Whether any accepted turn is still pre-stream. */
+  hasInFlight(): boolean;
+  /** The request id to advertise in the keep-waiting frame, if known. */
+  get latestRequestId(): string | null;
+  /**
+   * Park a reconnecting connection and tell it to keep waiting (so its
+   * transport does not resolve `reconnectToStream` early). No-op when nothing
+   * is in flight. Parked connections are deliberately NOT added to the host's
+   * `pendingResumeConnections` — they must keep receiving any live broadcast —
+   * until the host flushes them through `notifyStreamResuming` on stream start.
+   */
+  park(connection: TConnection): boolean;
+  /** Drop a single connection (e.g. on socket close) without releasing others. */
+  release(connectionId: string): void;
+  /**
+   * A stream has started: hand every parked connection to `notify` (the host's
+   * `notifyStreamResuming`, which sends `STREAM_RESUMING` and excludes the
+   * connection from live broadcast until it ACKs), then clear the awaiting map.
+   * The accepted set is untouched — the turn is still running.
+   */
+  flushOnStreamStart(notify: (connection: TConnection) => void): void;
+  /**
+   * Release every parked connection with `STREAM_RESUME_NONE` (the turn settled
+   * without ever starting a stream) and clear the awaiting map. Safe to call
+   * when the map is empty (no-op), so the host can call it liberally from a
+   * turn-settle path.
+   */
+  releaseAwaiting(): void;
+  /** Drop all state (chat clear / destroy). Does not send any frames. */
+  reset(): void;
+}
+//#endregion
+//#region src/chat/auto-continuation-controller.d.ts
+/**
+ * The data a host supplies to schedule (or re-target) a pending/deferred
+ * auto-continuation. Mirrors the fields a host writes onto
+ * {@link ContinuationState.pending} — the host owns where the values come from
+ * (e.g. Think hardcodes a fixed `errorPrefix` and `body: undefined`; ai-chat
+ * threads them per tool-result event).
+ */
+interface ContinuationSpec<
+  TConnection extends ContinuationConnection = ContinuationConnection
+> {
+  connection: TConnection;
+  clientTools: ClientToolSchema[] | undefined;
+  body: Record<string, unknown> | undefined;
+  errorPrefix: string;
+}
+/**
+ * Host substrate the controller parameterizes over. Implemented by the agent
+ * (typically via a small adapter object capturing `this`).
+ */
+interface AutoContinuationHost<
+  TConnection extends ContinuationConnection = ContinuationConnection
+> {
+  /** Shared continuation state (pending/deferred/awaiting connections). */
+  readonly continuation: ContinuationState<TConnection>;
+  /** Generate a request id for a freshly-created continuation turn. */
+  generateRequestId(): string;
+  /**
+   * `true` while an assistant turn is streaming — the parallel tool batch can
+   * still grow with tool calls the model hasn't emitted yet, so no completeness
+   * check is meaningful. (`_streamingAssistant !== null` in Think;
+   * `_streamingTurnActive` in ai-chat.)
+   */
+  isStreamActive(): boolean;
+  /** `true` while a tool-result/approval apply is in flight. */
+  hasPendingInteraction(): boolean;
+  /**
+   * `true` when the latest assistant message is mid-batch (a settled tool
+   * result beside an unanswered tool call/approval — the #1649 signature).
+   */
+  hasIncompleteToolBatch(): boolean;
+  /**
+   * Drain every in-flight tool-result/approval apply (including any enqueued
+   * while draining) so the subsequent completeness re-check sees every result
+   * that has already arrived. Bounded by real apply activity, never a timer.
+   */
+  drainInteractionApplies(): Promise<void>;
+  /** Hold the isolate alive for the duration of `fn` (alarm heartbeats). */
+  keepAliveWhile<T>(fn: () => Promise<T>): Promise<T>;
+  /**
+   * Run the continuation turn for the current {@link ContinuationState.pending}.
+   * Each host's inference/reply pipeline (Think: `_turnQueue.enqueue` +
+   * `_runInferenceLoop`; ai-chat: `_runExclusiveChatTurn` + `onChatMessage`).
+   * Reads everything it needs from `continuation.pending`, so it takes no args.
+   */
+  fire(): void;
+}
+declare class AutoContinuationController<
+  TConnection extends ContinuationConnection = ContinuationConnection
+> {
+  private readonly host;
+  /**
+   * Small debounce window to batch adjacent client-side tool results/approvals
+   * into a single server continuation barrier check (#1650).
+   */
+  static readonly COALESCE_MS = 50;
+  /**
+   * Coalesce/debounce timer for the event-driven barrier (#1650). Each tool
+   * result/approval re-arms it; on fire it runs {@link fireWhenStable}.
+   */
+  private _timer;
+  /**
+   * Double-fire guard (#1650). Ensures only one in-flight apply-drain runs;
+   * that drain re-checks completeness on completion before firing. A sibling
+   * that re-arms the coalesce timer during a drain is absorbed by the
+   * in-progress drain rather than starting its own.
+   */
+  private _barrierActive;
+  constructor(host: AutoContinuationHost<TConnection>);
+  /**
+   * Schedule an auto-continuation for a tool result/approval that opted in with
+   * `autoContinue` (#1650). Coalesces rapid sibling results into a single
+   * continuation via the debounce timer; the actual fire is gated by
+   * {@link fireWhenStable}. If a continuation is already running
+   * (`pastCoalesce`), the new result is stored as the deferred follow-up
+   * instead of re-arming.
+   */
+  schedule(spec: ContinuationSpec<TConnection>): void;
+  /**
+   * Re-arm the barrier for a result/approval that arrived WITHOUT `autoContinue`
+   * (#1650). A standalone errored result declines to continue on its own, but in
+   * a parallel batch a SIBLING may already have opted in — and this result can
+   * be the one that completes the batch, so we must re-run the barrier check.
+   * Unlike {@link schedule} this NEVER creates a pending continuation, and
+   * no-ops once the continuation is running (`pastCoalesce`).
+   */
+  rearmForBatch(): void;
+  /** (Re)arm the coalesce timer; on fire, run {@link fireWhenStable}. */
+  armTimer(): void;
+  /**
+   * Fire an auto-continuation, but only once the model's parallel tool-call
+   * batch is fully answered (#1649) and no assistant turn is mid-stream (#1650).
+   * The barrier is event-driven with NO orphan timeout: when the batch is still
+   * incomplete we drain the in-flight applies, re-check, and — if still
+   * incomplete — return WITHOUT firing and WITHOUT holding the isolate, leaving
+   * `continuation.pending` in place. The next sibling's result re-arms the
+   * coalesce timer and re-runs this check; the continuation fires once the final
+   * sibling lands. A true orphan (a sibling that never arrives) simply never
+   * auto-continues — a later user turn / chat recovery repairs the transcript.
+   */
+  fireWhenStable(): void;
+  /**
+   * Transition the deferred follow-up (stored while a continuation was running)
+   * to pending and re-run the barrier — its batch may still be incomplete (or a
+   * stream active), in which case it parks and re-arms instead of firing blind.
+   */
+  activateDeferredAndReschedule(): void;
+  /**
+   * Cancel any still-armed coalesce timer. Called on the fire path so a sibling
+   * result that re-armed it during a barrier wait can't fire a duplicate
+   * continuation after this one starts (#1649 / #1650).
+   */
+  cancelTimer(): void;
+  /**
+   * `true` when the barrier is going to fire on its own — its coalesce timer is
+   * still pending or its completeness drain is in progress. The host combines
+   * this with its own pending/`pastCoalesce` checks to decide idle/stable.
+   */
+  isArmed(): boolean;
+  /**
+   * Tear down the controller-owned barrier state (timer + double-fire guard).
+   * Scoped to ONLY this controller's fields — the host clears the rest of its
+   * turn state (stream gate, interaction tail, continuation data) separately.
+   */
+  reset(): void;
+}
+//#endregion
 //#region src/chat/abort-registry.d.ts
 /**
  * AbortRegistry — manages per-request AbortControllers.
@@ -1090,6 +1529,45 @@ declare class AbortRegistry {
   linkExternal(id: string, signal: AbortSignal | undefined): () => void;
 }
 //#endregion
+//#region src/chat/async-helpers.d.ts
+/**
+ * @internal Small async control-flow helpers shared by the chat hosts
+ * (`@cloudflare/ai-chat` and `@cloudflare/think`) — not a public API. Extracted
+ * so the host idle/stable waits and the interaction-apply completeness drain
+ * stay byte-identical across both. See `design/chat-shared-layer.md`.
+ */
+/**
+ * Sentinel returned by {@link awaitWithDeadline} when the deadline elapses
+ * before the awaited promise settles. A single shared symbol so both hosts
+ * compare against the same identity.
+ */
+declare const TIMED_OUT: unique symbol;
+/**
+ * Await `promise`, but give up and resolve to {@link TIMED_OUT} once `deadline`
+ * (an absolute `Date.now()` ms timestamp) passes. A `null` deadline waits
+ * indefinitely (the promise is returned unchanged). The timeout timer is always
+ * cleared so it can't pin the isolate awake past resolution.
+ */
+declare function awaitWithDeadline<T>(
+  promise: Promise<T>,
+  deadline: number | null
+): Promise<T | typeof TIMED_OUT>;
+/**
+ * Drain the host's interaction-apply chain so a subsequent completeness check
+ * (e.g. `hasIncompleteToolBatch`) sees every tool result that has ALREADY
+ * arrived.
+ *
+ * Bounded by real apply activity (a storage write each), never a fixed timer:
+ * `getTail` is re-read after every await because a sibling can extend the tail
+ * mid-drain, and the loop stops once the tail stops advancing. Bails early when
+ * `hasPending()` goes false (the pending continuation was cleared by a chat
+ * clear / turn reset) so a stale drain can't hold the isolate awake.
+ */
+declare function drainInteractionApplies(
+  hasPending: () => boolean,
+  getTail: () => Promise<unknown>
+): Promise<void>;
+//#endregion
 //#region src/chat/tool-state.d.ts
 /**
  * Tool State — shared update builders and applicator for tool part state changes.
@@ -1198,6 +1676,51 @@ declare function toolApprovalUpdate(
   toolCallId: string,
   approved: boolean
 ): ToolPartUpdate;
+/** A minimal message shape for the leaf tool/interaction scans. */
+type ToolBatchMessage = {
+  role: string;
+  parts: ReadonlyArray<unknown>;
+};
+/** Extract a tool part's name from its `tool-<name>` / `dynamic-tool` shape. */
+/**
+ * Whether a part is still awaiting a CLIENT interaction that can genuinely
+ * arrive after a restart: an `approval-requested` part (a reconnecting client
+ * replays the approval) or an `input-available` part for a CLIENT tool (the SPA
+ * replays the `tool-result`). A SERVER tool's `input-available` is NOT pending —
+ * its `execute()` died with the isolate.
+ */
+declare function partAwaitsClientInteraction(
+  part: unknown,
+  clientResolvable: Set<string>
+): boolean;
+/**
+ * Names of the CLIENT-resolvable tools — the client-provided schemas from the
+ * last request, which have no server `execute`. An interrupted `input-available`
+ * part for one of these can still be resolved by the client replaying a
+ * `tool-result`; a server tool's cannot.
+ */
+declare function clientResolvableToolNames(
+  tools:
+    | ReadonlyArray<
+        | {
+            name?: string;
+          }
+        | null
+        | undefined
+      >
+    | undefined
+): Set<string>;
+/**
+ * `true` when the latest assistant message is mid-batch: it carries at least
+ * one settled tool result AND at least one tool call/approval still awaiting a
+ * client result. That is the #1649 signature — the model fanned out parallel
+ * tool calls and only some have been answered. Scoped to the leaf (the step the
+ * continuation answers) so an unrelated dangling tool in an earlier message
+ * doesn't block a legitimate follow-up continuation.
+ */
+declare function hasIncompleteToolBatch(
+  messages: ReadonlyArray<ToolBatchMessage>
+): boolean;
 //#endregion
 //#region src/chat/parse-protocol.d.ts
 /**
@@ -1310,15 +1833,190 @@ declare function resolveToolMergeId(
   serverMessages: readonly UIMessage[]
 ): UIMessage;
 /**
- * Content key for assistant messages used for dedup of identical short replies.
- * Returns JSON of sanitized parts, or undefined for non-assistant messages.
+ * Merge a freshly-reconstructed orphaned partial onto the assistant message
+ * that already owns its target id (the orphan-persist **(c)** step).
+ *
+ * Used by hosts whose store can hold an assistant row for the SAME id BEFORE
+ * the stream finalizes — e.g. an early persist at tool-approval time, or a
+ * continuation resuming the prior assistant message. On recovery the engine
+ * replays the same chunks, so a naive append would leave two parts per tool
+ * call. The merge therefore:
+ *
+ *   - keeps ALL existing parts (the persisted row is authoritative for tool
+ *     parts that had a client result applied IN PLACE — that result lives only
+ *     in storage, never in the chunk stream, so a whole-message replace would
+ *     clobber it);
+ *   - appends only the reconstructed parts whose `toolCallId` is NOT already
+ *     present (dedup by tool-call identity);
+ *   - overlays the incoming metadata onto the existing metadata (incoming wins
+ *     on conflicts), falling back to whichever side is present.
+ *
+ * The result carries the INCOMING message's id/role (the caller has already
+ * resolved the incoming id to the existing row's id via the (b) target-id
+ * step), so it is safe to write straight back through `updateMessage`.
+ *
+ * Hosts whose orphan persist only ever runs at stream finalize (no early/
+ * mid-stream row for the same id) never hit the merge branch and don't need
+ * this — a plain append/replace is already dedup-safe because the shared
+ * reconstruction (`StreamAccumulator` / `applyChunkToParts`) is idempotent by
+ * `toolCallId`.
  */
-declare function assistantContentKey(
-  message: UIMessage,
-  sanitize?: (message: UIMessage) => UIMessage
-): string | undefined;
+declare function reconcileOrphanPartial(
+  existing: UIMessage,
+  incoming: UIMessage
+): UIMessage;
+//#endregion
+//#region src/chat/repair-transcript.d.ts
+/**
+ * Whether a tool part already has a settled result the provider accepts, so it
+ * must NOT be re-repaired into an errored result.
+ *
+ * Single source of truth for the terminal tool states. Mirrors the AI SDK's
+ * terminal states: `convertToModelMessages` emits a `tool-result` for
+ * `output-available`, `output-error`, AND `output-denied` (a user-denied
+ * approval — its denial reason becomes the tool-result). Omitting any of these
+ * makes repair re-flip the part every turn — clobbering a real `errorText` /
+ * denial with the generic "interrupted" message.
+ */
+declare function toolPartHasSettledResult(
+  record: Record<string, unknown>
+): boolean;
+interface RepairInterruptedToolPartsOptions {
+  /**
+   * Decide the replacement for an interrupted tool part (no settled result, not
+   * `approval-responded`). Its `input` has already been normalized to a valid
+   * object. The default host behavior flips it to an errored tool-result; hosts
+   * expose this as an overridable `repairInterruptedToolPart` hook so a subclass
+   * can, e.g., convert an interrupted client-resolved tool into a text part.
+   */
+  repairPart: (part: UIMessage["parts"][number]) => UIMessage["parts"][number];
+  /**
+   * Whether a tool part already carries a settled result (defaults to
+   * {@link toolPartHasSettledResult}).
+   */
+  isSettled?: (record: Record<string, unknown>) => boolean;
+  /**
+   * Normalize a tool part's `input` (defaults to the shared
+   * {@link normalizeToolInput}).
+   */
+  normalizeInput?: (input: unknown) => {
+    input: unknown;
+    changed: boolean;
+  };
+  /**
+   * Whether an interrupted tool part (no settled result, not
+   * `approval-responded`) should be repaired at all. Defaults to `true` (repair
+   * everything, like Think — which converts even client tools via its
+   * `repairPart` override). A host whose default `repairPart` errors the part
+   * (ai-chat) passes this to SKIP a part still legitimately awaiting a CLIENT
+   * interaction (an `input-available` client tool or an `approval-requested`
+   * part the user may still answer) so it is left verbatim rather than clobbered
+   * with an error. Skipped parts are not counted in `removedToolCalls`.
+   */
+  shouldRepair?: (part: UIMessage["parts"][number]) => boolean;
+}
+interface RepairInterruptedToolPartsResult {
+  /** A new messages array; unchanged messages keep their original reference. */
+  messages: UIMessage[];
+  /** Count of interrupted tool calls flipped to a repaired shape. */
+  removedToolCalls: number;
+  /** Count of tool parts whose malformed `input` was normalized. */
+  normalizedInputs: number;
+  /** The tool-call ids that were repaired. */
+  toolCallIds: string[];
+}
+/**
+ * Repair interrupted tool calls and normalize malformed tool inputs across a
+ * transcript. Behavior mirrors `@cloudflare/think`'s original
+ * `_repairToolTranscriptParts`:
+ *
+ *   - a tool part with NO settled result and state `approval-responded` is kept
+ *     verbatim (an approved server tool waiting for its continuation to run
+ *     `execute()` — not abandoned);
+ *   - a tool part with NO settled result for which `shouldRepair` returns false
+ *     is kept verbatim (a part still awaiting a CLIENT interaction; see option);
+ *   - any other tool part with no settled result is normalized then handed to
+ *     `repairPart` (default: flipped to an errored result);
+ *   - a tool part WITH a settled result only has its `input` normalized.
+ *
+ * Messages with no changed part keep their original object reference so callers
+ * can cheaply detect what to persist.
+ */
+declare function repairInterruptedToolParts(
+  messages: UIMessage[],
+  options: RepairInterruptedToolPartsOptions
+): RepairInterruptedToolPartsResult;
+//#endregion
+//#region src/chat/orphan-store.d.ts
+interface OrphanPersistStore<
+  M extends {
+    id: string;
+  } = UIMessage
+> {
+  /** Read the stored message with this id, or `null` if none exists. */
+  getMessage(id: string): M | null | Promise<M | null>;
+  /**
+   * Append a new message. `parentId` is honored by tree-structured stores
+   * (`undefined` → attach to the latest leaf); flat-array stores ignore it.
+   */
+  appendMessage(message: M, parentId?: string | null): void | Promise<void>;
+  /** Replace the stored message that owns `message.id`. */
+  updateMessage(message: M): void | Promise<void>;
+}
+//#endregion
+//#region src/chat/orphan-persist.d.ts
+interface PersistReconstructedOrphanOptions<
+  TMessage extends UIMessage = UIMessage
+> {
+  /** The store seam to upsert through (a `SessionProvider` write-subset). */
+  store: OrphanPersistStore<TMessage>;
+  /**
+   * Id for the reconstructed message when the stream carried no provider
+   * `start.messageId` to adopt. The accumulator still adopts a provider id when
+   * present.
+   */
+  fallbackId: string;
+  /**
+   * Finalize the reconstructed message before upsert — e.g. strip internal
+   * parts or resolve the persist-target id. Return `null` to skip persistence
+   * entirely (e.g. an empty structural-only message).
+   */
+  prepare: (message: TMessage) => TMessage | null;
+  /**
+   * Combine an existing row with the reconstructed message when a row already
+   * owns the id (replace, or reconcile partials).
+   */
+  merge: (existing: TMessage, incoming: TMessage) => TMessage;
+}
+/**
+ * Reconstruct a message from `chunks` and upsert it via the store. Returns
+ * `true` when a write happened (so a caller that broadcasts after — Think — can
+ * gate its broadcast on it), `false` when there was nothing to persist (no
+ * parts, or `prepare` returned `null`).
+ */
+declare function persistReconstructedOrphan<
+  TMessage extends UIMessage = UIMessage
+>(
+  chunks: ReadonlyArray<{
+    body: string;
+  }>,
+  options: PersistReconstructedOrphanOptions<TMessage>
+): Promise<boolean>;
 //#endregion
 //#region src/chat/recovery.d.ts
+/**
+ * The minimal transcript-tail shape {@link createChatFiberSnapshot} reads to
+ * derive the snapshot's `latest*Id` markers. Deliberately NOT `UIMessage`: the
+ * snapshot only ever needs each message's `id` + `role`, so any host transcript
+ * (AI SDK `UIMessage[]`, `Think`'s session leaves, or the pi adapter's plain
+ * `AgentMessage[]`) satisfies it structurally. Keeping this off `UIMessage` is
+ * the Phase-5 genericity seam — the snapshot builder must not couple to the AI
+ * SDK message shape.
+ */
+interface SnapshotMessage {
+  id?: string;
+  role: string;
+}
 type ChatFiberSnapshot<Kind extends string = string> = {
   kind: Kind;
   version: 1;
@@ -1345,7 +2043,7 @@ declare function createChatFiberSnapshot<Kind extends string>({
   requestId: string;
   recoveryRootRequestId?: string;
   continuation: boolean;
-  messages: UIMessage[];
+  messages: ReadonlyArray<SnapshotMessage>;
   lastBody?: Record<string, unknown>;
   lastClientTools?: ClientToolSchema[];
 }): ChatFiberSnapshot<Kind>;
@@ -1363,72 +2061,1330 @@ declare function unwrapChatFiberSnapshot<Kind extends string>(
   user: unknown | null;
 };
 //#endregion
+//#region src/chat/recovery-incident.d.ts
+/**
+ * Whether a recovery is retrying an unanswered user turn or continuing a
+ * partial assistant turn. Intentionally NOT part of the incident identity (see
+ * {@link chatRecoveryIncidentId}).
+ */
+type ChatRecoveryKind = "retry" | "continue";
+/**
+ * Durable per-incident recovery record.
+ *
+ * PERSISTED CONTRACT — this shape round-trips across deploys (including the
+ * deploy that ships the shared engine, which is itself a deploy-mid-recovery).
+ * Fields are added as optional so older persisted incidents keep recovering.
+ */
+type ChatRecoveryIncident = {
+  incidentId: string;
+  requestId: string /** Stable request ID for the whole continuation chain (the recovery root). */;
+  recoveryRootRequestId?: string;
+  recoveryKind: ChatRecoveryKind;
+  attempt: number;
+  maxAttempts: number;
+  status:
+    | "detected"
+    | "scheduled"
+    | "attempting"
+    | "completed"
+    | "skipped"
+    | "exhausted"
+    | "failed";
+  firstSeenAt: number;
+  lastAttemptAt: number;
+  /**
+   * Epoch ms of the last attempt that observed forward progress. The recovery
+   * budget is keyed to this (`now - lastProgressAt > noProgressTimeoutMs`), so a
+   * turn that keeps producing content survives churn indefinitely while a
+   * genuinely stuck turn is sealed within the window (#1637). Optional for
+   * backward-compat — falls back to `firstSeenAt`.
+   */
+  lastProgressAt?: number;
+  reason?: string;
+  /**
+   * High-water mark of the durable, monotonic recovery-progress counter
+   * observed for this incident. Distinguishes a turn making forward progress
+   * but repeatedly interrupted by isolate resets (deploys) — which must NOT
+   * exhaust the budget — from one that genuinely fails to advance. Sourced from
+   * a persisted counter, never the compactable transcript (#1628).
+   */
+  progress?: number;
+  /**
+   * Value of the durable progress counter when this incident opened. The
+   * runaway-loop work budget is `progress - workBaseline`, compared against
+   * `maxRecoveryWork`. Optional for backward-compat — a missing baseline is
+   * treated as the current marker (zero work so far), so an in-flight incident
+   * from an older build is never falsely sealed.
+   */
+  workBaseline?: number;
+  /**
+   * Count of recovery attempts for this incident that ended in a Durable Object
+   * memory-limit reset (the isolate exceeded its 128 MB limit — see
+   * `isDurableObjectMemoryLimitReset`). An OOM is a poison signal: re-running the
+   * same memory-heavy turn deterministically re-OOMs, so unlike a deploy/eviction
+   * it must NOT credit forward progress and must be bounded by a tight,
+   * OOM-specific budget (`maxOomRetries`) rather than the generic attempt cap
+   * (which resets on progress). Bumped by `ChatRecoveryEngine.recordOomAndDecide`
+   * when a recovery callback observes an OOM; exceeding `maxOomRetries` seals the
+   * incident with `reason="out_of_memory"` (#1825). Optional for backward-compat.
+   */
+  oomAttempts?: number;
+};
+declare const CHAT_RECOVERY_INCIDENT_KEY_PREFIX = "cf:chat-recovery:incident:";
+/**
+ * Durable, monotonic forward-progress counter for recovery budget resets.
+ * Bumped at production time when new content is streamed, so it reflects
+ * genuinely new content and is immune to reconnects/re-persists; never
+ * recomputed from the (compactable) transcript.
+ */
+declare const CHAT_RECOVERY_PROGRESS_KEY = "cf:chat-recovery:progress";
+/**
+ * Durable record of an in-progress recovery so a "recovering…" status (#1620)
+ * can be broadcast live and survive the set/clear happening in different
+ * isolates (a continuation runs in a later alarm invocation).
+ */
+declare const CHAT_RECOVERING_KEY = "cf:chat:recovering";
+/**
+ * Durable record of the last turn that ended in a terminal error / abandoned
+ * recovery (#1645). Replayed on the next reconnect via the resume handshake;
+ * cleared when a later turn supersedes it.
+ */
+declare const CHAT_LAST_TERMINAL_KEY = "cf:chat:last-terminal";
+/**
+ * Secondary backstop only. The primary recovery bound is the no-progress wall
+ * clock; with alarm debounce this cap rarely binds (it catches a pathological
+ * tight alarm-loop). Kept high so the no-progress window seals first under
+ * normal deploy cadence (#1637).
+ */
+declare const DEFAULT_CHAT_RECOVERY_MAX_ATTEMPTS = 10;
+/**
+ * Runaway-loop guard default — the framework-imposed backstop on cumulative
+ * recovery WORK (produced content/tool units) since an incident opened.
+ *
+ * Originally `Infinity` (rfc-chat-recovery-work-budget): the SDK shipped the
+ * *mechanism* but no default cap, so a progressing turn was never terminated on
+ * its own. Production issue #1825 showed that this is a footgun: an isolate that
+ * OOMs mid-stream still credits a little progress before it dies, which resets
+ * BOTH progress-keyed bounds (the attempt cap and the no-progress window) on
+ * every wake — and a fast crash loop (each attempt inside the alarm-debounce
+ * window) pins the attempt counter too. With `maxRecoveryWork = Infinity` the
+ * ONLY instrument whose meter still climbs across such a loop is disabled, so
+ * recovery re-runs the turn (and its LLM calls) forever.
+ *
+ * A finite default closes that loop out of the box: work climbs regardless of
+ * debounce/progress resets, so a content-emitting runaway is always sealed with
+ * `reason="work_budget_exceeded"`. The value is deliberately generous — it
+ * bounds wasted re-run cost without clipping a normal interrupted turn (work
+ * only accrues from the first interruption until the turn completes, after which
+ * the incident is deleted). A very long agentic turn under heavy interruption
+ * that legitimately needs more should raise `maxRecoveryWork` (or set it to
+ * `Infinity` to restore the pre-#1825 unbounded behavior).
+ */
+declare const DEFAULT_CHAT_RECOVERY_MAX_WORK = 1000;
+/**
+ * Tight, OOM-specific retry budget (#1825). A Durable Object memory-limit reset
+ * (`isDurableObjectMemoryLimitReset`) is usually deterministic — the turn's
+ * working set no longer fits in the isolate's 128 MB — so re-running it re-OOMs.
+ * But a single OOM CAN be a transient spike (the isolate's 128 MB is shared
+ * across the global scope / noisy neighbors), so recovery retries a small number
+ * of times before sealing with `reason="out_of_memory"` rather than abandoning a
+ * turn that one more attempt might have completed. Far tighter than the generic
+ * `maxRecoveryWork` backstop because an OOM is attributable and re-running it is
+ * expensive (it re-runs the model). Counts attempts that ended in an OOM, not
+ * total attempts, so a turn interrupted by deploys (no OOM) is unaffected.
+ */
+declare const DEFAULT_CHAT_RECOVERY_MAX_OOM_RETRIES = 3;
+declare const DEFAULT_CHAT_RECOVERY_STABLE_TIMEOUT_MS = 10000;
+/**
+ * Delay before retrying a recovery that timed out waiting for stable state.
+ * Gives an actively-churning isolate (e.g. a deploy in flight) time to settle.
+ */
+declare const CHAT_RECOVERY_STABLE_RETRY_DELAY_SECONDS = 3;
+declare const DEFAULT_CHAT_RECOVERY_TERMINAL_MESSAGE =
+  "The assistant was interrupted and could not recover. Please try again.";
+/**
+ * Incidents that have not seen a new attempt within this window are assumed
+ * abandoned and swept so durable storage does not grow without bound.
+ */
+declare const CHAT_RECOVERY_INCIDENT_TTL_MS: number;
+/** Max keys per Durable Object KV `delete([...])` call. */
+declare const KV_DELETE_MAX_KEYS = 128;
+/**
+ * PRIMARY recovery bound (#1637): seal an incident that has made no forward
+ * progress for this long. Keyed to `lastProgressAt`, which resets on every
+ * progress-bearing attempt — so a turn that keeps producing content survives
+ * deploy churn indefinitely, while a genuinely stuck turn dies within 5 min.
+ */
+declare const DEFAULT_CHAT_RECOVERY_NO_PROGRESS_TIMEOUT_MS: number;
+/**
+ * Alarm debounce: recovery alarms bunched within this window collapse into a
+ * single attempt. A deploy rollout drops/reconnects the socket several times
+ * over ~11–22s; without this, one logical deploy would burn several attempts.
+ */
+declare const CHAT_RECOVERY_ALARM_DEBOUNCE_MS: number;
+/**
+ * Staleness bound for the live "recovering…" flag (#1620). A flag older than
+ * this is treated as abandoned so it can neither pin the indicator on forever
+ * nor suppress a genuinely-new recovering signal. NOT a recovery budget.
+ */
+declare const CHAT_RECOVERING_FLAG_TTL_MS: number;
+/**
+ * Resolve a raw `chatRecovery` config field into the fully-defaulted form the
+ * engine reasons about. Identical defaulting in both packages today.
+ */
+declare function resolveChatRecoveryConfig(
+  raw: ChatRecoveryConfig | undefined
+): ResolvedChatRecoveryConfig;
+/**
+ * Sweep recovery incidents inactive past the TTL from durable storage. Lists by
+ * the incident key prefix, selects stale keys (`selectStaleIncidentKeys`), and
+ * batch-deletes them — the DO KV `delete([...])` accepts up to
+ * `KV_DELETE_MAX_KEYS` per call, collapsing N awaited round-trips into
+ * ceil(N / 128). Shared by `AIChatAgent` and `Think` so the sweep policy lives in
+ * one place. See `design/rfc-chat-recovery-foundation.md`.
+ */
+declare function sweepStaleChatRecoveryIncidents(
+  storage: Pick<DurableObjectStorage, "list" | "delete">,
+  now: number
+): Promise<void>;
+/**
+ * List the persisted recovery incidents that are still live (status
+ * `detected` / `scheduled` / `attempting`) — i.e. NOT yet terminalized
+ * (`exhausted` / `failed`). Used by the alarm-boundary OOM circuit breaker
+ * (#1825) to find the incident(s) it must seal when the in-DO budgets could not.
+ * Lists by the incident key prefix so the storage layout stays encapsulated.
+ */
+declare function listActiveChatRecoveryIncidents(
+  storage: Pick<DurableObjectStorage, "list">
+): Promise<
+  {
+    key: string;
+    incident: ChatRecoveryIncident;
+  }[]
+>;
+/**
+ * Summarize a child agent's persisted recovery incidents for the parent's
+ * agent-tool reattach decision: `"in-progress"` if any incident is still live
+ * (detected/scheduled/attempting), else `"failed"` if any terminalized
+ * (exhausted/failed), else `"none"`. In-progress takes precedence so a parent
+ * never gives up on a child that is still recovering. Shared by `AIChatAgent`
+ * and `Think`. See `design/rfc-chat-recovery-foundation.md`.
+ */
+declare function classifyAgentToolChildRecovery(
+  storage: Pick<DurableObjectStorage, "list">
+): Promise<"in-progress" | "failed" | "none">;
+/**
+ * Read the durable monotonic recovery-progress counter (0 when unset). The value
+ * feeds the no-progress budget decision; shared by `AIChatAgent` and `Think`.
+ */
+declare function readChatRecoveryProgress(
+  storage: Pick<DurableObjectStorage, "get">
+): Promise<number>;
+/**
+ * Advance the durable recovery-progress counter by one. Called when genuinely new
+ * content is durably flushed (real, reconnect-immune forward progress); shared by
+ * `AIChatAgent` and `Think`.
+ */
+declare function bumpChatRecoveryProgress(
+  storage: Pick<DurableObjectStorage, "get" | "put">
+): Promise<void>;
+/**
+ * Throttle window for crediting a parent turn's recovery progress from forwarded
+ * sub-agent (agent-tool) stream chunks (N9). Forwarding a child's chunks IS
+ * forward progress for the parent, but the credit must not write storage per
+ * token.
+ */
+declare const AGENT_TOOL_STREAM_PROGRESS_BUMP_THROTTLE_MS = 5000;
+/**
+ * Per-isolate throttle gate for agent-tool stream-progress crediting (N9). The
+ * `_lastBumpAt` clock is in-memory, so it resets per isolate and the first
+ * forwarded chunk after a restart always credits. `shouldCredit(now)` returns
+ * `true` at most once per `AGENT_TOOL_STREAM_PROGRESS_BUMP_THROTTLE_MS` window and
+ * records the time on each credit. Shared by `AIChatAgent` and `Think`.
+ */
+declare class AgentToolStreamProgressThrottle {
+  private _lastBumpAt;
+  shouldCredit(now: number): boolean;
+}
+/**
+ * Throttle window for crediting recovery progress from mid-segment streaming
+ * content (text/reasoning/tool-input deltas). A milestone chunk credits
+ * unconditionally; deltas credit at most once per window so a long single
+ * segment registers forward progress across crashes without writing storage per
+ * token. 5s is far finer than the 300s no-progress budget, so any crash gap
+ * longer than this window over an actively-streaming segment still credits.
+ */
+declare const CHAT_STREAM_PROGRESS_CREDIT_THROTTLE_MS = 5000;
+/**
+ * Per-isolate throttle gate for crediting recovery progress from mid-segment
+ * streaming-content chunks — the delta arm of {@link shouldCreditStreamProgress}.
+ * The `_lastBumpAt` clock is in-memory, so it resets per isolate and the first
+ * delta after a restart always credits. Shared by `AIChatAgent` and `Think`.
+ */
+declare class StreamProgressCreditThrottle {
+  private _lastBumpAt;
+  shouldCredit(now: number): boolean;
+}
+/** Durable record of the last turn that ended in a terminal error (#1645). */
+type ChatTerminalRecord = {
+  requestId: string;
+  body: string;
+};
+/**
+ * Persist a durable record of the last terminal turn so a client that
+ * (re)connects after the turn ended still learns its outcome (#1645). Kept
+ * until a later turn supersedes it ({@link clearChatTerminal}); a single record
+ * is sufficient because only the most recent terminal is relevant.
+ */
+declare function recordChatTerminal(
+  storage: Pick<DurableObjectStorage, "put">,
+  requestId: string,
+  body: string
+): Promise<void>;
+/** Clear the durable terminal record once a later turn supersedes it (#1645). */
+declare function clearChatTerminal(
+  storage: Pick<DurableObjectStorage, "delete">
+): Promise<void>;
+/** Read the pending terminal record, or `null` if none is stored (#1645). */
+declare function pendingChatTerminal(
+  storage: Pick<DurableObjectStorage, "get">
+): Promise<ChatTerminalRecord | null>;
+/**
+ * Build the on-connect "recovering…" replay frame (#1620), or `null` when no
+ * (non-stale) recovery is in progress. A client that connects between recovery
+ * attempts (no active stream) reads the turn as working rather than frozen. A
+ * record older than the flag TTL is treated as abandoned (its terminal-clear
+ * never ran) and skipped, so a dead recovery can't show "recovering…" forever.
+ * `messageType` is the package's recovering wire-type enum.
+ */
+declare function buildChatRecoveringFrame(
+  storage: Pick<DurableObjectStorage, "get">,
+  messageType: string,
+  now: number
+): Promise<Record<string, unknown> | null>;
+/**
+ * Set or clear the live "recovering…" status (#1620). Persists a durable record
+ * (so set/clear stay consistent across the isolates a recovery spans) and
+ * broadcasts a recovering frame — but only on a genuine transition, so a
+ * deploy/reconnect storm (which re-detects recovery many times) doesn't spam
+ * the wire. A flag older than the TTL is stale: the owning incident was
+ * abandoned without a terminal (e.g. the DO went idle before recovery could
+ * resolve), so it is treated as not-recovering and can neither pin the
+ * indicator on forever nor suppress a genuinely-new recovering signal.
+ * `messageType` is the package's recovering wire-type enum; `broadcast` is the
+ * package's chat-broadcast wrapper.
+ */
+declare function setChatRecovering(
+  active: boolean,
+  requestId: string | undefined,
+  deps: {
+    storage: Pick<DurableObjectStorage, "get" | "put" | "delete">;
+    messageType: string;
+    broadcast: (frame: Record<string, unknown>) => void;
+    now: number;
+  }
+): Promise<void>;
+/**
+ * Observability event produced by an incident evaluation or a status
+ * transition, emitted by the caller. The `detected`/`attempt` events come from
+ * the budget evaluation (begin path); the `scheduled` event comes from
+ * `ChatRecoveryEngine.scheduleRecovery`; the `completed`/`skipped`/`failed`
+ * events come from `ChatRecoveryEngine.updateIncident`. `reason` is carried only
+ * by the `skipped`/`failed` transitions that record a cause.
+ */
+type ChatRecoveryIncidentEvent = {
+  type:
+    | "chat:recovery:detected"
+    | "chat:recovery:attempt"
+    | "chat:recovery:scheduled"
+    | "chat:recovery:completed"
+    | "chat:recovery:skipped"
+    | "chat:recovery:failed";
+  incidentId: string;
+  requestId: string;
+  attempt: number;
+  maxAttempts: number;
+  recoveryKind: ChatRecoveryKind;
+  reason?: string;
+};
+type EvaluateChatRecoveryIncidentInput = {
+  /** Recovery identity for this turn. */ identity: {
+    requestId: string;
+    recoveryRootRequestId?: string | null;
+    latestUserMessageId?: string | null;
+    recoveryKind: ChatRecoveryKind;
+  } /** Fully-resolved recovery config. */;
+  config: ResolvedChatRecoveryConfig /** The existing incident for this identity, or `null` if this is fresh. */;
+  existing: ChatRecoveryIncident | null /** Current value of the durable monotonic progress counter. */;
+  currentProgress: number;
+  /**
+   * Whether the turn is parked on a pending CLIENT interaction (an
+   * `input-available` client-tool part or an `approval-requested` part). Such a
+   * turn is waiting on the human, not stuck, so it is budget-free.
+   */
+  awaitingClientInteraction: boolean /** Injected clock (epoch ms) for deterministic tests. */;
+  now: number;
+  /**
+   * Invoked when `config.shouldKeepRecovering` throws. Lets each package keep
+   * its own log prefix. A throwing predicate is treated as "keep recovering".
+   */
+  onShouldKeepRecoveringError?: (error: unknown) => void;
+};
+type EvaluateChatRecoveryIncidentResult = {
+  /** The next incident record to persist. */ incident: ChatRecoveryIncident /** Whether this incident is now sealed as exhausted. */;
+  exhausted: boolean /** Observability events to emit, in order. */;
+  events: ChatRecoveryIncidentEvent[];
+};
+//#endregion
+//#region src/chat/recovery-engine.d.ts
+/** The scheduled-callback entrypoints a recovery schedule can target. */
+type ChatRecoveryScheduleCallback =
+  | "_chatRecoveryContinue"
+  | "_chatRecoveryRetry";
+/**
+ * Why a recovery callback is being scheduled. The idempotency of the underlying
+ * `schedule()` call depends ONLY on this:
+ *
+ * - `"initial"` — the first schedule of a continuation/retry when an interrupted
+ *   turn is detected on wake. A deploy rollout drops/reconnects the socket
+ *   several times, re-triggering detection; idempotent scheduling (dedup on
+ *   callback + payload) collapses that storm into a single enqueued continuation
+ *   instead of N duplicates.
+ *
+ * - `"stable_timeout_retry"` — a reschedule issued from INSIDE the currently-
+ *   executing one-shot schedule row (a continuation that timed out waiting for
+ *   stable state). `alarm()` deletes that row only AFTER the callback returns,
+ *   so an idempotent reschedule would dedup onto the doomed row and be deleted
+ *   with it — the retry would never fire. A fresh (non-idempotent) delayed row
+ *   survives the deletion.
+ */
+type ChatRecoveryScheduleReason = "initial" | "stable_timeout_retry";
+/**
+ * A reconstructed orphaned-stream partial. The engine seam is deliberately
+ * **wire-vocabulary-agnostic**: `text` is the accumulated assistant text and
+ * `parts` is OPAQUE to the engine (`unknown[]`) — each host casts it back to its
+ * own message-part vocabulary (AI SDK `UIMessage` parts, AG-UI tool parts, …).
+ * The single fact the engine needs about parts — does the partial carry settled
+ * (non-idempotent) tool work that must survive a `{ persist: false }` recovery
+ * (#1631)? — is precomputed by the {@link ChatRecoveryCodec} as
+ * `hasSettledToolResults`. So the engine never imports a part vocabulary; the
+ * codec owns it (see `partialHasSettledToolResults` in `recovery-codec.ts` for
+ * the AI SDK codec's implementation of that predicate).
+ */
+type RecoveryPartial = {
+  text: string;
+  parts: unknown[];
+  hasSettledToolResults: boolean;
+};
+/** Lifecycle status of a recovered stream's metadata row. */
+type ChatStreamStatus = "streaming" | "completed" | "error";
+/**
+ * Resolve the `schedule()` idempotency option for a recovery schedule. Single
+ * source of truth for both packages; see {@link ChatRecoveryScheduleReason} for
+ * the rationale behind each case.
+ *
+ * This is a cutover invariant: flipping either case silently breaks deploy-storm
+ * dedup (initial) or stalls stable-timeout retries (reschedule), and neither is
+ * caught by a type error — only by the recovery suites.
+ */
+declare function chatRecoverySchedulePolicy(
+  reason: ChatRecoveryScheduleReason
+): {
+  idempotent: boolean;
+};
+/** Identity + context for opening (or re-evaluating) a recovery incident. */
+interface BeginChatRecoveryIncidentInput {
+  requestId: string;
+  recoveryRootRequestId?: string | null;
+  latestUserMessageId?: string | null;
+  recoveryKind: ChatRecoveryKind;
+  /** Test-only clock injection for deterministic debounce/window timing. */
+  nowMs?: number;
+}
+interface BeginChatRecoveryIncidentResult {
+  incident: ChatRecoveryIncident;
+  config: ResolvedChatRecoveryConfig;
+  exhausted: boolean;
+}
+/**
+ * Package-specific host operations the engine drives during incident
+ * orchestration. Every method is a thin pass-through to the package's existing
+ * storage / clock / event / interaction primitives — the engine owns only the
+ * *sequence*, not the I/O.
+ */
+interface ChatRecoveryAdapter {
+  /** Resolve the effective recovery config (defaults + caller overrides). */
+  resolveConfig(): ResolvedChatRecoveryConfig;
+  /** Wall clock; only consulted when the input carries no test `nowMs`. */
+  now(): number;
+  /** Evict incidents past the TTL. Runs before the existing-record read. */
+  sweepStaleIncidents(now: number): Promise<void>;
+  /** Read the persisted incident for `key`, or `null` if none. */
+  getIncident(key: string): Promise<ChatRecoveryIncident | null>;
+  /**
+   * Optional: rehydrate any state the interaction predicate depends on. Invoked
+   * after the existing-incident read and BEFORE `isAwaitingClientInteraction`.
+   * `Think` uses this to restore client tools from durable storage on a cold
+   * boot-recovery wake (so a HITL turn is not misread as stuck); `AIChatAgent`
+   * has no such state and omits it.
+   */
+  ensureInteractionStateLoaded?(): void;
+  /**
+   * Optional: give the package a chance to handle a NON-chat fiber before chat
+   * recovery inspects it. Returns `true` if the package fully consumed the
+   * fiber, in which case the engine tells the caller to skip chat-recovery
+   * processing for it. `Think` uses this for its messenger/workflow reply fibers
+   * (`think:messenger-reply`); `AIChatAgent` has no non-chat fibers and omits it
+   * (the engine then treats every recovered fiber as a chat-recovery candidate).
+   *
+   * Ordering invariant: the engine dispatches this FIRST, before the
+   * chat-fiber-name gate, so a non-chat fiber is never misclassified as an
+   * orphaned chat turn.
+   */
+  tryHandleNonChatFiberRecovery?(ctx: FiberRecoveryContext): Promise<boolean>;
+  /** Monotonic forward-progress marker for the no-progress budget. */
+  readProgress(): Promise<number>;
+  /**
+   * Whether the turn is parked on a pending CLIENT interaction (waiting on the
+   * human, not stuck). When true the engine keeps the incident budget-free.
+   * Optional: a host with no client-interaction/HITL substrate (e.g. the pi
+   * fixture) omits it and the engine treats the turn as never parked (`false`).
+   */
+  isAwaitingClientInteraction?(): boolean;
+  /** Persist the evaluated incident under `key`. */
+  putIncident(key: string, incident: ChatRecoveryIncident): Promise<void>;
+  /**
+   * Delete the incident record under `key`. The engine calls this on the
+   * terminal `completed` transition (a completed recovery is never retried, so
+   * its record is dropped rather than left in storage forever).
+   */
+  deleteIncident(key: string): Promise<void>;
+  /** Broadcast a lifecycle event produced by the evaluation or a transition. */
+  emitRecoveryEvent(event: ChatRecoveryIncidentEvent): void;
+  /**
+   * Enqueue a recovery callback. A thin pass-through to the package's
+   * `schedule(delaySeconds, callback, data, chatRecoverySchedulePolicy(reason))`
+   * — the engine owns the surrounding orchestration (the transition + emit for
+   * the initial schedule in {@link ChatRecoveryEngine.scheduleRecovery}, the
+   * attempt bump for {@link ChatRecoveryEngine.rescheduleAfterStableTimeout});
+   * the package owns the Durable Object alarm write and the payload shape.
+   * `reason` selects the idempotency policy and `delaySeconds` the alarm delay
+   * (`0` for the initial enqueue, `CHAT_RECOVERY_STABLE_RETRY_DELAY_SECONDS` for
+   * a stable-timeout reschedule).
+   */
+  scheduleRecovery(
+    callback: ChatRecoveryScheduleCallback,
+    data: Record<string, unknown>,
+    reason: ChatRecoveryScheduleReason,
+    delaySeconds: number
+  ): Promise<void>;
+  /**
+   * Set or clear the live "recovering…" status (#1620). The engine calls this on
+   * the incident transitions: `scheduled` → active (keyed by the recovery-root
+   * request id, falling back to the incident's request id), and
+   * `completed`/`skipped`/`failed` → cleared. The package owns the underlying
+   * staleness / idempotency / broadcast I/O.
+   */
+  setRecovering(active: boolean, requestId?: string): Promise<void>;
+  /**
+   * Report a throw from the caller's `shouldKeepRecovering` hook. Optional: a
+   * host that does not surface this diagnostic omits it (the engine swallows the
+   * report).
+   */
+  onShouldKeepRecoveringError?(error: unknown): void;
+  /**
+   * Terminalize a given-up recovery turn: deliver the exhaustion notification
+   * plus the package-owned terminal record / banner / submission writes. A thin
+   * pass-through to the package's `_exhaustChatRecovery` (which composes
+   * {@link runChatRecoveryExhaustion}). Driven by
+   * {@link ChatRecoveryEngine.exhaustRecoveryGiveUp}; the engine owns the
+   * surrounding read → re-entry-guard → build → terminalize → seal sequence, the
+   * package owns the terminal writes (uniformly broadcast-first; their set
+   * differs — `Think` also writes a submission row).
+   */
+  exhaustChatRecovery(
+    incident: ChatRecoveryIncident,
+    config: ResolvedChatRecoveryConfig,
+    partial: RecoveryPartial,
+    streamId: string,
+    createdAt: number
+  ): Promise<void>;
+  /**
+   * Resolve the orphaned stream identity for a (recovery-root) request id —
+   * `streamId` is `""` when no stream metadata survives. Drives BOTH the wake
+   * path (which consumes the full {@link ResolvedRecoveryStream}) and the
+   * give-up path (which reads only `.streamId`). A thin pass-through to the
+   * package's stream-metadata lookup: the newest row keyed by the request id,
+   * else the live active stream.
+   */
+  resolveRecoveryStream(requestId: string): ResolvedRecoveryStream;
+  /** Reconstruct the partial text/parts buffered for `streamId`. */
+  getPartialStreamText(streamId: string): RecoveryPartial;
+  /**
+   * The in-flight recovery-root request id, consulted as a fallback in the
+   * give-up root-id chain when the payload carries no `originalRequestId` /
+   * `recoveredRequestId` and no incident record survives. `undefined` when no
+   * recovery chain is active. (`AIChatAgent` and `Think` both back this with
+   * `_activeChatRecoveryRootRequestId`.)
+   */
+  activeChatRecoveryRootRequestId(): string | undefined;
+  /**
+   * Report a tolerated best-effort bookkeeping failure during give-up: the
+   * incident `"read"` (before synthesizing) or the sealing `"seal"` write
+   * (after terminalization). Neither aborts terminalization — see
+   * {@link ChatRecoveryEngine.exhaustRecoveryGiveUp}.
+   */
+  onGiveUpBookkeepingError(phase: "read" | "seal", error: unknown): void;
+}
+/** Resolved orphaned-stream identity for a recovered chat turn. */
+interface ResolvedRecoveryStream {
+  /** The orphaned stream id, or `""` when no stream metadata survives. */
+  streamId: string;
+  /**
+   * Whether the orphaned stream is still the live in-flight stream (so its
+   * partial has not already been persisted + completed by an ACK-driven
+   * reconnect). Gates persistence and stream completion.
+   */
+  streamStillActive: boolean;
+  /**
+   * The stream metadata row's lifecycle status, when the host tracks it
+   * (`Think`). `undefined` for hosts that do not model terminal streams
+   * (`AIChatAgent`) — those keep every terminal-stream branch dead, per the
+   * "substrate capabilities are optional" decision in the RFC.
+   */
+  streamStatus?: ChatStreamStatus;
+}
+/** Input to {@link ChatFiberWakeHooks.classifyRecoveredTurn}. */
+interface ClassifyRecoveredTurnInput {
+  snapshot: ChatFiberSnapshot | null;
+  requestId: string;
+  streamId: string;
+  partial: RecoveryPartial;
+  streamStillActive: boolean;
+  streamStatus?: ChatStreamStatus;
+}
+/** Input to {@link ChatFiberWakeHooks.invokeOnChatRecovery}. */
+interface InvokeOnChatRecoveryInput {
+  incident: ChatRecoveryIncident;
+  recoveryKind: ChatRecoveryKind;
+  recoveryRootRequestId: string;
+  requestId: string;
+  streamId: string;
+  partial: RecoveryPartial;
+  snapshot: ChatFiberSnapshot | null;
+  recoveryData: unknown;
+  createdAt: number;
+}
+/** Input to {@link ChatFiberWakeHooks.shouldPersistOrphanedPartial}. */
+interface PersistOrphanedPartialInput {
+  streamId: string;
+  streamStillActive: boolean;
+  streamStatus?: ChatStreamStatus;
+  snapshot: ChatFiberSnapshot | null;
+}
+/** Input to {@link ChatFiberWakeHooks.dispatchRecoveredTurn}. */
+interface DispatchRecoveredTurnInput<TClassify> {
+  incident: ChatRecoveryIncident;
+  config: ResolvedChatRecoveryConfig;
+  recoveryKind: ChatRecoveryKind;
+  options: ChatRecoveryOptions;
+  snapshot: ChatFiberSnapshot | null;
+  requestId: string;
+  recoveryRootRequestId: string;
+  streamId: string;
+  streamStatus?: ChatStreamStatus;
+  /** The package-specific classification detail produced by `classifyRecoveredTurn`. */
+  detail: TClassify;
+}
+/**
+ * The wake-dispatch host operations the engine drives when an interrupted CHAT
+ * fiber is detected on restart — the divergent organs the frame-collapse map
+ * flagged. Kept SEPARATE from {@link ChatRecoveryAdapter} (and passed per call to
+ * {@link ChatRecoveryEngine.handleChatFiberRecovery}) so the incident/give-up
+ * adapter stays focused, and generic over `TClassify` so the
+ * `classifyRecoveredTurn` → `dispatchRecoveredTurn` handoff is type-safe without a
+ * class-level generic.
+ *
+ * The engine owns the wake LIFECYCLE (gate → parse → unwrap → stream → partial →
+ * classify → begin-incident → exhausted-branch → onChatRecovery → persist →
+ * complete → dispatch → catch→failed) and the shared persist clause; these hooks
+ * own the package-specific I/O and the retry/continue/skip decision.
+ */
+interface ChatFiberWakeHooks<TClassify> {
+  /** The chat-fiber name prefix (`CHAT_FIBER_NAME + ":"`) gating the wake path. */
+  chatFiberPrefix(): string;
+  /** Decode the fiber snapshot into the recovery snapshot + checkpointed user data. */
+  unwrapRecoverySnapshot(ctx: FiberRecoveryContext): {
+    snapshot: ChatFiberSnapshot | null;
+    recoveryData: unknown;
+  };
+  /**
+   * Classify the recovered turn as a `retry` or `continue` and return any
+   * package-specific detail the dispatch decision needs (e.g. the pre-stream
+   * retry target id). Runs before the incident is opened.
+   */
+  classifyRecoveredTurn(input: ClassifyRecoveredTurnInput):
+    | {
+        recoveryKind: ChatRecoveryKind;
+        detail: TClassify;
+      }
+    | Promise<{
+        recoveryKind: ChatRecoveryKind;
+        detail: TClassify;
+      }>;
+  /**
+   * Build the package's `ChatRecoveryContext` and invoke the user `onChatRecovery`
+   * hook, returning its (defaulted) options. The engine wraps this in the
+   * incident `failed`-on-throw guard. Optional: a host with no user
+   * `onChatRecovery` surface (e.g. the pi fixture) omits it and the engine
+   * proceeds with empty options (`{}`).
+   */
+  invokeOnChatRecovery?(
+    input: InvokeOnChatRecoveryInput
+  ): Promise<ChatRecoveryOptions | void>;
+  /**
+   * The BASE persist gate: whether the orphaned partial is eligible to be
+   * materialized at all (live stream, or terminal-but-not-yet-persisted). The
+   * engine ANDs this with the shared `options.persist !== false ||
+   * partial.hasSettledToolResults` clause, so settled work is never dropped.
+   */
+  shouldPersistOrphanedPartial(
+    input: PersistOrphanedPartialInput
+  ): boolean | Promise<boolean>;
+  /** Materialize the orphaned stream's partial into a persisted assistant message. */
+  persistOrphanedStream(streamId: string): Promise<void>;
+  /** Mark the (still-active) recovered stream complete and schedule cleanup. */
+  completeRecoveredStream(streamId: string): void | Promise<void>;
+  /**
+   * The retry/continue/skip DECISION — the package-owned core. Runs after persist
+   * + complete; owns the leaf/submission computation, the schedule calls (via
+   * {@link ChatRecoveryEngine.scheduleRecovery}), the skip transitions, and any
+   * package-specific terminal/broadcast writes.
+   */
+  dispatchRecoveredTurn(
+    input: DispatchRecoveredTurnInput<TClassify>
+  ): Promise<void>;
+}
+/**
+ * Drives the shared recovery orchestration over a {@link ChatRecoveryAdapter}.
+ * The incident *budget math* lives in the pure `evaluateChatRecoveryIncident`;
+ * this class owns the surrounding sequence and its ordering invariants.
+ */
+declare class ChatRecoveryEngine {
+  private readonly adapter;
+  constructor(adapter: ChatRecoveryAdapter);
+  /**
+   * Open or re-evaluate the recovery incident for `input`, persist the result,
+   * and broadcast its lifecycle events. Returns the incident, the resolved
+   * config, and whether the budget is now exhausted.
+   */
+  /**
+   * Dispatch a recovered fiber to the package's non-chat handler (the
+   * messenger/workflow seam) before any chat-recovery processing. Returns `true`
+   * when the package consumed the fiber — the caller must then skip chat
+   * recovery for it. The engine owns the *ordering* (this runs before the
+   * chat-fiber gate); the *behavior* is adapter-owned. No-op (`false`) when the
+   * adapter omits {@link ChatRecoveryAdapter.tryHandleNonChatFiberRecovery}.
+   */
+  handleNonChatFiber(ctx: FiberRecoveryContext): Promise<boolean>;
+  /**
+   * The shared wake-recovery LIFECYCLE for an interrupted chat fiber. Both
+   * packages drove this exact frame; the divergent organs are the
+   * {@link ChatFiberWakeHooks}. In order:
+   *
+   * 1. non-chat dispatch ({@link handleNonChatFiber}) FIRST, then the chat-fiber
+   *    name gate — a non-chat fiber is never misread as an orphaned chat turn;
+   * 2. parse the request id, unwrap the snapshot, resolve the orphaned stream +
+   *    reconstruct its partial;
+   * 3. classify the turn (retry/continue + package detail) and open the incident;
+   * 4. if the budget is already exhausted, persist the settled partial (so
+   *    non-idempotent tool results are not discarded — #1631) and terminalize
+   *    BEFORE consulting `onChatRecovery`;
+   * 5. otherwise, inside a `failed`-on-throw guard: invoke `onChatRecovery`,
+   *    apply the shared persist gate (base eligibility AND `persist !== false ||
+   *    settled tool results`), complete the live stream, then hand the
+   *    retry/continue/skip DECISION to {@link ChatFiberWakeHooks.dispatchRecoveredTurn}.
+   *
+   * Returns `true` when the fiber was a chat (or non-chat) recovery the engine
+   * handled, `false` when it was not a chat fiber (the caller keeps looking). Any
+   * throw after the incident opens flips it to `failed` so it is never left
+   * leaking in `attempting`.
+   */
+  handleChatFiberRecovery<TClassify>(
+    ctx: FiberRecoveryContext,
+    wake: ChatFiberWakeHooks<TClassify>
+  ): Promise<boolean>;
+  /**
+   * The shared persist gate: base eligibility (the package's
+   * {@link ChatFiberWakeHooks.shouldPersistOrphanedPartial}) AND the
+   * never-drop-settled-work clause `options.persist !== false ||
+   * partial.hasSettledToolResults`. `options: undefined` (the exhausted branch)
+   * collapses the clause to the base gate. The clause lives here — not in each
+   * package — because settled-work preservation is a cross-package invariant
+   * (#1631), and the codec (not the engine) decides whether a partial carries
+   * settled tool work, so the engine stays wire-vocabulary-agnostic.
+   */
+  private _shouldPersistOrphanedPartial;
+  beginIncident(
+    input: BeginChatRecoveryIncidentInput
+  ): Promise<BeginChatRecoveryIncidentResult>;
+  /**
+   * Schedule a recovery continuation/retry: the transition + emit + enqueue
+   * triplet both packages repeat at every fiber-recovery and stall-routing
+   * decision. In order:
+   *
+   * 1. transition the incident to `scheduled` (persist + drive the #1620
+   *    "recovering…" status) via {@link updateIncident};
+   * 2. emit `chat:recovery:scheduled`; and
+   * 3. enqueue the callback through the adapter's idempotent schedule.
+   *
+   * `recoveryKind` is passed explicitly (not read off the incident) because a
+   * caller can legitimately report a different kind than the incident was opened
+   * with — e.g. `AIChatAgent`'s lost-partial branch opens a `continue` incident
+   * but schedules (and reports) a `retry`. `requestId` always matches
+   * `incident.requestId` (the evaluation rewrites it to the current attempt), so
+   * it is read from the incident.
+   */
+  scheduleRecovery(input: {
+    incident: ChatRecoveryIncident;
+    recoveryKind: ChatRecoveryKind;
+    callback: ChatRecoveryScheduleCallback;
+    data: Record<string, unknown>;
+    reason?: ChatRecoveryScheduleReason;
+  }): Promise<void>;
+  /**
+   * Reschedule a recovery continuation/retry that timed out waiting for stable
+   * state, INSIDE the currently-executing one-shot schedule row. Reads the
+   * incident; if it is still under the attempt cap, bumps `attempt`, marks it
+   * `scheduled` with `reason:"stable_timeout_retry"`, and issues a delayed,
+   * NON-idempotent schedule (`alarm()` deletes the executing row only after this
+   * returns, so an idempotent reschedule would dedup onto that doomed row and
+   * never fire — see {@link chatRecoverySchedulePolicy}).
+   *
+   * Returns `true` when a retry was scheduled, `false` when there is no incident
+   * (no id / record gone) or the attempt budget is already spent — in which case
+   * the caller falls through to the give-up path. Deliberately bypasses the
+   * `evaluateChatRecoveryIncident` budget (this is a coarse stable-state retry,
+   * not a fresh interruption) and {@link updateIncident} (no `scheduled` event /
+   * recovering-flag churn on a same-turn reschedule).
+   */
+  rescheduleAfterStableTimeout(input: {
+    incidentId: string | undefined;
+    callback: ChatRecoveryScheduleCallback;
+    data: Record<string, unknown> | undefined;
+    fallbackMaxAttempts: number;
+  }): Promise<boolean>;
+  /**
+   * Record that a recovery callback observed a Durable Object memory-limit reset
+   * (the isolate exceeded its 128 MB limit — `isDurableObjectMemoryLimitReset`)
+   * and decide what to do next (#1825).
+   *
+   * Bumps the incident's durable `oomAttempts` counter, then:
+   *  - if it is still within `maxOomRetries`, issues a delayed, NON-idempotent
+   *    reschedule of the SAME callback (same machinery as
+   *    {@link rescheduleAfterStableTimeout}: the executing one-shot row is
+   *    deleted only after the callback returns, so an idempotent reschedule
+   *    would dedup onto that doomed row) and returns `"rescheduled"`. The small
+   *    delay lets a transient memory spike clear before the re-run;
+   *  - otherwise leaves the incremented count persisted (so a begin-path
+   *    re-evaluation agrees) and returns `"exhausted"` — the caller then
+   *    terminalizes via the give-up path with `reason="out_of_memory"`.
+   *
+   * Returns `"exhausted"` when there is no incident to track against (no id /
+   * record gone): an OOM we cannot bound must seal rather than loop. Unlike a
+   * stable-state retry this is gated by the OOM-specific budget, NOT the generic
+   * attempt cap — re-running an OOM streams a little "progress" that would
+   * otherwise reset the attempt cap forever (the #1825 loop).
+   */
+  recordOomAndDecide(input: {
+    incidentId: string | undefined;
+    callback: ChatRecoveryScheduleCallback;
+    data: Record<string, unknown> | undefined;
+    maxOomRetries: number;
+  }): Promise<"rescheduled" | "exhausted">;
+  /**
+   * Give up on a recovery turn whose retry budget drained, terminalizing it so
+   * it can never become an eternal spinner (#1645). The shared spine both
+   * packages repeated verbatim:
+   *
+   * 1. resolve config + the incident key from `data.incidentId`;
+   * 2. best-effort READ the stored incident — a failed read is tolerated
+   *    (reported via `onGiveUpBookkeepingError("read", …)`) and the incident is
+   *    synthesized, because the read backs only the re-entry guard, not the
+   *    terminal UX;
+   * 3. re-entry guard: a `stored.status === "exhausted"` record means
+   *    terminalization already fired, so a duplicate stale alarm returns without
+   *    re-broadcasting the banner;
+   * 4. build the exhausted incident (reuse `stored`, or synthesize a minimal one
+   *    so a swept/missing record STILL terminalizes through `onExhausted`);
+   * 5. resolve the orphaned stream id + partial;
+   * 6. terminalize via `exhaustChatRecovery` — BEFORE sealing. The terminal
+   *    writes can reject with a platform transient in the deploy/storage window
+   *    a give-up runs in (#1730); letting that throw propagate is deliberate, so
+   *    `Agent._executeScheduleCallback` defers the one-shot row and the WHOLE
+   *    give-up re-runs on a healthy isolate. Sealing first would arm the
+   *    re-entry guard and turn that re-run into a no-op, dropping the durable
+   *    terminal record. The re-run is idempotent (terminal writes overwrite the
+   *    same key); a second banner is the documented at-least-once edge; and
+   * 7. best-effort SEAL write so the re-entry guard sees `exhausted` on a
+   *    duplicate alarm — a failed seal (reported via
+   *    `onGiveUpBookkeepingError("seal", …)`) costs at most one re-delivered
+   *    banner.
+   *
+   * The two packages diverged only in parameters the caller supplies:
+   * `reason` (`Think` passes `stable_timeout` | `recovery_error`; `AIChatAgent`
+   * always `stable_timeout`) and the root-id chain (`Think` includes
+   * `recoveredRequestId`; `AIChatAgent` never sets it, so the unified chain
+   * collapses identically). Exactly-once terminalization rests on the re-entry
+   * guard alone in `AIChatAgent`; `Think` additionally short-circuits duplicate
+   * alarms earlier in its durable-submission layer.
+   */
+  exhaustRecoveryGiveUp(input: {
+    callback: ChatRecoveryScheduleCallback;
+    data:
+      | {
+          incidentId?: string;
+          originalRequestId?: string;
+          recoveredRequestId?: string;
+        }
+      | undefined;
+    reason: string;
+  }): Promise<void>;
+  /**
+   * Apply a status transition to the recovery incident `incidentId`:
+   *
+   * - `completed` → drop the record (terminal, never retried);
+   * - any other status → persist the new status (and `reason`), so the attempt
+   *   budget survives restarts until the TTL sweep reclaims it;
+   * - emit the matching `completed`/`skipped`/`failed` lifecycle event; and
+   * - drive the live "recovering…" status (#1620): `scheduled` marks it active
+   *   (keyed by the recovery-root request id), terminal states clear it.
+   *
+   * No-op when `incidentId` is undefined or the record is already gone. This is
+   * the transition twin of {@link beginIncident}: all I/O is adapter-owned, the
+   * engine owns only the state-machine shape.
+   */
+  updateIncident(
+    incidentId: string | undefined,
+    status: ChatRecoveryIncident["status"],
+    reason?: string
+  ): Promise<void>;
+}
+/**
+ * The complete give-up choreography from a single call: build the exhausted
+ * context, fire the shared notification ({@link notifyChatRecoveryExhausted}),
+ * then hand that context to the host's `terminalize` step. Folds the
+ * `buildChatRecoveryExhaustedContext` → `notifyChatRecoveryExhausted` → host
+ * terminalize sequence that every host's `_exhaustChatRecovery` repeated.
+ *
+ * What this OWNS (the invariant, so it cannot drift per host):
+ * - the notification ALWAYS runs before any terminal write, and
+ * - a throwing `onExhausted` can NEVER block terminal delivery — it is swallowed
+ *   via `onError` (a tested invariant in both published packages).
+ *
+ * What it deliberately does NOT own: the terminal-record / broadcast /
+ * recovering-clear writes — their exact set diverges per host (both
+ * `AIChatAgent` and `Think` broadcast the banner first so it survives a storage
+ * write that rejects mid-deploy; `Think` additionally writes a submission row)
+ * — see {@link ChatRecoveryAdapter.exhaustChatRecovery}. The host expresses
+ * those writes inside `terminalize`. A `terminalize` that throws DOES propagate,
+ * so the whole give-up re-runs on a healthy isolate (#1730); see
+ * {@link ChatRecoveryEngine.exhaustRecoveryGiveUp}.
+ *
+ * `partialParts` is passed explicitly (not derived from a `RecoveryPartial`) so a
+ * foreign-vocabulary host can pass `[]` rather than fabricate AI-SDK parts — the
+ * engine seam stays parts-vocabulary-agnostic.
+ */
+declare function runChatRecoveryExhaustion(
+  input: {
+    incident: ChatRecoveryIncident;
+    config: ResolvedChatRecoveryConfig;
+    partialText: string;
+    partialParts: ChatRecoveryExhaustedContext["partialParts"];
+    streamId: string;
+    createdAt: number;
+  },
+  hooks: {
+    emit: (ctx: ChatRecoveryExhaustedContext) => void;
+    onExhausted?: (ctx: ChatRecoveryExhaustedContext) => void | Promise<void>;
+    onError: (error: unknown) => void;
+    terminalize: (ctx: ChatRecoveryExhaustedContext) => void | Promise<void>;
+  }
+): Promise<void>;
+//#endregion
+//#region src/chat/recovery-codec.d.ts
+/**
+ * Reconstructs the partial assistant state of an interrupted turn from its
+ * stored `ResumableStream` chunk bodies (oldest-first).
+ */
+interface ChatRecoveryCodec {
+  /**
+   * Replay the stored chunk bodies into the engine's `RecoveryPartial`. The
+   * codec — not the engine — both reconstructs `parts` (in its own vocabulary,
+   * opaque to the engine) AND decides `hasSettledToolResults`, so the engine
+   * never names a part type.
+   */
+  toRecoveryPartial(bodies: string[]): RecoveryPartial;
+  /**
+   * Whether a stored chunk of this wire `type` is a **progress milestone** — a
+   * started text/reasoning segment or a settled tool input/output — that should
+   * always credit the host's recovery no-progress window (#1637). The chunk-type
+   * list lives HERE (the codec owns the chunk vocabulary). A `undefined` type (a
+   * non-JSON / typeless body) is never progress.
+   */
+  isProgressChunk(type: string | undefined): boolean;
+  /**
+   * Whether a stored chunk of this wire `type` is **mid-segment streaming
+   * content** — a delta extending an already-started segment (text/reasoning
+   * body, partial tool input). On its own a delta is too granular to credit per
+   * token, but a long single segment that produces only deltas (no new
+   * milestone) must still register forward progress across repeated crashes, or
+   * its no-progress window can false-fire while content is genuinely streaming.
+   * Hosts credit these through a time throttle (see {@link
+   * shouldCreditStreamProgress}). Disjoint from {@link isProgressChunk}; a
+   * `undefined` type is never streaming content.
+   */
+  isStreamingContentChunk(type: string | undefined): boolean;
+}
+/** Minimal per-isolate throttle gate (see `StreamProgressCreditThrottle`). */
+interface ProgressCreditThrottle {
+  shouldCredit(now: number): boolean;
+}
+/**
+ * The single, host-agnostic rule for crediting recovery forward progress from a
+ * stored stream chunk — the convergence of what `AIChatAgent` and `Think`
+ * previously each decided on their own (ai-chat keyed on chunk type only; Think
+ * keyed on its flush cadence). Both hosts now call this at chunk-store time so
+ * the bump TIMING is identical:
+ *
+ *  - a **milestone** ({@link ChatRecoveryCodec.isProgressChunk}) always credits;
+ *  - **streaming content** ({@link ChatRecoveryCodec.isStreamingContentChunk})
+ *    credits at most once per throttle window, so a long single segment still
+ *    registers progress across crashes without writing storage per token;
+ *  - anything else never credits.
+ *
+ * Finer than either host's prior cadence in the worst case and never coarser, so
+ * it can only delay/avoid a false `no_progress_timeout`, never hasten give-up.
+ */
+declare function shouldCreditStreamProgress(input: {
+  codec: Pick<ChatRecoveryCodec, "isProgressChunk" | "isStreamingContentChunk">;
+  type: string | undefined;
+  throttle: ProgressCreditThrottle;
+  now: number;
+}): boolean;
+/**
+ * The AI SDK codec: replays SSE chunk bodies through {@link getPartialStreamText}
+ * (`applyChunkToParts` under the hood). Stateless — share the
+ * {@link aiSdkRecoveryCodec} singleton rather than constructing per call.
+ */
+declare class AISDKRecoveryCodec implements ChatRecoveryCodec {
+  toRecoveryPartial(bodies: string[]): {
+    text: string;
+    parts: MessagePart[];
+    hasSettledToolResults: boolean;
+  };
+  isProgressChunk(type: string | undefined): boolean;
+  isStreamingContentChunk(type: string | undefined): boolean;
+}
+/** Shared stateless {@link AISDKRecoveryCodec} instance. */
+declare const aiSdkRecoveryCodec: AISDKRecoveryCodec;
+//#endregion
+//#region src/chat/resume-handshake.d.ts
+/** A pending terminal outcome captured before connect (#1645). */
+interface PendingChatTerminal {
+  requestId: string;
+  body: string;
+}
+/**
+ * The host-owned surface the resume handshake threads. `pendingResumeConnections`
+ * (and the continuation `awaitingConnections` map) stay host-owned — they are
+ * also touched by the streaming loop, which is NOT part of this extraction — so
+ * the driver only reads/mutates them through this seam rather than owning them.
+ */
+interface ResumeHandshakeHost {
+  /** The host's use-chat-response message-type constant (wire string). */
+  readonly responseMessageType: string;
+  readonly resumableStream: ResumableStream;
+  readonly continuation: ContinuationState<Connection>;
+  /**
+   * Accepted-but-not-yet-streamed turns (#1784). Optional: experimental
+   * recovery adapters that don't track a pre-stream window omit it and keep the
+   * legacy `resume_none` behavior. When present, the handshake parks a
+   * reconnecting client here (sending a keep-waiting `STREAM_PENDING`) instead
+   * of telling it there is nothing to resume.
+   */
+  readonly preStream?: PreStreamTurns<Connection>;
+  /**
+   * Connections notified of a resumable stream, excluded from live broadcast
+   * until they ACK. Host-owned (shared with the streaming loop).
+   */
+  readonly pendingResumeConnections: Set<string>;
+  /** Read the pending terminal outcome (#1645), or `null` when none survives. */
+  pendingChatTerminal(): Promise<PendingChatTerminal | null>;
+  /** Materialize an orphaned stream's partial into a persisted assistant message. */
+  persistOrphanedStream(streamId: string): Promise<void>;
+  /**
+   * Whether the connection that owns the active continuation stream is still
+   * connected. Optional: when omitted the handshake assumes it is (legacy
+   * behavior). Hosts wire their live connection registry so a continuation
+   * stream whose owner vanished on an abrupt (1006) reconnect can still be
+   * resumed by the replacement connection (#1784).
+   */
+  isConnectionPresent?(connectionId: string): boolean;
+}
+/**
+ * Drives the server side of the stream-resume protocol over a
+ * {@link ResumeHandshakeHost}. Construct once per agent (the host wires its
+ * `ResumableStream` / `ContinuationState` / pending set in) and call the three
+ * public methods from the host's existing onConnect / onMessage wiring, so
+ * handler registration timing stays host-owned.
+ */
+declare class ResumeHandshake {
+  private readonly host;
+  constructor(host: ResumeHandshakeHost);
+  /**
+   * Notify a connection that an active stream can be resumed; it should reply
+   * with `STREAM_RESUME_ACK` to receive the replay.
+   *
+   * A connection can legitimately be notified more than once for the same
+   * request — proactively from onConnect AND in response to its explicit
+   * `STREAM_RESUME_REQUEST` (#1733). This is intentional and must NOT be deduped
+   * here: an explicit request always deserves a response (else the client's
+   * `reconnectToStream` hangs to its timeout with no replay), and the proactive
+   * notify is required for clients that never send a request. The notify is one
+   * tiny frame; the client dedupes its ACK so the buffer is not replayed twice.
+   */
+  notifyStreamResuming(connection: Connection): void;
+  /**
+   * Handle a client `STREAM_RESUME_REQUEST`. The client sends this after its
+   * message handler is registered, avoiding the race where a proactive
+   * `STREAM_RESUMING` from onConnect arrives before the handler is ready.
+   */
+  handleResumeRequest(connection: Connection): Promise<void>;
+  /** Send a keep-waiting `STREAM_PENDING` frame (#1784). */
+  private _sendStreamPending;
+  /** Whether the active continuation's owner connection is still present. */
+  private _ownerStillPresent;
+  /** Handle a client `STREAM_RESUME_ACK` for `requestId`. */
+  handleResumeAck(connection: Connection, requestId: string): Promise<void>;
+  /**
+   * Replay a pending terminal outcome (#1645) over the resume handshake so a
+   * reconnecting client surfaces it exactly like a live exhaustion. The bare
+   * terminal frame is dropped by the client unless it arrives on a resumed
+   * stream — the only path that reaches the transport's stream reader and
+   * becomes `useChat.error` — so we drive `STREAM_RESUMING` here and deliver the
+   * error frame once the client ACKs (see {@link _replayTerminalOnAck}). Returns
+   * `true` if a terminal was pending (and `STREAM_RESUMING` was sent).
+   */
+  private _replayTerminalOnResume;
+  /**
+   * Deliver the pending terminal error frame on the resumed stream the client
+   * ACKed (#1645). The record is retained (not cleared) so concurrent reconnects
+   * (e.g. multiple tabs) each learn the outcome; it is cleared when a later turn
+   * supersedes it.
+   */
+  private _replayTerminalOnAck;
+}
+//#endregion
+//#region src/chat/stall-watchdog.d.ts
+/**
+ * Shared inactivity watchdog for UI-message streams.
+ *
+ * A model/transport stream can park indefinitely without ever throwing (a hung
+ * provider, a wedged transport). Left unguarded, the consumer read-loop waits
+ * forever. {@link iterateWithStallWatchdog} wraps such a stream so that a gap of
+ * `timeoutMs` between chunks aborts the upstream and throws
+ * {@link ChatStreamStalledError}, letting the consumer route the stall into
+ * bounded recovery (#1626) — a transient hang is retried within the existing
+ * recovery budget — while genuine in-band errors stay terminal.
+ *
+ * @internal Sibling-package support for `@cloudflare/ai-chat` and
+ * `@cloudflare/think`, not a public API. See
+ * `design/rfc-chat-recovery-foundation.md`.
+ */
+/**
+ * Thrown by {@link iterateWithStallWatchdog} when the inactivity watchdog fires
+ * (a model/transport stream that parks without ever throwing). Distinct from
+ * in-band model/stream errors so the read-loop catch can route a stall into
+ * bounded recovery (#1626) — a transient hang is retried within the existing
+ * recovery budget — while genuine errors stay terminal.
+ */
+declare class ChatStreamStalledError extends Error {
+  readonly isChatStreamStall = true;
+  constructor(message: string);
+}
+/**
+ * Wrap a UI-message stream with an inactivity watchdog. If no chunk arrives
+ * within `timeoutMs`, `onStall` runs (aborting the upstream model stream) and
+ * the iterator throws, so the consumer loop exits with a terminal error
+ * instead of parking forever on a hung provider/transport. `timeoutMs <= 0`
+ * passes the source through untouched.
+ */
+declare function iterateWithStallWatchdog<T>(
+  source: AsyncIterable<T>,
+  timeoutMs: number,
+  onStall: () => void
+): AsyncGenerator<T>;
+//#endregion
 export {
+  AGENT_TOOL_STREAM_PROGRESS_BUMP_THROTTLE_MS,
   AbortRegistry,
+  type AgentToolBroadcastHooks,
   type AgentToolEvent,
   type AgentToolEventMessage,
   type AgentToolEventState,
+  type AgentToolProgressEmitHooks,
+  type AgentToolProgressEmitResult,
+  AgentToolProgressEmitter,
   type AgentToolRunState,
+  AgentToolStreamProgressThrottle,
+  AutoContinuationController,
+  type AutoContinuationHost,
+  type BeginChatRecoveryIncidentInput,
+  type BeginChatRecoveryIncidentResult,
   type BroadcastStreamEvent,
   type BroadcastStreamState,
   type TransitionResult as BroadcastTransitionResult,
+  CHAT_LAST_TERMINAL_KEY,
   CHAT_MESSAGE_TYPES,
+  CHAT_RECOVERING_FLAG_TTL_MS,
+  CHAT_RECOVERING_KEY,
+  CHAT_RECOVERY_ALARM_DEBOUNCE_MS,
+  CHAT_RECOVERY_INCIDENT_KEY_PREFIX,
+  CHAT_RECOVERY_INCIDENT_TTL_MS,
+  CHAT_RECOVERY_PROGRESS_KEY,
+  CHAT_RECOVERY_STABLE_RETRY_DELAY_SECONDS,
+  CHAT_STREAM_PROGRESS_CREDIT_THROTTLE_MS,
+  type ChatConnection,
   type ChatFiberSnapshot,
+  type ChatFiberWakeHooks,
   type ChatProtocolEvent,
+  type ChatRecoveryAdapter,
+  type ChatRecoveryCodec,
   type ChatRecoveryConfig,
   type ChatRecoveryContext,
+  ChatRecoveryEngine,
   type ChatRecoveryExhaustedContext,
+  type ChatRecoveryIncident,
+  type ChatRecoveryIncidentEvent,
+  type ChatRecoveryKind,
   type ChatRecoveryOptions,
   type ChatRecoveryProgressContext,
+  type ChatRecoveryScheduleCallback,
+  type ChatRecoveryScheduleReason,
   type ChatResponseResult,
+  ChatStreamStalledError,
+  type ChatStreamStatus,
+  type ChatTerminalRecord,
   type ChunkAction,
   type ChunkResult,
+  type ClassifyRecoveredTurnInput,
   type ClientToolExecutor,
   type ClientToolSchema,
   type ContinuationConnection,
   type ContinuationDeferred,
   type ContinuationPending,
+  type ContinuationSpec,
   ContinuationState,
+  DEFAULT_CHAT_RECOVERY_MAX_ATTEMPTS,
+  DEFAULT_CHAT_RECOVERY_MAX_OOM_RETRIES,
+  DEFAULT_CHAT_RECOVERY_MAX_WORK,
+  DEFAULT_CHAT_RECOVERY_NO_PROGRESS_TIMEOUT_MS,
+  DEFAULT_CHAT_RECOVERY_STABLE_TIMEOUT_MS,
+  DEFAULT_CHAT_RECOVERY_TERMINAL_MESSAGE,
+  type DispatchRecoveredTurnInput,
+  type EnforceRowSizeLimitOptions,
   type EnqueueOptions,
+  type EvaluateChatRecoveryIncidentInput,
+  type EvaluateChatRecoveryIncidentResult,
+  type IncomingMessage,
+  type InvokeOnChatRecoveryInput,
+  KV_DELETE_MAX_KEYS,
   MAX_BOUND_PARAMS,
   type MessageConcurrency,
   type MessagePart,
   type MessageParts,
+  MessageType,
   type NormalizedMessageConcurrency,
+  type OrphanPersistStore,
+  type OutgoingMessage,
+  type PendingChatTerminal,
+  type PersistOrphanedPartialInput,
+  type PersistReconstructedOrphanOptions,
+  PreStreamTurns,
+  type ProgressCreditThrottle,
   ROW_MAX_BYTES,
+  type RecoveryPartial,
+  type RepairInterruptedToolPartsOptions,
+  type RepairInterruptedToolPartsResult,
+  type ReplyAttachment,
   type ResolvedChatRecoveryConfig,
+  type ResolvedRecoveryStream,
   ResumableStream,
+  ResumeHandshake,
+  type ResumeHandshakeHost,
+  STREAM_CLEANUP_DELAY_SECONDS,
   type SaveMessagesOptions,
   type SaveMessagesResult,
+  type SnapshotMessage,
   type SqlTaggedTemplate,
   StreamAccumulator,
   type StreamAccumulatorOptions,
   type StreamChunkData,
+  StreamProgressCreditThrottle,
   SubmitConcurrencyController,
   type SubmitConcurrencyDecision,
+  TIMED_OUT,
   type ToolPartUpdate,
   TurnQueue,
   type TurnResult,
+  aiSdkRecoveryCodec,
   applyAgentToolEvent,
   applyChunkToParts,
   applyToolUpdate,
-  assistantContentKey,
+  awaitWithDeadline,
   transition as broadcastTransition,
+  buildChatRecoveringFrame,
   buildInClauseStrings,
+  bumpChatRecoveryProgress,
   byteLength,
+  chatRecoverySchedulePolicy,
+  classifyAgentToolChildRecovery,
+  cleanupStreamBuffers,
+  clearChatTerminal,
+  clientResolvableToolNames,
   createAgentToolEventState,
   createChatFiberSnapshot,
   createToolsFromClientSchemas,
   crossMessageToolResultUpdate,
+  drainInteractionApplies,
   enforceRowSizeLimit,
+  hasIncompleteToolBatch,
+  interceptAgentToolBroadcast,
   isReplayChunk,
+  iterateWithStallWatchdog,
+  listActiveChatRecoveryIncidents,
   normalizeToolInput,
   parseProtocolMessage,
+  partAwaitsClientInteraction,
   pausedExecutionUpdate,
+  pendingChatTerminal,
+  persistReconstructedOrphan,
+  readChatRecoveryProgress,
   reconcileMessages,
+  reconcileOrphanPartial,
+  recordChatTerminal,
+  repairInterruptedToolParts,
+  resolveChatRecoveryConfig,
   resolveToolMergeId,
+  runChatRecoveryExhaustion,
   sanitizeMessage,
+  sendIfOpen,
+  setChatRecovering,
+  shouldCreditStreamProgress,
+  sweepStaleChatRecoveryIncidents,
   toolApprovalUpdate,
+  toolPartHasSettledResult,
   toolResultUpdate,
   unwrapChatFiberSnapshot,
   wrapChatFiberSnapshot