agents 0.22.0 → 0.23.0

package/dist/chat/index.d.ts

@@ -1,15 +1,18 @@
+import { o as isPlatformFailure } from "../retries-D9Ds-1lz.js";
 import {
-  H as AgentToolEvent,
-  U as AgentToolEventMessage,
-  W as AgentToolEventState,
-  et as AgentToolRunState,
-  v as FiberRecoveryContext
-} from "../agent-routing-CnkaHb-v.js";
+  L as AgentToolEvent,
+  R as AgentToolEventMessage,
+  Y as AgentToolRunState,
+  _ as FiberRecoveryContext$1,
+  z as AgentToolEventState
+} from "../agent-routing-DE5zmCQ8.js";
+import { _ as TaskStep, m as TaskRunOptions } from "../tasks-BRJ5zgya.js";
 import {
   n as ClientToolSchema,
   r as createToolsFromClientSchemas,
   t as ClientToolExecutor
 } from "../client-tools-aIBO0Fk7.js";
+import { n as Streams } from "../streams-D6tJ0NN9.js";
 import {
   a as applyAgentToolEvent,
   i as AgentToolProgressEmitter,
@@ -18,9 +21,10 @@ import {
   r as AgentToolProgressEmitResult,
   s as interceptAgentToolBroadcast,
   t as AgentToolBroadcastHooks
-} from "../agent-tools-C0XJqWzB.js";
+} from "../agent-tools-DtXMTDGM.js";
+import { l as SessionMessage } from "../types-B7LojTe4.js";
 import { JSONSchema7, UIMessage } from "ai";
-import { Connection } from "agents";
+import { Connection, FiberRecoveryContext } from "agents";
 
 //#region src/chat/message-builder.d.ts
 /** The parts array type from UIMessage */
@@ -151,10 +155,16 @@ declare function isReplayChunk(
   chunk: StreamChunkData
 ): boolean;
 //#endregion
-//#region src/chat/sanitize.d.ts
-/** Maximum serialized message size before compaction (bytes). 1.8MB with headroom below SQLite's 2MB limit. */
-declare const ROW_MAX_BYTES = 1800000;
-/** Measure UTF-8 byte length of a string. */
+//#region src/sessions/sanitize.d.ts
+/**
+ * Message hygiene shared by every Sessions write: UTF-8 measurement without a
+ * full encoded copy, and removal of ephemeral provider metadata that must not
+ * be stored or replayed.
+ */
+/**
+ * Measure UTF-8 byte length without allocating a complete encoded copy.
+ * Memory stays bounded by a 16 KiB buffer even for near-row-limit strings.
+ */
 declare function byteLength(s: string): number;
 /**
  * Sanitize a message for persistence by removing ephemeral provider-specific
@@ -163,7 +173,15 @@ declare function byteLength(s: string): number;
  * 1. Strips OpenAI ephemeral fields (itemId, reasoningEncryptedContent)
  * 2. Filters truly empty reasoning parts (no text, no remaining providerMetadata)
  */
-declare function sanitizeMessage(message: UIMessage): UIMessage;
+declare function sanitizeMessage<
+  M extends {
+    parts: readonly object[];
+  }
+>(message: M): M;
+//#endregion
+//#region src/chat/sanitize.d.ts
+/** Maximum serialized message size before compaction (bytes). 1.8MB with headroom below SQLite's 2MB limit. */
+declare const ROW_MAX_BYTES = 1800000;
 /** Optional hooks for {@link enforceRowSizeLimit}. */
 interface EnforceRowSizeLimitOptions {
   /**
@@ -330,7 +348,7 @@ type TextSegmentEvent =
 /**
  * @internal Converts structured stream chunks into text and boundary events
  * without gluing words across non-text chunks. Sibling-package support for
- * `@cloudflare/voice` and `@cloudflare/think`, not a public API.
+ * Voice and `@cloudflare/think`, not a public API.
  */
 declare class TextSegmentJoiner {
   #private;
@@ -528,7 +546,7 @@ type ChatRecoveryProgressContext = {
  * Configuration for durable chat recovery, which is always enabled for chat
  * turns. `true` uses these defaults: `maxAttempts: 10`,
  * `stableTimeoutMs: 10_000`, `noProgressTimeoutMs: 300_000` (5 min),
- * `maxRecoveryWork: 1000`, and a generic terminal message. Assign an object to
+ * `maxRecoveryWork: 10000`, and a generic terminal message. Assign an object to
  * tune recovery without disabling its durable bookkeeping.
  *
  * **Apply this as a class field or in the constructor — never assign it in
@@ -737,21 +755,16 @@ declare function transition(
 //#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`.
+ * Construct the Streams capability instance a chat host must install to back
+ * its `ResumableStream`: identical to `new Streams()` except for the raised
+ * per-chunk ceiling that chat's packed segments require.
  */
-declare const STREAM_CLEANUP_DELAY_SECONDS: number;
+declare function createChatStreams(): Streams;
+/** Public status vocabulary predates the Streams state names. */
+type PublicStreamStatus = "streaming" | "completed" | "error";
 /**
- * Minimal SQL interface matching Agent's this.sql tagged template.
- * Allows ResumableStream to work with the Agent's SQLite without
- * depending on the full Agent class.
+ * Minimal SQL interface matching Agent's this.sql tagged template. The
+ * adapter uses it exclusively for chat's own legacy tables during migration.
  */
 type SqlTaggedTemplate = {
   <T = Record<string, unknown>>(
@@ -759,12 +772,21 @@ type SqlTaggedTemplate = {
     ...values: (string | number | boolean | null)[]
   ): T[];
 };
+/** Host hooks for the chat stream adapter. */
+type ResumableStreamOptions = {
+  /**
+   * Called with the durable part of the recovery progress marker (retired
+   * segments plus credits plus the seeded legacy counter) after it advances,
+   * outside any transaction. Hosts mirror it to the pre-derivation KV key so
+   * a build rolled back to the KV counter never reads a marker lower than
+   * an incident recorded under this one. Fires per stream retired and per
+   * credit, never per chunk.
+   */
+  onProgress?: (durableSegments: number) => void;
+};
 declare class ResumableStream {
-  private sql;
   private _activeStreamId;
   private _activeRequestId;
-  /** Monotonic row-ordering index; one increment per flushed segment row. */
-  private _segmentIndex;
   /**
    * Whether the active stream was started in this instance (true) or
    * restored from SQLite after hibernation/restart (false). An orphaned
@@ -774,23 +796,103 @@ declare class ResumableStream {
   private _isLive;
   /**
    * Whether the active stream is a continuation. Mirrors the durable
-   * `is_continuation` column so replay frames can carry the flag without a
-   * per-replay query; restored from SQLite after hibernation in restore().
+   * metadata so replay frames can carry the flag without a per-replay query;
+   * restored from SQLite after hibernation in restore().
    */
   private _activeIsContinuation;
   private _chunkBuffer;
   private _chunkBufferBytes;
   private _isFlushingChunks;
-  private _lastCleanupTime;
-  constructor(sql: SqlTaggedTemplate);
   /**
-   * Add metadata columns for rows created before they existed. Constructors
-   * intentionally do not run this: most wakes never start a stream, so paying a
-   * schema-introspection read every time is wasteful. New tables include these
-   * columns in CREATE TABLE; legacy tables migrate lazily only if a write/read
-   * discovers the columns are missing.
+   * A stream whose producer finished but whose row is deliberately still
+   * `streaming`: the host will {@link cutover} it together with the message
+   * write, or {@link finalizePending} it when there is nothing to persist.
+   */
+  private _pendingCutover;
+  private readonly ops;
+  constructor(
+    streams: Streams,
+    sql: SqlTaggedTemplate,
+    options?: ResumableStreamOptions
+  );
+  private readonly _sql;
+  private readonly _onProgress;
+  /**
+   * Tell the host the durable part of the marker moved. Called after the
+   * write that moved it has left any transaction, never inside one: the
+   * host's mirror is an async KV put, which a synchronous transaction
+   * would reject.
+   */
+  private _notifyProgress;
+  /**
+   * One row: `retired` accumulates the segments of deleted streams and
+   * explicit credits; `legacy` holds the pre-derivation KV counter, folded
+   * in once. They are separate columns so a seed can never swallow
+   * segments retired before it landed, and a repeated seed is idempotent.
+   */
+  private _ensureProgressTable;
+  private _retiredSegments;
+  /** Add `segments` to the retired total. One row write; a no-op for zero. */
+  private _retire;
+  /**
+   * Segments a row still accounts for: a live stream's log tail, a settled
+   * stream's final cursor (stamped exact at settlement).
+   */
+  private _segmentsOf;
+  /**
+   * Monotonic count of durably flushed chat segments on this Durable
+   * Object, plus explicit credits (see {@link creditProgress}): the recovery
+   * engine's forward-progress marker. Advances only when a segment lands in
+   * the log — never on a reconnect replay or a recovery re-persist, which
+   * read the log without appending — and is untouched by compaction, which
+   * rewrites the transcript, not the log. Reads the stream rows plus one
+   * log-tail row per live stream: called at incident evaluation, not on the
+   * hot path.
+   *
+   * A chat row leaving the table by any path — this adapter's cutover,
+   * reclaim and clear, or the capability's own `delete()` — passes through
+   * the deletion hook, so its segments are retired before they are gone
+   * and the marker never moves on a deletion.
+   */
+  progressMarker(): number;
+  /**
+   * Credit one unit of forward progress that the log cannot see: a parent
+   * forwarding a sub-agent's output (N9) produces no chunks of its own, yet
+   * that output is the parent turn advancing. One row write; callers
+   * throttle.
+   */
+  creditProgress(): void;
+  /**
+   * Carry the pre-derivation KV counter forward: the marker must not read
+   * lower after the upgrade than the high-water mark an in-flight incident
+   * already recorded, or a progressing turn would look stuck until the log
+   * caught up. The counter is never written again, so its value is a
+   * constant this folds into its own column by max — idempotent across
+   * isolates, and never touching segments retired before the seed landed.
+   * A no-op for zero, so a fresh object never writes.
+   *
+   * The counter already credited a stream that was in flight at the
+   * upgrade, and that stream's live segments count again here, so the
+   * first read after the upgrade can exceed the counter by those segments.
+   * That reads as progress once, and hands an in-flight incident one extra
+   * no-progress window; it cannot recur.
+   */
+  seedProgress(legacyTotal: number): void;
+  /**
+   * Delete chat rows. The deletion hook folds each row's segments into the
+   * retired total in the same synchronous block, retire before delete, so
+   * a partial commit could only ever count a stream twice, never lose it.
    */
-  private _migrateMetadataColumns;
+  private _deleteRetiring;
+  /**
+   * One-time migration of the pre-capability `cf_ai_chat_stream_*` tables
+   * into the Streams tables, preserving in-flight resumability across the
+   * upgrade (an active stream keeps its id, chunks, and last-activity), then
+   * dropping the legacy tables. Tolerates the pre-#1691/#1733 metadata
+   * schema (no `message_id` / `is_continuation` columns). The host `sql`
+   * handle touches only these chat-owned legacy tables.
+   */
+  private _migrateLegacyTables;
   get activeStreamId(): string | null;
   get activeRequestId(): string | null;
   hasActiveStream(): boolean;
@@ -801,7 +903,7 @@ declare class ResumableStream {
   get isLive(): boolean;
   /**
    * Start tracking a new stream for resumable streaming.
-   * Creates metadata entry in SQLite and sets up tracking state.
+   * Creates the backing stream row and sets up tracking state.
    * @param requestId - The unique ID of the chat request
    * @returns The generated stream ID
    */
@@ -816,7 +918,7 @@ declare class ResumableStream {
    * The assistant message id an orphaned stream was producing — the same id the
    * live path persists under, so recovery re-associates reconstructed chunks
    * with the correct message (#1691). Returns null when the row is missing or
-   * is a legacy row written before the `message_id` column existed.
+   * predates message-id tracking.
    */
   getStreamMessageId(streamId: string): string | null;
   /**
@@ -824,15 +926,44 @@ declare class ResumableStream {
    * @param streamId - The stream to mark as completed
    */
   complete(streamId: string): void;
+  /**
+   * The producer finished, but leave the row `streaming` for the cutover:
+   * the host persists the message and settles the stream in one
+   * transaction with {@link cutover}. Until then a crash leaves the stream
+   * live — exactly the evidence recovery rebuilds the message from. The
+   * host MUST follow with {@link cutover} or {@link finalizePending}.
+   */
+  finish(streamId: string): void;
+  /** The stream {@link finish}ed and awaiting its cutover, if any. */
+  get pendingCutoverId(): string | null;
+  /**
+   * The cutover: settle the stream, run `persist` (synchronous writes — the
+   * message), and delete the stream's rows in one SQLite transaction. A
+   * crash leaves either the live stream or the finished message, never
+   * neither; nothing is left to sweep. `discard: false` keeps the settled
+   * rows (an agent-tool child whose parent still tails them); they are
+   * reclaimed by the next {@link start}.
+   */
+  cutover(
+    streamId: string,
+    persist: () => void,
+    options?: {
+      discard?: boolean;
+    }
+  ): void;
+  /**
+   * Settle a {@link finish}ed stream that had nothing to persist (no parts,
+   * a persist that threw). Idempotent; a no-op when nothing is pending.
+   */
+  finalizePending(): void;
+  private _clearActive;
   /**
    * Mark a stream as errored and clean up state.
    * @param streamId - The stream to mark as errored
    */
   markError(streamId: string): void;
-  /** Maximum chunk body size before skipping storage (bytes). Prevents SQLite row limit crash. */
-  private static CHUNK_MAX_BYTES;
   /**
-   * Buffer a stream chunk for batch write to SQLite.
+   * Buffer a stream chunk for batch write to storage.
    * Chunks exceeding the row size limit are skipped to prevent crashes.
    * The chunk is still broadcast to live clients (caller handles that),
    * but will be missing from replay on reconnection.
@@ -841,15 +972,24 @@ declare class ResumableStream {
    */
   storeChunk(streamId: string, body: string): void;
   /**
-   * Flush the buffered chunks to SQLite as a single packed row.
+   * Flush the buffered chunks to storage as a single packed segment.
    * Uses a lock to prevent concurrent flush operations.
    *
-   * The whole buffer becomes one row: a single-chunk segment is stored
-   * unwrapped (legacy object format) so a large chunk avoids array-escaping
-   * inflation, while a multi-chunk segment stores a JSON array of bodies. This
-   * collapses N chunk rows into one, cutting rows written / stored / scanned.
+   * The whole buffer becomes one stored chunk on the backing stream: a
+   * single-chunk segment is stored unwrapped so a large chunk avoids
+   * array-escaping inflation, while a multi-chunk segment stores a JSON
+   * array of bodies. This collapses N chunk writes into one fenced append,
+   * cutting rows written / stored / scanned.
    */
   flushBuffer(): void;
+  /**
+   * Stored chunk bodies for one stream, packed segments expanded, in order.
+   * A generator over paged reads, so replaying a large turn holds one page
+   * of segments in memory instead of the whole stored stream; iteration is
+   * synchronous end to end (WebSocket sends don't await), so the pages see
+   * a consistent log.
+   */
+  private _storedBodies;
   /**
    * Send stored stream chunks to a connection for replay.
    * Chunks are marked with replay: true so the client can batch-apply them.
@@ -860,11 +1000,10 @@ declare class ResumableStream {
    * - **Orphaned stream** (restored from SQLite after hibernation, no reader):
    *   sends chunks + `done` and completes the stream. The caller should
    *   reconstruct and persist the partial message from the stored chunks.
-   * - **Completed during replay** (defensive): sends chunks + `done`.
    *
-   * All sends use {@link sendIfOpen}, so a WebSocket closing mid-replay
-   * does not throw. If the connection drops while iterating chunks the
-   * stream is left active so the next reconnect can retry.
+   * All sends tolerate a WebSocket closing mid-replay. If the connection
+   * drops while iterating chunks the stream is left active so the next
+   * reconnect can retry.
    *
    * @param connection - The WebSocket connection
    * @param requestId - The original request ID
@@ -872,6 +1011,13 @@ declare class ResumableStream {
    *          When non-null the caller should reconstruct the message from chunks.
    */
   replayChunks(connection: Connection, requestId: string): string | null;
+  /**
+   * Latest CHAT-owned row carrying a request tag. The stream table is
+   * shared with application producers and tags are non-unique, so the
+   * newest row by tag alone could be an unrelated stream masking chat's
+   * recovery evidence — ownership is the `cfChat` metadata marker.
+   */
+  private _latestChatRowByTag;
   replayCompletedChunksByRequestId(
     connection: Connection,
     requestId: string
@@ -882,9 +1028,7 @@ declare class ResumableStream {
    * frame carrying the durable terminal record's error text, mirroring what a
    * live client observed (content chunks, then the error). Without this, a
    * client that missed broadcast frames while disconnected has no other
-   * channel to the pre-error partial content: the server does not push
-   * messages on connect, and {@link replayCompletedChunksByRequestId} only
-   * serves `completed` streams (#1575).
+   * channel to the pre-error partial content (#1575).
    *
    * Returns true when the caller should proceed to send its terminal frame:
    * either no errored stream existed (nothing to replay) or its chunks were
@@ -896,13 +1040,24 @@ declare class ResumableStream {
     connection: Connection,
     requestId: string
   ): boolean;
-  /** Latest stream row for a request with the given terminal status. */
-  private _latestStreamForRequest;
   /**
-   * Send a finished stream's stored chunks to a connection as replay frames.
-   * Returns false if the connection closed mid-replay.
+   * Latest chat stream row for a request regardless of status — the recovery
+   * engines' stream-evidence lookup.
+   */
+  latestStreamInfoForRequest(requestId: string): {
+    id: string;
+    status: PublicStreamStatus;
+    createdAt: number;
+  } | null;
+  /**
+   * Latest in-flight chat stream for a request — recoverable-turn evidence.
    */
-  private _replayStoredChunks;
+  latestActiveStreamInfoForRequest(requestId: string): {
+    id: string;
+    createdAt: number;
+  } | null;
+  /** Every chat-owned stream row, newest first. */
+  private _chatRows;
   /**
    * Restore active stream state if the agent was restarted during streaming.
    * All streams are restored regardless of age — stale cleanup happens
@@ -910,38 +1065,37 @@ declare class ResumableStream {
    */
   restore(): void;
   /**
-   * Clear all stream data (called on chat history clear).
+   * Clear all chat stream data (called on chat history clear). Streams other
+   * producers opened on the same Durable Object are untouched.
    */
   clearAll(): void;
   /**
-   * Drop all stream tables (called on destroy).
+   * Remove all chat stream data (called on destroy). The backing tables
+   * belong to the Streams capability and are shared with other producers,
+   * so this deletes chat's rows rather than dropping tables. Buffered
+   * chunks are dropped (clearAll resets the buffer), not flushed: they
+   * belong to a chat-owned stream this very call deletes, so writing them
+   * first would only pay row writes for rows that die in the same
+   * synchronous block.
    */
   destroy(): void;
   /**
-   * Force a sweep of aged stream buffers now, bypassing the lazy interval
-   * gate used by {@link _maybeCleanupOldStreams}. Intended to be driven by an
-   * alarm so idle/hibernated chat DOs still reclaim buffers even when no
-   * further stream ever completes to trigger the lazy path.
-   */
-  cleanup(now?: number): void;
-  /**
-   * True if any stream rows remain at all. Used by alarm-driven cleanup to
-   * decide whether to re-arm: once no rows remain there is nothing left to
-   * sweep, so the DO can stop waking itself.
+   * Delete every chat stream row this Durable Object no longer needs:
+   * finished streams (their messages are persisted; the cutover normally
+   * deletes them in the same transaction, so these are crash leftovers) and
+   * in-flight rows abandoned past {@link ABANDONED_STREAM_RETENTION_MS} by
+   * last chunk activity. Runs on every {@link start}, so nothing needs an
+   * alarm to be reclaimed; a Durable Object that never starts another turn
+   * keeps at most one turn's rows. Streams other producers opened on the
+   * same object are untouched.
+   * @returns How many rows were reclaimed.
    */
-  hasReclaimableStreams(): boolean;
-  private _maybeCleanupOldStreams;
-  /** Delete completed/errored buffers past the completion grace window, plus
-   *  abandoned "streaming" rows past the stale-in-flight window. The two use
-   *  different retentions: a completed buffer is redundant with the persisted
-   *  message and needs only a brief replay grace, whereas an in-flight buffer
-   *  must outlive resume/recovery before it is presumed dead. */
-  private _sweepOldStreams;
+  reclaim(now?: number): number;
   /**
    * Return the stored chunks for a stream as individual chunk bodies in order,
-   * unpacking packed segment rows. The returned `chunk_index` is a running
-   * per-chunk sequence (0, 1, 2, …) — stable across calls because rows are
-   * append-only — so callers can use it as a monotonic chunk sequence.
+   * unpacking packed segments. The returned `chunk_index` is a running
+   * per-chunk sequence (0, 1, 2, …) — stable across calls because segments
+   * are append-only — so callers can use it as a monotonic chunk sequence.
    */
   getStreamChunks(streamId: string): Array<{
     body: string;
@@ -958,2108 +1112,2216 @@ declare class ResumableStream {
     status: string;
     request_id: string;
     created_at: number;
+    message_id: string | null;
   }>;
   /** @internal For testing only */
   insertStaleStream(streamId: string, requestId: string, ageMs: number): void;
   /**
-   * Append a chunk to a stream dated `ageMs` in the past. Used to exercise the
-   * last-activity sweep threshold: a long-running streaming row with a *recent*
-   * chunk must survive even when its start time is older than the cutoff.
+   * Append a chunk to a stream dated `ageMs` in the past. Used to exercise
+   * reclaim's phase-2 verification: a long-running streaming row with a
+   * *recent* chunk must survive even when its row `updated_at` (stamped at
+   * open, not per append) is older than the coarse cutoff.
    * @internal For testing only
    */
   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
-/**
- * Helpers for building batched SQLite statements that run through the Agent's
- * `sql` tagged template (which interleaves a `?` placeholder between every
- * string fragment). Used to collapse per-row INSERT/DELETE loops into a small
- * number of multi-row statements.
- *
- * SQLite (Durable Object / D1) caps bound parameters at 100 per query, so
- * callers must chunk their inputs to stay within {@link MAX_BOUND_PARAMS}.
- * See https://developers.cloudflare.com/d1/platform/limits/
- */
-/** Maximum bound parameters allowed in a single SQLite (DO / D1) query. */
-declare const MAX_BOUND_PARAMS = 100;
+//#region src/chat/turn-task.d.ts
+/** One live turn closure, registered under its nonce while this isolate runs it. */
+type ChatTurnClosureEntry = {
+  /** The snapshot persisted at claim, before the turn produces anything. */ readonly initial: unknown /** Wrap user stash data into the durable snapshot envelope. */;
+  wrap(data: unknown): unknown /** Execute the live turn. */;
+  run(): Promise<unknown> /** Settles the caller awaiting the turn's outcome. */;
+  readonly settle: {
+    resolve(value: unknown): void;
+    reject(error: unknown): void;
+  };
+};
+/** The host internals one chat-turn definition runs against. */
+type ChatTurnTaskHooks = {
+  /** The registered definition name (the host's `CHAT_FIBER_NAME`). */ readonly definitionName: string;
+  readonly storage: DurableObjectStorage /** The run row's creation time, for recovery staleness accounting. */;
+  getRunCreatedAt(runId: string): Promise<number | null>;
+  getLiveClosure(nonce: string): ChatTurnClosureEntry | undefined;
+  keepAliveWhile<T>(
+    fn: () => Promise<T>
+  ): Promise<T> /** The host's fiber stash context, so `this.stash()` keeps working. */;
+  withStash<T>(
+    context: {
+      id: string;
+      signal: AbortSignal;
+      stash: (data: unknown) => void;
+    },
+    fn: () => Promise<T>
+  ): Promise<T> /** The unchanged recovery seam (ChatRecoveryEngine behind it). */;
+  handleRecovery(ctx: FiberRecoveryContext): Promise<unknown>;
+};
 /**
- * Build a TemplateStringsArray for a single-column `IN (...)` clause. Produces
- * fragments for:
- *   `${prefix}(?, ?, ...)`
- *
- * @throws if `count` is less than 1.
+ * Build the chat-turn Task handler for one host. Registered under the
+ * host's `CHAT_FIBER_NAME` via `Tasks#register`.
  */
-declare function buildInClauseStrings(
-  prefix: string,
-  count: number
-): TemplateStringsArray;
+declare function createChatTurnTaskDefinition(
+  hooks: ChatTurnTaskHooks
+): (input: unknown, step: TaskStep) => Promise<void>;
 //#endregion
-//#region src/chat/protocol.d.ts
+//#region src/chat/recovery.d.ts
 /**
- * Wire protocol message type constants for the cf_agent_chat_* protocol.
- *
- * These are the string values used on the wire between agent servers and
- * clients. Both @cloudflare/ai-chat (via its MessageType enum) and
- * @cloudflare/think use these values.
+ * 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.
  */
-declare const STREAM_RESUME_NONE_REASONS: {
-  /** No active, pending, or terminal stream exists for this agent. */ readonly IDLE: "idle" /** An active tool continuation is owned by another live connection. */;
-  readonly CONTINUATION_OWNED: "continuation-owned";
+interface SnapshotMessage {
+  id?: string;
+  role: string;
+}
+type ChatFiberSnapshot<Kind extends string = string> = {
+  kind: Kind;
+  version: 1;
+  requestId: string;
+  recoveryRootRequestId?: string;
+  continuation: boolean;
+  latestMessageId?: string;
+  latestMessageRole?: string;
+  latestUserMessageId?: string;
+  startedAt: number;
+  lastBody?: Record<string, unknown>;
+  lastClientTools?: ClientToolSchema[];
 };
-type StreamResumeNoneReason =
-  (typeof STREAM_RESUME_NONE_REASONS)[keyof typeof STREAM_RESUME_NONE_REASONS];
-declare const CHAT_MESSAGE_TYPES: {
-  readonly CHAT_MESSAGES: "cf_agent_chat_messages";
-  readonly USE_CHAT_REQUEST: "cf_agent_use_chat_request";
-  readonly USE_CHAT_RESPONSE: "cf_agent_use_chat_response";
-  readonly CHAT_CLEAR: "cf_agent_chat_clear";
-  readonly CHAT_REQUEST_CANCEL: "cf_agent_chat_request_cancel";
-  readonly STREAM_RESUMING: "cf_agent_stream_resuming";
-  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";
+declare function createChatFiberSnapshot<Kind extends string>({
+  kind,
+  requestId,
+  recoveryRootRequestId,
+  continuation,
+  messages,
+  lastBody,
+  lastClientTools
+}: {
+  kind: Kind;
+  requestId: string;
+  recoveryRootRequestId?: string;
+  continuation: boolean;
+  messages: ReadonlyArray<SnapshotMessage>;
+  lastBody?: Record<string, unknown>;
+  lastClientTools?: ClientToolSchema[];
+}): ChatFiberSnapshot<Kind>;
+declare function wrapChatFiberSnapshot<Kind extends string>(
+  key: string,
+  snapshot: ChatFiberSnapshot<Kind>,
+  user: unknown | null
+): Record<string, unknown>;
+declare function unwrapChatFiberSnapshot<Kind extends string>(
+  key: string,
+  value: unknown,
+  expectedKind?: Kind
+): {
+  snapshot: ChatFiberSnapshot<Kind> | null;
+  user: unknown | null;
 };
 //#endregion
-//#region src/chat/wire-types.d.ts
+//#region src/chat/recovery-incident.d.ts
 /**
- * Enum for message types to improve type safety and maintainability
+ * 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}).
  */
-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",
+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;
   /**
-   * 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.
+   * 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`.
    */
-  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",
+  lastProgressAt?: number;
+  reason?: string;
   /**
-   * 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.
+   * 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).
    */
-  CF_AGENT_CHAT_RECOVERING = "cf_agent_chat_recovering"
-}
+  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:";
 /**
- * Types of messages sent from the Agent to clients
+ * The pre-derivation forward-progress counter: a KV integer bumped per
+ * credited chunk. The marker is now derived from the stream log
+ * (`ResumableStream.progressMarker`), and this key is only read — once per
+ * isolate, to seed the derived marker so it never reads lower than the
+ * high-water mark an incident recorded before the upgrade. Current code
+ * writes it only as a mirror of the derived marker's durable part — one put
+ * per stream retired, none per chunk — so a build rolled back to the
+ * counter never reads a marker lower than an incident recorded here.
  */
-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 /** Present when this offer directly answers a client resume probe. */;
-      probeId?: 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 a resume request with no stream for this client. */ type: MessageType.CF_AGENT_STREAM_RESUME_NONE;
-      /**
-       * Why no stream was offered. Only `idle` proves global inactivity;
-       * omitted by older servers and by non-authoritative delayed releases.
-       */
-      reason?: StreamResumeNoneReason /** Correlates an authoritative response to its client resume probe. */;
-      probeId?: string;
-    }
-  | {
-      /**
-       * 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 /** Correlates a direct keep-waiting response to its client probe. */;
-      probeId?: 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;
-    };
+declare const CHAT_RECOVERY_PROGRESS_KEY = "cf:chat-recovery:progress";
 /**
- * Types of messages sent from clients to the Agent
+ * 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).
  */
-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 /** Opaque correlation id echoed by direct server responses. */;
-      probeId?: string;
-    }
-  | {
-      /** 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
+declare const CHAT_RECOVERING_KEY = "cf:chat:recovering";
 /**
- * Connection I/O — shared WebSocket send guard for chat agents.
+ * 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.
  *
- * `@internal` — sibling-package support for `@cloudflare/ai-chat` and
- * `@cloudflare/think`, not a public API. See
- * `design/rfc-chat-recovery-foundation.md`.
+ * 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.
  *
- * Both packages (and `continuation-state`) hand-maintained byte-identical
- * copies of `sendIfOpen` / `isWebSocketClosedSendError`; this is the single
- * shared implementation.
+ * 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).
+ *
+ * The unit is one durable stream segment — about ten packed streaming chunks,
+ * or one settled tool result, which is flushed on its own — plus one per
+ * explicit credit for forwarded sub-agent output. The marker is derived from
+ * the stream log (`ResumableStream.progressMarker`), so that is what it can
+ * count. The earlier KV counter credited per milestone chunk and per five
+ * seconds of deltas, a coarser measure of streamed text; 10 000 segments
+ * (on the order of 100 000 chunks of re-run output) keeps the budget as
+ * generous as 1 000 credits was for delta-heavy turns, and still finite.
  */
+declare const DEFAULT_CHAT_RECOVERY_MAX_WORK = 10000;
 /**
- * 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.
+ * 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.
  */
-interface ChatConnection {
-  readonly id: string;
-  send(message: string): void;
-}
+declare const DEFAULT_CHAT_RECOVERY_MAX_OOM_RETRIES = 3;
+declare const DEFAULT_CHAT_RECOVERY_STABLE_TIMEOUT_MS = 10000;
 /**
- * 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.
+ * 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 function sendIfOpen(
-  connection: ChatConnection,
-  message: string
-): boolean;
-//#endregion
-//#region src/chat/continuation-state.d.ts
+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.";
 /**
- * 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.
+ * Incidents that have not seen a new attempt within this window are assumed
+ * abandoned and swept so durable storage does not grow without bound.
  */
-type ContinuationConnection = ChatConnection;
-interface ContinuationPending<
-  TConnection extends ContinuationConnection = ContinuationConnection
-> {
-  connection: TConnection;
-  connectionId: string | null;
-  requestId: string;
-  clientTools?: ClientToolSchema[];
-  body?: Record<string, unknown>;
-  errorPrefix: string | null;
-  prerequisite: Promise<boolean> | null;
-  pastCoalesce: boolean;
-}
-interface ContinuationDeferred<
-  TConnection extends ContinuationConnection = ContinuationConnection
-> {
-  connection: TConnection;
-  connectionId: string | null;
-  clientTools?: ClientToolSchema[];
-  body?: Record<string, unknown>;
-  errorPrefix: string;
-  prerequisite: Promise<boolean> | null;
-}
-declare class ContinuationState<
-  TConnection extends ContinuationConnection = ContinuationConnection
-> {
-  pending: ContinuationPending<TConnection> | null;
-  deferred: ContinuationDeferred<TConnection> | null;
-  activeRequestId: string | null;
-  activeConnectionId: string | null;
-  awaitingConnections: Map<string, TConnection>;
-  /** Clear pending state and awaiting connections (without sending RESUME_NONE). */
-  clearPending(): void;
-  clearDeferred(): void;
-  clearAll(): void;
-  /**
-   * Mark a connection as no longer available without canceling the
-   * continuation it initiated.
-   */
-  releaseConnection(connectionId: string): void;
-  /**
-   * Send STREAM_RESUME_NONE to all connections waiting for a
-   * continuation stream to start, then clear the map.
-   */
-  sendResumeNone(): void;
-  /**
-   * Flush awaiting connections by notifying each one via the provided
-   * callback (typically sends STREAM_RESUMING), then clear.
-   */
-  flushAwaitingConnections(notify: (conn: TConnection) => void): void;
-  /**
-   * Transition pending → active. Called when the continuation stream
-   * actually starts. Moves request/connection IDs to active slots,
-   * clears pending fields.
-   */
-  activatePending(): void;
-  /**
-   * Transition deferred → pending. Called when a continuation turn
-   * completes and there's a deferred follow-up waiting.
-   *
-   * Returns the new pending state (so the host can enqueue the turn),
-   * or null if there was nothing deferred.
-   */
-  activateDeferred(
-    generateRequestId: () => string
-  ): 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, probeId?: string): 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
+declare const CHAT_RECOVERY_INCIDENT_TTL_MS: number;
+/** Max keys per Durable Object KV `delete([...])` call. */
+declare const KV_DELETE_MAX_KEYS = 128;
 /**
- * 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).
+ * 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.
  */
-interface ContinuationSpec<
-  TConnection extends ContinuationConnection = ContinuationConnection
-> {
-  connection: TConnection;
-  clientTools: ClientToolSchema[] | undefined;
-  body: Record<string, unknown> | undefined;
-  errorPrefix: string;
-}
+declare const DEFAULT_CHAT_RECOVERY_NO_PROGRESS_TIMEOUT_MS: number;
 /**
- * Host substrate the controller parameterizes over. Implemented by the agent
- * (typically via a small adapter object capturing `this`).
+ * 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.
  */
-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
+declare const CHAT_RECOVERY_ALARM_DEBOUNCE_MS: number;
 /**
- * AbortRegistry — manages per-request AbortControllers.
- *
- * Shared between AIChatAgent and Think for chat turn cancellation.
- * Each request gets its own AbortController keyed by request ID.
- * Controllers are created lazily on first signal access.
- */
-declare class AbortRegistry {
-  private controllers;
-  /**
-   * Get or create an AbortController for the given ID and return its signal.
-   * Creates the controller lazily on first access.
-   */
-  getSignal(id: string): AbortSignal | undefined;
-  /**
-   * Get the signal for an existing controller without creating one.
-   * Returns undefined if no controller exists for this ID.
-   */
-  getExistingSignal(id: string): AbortSignal | undefined;
-  /**
-   * Cancel a specific request by aborting its controller. Optionally
-   * propagate a reason — surfaces as `signal.reason` on the registry's
-   * controller and through any `AbortError` it produces downstream.
-   */
-  cancel(id: string, reason?: unknown): void;
-  /** Remove a controller after the request completes. */
-  remove(id: string): void;
-  /**
-   * Abort all pending requests and clear the registry. Optionally propagate a
-   * reason — surfaces as `signal.reason` on each controller and through any
-   * `AbortError` it produces downstream, exactly like {@link cancel}.
-   */
-  destroyAll(reason?: unknown): void;
-  /** Check if a controller exists for the given ID. */
-  has(id: string): boolean;
-  /** Number of tracked controllers. */
-  get size(): number;
-  /**
-   * Link an external `AbortSignal` to the controller for `id`. When the
-   * external signal aborts, the registry's controller is cancelled —
-   * propagating the abort reason — exactly the same way an internal
-   * cancel would (e.g. via a `chat-request-cancel` WebSocket message).
-   *
-   * This is the integration point for callers that drive a chat turn
-   * programmatically and want to cancel it from outside without knowing
-   * the internally-generated request id (e.g. the helper-as-sub-agent
-   * pattern, where a parent's `AbortSignal` from the AI SDK tool
-   * `execute` needs to land inside a `Think.saveMessages` call running
-   * on a child DO).
-   *
-   * Behavior:
-   *
-   * - Passing `undefined` is a no-op and returns a no-op detacher, so
-   *   callers can unconditionally call this with `options?.signal`.
-   * - If the external signal is already aborted, the registry's
-   *   controller is created (if needed) and cancelled synchronously.
-   * - Otherwise a one-shot `abort` listener is attached. The returned
-   *   function detaches it.
-   *
-   * **Always call the returned detacher in a `finally` block** — the
-   * external signal may outlive the request (a parent chat turn that
-   * drives many helper turns reuses one signal across all of them) and
-   * leaving listeners attached pins closures and grows the listener
-   * list on each turn.
-   *
-   * @returns A detacher function. Call it after the request finishes
-   *   (success or failure) to remove the abort listener from `signal`.
-   */
-  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`.
+ * 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;
 /**
- * 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.
+ * Resolve a raw `chatRecovery` config field into the fully-defaulted form the
+ * engine reasons about. Durable recovery is always enabled; a legacy runtime
+ * `false` value from previously compiled JavaScript safely receives defaults.
  */
-declare const TIMED_OUT: unique symbol;
+declare function resolveChatRecoveryConfig(
+  raw: ChatRecoveryConfig | undefined
+): ResolvedChatRecoveryConfig;
 /**
- * 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.
+ * 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 awaitWithDeadline<T>(
-  promise: Promise<T>,
-  deadline: number | null
-): Promise<T | typeof TIMED_OUT>;
+declare function sweepStaleChatRecoveryIncidents(
+  storage: Pick<DurableObjectStorage, "list" | "delete">,
+  now: number
+): Promise<void>;
 /**
- * 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.
+ * 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 drainInteractionApplies(
-  hasPending: () => boolean,
-  getTail: () => Promise<unknown>
-): Promise<void>;
-//#endregion
-//#region src/chat/tool-state.d.ts
+declare function listActiveChatRecoveryIncidents(
+  storage: Pick<DurableObjectStorage, "list">
+): Promise<
+  {
+    key: string;
+    incident: ChatRecoveryIncident;
+  }[]
+>;
 /**
- * Tool State — shared update builders and applicator for tool part state changes.
- *
- * Used by both AIChatAgent and Think to apply tool results and approvals
- * to message parts. Each agent handles find-message, persist, and broadcast
- * in their own way; this module provides the state matching and update logic.
+ * 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">;
 /**
- * Describes an update to apply to a tool part.
+ * Read the durable monotonic recovery-progress counter (0 when unset). The value
+ * feeds the no-progress budget decision; shared by `AIChatAgent` and `Think`.
  */
-type ToolPartUpdate = {
-  toolCallId: string;
-  matchStates: string[];
-  apply: (part: Record<string, unknown>) => Record<string, unknown>;
-};
+declare function readChatRecoveryProgress(
+  storage: Pick<DurableObjectStorage, "get">
+): Promise<number>;
 /**
- * Apply a tool part update to a parts array.
- * Finds the first part matching `update.toolCallId` in one of `update.matchStates`,
- * applies the update immutably, and returns the new parts array with the index.
+ * Advance the KV progress counter by one.
  *
- * Returns `null` if no matching part was found.
+ * @deprecated Hosts no longer bump a counter per credited chunk: the marker
+ * is derived from the stream log (`ResumableStream.progressMarker`) and
+ * explicit credits go through `ResumableStream.creditProgress`. Kept for
+ * code that still maintains the KV counter; a value written here is folded
+ * into the derived marker on the next seed.
  */
-declare function applyToolUpdate(
-  parts: Array<Record<string, unknown>>,
-  update: ToolPartUpdate
-): {
-  parts: Array<Record<string, unknown>>;
-  index: number;
-} | null;
+declare function bumpChatRecoveryProgress(
+  storage: Pick<DurableObjectStorage, "get" | "put">
+): Promise<void>;
 /**
- * Build an update descriptor for applying a tool result.
- *
- * Matches parts in `input-available`, `approval-requested`, or `approval-responded` state.
- * Sets state to `output-available` (with output) or `output-error` (with errorText).
+ * 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 function toolResultUpdate(
-  toolCallId: string,
-  output: unknown,
-  overrideState?: "output-error",
-  errorText?: string
-): ToolPartUpdate;
+declare const AGENT_TOOL_STREAM_PROGRESS_BUMP_THROTTLE_MS = 5000;
 /**
- * Build an update descriptor for a terminal tool result that belongs to a
- * tool part in a *different* (earlier) assistant message than the one
- * currently being streamed.
- *
- * This is the "cross-message" case: an approved server tool executes during a
- * continuation stream, but its tool part lives in the assistant message that
- * originally requested it. `StreamAccumulator` surfaces this as a
- * `cross-message-tool-update` action because the accumulator only owns the
- * current turn's new content and cannot mutate a part from a prior message.
- *
- * Compared to {@link toolResultUpdate} this builder is deliberately more
- * defensive, mirroring the equivalent fallback in `@cloudflare/ai-chat`:
- *
- * - It matches the broad set of pre-terminal **and** terminal states, so a
- *   provider that replays the entire prior tool round-trip during a
- *   continuation (notably the OpenAI Responses API — issue #1404) still
- *   resolves to the same part instead of silently missing it.
- * - It is **first-write-wins**: a chunk arriving for a tool that already holds
- *   a terminal result is treated as a replay and the existing output is never
- *   overwritten. In that case `apply` returns the *same part reference*, which
- *   callers use as an idempotent-no-op signal to skip the durable write and a
- *   redundant `MESSAGE_UPDATED` broadcast.
- * - It preserves a streamed `preliminary` flag when one is present, otherwise
- *   marks the result final (`preliminary: false`).
+ * 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 function crossMessageToolResultUpdate(
-  toolCallId: string,
-  updateType: "output-available" | "output-error",
-  output?: unknown,
-  errorText?: string,
-  preliminary?: boolean
-): ToolPartUpdate;
+declare class AgentToolStreamProgressThrottle {
+  private _lastBumpAt;
+  shouldCredit(now: number): boolean;
+}
 /**
- * Build an update descriptor that replaces the output of a *paused durable
- * execution* tool part (e.g. a codemode runtime tool that paused for
- * approval).
- *
- * A paused execution completes its tool call normally — the part is already
- * `output-available` with an output of `{ status: "paused", executionId }`.
- * When the host later approves/rejects the execution, the new outcome
- * (completed / rejected / paused-again) must replace that output in place.
- *
- * Matching is deliberately narrow and idempotent:
- *
- * - only `output-available` parts are considered;
- * - the existing output must be a paused-execution object carrying the same
- *   `executionId` — anything else (already replaced, different execution)
- *   returns the *same part reference*, which callers treat as a no-op signal
- *   (skip persist + broadcast), mirroring {@link crossMessageToolResultUpdate}.
+ * 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 function pausedExecutionUpdate(
-  toolCallId: string,
-  executionId: string,
-  output: unknown
-): ToolPartUpdate;
+declare const CHAT_STREAM_PROGRESS_CREDIT_THROTTLE_MS = 5000;
 /**
- * Build an update descriptor for applying a tool approval.
- *
- * Matches parts in `input-available` or `approval-requested` state.
- * Sets state to `approval-responded` (if approved) or `output-denied` (if denied).
+ * 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 function toolApprovalUpdate(
-  toolCallId: string,
-  approved: boolean
-): ToolPartUpdate;
-/** A minimal message shape for the leaf tool/interaction scans. */
-type ToolBatchMessage = {
-  role: string;
-  parts: ReadonlyArray<unknown>;
+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;
 };
-/** 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.
+ * 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 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
+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>;
 /**
- * Protocol Message Parser — typed parsing of cf_agent_chat_* WebSocket messages.
- *
- * Parses raw WebSocket messages into a discriminated union of protocol events.
- * Both AIChatAgent and Think can use this instead of manual JSON.parse + type checking.
+ * 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>;
 /**
- * Discriminated union of all incoming chat protocol events.
- *
- * Each agent handles the events it cares about and ignores the rest.
- * Returns `null` for non-JSON messages or unrecognized types.
+ * 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.
  */
-type ChatProtocolEvent =
-  | {
-      type: "chat-request";
-      id: string;
-      init: {
-        method?: string;
-        body?: string;
-        [key: string]: unknown;
-      };
-    }
-  | {
-      type: "clear";
-    }
-  | {
-      type: "cancel";
-      id: string;
-    }
-  | {
-      type: "tool-result";
-      toolCallId: string;
-      toolName: string;
-      output: unknown;
-      state?: string;
-      errorText?: string;
-      autoContinue?: boolean;
-      clientTools?: Array<{
-        name: string;
-        description?: string;
-        parameters?: unknown;
-      }>;
-    }
-  | {
-      type: "tool-approval";
-      toolCallId: string;
-      approved: boolean;
-      autoContinue?: boolean;
-    }
-  | {
-      type: "stream-resume-request";
-      probeId?: string;
-    }
-  | {
-      type: "stream-resume-ack";
-      id: string;
-    }
-  | {
-      type: "messages";
-      messages: unknown[];
-    };
+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>;
 /**
- * Parse a raw WebSocket message string into a typed protocol event.
- *
- * Returns `null` if the message is not valid JSON or not a recognized
- * protocol message type. Callers should fall through to the user's
- * `onMessage` handler when `null` is returned.
- *
- * @example
- * ```typescript
- * const event = parseProtocolMessage(rawMessage);
- * if (!event) return userOnMessage(connection, rawMessage);
- *
- * switch (event.type) {
- *   case "chat-request": { ... }
- *   case "clear": { ... }
- *   case "tool-result": { ... }
- * }
- * ```
+ * 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.
  */
-declare function parseProtocolMessage(raw: string): ChatProtocolEvent | null;
+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/message-reconciler.d.ts
+//#region src/chat/recovery-engine.d.ts
+/** The scheduled-callback entrypoints a recovery schedule can target. */
+type ChatRecoveryScheduleCallback =
+  | "_chatRecoveryContinue"
+  | "_chatRecoveryRetry";
 /**
- * Reconcile incoming client messages against server state.
+ * Why a recovery callback is being scheduled. The idempotency of the
+ * underlying Task run's `idempotencyKey` depends ONLY on this:
  *
- * 1. Merges server-known tool outputs into incoming messages that still
- *    show stale states (input-available, approval-requested, approval-responded)
- * 2. Reconciles assistant IDs: exact match → content-key match → toolCallId match
+ * - `"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.
  *
- * @param incoming - Messages from the client
- * @param serverMessages - Current server-side messages (source of truth)
- * @param sanitizeForContentKey - Function to sanitize a message before computing
- *   its content key (typically strips ephemeral provider metadata)
- * @returns Reconciled messages ready for persistence
+ * - `"stable_timeout_retry"` — a reschedule issued from INSIDE the currently-
+ *   executing recovery attempt (a continuation that timed out waiting for
+ *   stable state). That attempt — a `__cf_internal_chat_recovery` Task run —
+ *   settles only AFTER the callback returns, so an idempotent reschedule would
+ *   dedup onto the doomed attempt and settle with it — the retry would never
+ *   fire. A fresh (non-idempotent) delayed attempt survives.
  */
-declare function reconcileMessages(
-  incoming: UIMessage[],
-  serverMessages: readonly UIMessage[],
-  sanitizeForContentKey?: (message: UIMessage) => UIMessage
-): UIMessage[];
+type ChatRecoveryScheduleReason = "initial" | "stable_timeout_retry";
 /**
- * For a single message, resolve its ID by matching toolCallId against server state.
- * Prevents duplicate DB rows when client IDs differ from server IDs.
- * Tool call IDs are unique per conversation, so matching is safe regardless of state.
+ * 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).
  */
-declare function resolveToolMergeId(
-  message: UIMessage,
-  serverMessages: readonly UIMessage[]
-): UIMessage;
-/**
- * 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 reconcileOrphanPartial(
-  existing: UIMessage,
-  incoming: UIMessage
-): UIMessage;
-//#endregion
-//#region src/chat/repair-transcript.d.ts
+type RecoveryPartial = {
+  text: string;
+  parts: unknown[];
+  hasSettledToolResults: boolean;
+};
+/** Lifecycle status of a recovered stream's metadata row. */
+type ChatStreamStatus = "streaming" | "completed" | "error";
+/** 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;
+}
 /**
- * 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.
+ * 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.
  */
-declare function toolPartHasSettledResult(
-  record: Record<string, unknown>
-): boolean;
-interface RepairInterruptedToolPartsOptions {
+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>;
   /**
-   * 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.
+   * 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.
    */
-  repairPart: (part: UIMessage["parts"][number]) => UIMessage["parts"][number];
+  ensureInteractionStateLoaded?(): void;
   /**
-   * Whether a tool part already carries a settled result (defaults to
-   * {@link toolPartHasSettledResult}).
+   * 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.
    */
-  isSettled?: (record: Record<string, unknown>) => boolean;
+  tryHandleNonChatFiberRecovery?(ctx: FiberRecoveryContext$1): Promise<boolean>;
+  /** Monotonic forward-progress marker for the no-progress budget. */
+  readProgress(): Promise<number>;
   /**
-   * Normalize a tool part's `input` (defaults to the shared
-   * {@link normalizeToolInput}).
+   * 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`).
    */
-  normalizeInput?: (input: unknown) => {
-    input: unknown;
-    changed: boolean;
-  };
+  isAwaitingClientInteraction?(): boolean;
+  /** Persist the evaluated incident under `key`. */
+  putIncident(key: string, incident: ChatRecoveryIncident): Promise<void>;
   /**
-   * 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`.
+   * 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).
    */
-  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>;
+  deleteIncident(key: string): Promise<void>;
+  /** Broadcast a lifecycle event produced by the evaluation or a transition. */
+  emitRecoveryEvent(event: ChatRecoveryIncidentEvent): void;
   /**
-   * Append a new message. `parentId` is honored by tree-structured stores
-   * (`undefined` → attach to the latest leaf); flat-array stores ignore it.
+   * Enqueue a recovery callback. The engine owns the surrounding orchestration
+   * and the package chooses its durable transport: a Task for a root chat agent,
+   * or the temporary routed-schedule fallback for a dynamic agent. `reason`
+   * selects deduplication and `delaySeconds` is `0` initially or the stable
+   * retry delay for a chained attempt.
    */
-  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>;
+  scheduleRecovery(
+    callback: ChatRecoveryScheduleCallback,
+    data: Record<string, unknown>,
+    reason: ChatRecoveryScheduleReason,
+    delaySeconds: number
+  ): Promise<void>;
   /**
-   * Id for the reconstructed message when the stream carried no provider
-   * `start.messageId` to adopt. The accumulator still adopts a provider id when
-   * present.
+   * 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.
    */
-  fallbackId: string;
+  setRecovering(active: boolean, requestId?: string): Promise<void>;
   /**
-   * 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).
+   * 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).
    */
-  prepare: (message: TMessage) => TMessage | null;
+  onShouldKeepRecoveringError?(error: unknown): void;
   /**
-   * Combine an existing row with the reconstructed message when a row already
-   * owns the id (replace, or reconcile partials).
+   * 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).
    */
-  merge: (existing: TMessage, incoming: TMessage) => TMessage;
+  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;
 }
-/**
- * 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;
+/** 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;
 }
-type ChatFiberSnapshot<Kind extends string = string> = {
-  kind: Kind;
-  version: 1;
+/** Input to {@link ChatFiberWakeHooks.classifyRecoveredTurn}. */
+interface ClassifyRecoveredTurnInput {
+  snapshot: ChatFiberSnapshot | null;
   requestId: string;
-  recoveryRootRequestId?: string;
-  continuation: boolean;
-  latestMessageId?: string;
-  latestMessageRole?: string;
-  latestUserMessageId?: string;
-  startedAt: number;
-  lastBody?: Record<string, unknown>;
-  lastClientTools?: ClientToolSchema[];
-};
-declare function createChatFiberSnapshot<Kind extends string>({
-  kind,
-  requestId,
-  recoveryRootRequestId,
-  continuation,
-  messages,
-  lastBody,
-  lastClientTools
-}: {
-  kind: Kind;
+  streamId: string;
+  partial: RecoveryPartial;
+  streamStillActive: boolean;
+  streamStatus?: ChatStreamStatus;
+}
+/** Input to {@link ChatFiberWakeHooks.invokeOnChatRecovery}. */
+interface InvokeOnChatRecoveryInput {
+  incident: ChatRecoveryIncident;
+  recoveryKind: ChatRecoveryKind;
+  recoveryRootRequestId: string;
   requestId: string;
-  recoveryRootRequestId?: string;
-  continuation: boolean;
-  messages: ReadonlyArray<SnapshotMessage>;
-  lastBody?: Record<string, unknown>;
-  lastClientTools?: ClientToolSchema[];
-}): ChatFiberSnapshot<Kind>;
-declare function wrapChatFiberSnapshot<Kind extends string>(
-  key: string,
-  snapshot: ChatFiberSnapshot<Kind>,
-  user: unknown | null
-): Record<string, unknown>;
-declare function unwrapChatFiberSnapshot<Kind extends string>(
-  key: string,
-  value: unknown,
-  expectedKind?: Kind
-): {
-  snapshot: ChatFiberSnapshot<Kind> | null;
-  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";
+  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;
+}
 /**
- * Durable per-incident recovery record.
+ * 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.
  *
- * 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.
+ * 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.
  */
-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;
+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$1): {
+    snapshot: ChatFiberSnapshot | null;
+    recoveryData: unknown;
+  };
   /**
-   * 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`.
+   * 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.
    */
-  lastProgressAt?: number;
-  reason?: string;
+  classifyRecoveredTurn(input: ClassifyRecoveredTurnInput):
+    | {
+        recoveryKind: ChatRecoveryKind;
+        detail: TClassify;
+      }
+    | Promise<{
+        recoveryKind: ChatRecoveryKind;
+        detail: TClassify;
+      }>;
   /**
-   * 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).
+   * 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 (`{}`).
    */
-  progress?: number;
+  invokeOnChatRecovery?(
+    input: InvokeOnChatRecoveryInput
+  ): Promise<ChatRecoveryOptions | void>;
   /**
-   * 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.
+   * 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.
    */
-  workBaseline?: number;
+  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>;
   /**
-   * 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.
+   * 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.
    */
-  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";
+  dispatchRecoveredTurn(
+    input: DispatchRecoveredTurnInput<TClassify>
+  ): Promise<void>;
+}
 /**
- * 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).
+ * 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 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.
+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$1): 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$1,
+    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 transport — a Task run on
+   *    a root agent, an idempotent schedule on the routed fallback.
+   *
+   * `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, from INSIDE the currently-executing recovery attempt (a
+   * `__cf_internal_chat_recovery` Task run for a root agent, the routed
+   * one-shot schedule row for a dynamic agent). Reads the
+   * incident; if it is still under the attempt cap, bumps `attempt`, marks it
+   * `scheduled` with `reason:"stable_timeout_retry"`, and issues a separate
+   * delayed attempt. It must not join the currently executing attempt: Tasks
+   * enqueue an unkeyed chained run, while the routed fallback creates a
+   * non-idempotent schedule.
+   *
+   * 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 attempt settles
+   *    only after the callback returns, so an idempotent reschedule would
+   *    dedup onto that doomed attempt) 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
+   *    the current recovery attempt (a Task run on a root agent, a one-shot
+   *    schedule row on the routed fallback) defers 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-task.d.ts
+/** Reserved Task definition shared by the chat hosts. */
+declare const CHAT_RECOVERY_TASK_NAME = "__cf_internal_chat_recovery";
+/** Input persisted for one recovery continuation attempt. */
+type ChatRecoveryTaskInput = {
+  /** Host continuation to dispatch. */ readonly callback: ChatRecoveryScheduleCallback /** Continuation context owned by the chat host. */;
+  readonly data: Record<
+    string,
+    unknown
+  > /** Durable delay before dispatch, in seconds. */;
+  readonly delaySeconds: number;
+};
+/** Why a recovery attempt is being enqueued. */
+type ChatRecoveryTaskReason = "initial" | "stable_timeout_retry" | "redefer";
+/** The host's bounded entry point for each continuation callback. */
+type ChatRecoveryTaskHooks = Record<
+  ChatRecoveryScheduleCallback,
+  (data: Record<string, unknown>) => Promise<void>
+>;
+/** How a bounded recovery callback hands its model turn to the alarm domain. */
+type ChatRecoveryHandoff = {
+  /**
+   * Start the detached continuation. It calls `onTurnStarted` once the model
+   * turn begins — the point after which the bounded callback returns.
+   */
+  readonly detached: (
+    onTurnStarted: () => void
+  ) => Promise<void> /** Keep the detached turn inside the current alarm's breaker domain. */;
+  readonly track: (turn: Promise<void>) => void;
+  /**
+   * Enqueue exactly one replacement attempt for a detached platform
+   * failure. `dedupeKey` is stable across every retried call for the same
+   * failure (see {@link dispatchChatRecoveryToHandoff}): acceptance may
+   * throw after already durably creating the run — most likely on the
+   * wake-mirror push, not the run insert itself — so a naive retry of an
+   * unkeyed enqueue risks creating another one. Pass it straight through as
+   * the run's `runId` so a retry joins that same row instead.
+   */
+  readonly redefer: (
+    dedupeKey: string
+  ) => Promise<void> /** Report a detached failure the turn's own bookkeeping already handled. */;
+  readonly onDetachedError: (error: unknown) => void;
+};
+/**
+ * Run a queue-driven recovery callback up to its model handoff, then return.
+ *
+ * The recovered turn can legitimately run for a long time, and awaiting it
+ * would hold the Lifecycle job loop, starving every other job on the object.
+ * A failure before the handoff rejects here, so the executing Task run (or
+ * compatibility schedule row) keeps ownership and the driver's
+ * platform-failure deferral applies (#1730). After the handoff the turn is
+ * detached alarm work: a platform failure enqueues one replacement attempt,
+ * retried a few times since the completed Task no longer owns this incident
+ * and a failure here would otherwise abandon it silently, and any other
+ * failure belongs to the turn's own incident bookkeeping.
+ */
+declare function dispatchChatRecoveryToHandoff(
+  handoff: ChatRecoveryHandoff
+): Promise<void>;
+/**
+ * Build run options for one recovery attempt.
+ *
+ * Initial detection joins an existing in-flight attempt for the same incident
+ * and callback. Chained retries are otherwise unkeyed because each one is
+ * enqueued while the preceding run still exists — a genuinely new attempt,
+ * not a retry of this same enqueue. `dedupeKey`, when supplied, keys this
+ * specific enqueue call by `runId` instead: every retry of one failed
+ * `redefer` (see {@link dispatchChatRecoveryToHandoff}) reuses the same key,
+ * so a rejected-but-already-inserted attempt is joined rather than
+ * duplicated. Non-retention releases the initial key when the run settles.
+ */
+declare function chatRecoveryTaskRunOptions(
+  input: ChatRecoveryTaskInput,
+  reason: ChatRecoveryTaskReason,
+  dedupeKey?: string
+): TaskRunOptions;
+/** Build the shared recovery Task handler for one chat host. */
+declare function createChatRecoveryTaskDefinition(
+  hooks: ChatRecoveryTaskHooks
+): (input: unknown, step: TaskStep) => Promise<void>;
+//#endregion
+//#region src/chat/sql-batch.d.ts
+/**
+ * Helpers for building batched SQLite statements that run through the Agent's
+ * `sql` tagged template (which interleaves a `?` placeholder between every
+ * string fragment). Used to collapse per-row INSERT/DELETE loops into a small
+ * number of multi-row statements.
+ *
+ * SQLite (Durable Object / D1) caps bound parameters at 100 per query, so
+ * callers must chunk their inputs to stay within {@link MAX_BOUND_PARAMS}.
+ * See https://developers.cloudflare.com/d1/platform/limits/
+ */
+/** Maximum bound parameters allowed in a single SQLite (DO / D1) query. */
+declare const MAX_BOUND_PARAMS = 100;
+/**
+ * Build a TemplateStringsArray for a single-column `IN (...)` clause. Produces
+ * fragments for:
+ *   `${prefix}(?, ?, ...)`
+ *
+ * @throws if `count` is less than 1.
+ */
+declare function buildInClauseStrings(
+  prefix: string,
+  count: number
+): TemplateStringsArray;
+//#endregion
+//#region src/chat/protocol.d.ts
+/**
+ * Wire protocol message type constants for the cf_agent_chat_* protocol.
+ *
+ * These are the string values used on the wire between agent servers and
+ * clients. Both @cloudflare/ai-chat (via its MessageType enum) and
+ * @cloudflare/think use these values.
+ */
+declare const STREAM_RESUME_NONE_REASONS: {
+  /** No active, pending, or terminal stream exists for this agent. */ readonly IDLE: "idle" /** An active tool continuation is owned by another live connection. */;
+  readonly CONTINUATION_OWNED: "continuation-owned";
+};
+type StreamResumeNoneReason =
+  (typeof STREAM_RESUME_NONE_REASONS)[keyof typeof STREAM_RESUME_NONE_REASONS];
+declare const CHAT_MESSAGE_TYPES: {
+  readonly CHAT_MESSAGES: "cf_agent_chat_messages";
+  readonly USE_CHAT_REQUEST: "cf_agent_use_chat_request";
+  readonly USE_CHAT_RESPONSE: "cf_agent_use_chat_response";
+  readonly CHAT_CLEAR: "cf_agent_chat_clear";
+  readonly CHAT_REQUEST_CANCEL: "cf_agent_chat_request_cancel";
+  readonly STREAM_RESUMING: "cf_agent_stream_resuming";
+  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/wire-types.d.ts
+/**
+ * Enum for message types to improve type safety and maintainability
+ */
+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 /** Present when this offer directly answers a client resume probe. */;
+      probeId?: 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 a resume request with no stream for this client. */ type: MessageType.CF_AGENT_STREAM_RESUME_NONE;
+      /**
+       * Why no stream was offered. Only `idle` proves global inactivity;
+       * omitted by older servers and by non-authoritative delayed releases.
+       */
+      reason?: StreamResumeNoneReason /** Correlates an authoritative response to its client resume probe. */;
+      probeId?: string;
+    }
+  | {
+      /**
+       * 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 /** Correlates a direct keep-waiting response to its client probe. */;
+      probeId?: 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 /** Opaque correlation id echoed by direct server responses. */;
+      probeId?: string;
+    }
+  | {
+      /** 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.
  *
- * 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.
+ * `@internal` — sibling-package support for `@cloudflare/ai-chat` and
+ * `@cloudflare/think`, not a public API. See
+ * `design/rfc-chat-recovery-foundation.md`.
  *
- * 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.
+ * Both packages (and `continuation-state`) hand-maintained byte-identical
+ * copies of `sendIfOpen` / `isWebSocketClosedSendError`; this is the single
+ * shared implementation.
  */
-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.
+ * 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.
  */
-declare const CHAT_RECOVERING_FLAG_TTL_MS: number;
+interface ChatConnection {
+  readonly id: string;
+  send(message: string): void;
+}
 /**
- * Resolve a raw `chatRecovery` config field into the fully-defaulted form the
- * engine reasons about. Durable recovery is always enabled; a legacy runtime
- * `false` value from previously compiled JavaScript safely receives defaults.
+ * 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 resolveChatRecoveryConfig(
-  raw: ChatRecoveryConfig | undefined
-): ResolvedChatRecoveryConfig;
+declare function sendIfOpen(
+  connection: ChatConnection,
+  message: string
+): boolean;
+//#endregion
+//#region src/chat/continuation-state.d.ts
 /**
- * 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`.
+ * 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.
  */
-declare function sweepStaleChatRecoveryIncidents(
-  storage: Pick<DurableObjectStorage, "list" | "delete">,
-  now: number
-): Promise<void>;
+type ContinuationConnection = ChatConnection;
+interface ContinuationPending<
+  TConnection extends ContinuationConnection = ContinuationConnection
+> {
+  connection: TConnection;
+  connectionId: string | null;
+  requestId: string;
+  clientTools?: ClientToolSchema[];
+  body?: Record<string, unknown>;
+  errorPrefix: string | null;
+  prerequisite: Promise<boolean> | null;
+  pastCoalesce: boolean;
+}
+interface ContinuationDeferred<
+  TConnection extends ContinuationConnection = ContinuationConnection
+> {
+  connection: TConnection;
+  connectionId: string | null;
+  clientTools?: ClientToolSchema[];
+  body?: Record<string, unknown>;
+  errorPrefix: string;
+  prerequisite: Promise<boolean> | null;
+}
+declare class ContinuationState<
+  TConnection extends ContinuationConnection = ContinuationConnection
+> {
+  pending: ContinuationPending<TConnection> | null;
+  deferred: ContinuationDeferred<TConnection> | null;
+  activeRequestId: string | null;
+  activeConnectionId: string | null;
+  awaitingConnections: Map<string, TConnection>;
+  /** Clear pending state and awaiting connections (without sending RESUME_NONE). */
+  clearPending(): void;
+  clearDeferred(): void;
+  clearAll(): void;
+  /**
+   * Mark a connection as no longer available without canceling the
+   * continuation it initiated.
+   */
+  releaseConnection(connectionId: string): void;
+  /**
+   * Send STREAM_RESUME_NONE to all connections waiting for a
+   * continuation stream to start, then clear the map.
+   */
+  sendResumeNone(): void;
+  /**
+   * Flush awaiting connections by notifying each one via the provided
+   * callback (typically sends STREAM_RESUMING), then clear.
+   */
+  flushAwaitingConnections(notify: (conn: TConnection) => void): void;
+  /**
+   * Transition pending → active. Called when the continuation stream
+   * actually starts. Moves request/connection IDs to active slots,
+   * clears pending fields.
+   */
+  activatePending(): void;
+  /**
+   * Transition deferred → pending. Called when a continuation turn
+   * completes and there's a deferred follow-up waiting.
+   *
+   * Returns the new pending state (so the host can enqueue the turn),
+   * or null if there was nothing deferred.
+   */
+  activateDeferred(
+    generateRequestId: () => string
+  ): 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, probeId?: string): 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
 /**
- * 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.
+ * 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).
  */
-declare function listActiveChatRecoveryIncidents(
-  storage: Pick<DurableObjectStorage, "list">
-): Promise<
-  {
-    key: string;
-    incident: ChatRecoveryIncident;
-  }[]
->;
+interface ContinuationSpec<
+  TConnection extends ContinuationConnection = ContinuationConnection
+> {
+  connection: TConnection;
+  clientTools: ClientToolSchema[] | undefined;
+  body: Record<string, unknown> | undefined;
+  errorPrefix: string;
+}
 /**
- * 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`.
+ * Host substrate the controller parameterizes over. Implemented by the agent
+ * (typically via a small adapter object capturing `this`).
  */
-declare function classifyAgentToolChildRecovery(
-  storage: Pick<DurableObjectStorage, "list">
-): Promise<"in-progress" | "failed" | "none">;
+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
 /**
- * Read the durable monotonic recovery-progress counter (0 when unset). The value
- * feeds the no-progress budget decision; shared by `AIChatAgent` and `Think`.
+ * AbortRegistry — manages per-request AbortControllers.
+ *
+ * Shared between AIChatAgent and Think for chat turn cancellation.
+ * Each request gets its own AbortController keyed by request ID.
+ * Controllers are created lazily on first signal access.
  */
-declare function readChatRecoveryProgress(
-  storage: Pick<DurableObjectStorage, "get">
-): Promise<number>;
+declare class AbortRegistry {
+  private controllers;
+  /**
+   * Get or create an AbortController for the given ID and return its signal.
+   * Creates the controller lazily on first access.
+   */
+  getSignal(id: string): AbortSignal | undefined;
+  /**
+   * Get the signal for an existing controller without creating one.
+   * Returns undefined if no controller exists for this ID.
+   */
+  getExistingSignal(id: string): AbortSignal | undefined;
+  /**
+   * Cancel a specific request by aborting its controller. Optionally
+   * propagate a reason — surfaces as `signal.reason` on the registry's
+   * controller and through any `AbortError` it produces downstream.
+   */
+  cancel(id: string, reason?: unknown): void;
+  /** Remove a controller after the request completes. */
+  remove(id: string): void;
+  /**
+   * Abort all pending requests and clear the registry. Optionally propagate a
+   * reason — surfaces as `signal.reason` on each controller and through any
+   * `AbortError` it produces downstream, exactly like {@link cancel}.
+   */
+  destroyAll(reason?: unknown): void;
+  /** Check if a controller exists for the given ID. */
+  has(id: string): boolean;
+  /** Number of tracked controllers. */
+  get size(): number;
+  /**
+   * Link an external `AbortSignal` to the controller for `id`. When the
+   * external signal aborts, the registry's controller is cancelled —
+   * propagating the abort reason — exactly the same way an internal
+   * cancel would (e.g. via a `chat-request-cancel` WebSocket message).
+   *
+   * This is the integration point for callers that drive a chat turn
+   * programmatically and want to cancel it from outside without knowing
+   * the internally-generated request id (e.g. the helper-as-sub-agent
+   * pattern, where a parent's `AbortSignal` from the AI SDK tool
+   * `execute` needs to land inside a `Think.saveMessages` call running
+   * on a child DO).
+   *
+   * Behavior:
+   *
+   * - Passing `undefined` is a no-op and returns a no-op detacher, so
+   *   callers can unconditionally call this with `options?.signal`.
+   * - If the external signal is already aborted, the registry's
+   *   controller is created (if needed) and cancelled synchronously.
+   * - Otherwise a one-shot `abort` listener is attached. The returned
+   *   function detaches it.
+   *
+   * **Always call the returned detacher in a `finally` block** — the
+   * external signal may outlive the request (a parent chat turn that
+   * drives many helper turns reuses one signal across all of them) and
+   * leaving listeners attached pins closures and grows the listener
+   * list on each turn.
+   *
+   * @returns A detacher function. Call it after the request finishes
+   *   (success or failure) to remove the abort listener from `signal`.
+   */
+  linkExternal(id: string, signal: AbortSignal | undefined): () => void;
+}
+//#endregion
+//#region src/chat/async-helpers.d.ts
 /**
- * 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`.
+ * @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`.
  */
-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.
+ * 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 AGENT_TOOL_STREAM_PROGRESS_BUMP_THROTTLE_MS = 5000;
+declare const TIMED_OUT: unique symbol;
 /**
- * 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`.
+ * 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 class AgentToolStreamProgressThrottle {
-  private _lastBumpAt;
-  shouldCredit(now: number): boolean;
-}
+declare function awaitWithDeadline<T>(
+  promise: Promise<T>,
+  deadline: number | null
+): Promise<T | typeof TIMED_OUT>;
 /**
- * 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.
+ * 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.
+ *
+ * Used by both AIChatAgent and Think to apply tool results and approvals
+ * to message parts. Each agent handles find-message, persist, and broadcast
+ * in their own way; this module provides the state matching and update logic.
  */
-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`.
+ * Describes an update to apply to a tool part.
  */
-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;
+type ToolPartUpdate = {
+  toolCallId: string;
+  matchStates: string[];
+  apply: (part: Record<string, unknown>) => Record<string, unknown>;
 };
 /**
- * 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.
+ * Apply a tool part update to a parts array.
+ * Finds the first part matching `update.toolCallId` in one of `update.matchStates`,
+ * applies the update immutably, and returns the new parts array with the index.
+ *
+ * Returns `null` if no matching part was found.
  */
-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>;
+declare function applyToolUpdate(
+  parts: Array<Record<string, unknown>>,
+  update: ToolPartUpdate
+): {
+  parts: Array<Record<string, unknown>>;
+  index: number;
+} | 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.
+ * Build an update descriptor for applying a tool result.
+ *
+ * Matches parts in `input-available`, `approval-requested`, or `approval-responded` state.
+ * Sets state to `output-available` (with output) or `output-error` (with errorText).
  */
-declare function buildChatRecoveringFrame(
-  storage: Pick<DurableObjectStorage, "get">,
-  messageType: string,
-  now: number
-): Promise<Record<string, unknown> | null>;
+declare function toolResultUpdate(
+  toolCallId: string,
+  output: unknown,
+  overrideState?: "output-error",
+  errorText?: string
+): ToolPartUpdate;
 /**
- * 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.
+ * Build an update descriptor for a terminal tool result that belongs to a
+ * tool part in a *different* (earlier) assistant message than the one
+ * currently being streamed.
+ *
+ * This is the "cross-message" case: an approved server tool executes during a
+ * continuation stream, but its tool part lives in the assistant message that
+ * originally requested it. `StreamAccumulator` surfaces this as a
+ * `cross-message-tool-update` action because the accumulator only owns the
+ * current turn's new content and cannot mutate a part from a prior message.
+ *
+ * Compared to {@link toolResultUpdate} this builder is deliberately more
+ * defensive, mirroring the equivalent fallback in `@cloudflare/ai-chat`:
+ *
+ * - It matches the broad set of pre-terminal **and** terminal states, so a
+ *   provider that replays the entire prior tool round-trip during a
+ *   continuation (notably the OpenAI Responses API — issue #1404) still
+ *   resolves to the same part instead of silently missing it.
+ * - It is **first-write-wins**: a chunk arriving for a tool that already holds
+ *   a terminal result is treated as a replay and the existing output is never
+ *   overwritten. In that case `apply` returns the *same part reference*, which
+ *   callers use as an idempotent-no-op signal to skip the durable write and a
+ *   redundant `MESSAGE_UPDATED` broadcast.
+ * - It preserves a streamed `preliminary` flag when one is present, otherwise
+ *   marks the result final (`preliminary: false`).
  */
-declare function 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>;
+declare function crossMessageToolResultUpdate(
+  toolCallId: string,
+  updateType: "output-available" | "output-error",
+  output?: unknown,
+  errorText?: string,
+  preliminary?: boolean
+): ToolPartUpdate;
 /**
- * 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.
+ * Build an update descriptor that replaces the output of a *paused durable
+ * execution* tool part (e.g. a codemode runtime tool that paused for
+ * approval).
+ *
+ * A paused execution completes its tool call normally — the part is already
+ * `output-available` with an output of `{ status: "paused", executionId }`.
+ * When the host later approves/rejects the execution, the new outcome
+ * (completed / rejected / paused-again) must replace that output in place.
+ *
+ * Matching is deliberately narrow and idempotent:
+ *
+ * - only `output-available` parts are considered;
+ * - the existing output must be a paused-execution object carrying the same
+ *   `executionId` — anything else (already replaced, different execution)
+ *   returns the *same part reference*, which callers treat as a no-op signal
+ *   (skip persist + broadcast), mirroring {@link crossMessageToolResultUpdate}.
  */
-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";
+declare function pausedExecutionUpdate(
+  toolCallId: string,
+  executionId: string,
+  output: unknown
+): ToolPartUpdate;
 /**
- * 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.
+ * Build an update descriptor for applying a tool approval.
  *
- * - `"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.
+ * Matches parts in `input-available` or `approval-requested` state.
+ * Sets state to `approval-responded` (if approved) or `output-denied` (if denied).
  */
-type ChatRecoveryScheduleReason = "initial" | "stable_timeout_retry";
+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. */
 /**
- * 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).
+ * 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.
  */
-type RecoveryPartial = {
-  text: string;
-  parts: unknown[];
-  hasSettledToolResults: boolean;
-};
-/** Lifecycle status of a recovered stream's metadata row. */
-type ChatStreamStatus = "streaming" | "completed" | "error";
+declare function hasIncompleteToolBatch(
+  messages: ReadonlyArray<ToolBatchMessage>
+): boolean;
+//#endregion
+//#region src/chat/parse-protocol.d.ts
 /**
- * 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.
+ * Protocol Message Parser — typed parsing of cf_agent_chat_* WebSocket messages.
  *
- * 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.
+ * Parses raw WebSocket messages into a discriminated union of protocol events.
+ * Both AIChatAgent and Think can use this instead of manual JSON.parse + type checking.
  */
-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.
+ * Discriminated union of all incoming chat protocol events.
+ *
+ * Each agent handles the events it cares about and ignores the rest.
+ * Returns `null` for non-JSON messages or unrecognized types.
  */
-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;
-}
+type ChatProtocolEvent =
+  | {
+      type: "chat-request";
+      id: string;
+      init: {
+        method?: string;
+        body?: string;
+        [key: string]: unknown;
+      };
+    }
+  | {
+      type: "clear";
+    }
+  | {
+      type: "cancel";
+      id: string;
+    }
+  | {
+      type: "tool-result";
+      toolCallId: string;
+      toolName: string;
+      output: unknown;
+      state?: string;
+      errorText?: string;
+      autoContinue?: boolean;
+      clientTools?: Array<{
+        name: string;
+        description?: string;
+        parameters?: unknown;
+      }>;
+    }
+  | {
+      type: "tool-approval";
+      toolCallId: string;
+      approved: boolean;
+      autoContinue?: boolean;
+    }
+  | {
+      type: "stream-resume-request";
+      probeId?: string;
+    }
+  | {
+      type: "stream-resume-ack";
+      id: string;
+    }
+  | {
+      type: "messages";
+      messages: unknown[];
+    };
 /**
- * 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.
+ * Parse a raw WebSocket message string into a typed protocol event.
  *
- * 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.
+ * Returns `null` if the message is not valid JSON or not a recognized
+ * protocol message type. Callers should fall through to the user's
+ * `onMessage` handler when `null` is returned.
+ *
+ * @example
+ * ```typescript
+ * const event = parseProtocolMessage(rawMessage);
+ * if (!event) return userOnMessage(connection, rawMessage);
+ *
+ * switch (event.type) {
+ *   case "chat-request": { ... }
+ *   case "clear": { ... }
+ *   case "tool-result": { ... }
+ * }
+ * ```
  */
-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>;
-}
+declare function parseProtocolMessage(raw: string): ChatProtocolEvent | null;
+//#endregion
+//#region src/chat/message-reconciler.d.ts
 /**
- * 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.
+ * Reconcile incoming client messages against server state.
+ *
+ * 1. Merges server-known tool outputs into incoming messages that still
+ *    show stale states (input-available, approval-requested, approval-responded)
+ * 2. Reconciles assistant IDs: exact match → content-key match → toolCallId match
+ *
+ * @param incoming - Messages from the client
+ * @param serverMessages - Current server-side messages (source of truth)
+ * @param sanitizeForContentKey - Function to sanitize a message before computing
+ *   its content key (typically strips ephemeral provider metadata)
+ * @returns Reconciled messages ready for persistence
  */
-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>;
+declare function reconcileMessages(
+  incoming: UIMessage[],
+  serverMessages: readonly UIMessage[],
+  sanitizeForContentKey?: (message: UIMessage) => UIMessage
+): UIMessage[];
+/**
+ * For a single message, resolve its ID by matching toolCallId against server state.
+ * Prevents duplicate DB rows when client IDs differ from server IDs.
+ * Tool call IDs are unique per conversation, so matching is safe regardless of state.
+ */
+declare function resolveToolMergeId(
+  message: UIMessage,
+  serverMessages: readonly UIMessage[]
+): UIMessage;
+/**
+ * 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 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 {
   /**
-   * 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).
+   * 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.
    */
-  rescheduleAfterStableTimeout(input: {
-    incidentId: string | undefined;
-    callback: ChatRecoveryScheduleCallback;
-    data: Record<string, unknown> | undefined;
-    fallbackMaxAttempts: number;
-  }): Promise<boolean>;
+  repairPart: (part: UIMessage["parts"][number]) => UIMessage["parts"][number];
   /**
-   * 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).
+   * Whether a tool part already carries a settled result (defaults to
+   * {@link toolPartHasSettledResult}).
    */
-  recordOomAndDecide(input: {
-    incidentId: string | undefined;
-    callback: ChatRecoveryScheduleCallback;
-    data: Record<string, unknown> | undefined;
-    maxOomRetries: number;
-  }): Promise<"rescheduled" | "exhausted">;
+  isSettled?: (record: Record<string, unknown>) => boolean;
   /**
-   * 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.
+   * Normalize a tool part's `input` (defaults to the shared
+   * {@link normalizeToolInput}).
    */
-  exhaustRecoveryGiveUp(input: {
-    callback: ChatRecoveryScheduleCallback;
-    data:
-      | {
-          incidentId?: string;
-          originalRequestId?: string;
-          recoveredRequestId?: string;
-        }
-      | undefined;
-    reason: string;
-  }): Promise<void>;
+  normalizeInput?: (input: unknown) => {
+    input: unknown;
+    changed: boolean;
+  };
   /**
-   * 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.
+   * 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`.
    */
-  updateIncident(
-    incidentId: string | undefined,
-    status: ChatRecoveryIncident["status"],
-    reason?: string
-  ): Promise<void>;
+  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[];
 }
 /**
- * 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).
+ * Repair interrupted tool calls and normalize malformed tool inputs across a
+ * transcript. Behavior mirrors `@cloudflare/think`'s original
+ * `_repairToolTranscriptParts`:
  *
- * 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}.
+ *   - 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.
  *
- * `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.
+ * Messages with no changed part keep their original object reference so callers
+ * can cheaply detect what to persist.
  */
-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>;
+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-codec.d.ts
 /**
@@ -3100,11 +3362,12 @@ 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:
+ * The host-agnostic rule for crediting recovery forward progress from a stored
+ * stream chunk, from when the marker was a counter bumped per chunk. Neither
+ * host bumps a counter any more: the marker is derived from the stream log
+ * (`ResumableStream.progressMarker`), so a chunk counts once its segment is
+ * durably flushed. The rule stays exported for consumers that still keep a
+ * counter of their own:
  *
  *  - a **milestone** ({@link ChatRecoveryCodec.isProgressChunk}) always credits;
  *  - **streaming content** ({@link ChatRecoveryCodec.isStreamingContentChunk})
@@ -3277,6 +3540,37 @@ declare function iterateWithStallWatchdog<T>(
   onStall: () => void
 ): AsyncGenerator<T>;
 //#endregion
+//#region src/chat/truncate-older-messages.d.ts
+interface TruncateOptions {
+  /** Number of recent messages to keep intact (default: 4) */
+  keepRecent?: number;
+  /** Max chars for tool outputs in older messages (default: 500) */
+  maxToolOutputChars?: number;
+  /** Max chars for text parts in older messages (default: 10000) */
+  maxTextChars?: number;
+}
+/**
+ * Truncate tool outputs and long text in older messages.
+ * Returns a new array — input messages are not mutated.
+ *
+ * Recent messages (last `keepRecent`) are left intact.
+ * Older messages get tool outputs and long text truncated. Structured tool
+ * outputs are truncated in place instead of being replaced by raw strings.
+ *
+ * Use in assembleContext() before sending to the LLM:
+ * ```typescript
+ * async assembleContext() {
+ *   const history = this.sessions.getHistory(this._sessionId);
+ *   const truncated = truncateOlderMessages(history);
+ *   return convertToModelMessages(truncated);
+ * }
+ * ```
+ */
+declare function truncateOlderMessages(
+  messages: SessionMessage[],
+  options?: TruncateOptions
+): SessionMessage[];
+//#endregion
 export {
   AGENT_TOOL_STREAM_PROGRESS_BUMP_THROTTLE_MS,
   AbortRegistry,
@@ -3305,6 +3599,7 @@ export {
   CHAT_RECOVERY_INCIDENT_TTL_MS,
   CHAT_RECOVERY_PROGRESS_KEY,
   CHAT_RECOVERY_STABLE_RETRY_DELAY_SECONDS,
+  CHAT_RECOVERY_TASK_NAME,
   CHAT_STREAM_PROGRESS_CREDIT_THROTTLE_MS,
   type ChatConnection,
   type ChatFiberSnapshot,
@@ -3316,6 +3611,7 @@ export {
   type ChatRecoveryContext,
   ChatRecoveryEngine,
   type ChatRecoveryExhaustedContext,
+  type ChatRecoveryHandoff,
   type ChatRecoveryIncident,
   type ChatRecoveryIncidentEvent,
   type ChatRecoveryKind,
@@ -3323,10 +3619,15 @@ export {
   type ChatRecoveryProgressContext,
   type ChatRecoveryScheduleCallback,
   type ChatRecoveryScheduleReason,
+  type ChatRecoveryTaskHooks,
+  type ChatRecoveryTaskInput,
+  type ChatRecoveryTaskReason,
   type ChatResponseResult,
   ChatStreamStalledError,
   type ChatStreamStatus,
   type ChatTerminalRecord,
+  type ChatTurnClosureEntry,
+  type ChatTurnTaskHooks,
   type ChunkAction,
   type ChunkResult,
   type ClassifyRecoveredTurnInput,
@@ -3374,7 +3675,6 @@ export {
   ResumableStream,
   ResumeHandshake,
   type ResumeHandshakeHost,
-  STREAM_CLEANUP_DELAY_SECONDS,
   STREAM_RESUME_NONE_REASONS,
   type SaveMessagesOptions,
   type SaveMessagesResult,
@@ -3392,6 +3692,7 @@ export {
   type TextSegmentEvent,
   TextSegmentJoiner,
   type ToolPartUpdate,
+  type TruncateOptions,
   TurnQueue,
   type TurnResult,
   aiSdkRecoveryCodec,
@@ -3404,19 +3705,23 @@ export {
   buildInClauseStrings,
   bumpChatRecoveryProgress,
   byteLength,
-  chatRecoverySchedulePolicy,
+  chatRecoveryTaskRunOptions,
   classifyAgentToolChildRecovery,
-  cleanupStreamBuffers,
   clearChatTerminal,
   clientResolvableToolNames,
   createAgentToolEventState,
   createChatFiberSnapshot,
+  createChatRecoveryTaskDefinition,
+  createChatStreams,
+  createChatTurnTaskDefinition,
   createToolsFromClientSchemas,
   crossMessageToolResultUpdate,
+  dispatchChatRecoveryToHandoff,
   drainInteractionApplies,
   enforceRowSizeLimit,
   hasIncompleteToolBatch,
   interceptAgentToolBroadcast,
+  isPlatformFailure,
   isReplayChunk,
   iterateWithStallWatchdog,
   listActiveChatRecoveryIncidents,
@@ -3442,6 +3747,7 @@ export {
   toolApprovalUpdate,
   toolPartHasSettledResult,
   toolResultUpdate,
+  truncateOlderMessages,
   unwrapChatFiberSnapshot,
   wrapChatFiberSnapshot
 };