agents
Version:
A home for your AI agents
3,827 lines • 155 kB
JavaScript
import { isPlatformFailure, tryN } from "../retries.js";
import { i as normalizeToolInput, n as getPartialStreamText, r as isReplayChunk, t as applyChunkToParts } from "../message-builder-BymO4N_D.js";
import { i as interceptAgentToolBroadcast, n as applyAgentToolEvent, r as createAgentToolEventState, t as AgentToolProgressEmitter } from "../agent-tools-y7zLfw4Q.js";
import { t as TextSegmentJoiner } from "../text-segment-joiner-BtAFQSA_.js";
import { n as sanitizeMessage, t as byteLength } from "../sanitize-D9TujEK8.js";
import { i as StreamAccumulator, n as STREAM_RESUME_NONE_REASONS, r as transition, t as CHAT_MESSAGE_TYPES } from "../protocol-B0nh6KNf.js";
import { n as Streams } from "../streams-CCPRV6dt.js";
import { t as MessageType } from "../wire-types-CnMt6_HR.js";
import { jsonSchema, tool } from "ai";
import { nanoid } from "nanoid";
//#region src/chat/tool-output-truncation.ts
const DEFAULT_MAX_DEPTH = 8;
const TRUNCATED_FLAG = "__truncated";
const TRUNCATED_CHARS = "__truncatedChars";
function truncateToolOutput(output, maxChars) {
const original = stringifyForLength(output);
if (original.length <= maxChars) return {
output,
truncated: false,
originalLength: original.length
};
return {
output: truncateValue(output, maxChars, original.length, 0),
truncated: true,
originalLength: original.length
};
}
function truncatedSuffix(originalLength) {
return `... [truncated ${originalLength} chars]`;
}
function truncateValue(value, maxChars, originalLength, depth) {
if (typeof value === "string") return truncateString(value, maxChars, value.length);
if (value === null || typeof value !== "object") return value;
if (depth >= DEFAULT_MAX_DEPTH) return `[Nested output omitted ${truncatedSuffix(originalLength)}]`;
if (Array.isArray(value)) return truncateArray(value, maxChars, originalLength, depth);
return truncateObject(value, maxChars, originalLength, depth);
}
function truncateArray(value, maxChars, originalLength, depth) {
const childBudget = childMaxChars(maxChars, value.length);
const result = value.map((item) => truncateValue(item, childBudget, stringifyForLength(item).length, depth + 1));
while (result.length > 1 && stringifyForLength(result).length > maxChars) result.pop();
if (result.length < value.length) result.push(`Array output truncated ${truncatedSuffix(originalLength)}`);
if (stringifyForLength(result).length > maxChars) return compactArrayMarker(maxChars, originalLength);
return result;
}
function truncateObject(value, maxChars, originalLength, depth) {
const entries = Object.entries(value);
const childBudget = childMaxChars(maxChars, entries.length);
const result = {};
for (const [key, entryValue] of entries) result[key] = truncateValue(entryValue, childBudget, stringifyForLength(entryValue).length, depth + 1);
const resultLength = stringifyForLength(result).length;
if (resultLength <= maxChars) return result;
shrinkStringFields(result, maxChars);
if (stringifyForLength(result).length > maxChars) {
result[TRUNCATED_FLAG] = true;
result[TRUNCATED_CHARS] = resultLength;
}
if (stringifyForLength(result).length > maxChars) return compactObjectMarker(maxChars, originalLength);
return result;
}
function shrinkStringFields(value, maxChars) {
const stringEntries = Object.entries(value).filter((entry) => typeof entry[1] === "string").sort((a, b) => b[1].length - a[1].length);
for (const [key, str] of stringEntries) {
if (stringifyForLength(value).length <= maxChars) return;
value[key] = truncateString(str, Math.max(0, Math.floor(maxChars / 4)), str.length);
}
}
function truncateString(value, maxChars, originalLength) {
if (value.length <= maxChars) return value;
const suffix = truncatedSuffix(originalLength);
if (maxChars <= suffix.length) return suffix.slice(0, maxChars);
return `${value.slice(0, maxChars - suffix.length)}${suffix}`;
}
function compactObjectMarker(maxChars, originalLength) {
const marker = {
[TRUNCATED_FLAG]: true,
[TRUNCATED_CHARS]: originalLength,
note: "Tool output omitted because it was too large to preserve structurally."
};
if (stringifyForLength(marker).length <= maxChars) return marker;
return {
[TRUNCATED_FLAG]: true,
[TRUNCATED_CHARS]: originalLength
};
}
function compactArrayMarker(maxChars, originalLength) {
const structuredMarker = compactObjectMarker(maxChars, originalLength);
if (stringifyForLength([structuredMarker]).length <= maxChars) return [structuredMarker];
const marker = [`Array output omitted because it was too large to preserve structurally ${truncatedSuffix(originalLength)}`];
if (stringifyForLength(marker).length <= maxChars) return marker;
return [truncatedSuffix(originalLength).slice(0, maxChars)];
}
function childMaxChars(maxChars, childCount) {
if (childCount <= 1) return maxChars;
return Math.max(80, Math.floor(maxChars / Math.min(childCount, 10)));
}
function stringifyForLength(value) {
try {
if (typeof value === "string") return value;
return JSON.stringify(value) ?? String(value);
} catch {
return String(value);
}
}
//#endregion
//#region src/chat/sanitize.ts
/** Maximum serialized message size before compaction (bytes). 1.8MB with headroom below SQLite's 2MB limit. */
const ROW_MAX_BYTES = 18e5;
/**
* Enforce SQLite row size limits by compacting tool outputs and text parts
* when a serialized message exceeds the safety threshold (1.8MB). Shared by
* `@cloudflare/ai-chat` and `@cloudflare/think` so both compact identically.
*
* Compaction strategy:
* 1. Compact tool outputs over 1KB with {@link truncateToolOutput}, preserving
* the structured output shape, and annotate `metadata.compactedToolOutputs`
* with the compacted tool-call IDs.
* 2. If still too big, truncate text parts from oldest to newest, annotating
* `metadata.compactedTextParts` with the truncated part indices.
*/
function enforceRowSizeLimit(message, options) {
let json = JSON.stringify(message);
let size = byteLength(json);
if (size <= 18e5) return message;
if (message.role !== "assistant") {
options?.warn?.(`Non-assistant message ${message.id} is ${size} bytes, exceeds row limit. Truncating text parts.`);
return truncateTextParts(message);
}
options?.warn?.(`Message ${message.id} is ${size} bytes, compacting tool outputs to fit SQLite row limit`);
const compactedToolCallIds = [];
const compactedParts = message.parts.map((part) => {
if ("output" in part && "toolCallId" in part && "state" in part && part.state === "output-available") {
const output = part.output;
const truncated = truncateToolOutput(output, 1e3);
if (truncated.truncated) {
compactedToolCallIds.push(part.toolCallId);
return {
...part,
output: truncated.output
};
}
}
return part;
});
const result = {
...message,
parts: compactedParts
};
if (compactedToolCallIds.length > 0) result.metadata = {
...result.metadata ?? {},
compactedToolOutputs: compactedToolCallIds
};
json = JSON.stringify(result);
size = byteLength(json);
if (size <= 18e5) return result;
options?.warn?.(`Message ${message.id} still ${size} bytes after tool compaction, truncating text parts`);
return truncateTextParts(result);
}
function truncateTextParts(message) {
const compactedTextPartIndices = [];
const parts = [...message.parts];
for (let i = 0; i < parts.length; i++) {
const part = parts[i];
if (part.type === "text" && "text" in part) {
const text = part.text;
if (text.length > 1e3) {
compactedTextPartIndices.push(i);
parts[i] = {
...part,
text: `[Text truncated for storage (${text.length} chars). First 500 chars: ${text.slice(0, 500)}...]`
};
const candidate = {
...message,
parts
};
if (byteLength(JSON.stringify(candidate)) <= 18e5) break;
}
}
}
const result = {
...message,
parts
};
if (compactedTextPartIndices.length > 0) result.metadata = {
...result.metadata ?? {},
compactedTextParts: compactedTextPartIndices
};
return result;
}
//#endregion
//#region src/chat/turn-queue.ts
var TurnQueue = class {
constructor() {
this._queue = Promise.resolve();
this._generation = 0;
this._activeRequestId = null;
this._countsByGeneration = /* @__PURE__ */ new Map();
}
get generation() {
return this._generation;
}
get activeRequestId() {
return this._activeRequestId;
}
get isActive() {
return this._activeRequestId !== null;
}
async enqueue(requestId, fn, options) {
const previousTurn = this._queue;
let releaseTurn;
const capturedGeneration = options?.generation ?? this._generation;
this._countsByGeneration.set(capturedGeneration, (this._countsByGeneration.get(capturedGeneration) ?? 0) + 1);
this._queue = new Promise((resolve) => {
releaseTurn = resolve;
});
await previousTurn;
if (this._generation !== capturedGeneration) {
this._decrementCount(capturedGeneration);
releaseTurn();
return { status: "stale" };
}
this._activeRequestId = requestId;
try {
return {
status: "completed",
value: await fn()
};
} finally {
this._activeRequestId = null;
this._decrementCount(capturedGeneration);
releaseTurn();
}
}
/**
* Advance the generation counter. All turns enqueued under older
* generations will be skipped when they reach the front of the queue.
*/
reset() {
this._generation++;
}
/**
* Wait until the queue is fully drained (no pending or active turns).
*/
async waitForIdle() {
let queue;
do {
queue = this._queue;
await queue;
} while (this._queue !== queue);
}
/**
* Number of active + queued turns for a given generation.
* Defaults to the current generation.
*/
queuedCount(generation) {
return this._countsByGeneration.get(generation ?? this._generation) ?? 0;
}
_decrementCount(generation) {
const count = (this._countsByGeneration.get(generation) ?? 1) - 1;
if (count <= 0) this._countsByGeneration.delete(generation);
else this._countsByGeneration.set(generation, count);
}
};
//#endregion
//#region src/chat/submit-concurrency.ts
var SubmitConcurrencyController = class {
constructor(options) {
this.options = options;
this._submitSequence = 0;
this._latestOverlappingSubmitSequence = 0;
this._pendingEnqueueCount = 0;
this._resetEpoch = 0;
this._activeDebounceTimers = /* @__PURE__ */ new Set();
this._activeDebounceResolves = /* @__PURE__ */ new Set();
}
get pendingEnqueueCount() {
return this._pendingEnqueueCount;
}
get overlappingSubmitCount() {
return this._latestOverlappingSubmitSequence;
}
decide(options) {
const queuedTurnsInCurrentEpoch = options.queuedTurns + this._pendingEnqueueCount;
if (!options.isSubmitMessage || queuedTurnsInCurrentEpoch === 0) return {
action: "execute",
strategy: null,
submitSequence: null,
debounceUntilMs: null
};
const concurrency = this.normalize(options.concurrency);
if (concurrency === "drop") return {
action: "drop",
strategy: concurrency,
submitSequence: null,
debounceUntilMs: null
};
if (concurrency === "queue") return {
action: "execute",
strategy: concurrency,
submitSequence: null,
debounceUntilMs: null
};
const submitSequence = ++this._submitSequence;
this._latestOverlappingSubmitSequence = submitSequence;
if (concurrency === "latest" || concurrency === "merge") return {
action: "execute",
strategy: concurrency,
submitSequence,
debounceUntilMs: null
};
return {
action: "execute",
strategy: concurrency,
submitSequence,
debounceUntilMs: Date.now() + concurrency.debounceMs
};
}
/**
* Mark a submit as accepted and in-flight between admission and turn
* queue registration. Returns an idempotent `release()` function that
* must be called when the submit either reaches the turn queue or is
* abandoned. The returned function is bound to the controller's reset
* epoch — releases from before the most recent `reset()` are no-ops,
* so post-reset submits keep an accurate count.
*/
beginEnqueue() {
this._pendingEnqueueCount++;
const epoch = this._resetEpoch;
let released = false;
return () => {
if (released) return;
released = true;
if (this._resetEpoch !== epoch) return;
this._pendingEnqueueCount = Math.max(0, this._pendingEnqueueCount - 1);
};
}
isSuperseded(submitSequence) {
return submitSequence !== null && submitSequence < this._latestOverlappingSubmitSequence;
}
async waitForTimestamp(timestampMs) {
const remainingMs = timestampMs - Date.now();
if (remainingMs <= 0) return;
await new Promise((resolve) => {
const wrappedResolve = () => {
this._activeDebounceResolves.delete(wrappedResolve);
resolve();
};
const timer = setTimeout(() => {
this._activeDebounceTimers.delete(timer);
wrappedResolve();
}, remainingMs);
this._activeDebounceTimers.add(timer);
this._activeDebounceResolves.add(wrappedResolve);
});
}
cancelActiveDebounce() {
for (const timer of this._activeDebounceTimers) clearTimeout(timer);
this._activeDebounceTimers.clear();
const resolves = [...this._activeDebounceResolves];
this._activeDebounceResolves.clear();
for (const resolve of resolves) resolve();
}
reset() {
this._resetEpoch++;
this._pendingEnqueueCount = 0;
this.cancelActiveDebounce();
}
async waitForIdle(waitForQueueIdle) {
while (true) {
await waitForQueueIdle();
if (this._pendingEnqueueCount === 0) return;
await new Promise((resolve) => setTimeout(resolve, 5));
}
}
normalize(concurrency) {
if (typeof concurrency === "string") return concurrency;
const debounceMs = concurrency.debounceMs;
return {
strategy: "debounce",
debounceMs: typeof debounceMs === "number" && Number.isFinite(debounceMs) && debounceMs >= 0 ? debounceMs : this.options.defaultDebounceMs
};
}
};
//#endregion
//#region src/chat/connection.ts
/**
* 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.
*/
function sendIfOpen(connection, message) {
try {
connection.send(message);
return true;
} catch (error) {
if (isWebSocketClosedSendError(error)) return false;
throw error;
}
}
/** Whether an error is the "WebSocket send() after close" `TypeError`. */
function isWebSocketClosedSendError(error) {
return error instanceof TypeError && error.message.includes("WebSocket send() after close");
}
//#endregion
//#region src/chat/replay-frames.ts
/**
* Send stored chunk bodies to a connection as replay frames.
*
* @returns False when the connection closed mid-replay — the caller leaves
* its stream state untouched so the next reconnect can retry.
*/
function sendReplayBodies(connection, requestId, bodies, continuation) {
for (const body of bodies) if (!sendIfOpen(connection, JSON.stringify({
body,
done: false,
id: requestId,
type: CHAT_MESSAGE_TYPES.USE_CHAT_RESPONSE,
replay: true,
...continuation && { continuation: true }
}))) return false;
return true;
}
/**
* Send one replay control frame: `done: true` ends the replayed stream;
* `replayComplete` tells a live client to flush accumulated parts and keep
* listening. Replay frames must mirror what a live client observed,
* including the continuation flag (#1733).
*/
function sendReplayControl(connection, requestId, options) {
return sendIfOpen(connection, JSON.stringify({
body: "",
done: options.done,
id: requestId,
type: CHAT_MESSAGE_TYPES.USE_CHAT_RESPONSE,
replay: true,
...options.replayComplete && { replayComplete: true },
...options.continuation && { continuation: true }
}));
}
//#endregion
//#region src/chat/resumable-stream.ts
/**
* ResumableStream: chat's producer-side coalescing and wire-protocol replay
* adapter over the `agents/streams` capability. Chat's in-flight output
* lives in the shared durable chunk log (`cf_agents_streams` /
* `cf_agents_stream_blocks`), one stream per turn, tagged with the turn's
* request id so replay-by-request rides the capability's indexed lookup.
*
* Handles:
* - Chunk buffering (packed segments — batched writes for storage-op economy)
* - Stream lifecycle (start, complete, error) mapped onto Streams settlement
* - Chunk replay for reconnecting clients (framing in `replay-frames.ts`)
* - Stale stream cleanup (row-level retention; at most one indexed
* chunk-tail read per stale live candidate, never a chunk-table scan)
* - Active stream restoration after agent restart
* - One-time migration of legacy `cf_ai_chat_stream_*` tables
*
* The adapter's public surface is synchronous and may be constructed before
* the Lifecycle starts, so it runs on the Streams internal sync aperture; the
* invariant-bearing writes (append fence, settlement, wakeups, events) go
* through the capability, so live `streams.read()` consumers and diagnostics
* observe chat streams like any other stream. The host `sql` handle is used
* only for chat's own legacy tables during migration.
*/
/** Number of chunks to pack into a single stored segment before flushing */
const CHUNK_BUFFER_SIZE = 10;
/** Maximum buffer size to prevent memory issues on rapid reconnections */
const CHUNK_BUFFER_MAX_SIZE = 100;
/**
* Max accumulated raw chunk bytes packed into one segment before forcing a
* flush. The SQLite row limit is 2 MB; packing serializes bodies into a JSON
* array, which re-escapes their contents (quotes/backslashes), so we keep the
* raw total well under the limit to leave generous headroom for escaping
* overhead. A chunk larger than this is flushed as its own (unwrapped)
* segment.
*/
const SEGMENT_MAX_BYTES = 512e3;
/**
* Stored segments per page when replaying a stream's chunk log. Bounds
* replay memory to one page of segment bodies rather than the whole turn.
*/
const REPLAY_PAGE_SEGMENTS = 10;
/**
* Retention for abandoned `streaming` rows, measured from LAST chunk activity.
*
* An interrupted turn must have ample time to be resumed by a reconnecting
* client or healed by task replay before its buffer is reaped. Only a stream
* that has produced no chunk for this long is treated as truly dead. Last
* activity is decided in two phases — a coarse cutoff on the stream row's
* `updated_at` (stamped at open, not per append), then one indexed read of
* the newest chunk's timestamp for rows past it — so a long but still-active
* stream is never reclaimed mid-flight. Terminal rows carry no such window:
* a stream that finished is redundant with its persisted message, and the
* cutover deletes it in the same transaction; leftovers are reclaimed by
* the next {@link ResumableStream.start}.
*/
const ABANDONED_STREAM_RETENTION_MS = 3600 * 1e3;
/** Shared encoder for UTF-8 byte length measurement */
const textEncoder = new TextEncoder();
/**
* Ceiling for one stored chat segment after JSON serialization, and the
* `maxChunkBytes` the backing Streams capability must be constructed with.
* Kept under the 2 MB SQLite row limit with headroom for escaping.
*/
const CHAT_STREAM_MAX_CHUNK_BYTES = 19e5;
/** Maximum serialized chunk body size before skipping storage (bytes). */
const CHUNK_MAX_BYTES = 18e5;
/**
* 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.
*/
function createChatStreams() {
return new Streams({ maxChunkBytes: CHAT_STREAM_MAX_CHUNK_BYTES });
}
function toPublicStatus(state) {
return state === "errored" ? "error" : state;
}
function parseChatMetadata(row) {
if (row.metadata === null) return null;
try {
const parsed = JSON.parse(row.metadata);
if (parsed && parsed.cfChat === 1) return parsed;
} catch {}
return null;
}
/**
* A stored segment is either a single chunk body (a JSON string value) or a
* packed segment (a JSON array of chunk body strings). Unpack to the
* individual chunk bodies in order.
*/
function unpackSegment(rawChunkJson) {
const parsed = JSON.parse(rawChunkJson);
if (Array.isArray(parsed)) return parsed;
return [parsed];
}
/**
* The deletion hook each adapter holds on its Streams capability. One
* adapter per capability: a host whose startup retried constructs the
* adapter again on the same capability, and the earlier hook must go, or a
* deleted stream's segments would be retired once per construction.
*/
const deletionHooks = /* @__PURE__ */ new WeakMap();
var ResumableStream = class {
constructor(streams, sql, options = {}) {
this._activeStreamId = null;
this._activeRequestId = null;
this._isLive = false;
this._activeIsContinuation = false;
this._chunkBuffer = [];
this._chunkBufferBytes = 0;
this._isFlushingChunks = false;
this._pendingCutover = null;
this.ops = streams.__DO_NOT_USE_WILL_BREAK__sync();
this.ops.ensureTables();
this._sql = sql;
this._onProgress = options.onProgress;
this._ensureProgressTable();
deletionHooks.get(streams)?.();
deletionHooks.set(streams, this.ops.onDelete((row, cursor) => {
if (parseChatMetadata(row)) this._retire(cursor);
}));
this._migrateLegacyTables(sql);
this.restore();
}
/**
* 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.
*/
_notifyProgress() {
this._onProgress?.(this._retiredSegments());
}
/**
* 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.
*/
_ensureProgressTable() {
this._sql`
CREATE TABLE IF NOT EXISTS cf_agents_chat_progress (
key TEXT PRIMARY KEY,
retired INTEGER NOT NULL,
legacy INTEGER NOT NULL DEFAULT 0
) WITHOUT ROWID
`;
}
_retiredSegments() {
const row = this._sql`
SELECT retired, legacy FROM cf_agents_chat_progress WHERE key = 'chat'
`[0];
return row ? row.retired + row.legacy : 0;
}
/** Add `segments` to the retired total. One row write; a no-op for zero. */
_retire(segments) {
if (segments <= 0) return;
this._sql`
INSERT INTO cf_agents_chat_progress (key, retired, legacy)
VALUES ('chat', ${segments}, 0)
ON CONFLICT(key) DO UPDATE SET retired = retired + excluded.retired
`;
}
/**
* Segments a row still accounts for: a live stream's log tail, a settled
* stream's final cursor (stamped exact at settlement).
*/
_segmentsOf(row) {
return row.state === "streaming" ? this.ops.cursor(row.stream_id) : row.chunk_count;
}
/**
* 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() {
let live = 0;
for (const row of this._chatRows()) live += this._segmentsOf(row);
return this._retiredSegments() + live;
}
/**
* 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() {
this._retire(1);
this._notifyProgress();
}
/**
* 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) {
if (legacyTotal <= 0) return;
this._sql`
INSERT INTO cf_agents_chat_progress (key, retired, legacy)
VALUES ('chat', 0, ${legacyTotal})
ON CONFLICT(key) DO UPDATE
SET legacy = MAX(legacy, excluded.legacy)
`;
}
/**
* 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.
*/
_deleteRetiring(rows) {
if (rows.length === 0) return;
this.ops.deleteMany(rows.map((row) => row.stream_id));
this._notifyProgress();
}
/**
* 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.
*/
_migrateLegacyTables(sql) {
const legacyTables = sql`
SELECT name FROM sqlite_master WHERE type = 'table'
AND name IN ('cf_ai_chat_stream_metadata', 'cf_ai_chat_stream_chunks')
`.map((row) => row.name);
if (legacyTables.length === 0) return;
if (legacyTables.includes("cf_ai_chat_stream_metadata")) {
const columns = sql`
SELECT name FROM pragma_table_info('cf_ai_chat_stream_metadata')
`.map((row) => row.name);
const hasMessageId = columns.includes("message_id");
const hasContinuation = columns.includes("is_continuation");
const hasChunks = legacyTables.includes("cf_ai_chat_stream_chunks");
const rows = sql`SELECT * FROM cf_ai_chat_stream_metadata`;
for (const row of rows) {
const streamId = String(row.id);
if (this.ops.getStream(streamId)) continue;
const metadata = { cfChat: 1 };
if (hasMessageId && row.message_id != null) metadata.messageId = String(row.message_id);
if (hasContinuation && row.is_continuation === 1) metadata.isContinuation = 1;
const chunkRows = hasChunks ? sql`
SELECT body, created_at FROM cf_ai_chat_stream_chunks
WHERE stream_id = ${streamId} ORDER BY chunk_index ASC
` : [];
const status = String(row.status);
const state = status === "error" ? "errored" : status === "completed" ? "completed" : "streaming";
const createdAt = Number(row.created_at);
const closedAt = row.completed_at != null ? Number(row.completed_at) : null;
const lastChunkAt = chunkRows.reduce((max, chunk) => Math.max(max, Number(chunk.created_at)), createdAt);
this.ops.importStream({
streamId,
state,
tag: String(row.request_id),
metadata,
chunkCount: chunkRows.length,
createdAt,
updatedAt: closedAt ?? lastChunkAt,
closedAt
});
for (const chunk of chunkRows) {
const body = String(chunk.body);
let value = body;
try {
const parsed = JSON.parse(body);
if (Array.isArray(parsed)) value = parsed;
} catch {}
this.ops.importChunk(streamId, value, Number(chunk.created_at));
}
}
}
sql`DROP TABLE IF EXISTS cf_ai_chat_stream_chunks`;
sql`DROP TABLE IF EXISTS cf_ai_chat_stream_metadata`;
}
get activeStreamId() {
return this._activeStreamId;
}
get activeRequestId() {
return this._activeRequestId;
}
hasActiveStream() {
return this._activeStreamId !== null;
}
/**
* Whether the active stream has a live LLM reader (started in this
* instance) vs being restored from SQLite after hibernation (orphaned).
*/
get isLive() {
return this._isLive;
}
/**
* Start tracking a new stream for resumable streaming.
* Creates the backing stream row and sets up tracking state.
* @param requestId - The unique ID of the chat request
* @returns The generated stream ID
*/
start(requestId, options = {}) {
this.flushBuffer();
this.reclaim();
const streamId = nanoid();
this._activeStreamId = streamId;
this._activeRequestId = requestId;
this._isLive = true;
this._activeIsContinuation = options.continuation ?? false;
const metadata = { cfChat: 1 };
if (options.messageId != null) metadata.messageId = options.messageId;
if (this._activeIsContinuation) metadata.isContinuation = 1;
this.ops.insertStream(streamId, requestId, metadata);
return streamId;
}
/**
* 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
* predates message-id tracking.
*/
getStreamMessageId(streamId) {
const row = this.ops.getStream(streamId);
if (!row) return null;
return parseChatMetadata(row)?.messageId ?? null;
}
/**
* Mark a stream as completed and flush any pending chunks.
* @param streamId - The stream to mark as completed
*/
complete(streamId) {
this.flushBuffer();
this.ops.settle(streamId, "completed", null);
if (this._pendingCutover === streamId) this._pendingCutover = null;
this._clearActive();
}
/**
* 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) {
this.flushBuffer();
this._pendingCutover = streamId;
this._clearActive();
}
/** The stream {@link finish}ed and awaiting its cutover, if any. */
get pendingCutoverId() {
return this._pendingCutover;
}
/**
* 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}. The settlement and `persist`
* writes commit or roll back together.
*/
cutover(streamId, persist, options = {}) {
this.flushBuffer();
const discard = options.discard ?? true;
const commit = persist;
const settled = this.ops.settle(streamId, "completed", null, {
commit,
discard
});
if (settled && discard) this._notifyProgress();
if (!settled) commit();
if (this._pendingCutover === streamId) this._pendingCutover = null;
this._clearActive();
}
/**
* 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.
* The pending marker clears only once settlement succeeds, so a caller
* may retry after a settlement failure — matching {@link cutover}.
*/
finalizePending() {
const streamId = this._pendingCutover;
if (streamId === null) return;
this.ops.settle(streamId, "completed", null);
this._pendingCutover = null;
}
_clearActive() {
this._activeStreamId = null;
this._activeRequestId = null;
this._isLive = false;
this._activeIsContinuation = false;
}
/**
* Mark a stream as errored and clean up state.
* @param streamId - The stream to mark as errored
*/
markError(streamId) {
this.flushBuffer();
this.ops.settle(streamId, "errored", null);
if (this._pendingCutover === streamId) this._pendingCutover = null;
this._clearActive();
}
/**
* 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.
* @param streamId - The stream this chunk belongs to
* @param body - The serialized chunk body
*/
storeChunk(streamId, body) {
const bodyBytes = textEncoder.encode(JSON.stringify(body)).byteLength;
if (bodyBytes > CHUNK_MAX_BYTES) {
console.warn(`[ResumableStream] Skipping oversized chunk (${bodyBytes} bytes) to prevent SQLite row limit crash. Live clients still receive it.`);
return;
}
if (this._chunkBuffer.length >= CHUNK_BUFFER_MAX_SIZE) this.flushBuffer();
if (this._chunkBuffer.length > 0 && this._chunkBufferBytes + bodyBytes > SEGMENT_MAX_BYTES) this.flushBuffer();
this._chunkBuffer.push({
streamId,
body
});
this._chunkBufferBytes += bodyBytes;
if (this._chunkBuffer.length >= CHUNK_BUFFER_SIZE) this.flushBuffer();
}
/**
* Flush the buffered chunks to storage as a single packed segment.
* Uses a lock to prevent concurrent flush operations.
*
* 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() {
if (this._isFlushingChunks || this._chunkBuffer.length === 0) return;
this._isFlushingChunks = true;
try {
const chunks = this._chunkBuffer;
this._chunkBuffer = [];
this._chunkBufferBytes = 0;
const streamId = chunks[0].streamId;
const segment = chunks.length === 1 ? chunks[0].body : chunks.map((chunk) => chunk.body);
try {
this.ops.append(streamId, segment);
} catch {}
} finally {
this._isFlushingChunks = false;
}
}
/**
* 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.
*/
*_storedBodies(streamId) {
let next = 0;
for (;;) {
const rows = this.ops.readChunks(streamId, next, REPLAY_PAGE_SEGMENTS);
for (const row of rows) {
next = row.seq + 1;
yield* unpackSegment(row.chunk);
}
if (rows.length < REPLAY_PAGE_SEGMENTS) return;
}
}
/**
* Send stored stream chunks to a connection for replay.
* Chunks are marked with replay: true so the client can batch-apply them.
*
* Three outcomes:
* - **Live stream**: sends chunks + `replayComplete` — client flushes and
* continues receiving live chunks from the LLM reader.
* - **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.
*
* 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
* @returns The stream ID if the stream was orphaned and finalized, null otherwise.
* When non-null the caller should reconstruct the message from chunks.
*/
replayChunks(connection, requestId) {
const streamId = this._activeStreamId;
if (!streamId) return null;
this.flushBuffer();
const continuation = this._activeIsContinuation;
if (!sendReplayBodies(connection, requestId, this._storedBodies(streamId), continuation)) return null;
if (!this._isLive) {
sendReplayControl(connection, requestId, {
done: true,
continuation
});
this.complete(streamId);
return streamId;
}
sendReplayControl(connection, requestId, {
done: false,
replayComplete: true,
continuation
});
return 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.
*/
_latestChatRowByTag(requestId, state) {
return this.ops.rowsByTag(requestId, state).find((row) => parseChatMetadata(row) !== null);
}
replayCompletedChunksByRequestId(connection, requestId) {
this.flushBuffer();
const row = this._latestChatRowByTag(requestId, "completed");
if (!row) return false;
const continuation = parseChatMetadata(row)?.isContinuation === 1;
if (!sendReplayBodies(connection, requestId, this._storedBodies(row.stream_id), continuation)) return false;
return sendReplayControl(connection, requestId, {
done: true,
continuation
});
}
/**
* Replay the stored chunks of an errored stream for a request, WITHOUT a
* terminal frame — the caller follows up with the `done: true, error: true`
* 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 (#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
* replayed successfully. Returns false only when a send failed mid-replay,
* signalling the caller to skip the terminal frame — the connection is gone
* and the next reconnect retries the whole sequence.
*/
replayErroredChunksByRequestId(connection, requestId) {
this.flushBuffer();
const row = this._latestChatRowByTag(requestId, "errored");
if (!row) return true;
return sendReplayBodies(connection, requestId, this._storedBodies(row.stream_id), parseChatMetadata(row)?.isContinuation === 1);
}
/**
* Latest chat stream row for a request regardless of status — the recovery
* engines' stream-evidence lookup.
*/
latestStreamInfoForRequest(requestId) {
const row = this._latestChatRowByTag(requestId);
if (!row) return null;
return {
id: row.stream_id,
status: toPublicStatus(row.state),
createdAt: row.created_at
};
}
/**
* Latest in-flight chat stream for a request — recoverable-turn evidence.
*/
latestActiveStreamInfoForRequest(requestId) {
const row = this._latestChatRowByTag(requestId, "streaming");
if (!row) return null;
return {
id: row.stream_id,
createdAt: row.created_at
};
}
/** Every chat-owned stream row, newest first. */
_chatRows() {
const rows = [];
for (const row of this.ops.listRows()) {
const chat = parseChatMetadata(row);
if (chat) rows.push({
...row,
chat
});
}
return rows;
}
/**
* Restore active stream state if the agent was restarted during streaming.
* All streams are restored regardless of age — stale cleanup happens
* lazily in _maybeCleanupOldStreams after recovery has had its chance.
*/
restore() {
const row = this._chatRows().find((r) => r.state === "streaming");
if (row) {
this._activeStreamId = row.stream_id;
this._activeRequestId = row.tag;
this._activeIsContinuation = row.chat.isContinuation === 1;
}
}
/**
* Clear all chat stream data (called on chat history clear). Streams other
* producers opened on the same Durable Object are untouched.
*/
clearAll() {
this._chunkBuffer = [];
this._chunkBufferBytes = 0;
this._deleteRetiring(this._chatRows());
this._activeStreamId = null;
this._activeRequestId = null;
this._activeIsContinuation = false;
}
/**
* 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() {
this.clearAll();
}
/**
* 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.
*/
reclaim(now = Date.now()) {
const abandonedCutoff = now - ABANDONED_STREAM_RETENTION_MS;
const reclaimable = this._chatRows().filter((row) => row.state === "streaming" ? row.stream_id !== this._activeStreamId && row.updated_at < abandonedCutoff && (this.ops.lastChunkAt(row.stream_id) ?? row.updated_at) < abandonedCutoff : true);
this._deleteRetiring(reclaimable);
return reclaimable.length;
}
/**
* Return the stored chunks for a stream as individual chunk bodies in order,
* 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) {
return [...this._storedBodies(streamId)].map((body, chunk_index) => ({
body,
chunk_index
}));
}
/** @internal For testing only */
getStreamMetadata(streamId) {
const row = this.ops.getStream(streamId);
if (!row || !parseChatMetadata(row)) return null;
return {
status: toPublicStatus(row.state),
request_id: row.tag ?? ""
};
}
/** @internal For testing only */
getAllStreamMetadata() {
return this._chatRows().map((row) => ({
id: row.stream_id,
status: toPublicStatus(row.state),
request_id: row.tag ?? "",
created_at: row.created_at,
message_id: row.chat.messageId ?? null
}));
}
/** @internal For testing only */
insertStaleStream(streamId, requestId, ageMs) {
const createdAt = Date.now() - ageMs;
this.ops.importStream({
streamId,
state: "streaming",
tag: requestId,
metadata: { cfChat: 1 },
chunkCount: 0,
createdAt,
updatedAt: createdAt,
closedAt: null
});
}
/**
* 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, body, ageMs) {
this.ops.importChunk(streamId, body, Date.now() - ageMs);
}
};
//#endregion
//#region src/chat/turn-task.ts
/** Durable snapshot key for one chat turn's stash envelope. */
function turnSnapshotKey(runId) {
return `__cf_chat_turn_snapshot:${runId}`;
}
/**
* Build the chat-turn Task handler for one host. Registered under the
* host's `CHAT_FIBER_NAME` via `Tasks#register`.
*/
function createChatTurnTaskDefinition(hooks) {
return async (input, step) => {
const { requestId, nonce } = input;
await step.do("model-turn", {
retries: { limit: 1 },
timeout: "1 day"
}, async ({ signal }) => {
const runId = `chat_${nonce}`;
const snapshotKey = turnSnapshotKey(runId);
const entry = hooks.getLiveClosure(nonce);
if (!entry) {
const persisted = await hooks.storage.get(snapshotKey);
const createdAt = await hooks.getRunCreatedAt(runId) ?? Date.now();
await hooks.handleRecovery({
id: runId,
name: `${hooks.definitionName}:${requestId}`,
snapshot: persisted ?? null,
createdAt,
recoveryReason: "interrupted"
});
await hooks.storage.delete(snapshotKey);
return;
}
await hooks.storage.put(snapshotKey, entry.initial);
try {
const value = await hooks.keepAliveWhile(() => hooks.withStash({
id: nonce,
signal,
stash: (data) => void hooks.storage.put(snapshotKey, entry.wrap(data)).catch(() => {})
}, () => entry.run()));
entry.settle.resolve(value);
} catch (error) {
entry.settle.reject(error);
throw error;
} finally {
hooks.storage.delete(snapshotKey).catch(() => {});
}
});
};
}
//#endregion
//#region src/chat/recovery-task.ts
/**
* Chat recovery transport on the Tasks capability.
*
* Each continuation attempt is one short Task run. The Task waits for any
* requested backoff, dispatches the bounded host callback through model
* handoff, then disappears after terminal settlement. The durable recovery
* incident remains the source of truth for attempt and work budgets.
*
* @internal Sibling-package support for AI Chat and Think.
*/
/** Reserved Task definition shared by the chat hosts. */
const CHAT_RECOVERY_TASK_NAME = "__cf_internal_chat_recovery";
/**
* 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.
*/
async function dispatchChatRecoveryToHandoff(handoff) {
let handedOff = false;
let signalHandoff = () => {};
const reachedTurn = new Promise((resolve) => {
signalHandoff = () => {
handedOff = true;
resolve();
};
});
const turn = handoff.detached(signalHandoff);
const tracked = reachedTurn.then(() => handoff.track(turn));
turn.catch((error) => {
if (!handedOff) return;
if (isPlatformFailure(error)) {
const dedupeKey = crypto.randomUUID();
tryN(3, () => handoff.redefer(dedupeKey), {
baseDelayMs: 50,
maxDelayMs: 500
}).catch((redeferError) => handoff.onDetachedError(redeferError));
return;
}
handoff.onDetachedError(error);
});
await Promise.race([turn, tracked]);
}
function isRecord(value) {
return typeof value === "object" && value !== null && !Array.isArray(value);
}
function parseChatRecoveryTaskInput(input) {
if (!isRecord(input)) throw new Error("Chat recovery Task input must be an object");
const callback = input.callback;
if (callback !== "_chatRecoveryContinue" && callback !== "_chatRecoveryRetry") throw new Error("Chat recovery Task input has an unknown callback");
if (!isRecord(input.data)) throw new Error("Chat recovery Task input data must be an object");
const delaySeconds = input.delaySeconds;
if (typeof delaySeconds !== "number" || !Number.isFinite(delaySeconds) || delaySeconds < 0) throw new Error("Chat recovery Task delaySeconds must be a finite non-negative number");
return {
callback,
data: input.data,
delaySeconds
};
}
/**
* 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.
*/
function chatRecoveryTaskRunOptions(input, reason, dedupeKey) {
const incidentId = typeof input.data.incidentId === "string" ? input.data.incidentId : void 0;
const recoveredRequestId = typeof input.data.recoveredRequestId === "string" ? input.data.recoveredRequestId : void 0;
return {
retain: false,
...dedupeKey !== void 0 ? { runId: dedupeKey } : {},
...reason === "initial" && incidentId ? { idempotencyKey: `chat-recovery:${input.callback}:${incidentId}` } : {},
metadata: {
callback: input.callback,
...incidentId ? { incidentId } : {},
...recoveredRequestId ? { recoveredRequestId } : {}
}
};
}
/** Build the shared recovery Task handler for one chat host. */
function createChatRecoveryTaskDefinition(hooks) {
return async (unknownInput, step) => {
const input = parseChatRecoveryTaskInput(unknownInput);
if (input.delaySeconds > 0) await step.sleep("backoff", input.delaySeconds * 1e3);
await step.do("continuation", {
retries: {
limit: 3,
delay: 100,
backoff: "exponential"
},
timeout: "15 minutes"
}, () => hooks[input.callback](input.data));
};
}
//#endregion
//#region src/chat/sql-batch.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. */
const MAX_BOUND_PARAMS = 100;
/**
* Attach a self-referential `raw` property so a plain string[] satisfies the
* TemplateStringsArray shape. `sql` only reads indexed string fragments, so
* `raw` is never consumed — this just keeps the type system happy.
*/
function asTemplateStringsArray(parts) {
parts.raw = parts;
return parts;
}
/**
* Build a TemplateStringsArray for a single-column `IN (...)` clause. Produces
* fragments for:
* `${prefix}(?, ?, ...)`
*
* @throws if `count` is less than 1.
*/
function buildInClauseStrings(prefix, count) {
if (count < 1) throw new Error(`buildInClauseStrings requires count >= 1 (got ${count})`);
const parts = new Array(count + 1);
parts[0] = `${prefix}(`;
for (let i = 1; i < count; i++) parts[i] = ", ";
parts[count] = ")";
return asTemplateStringsArray(parts);
}
//#endregion
//#region src/chat/client-tools.ts
/**
* Converts client tool schemas to AI SDK tool format.
*
* By default these tools have no `execute` function — when the AI model calls
* them, the tool call is sent back to the client for execution.
*
* When `options.execute` is provided, each tool is built WITH an `execute` that
* delegates to it. This is used by the RPC path (e.g. a parent agent driving a
* Think sub-agent) so the model's client-tool call is resolved inline within
* the same turn.
*
* @param clientTools - Array of tool schemas from the client
* @param options - Optional `execute` delegate to run the tools inline
* @returns Record of AI SDK tools that can be spread into your tools object
*/
function createToolsFromClientSchemas(clientTools, options) {
if (!clientTools || clientTools.length === 0) return {};
const seenNames = /* @__PURE__ */ new Set();
for (const t of clientTools) {
if (seenNames.has(t.name)) console.warn(`[createToolsFromClientSchemas] Duplicate tool name "${t.name}" found. Later definitions will override earlier ones.`);
seenNames.add(t.name);
}
const execute = options?.execute;
const createTool = tool;
return Object.fromEntries(clientTools.map((t) => [t.name, createTool({
description: typeof t.description === "function" ? "" : t.description ?? "",
inputSchema: jsonSchema(t.parameters ?? { type: "object" }),
...execute ? { execute: (input, executeOptions) => execute({
toolName: t.name,
input,
toolCallId: executeOptions?.toolCallId ?? ""
}) } : {}
})]));
}
//#endregion
//#region src/chat/continuation-state.ts
/**
* ContinuationState — shared state container for auto-continuation lifecycle.
*
* Tracks pending, deferred, and active continuation state for the
* tool-result → auto-continue flow. Both AIChatAgent and Think use this
* to manage which connection/tools/body a continuation turn should use
* and to coordinate with clients requesting stream resume.
*
* The scheduling algorithm (prerequisite chaining, debounce, TurnQueue
* enrollment) stays in the host — this class only manages the data.
*/
const MSG_STREAM_RESUME_NONE$1 = CHAT_MESSAGE_TYPES.STREAM_RESUME_NONE;
var ContinuationState = class {
constructor() {
this.pending = null;
this.deferred = null;
this.activeRequestId = null;
this.activeConnectionId = null;
this.awaitingConnections = /* @__PURE__ */ new Map();
}
/** Clear pending state and awaiting connections (without sending RESUME_NONE). */
clearPending() {
this.pending = null;
this.awaitingConnections.clear();
}
clearDeferred() {
this.deferred = null;
}
clearAll() {
this.clearPending();
this.clearDeferred();
this.activeRequestId = null;
this.activeConnectionId = null;
}
/**
* Mark a connection as no longer available without canceling the
* continuation it initiated.
*/
releaseConnection(connectionId) {
this.awaitingConnections.delete(connectionId);
if (this.pending?.connectionId === connectionId) this.pending = {
...this.pending,
connectionId: null
};
if (this.deferred?.connectionId === connectionId) this.deferred = {
...this.deferred,
connectionId: null
};
if (this.activeConnectionId === connectionId) this.activeConnectionId = null;
}
/**
* Send STREAM_RESUME_NONE to all connections waiting for a
* continuation stream to start, then clear the map.
*/
sendResumeNone() {
const msg = JSON.stringify({ type: MSG_STREAM_RESUME_NONE$1 });
for (const connection of this.awaitingConnections.values()) sendIfOpen(connection, msg);
this.awaitingConnections.clear();
}
/**
* Flush awaiting connections by notifying each one via the provided
* callback (typically sends STREAM_RESUMING), then clear.
*/
flushAwaitingConnections(notify) {
for (const connection of this.awaitingConnections.values()) notify(connection);
this.awaitingConnections.clear();
}
/**
* Transition pending → active. Called when the continuation stream
* actually starts. Moves request/connection IDs to active slots,
* clears pending fields.
*/
activatePending() {
if (!this.pending) return;
this.activeRequestId = this.pending.requestId;
this.activeConnectionId = this.pending.connectionId;
this.pending = null;
}
/**
* 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) {
if (this.pending || !this.deferred) return null;
const d = this.deferred;
this.deferred = null;
this.activeRequestId = null;
this.activeConnectionId = null;
this.pending = {
connection: d.connection,
connectionId: d.connectionId,
requestId: generateRequestId(),
clientTools: d.clientTools,
body: d.body,
errorPrefix: d.errorPrefix,
prerequisite: d.prerequisite,
pastCoalesce: false
};
if (d.connectionId !== null) this.awaitingConnections.set(d.connectionId, d.connection);
return this.pending;
}
};
//#endregion
//#region src/chat/pre-stream-turns.ts
/**
* PreStreamTurns — tracks accepted chat turns that have not yet started a
* resumable stream, and the connections parked waiting for one.
*
* The resume handshake can resume an ACTIVE stream (chunks buffering) and can
* replay a TERMINAL outcome, but a normal turn spends a window between "request
* accepted" and "first chunk produced" in neither state: it is queued, waiting
* on `waitForMcpConnections`, debouncing, or simply running async setup inside
* `onChatMessage` before a stream object exists. A client that reconnects or
* re-mounts in that window used to get `cf_agent_stream_resume_none` and give
* up, so the turn the server went on to complete normally never drove the
* client's AI-SDK `status` (issue #1784).
*
* This container lets a host represent that window as resumable: the handshake
* parks the reconnecting connection here (and tells it to keep waiting), and the
* host flushes the parked connections into the normal `STREAM_RESUMING` path the
* moment a stream actually starts — or releases them with `resume_none` if the
* turn settles without ever streaming.
*
* Concurrency-safe under queued turns via an accepted-request set: parked
* connections are only released with `resume_none` once EVERY accepted turn has
* settled with no active stream, so a client parked during the gap between one
* turn finishing and the next starting still resumes onto the next stream.
*
* Pure data + send-through-callback, mirroring {@link ContinuationState}: the
* host owns the actual frame sends and the stream-start / turn-settle wiring.
*
* @internal Sibling-package support for `@cloudflare/ai-chat` and
* `@cloudflare/think`, not a public API.
*/
const MSG_STREAM_PENDING = CHAT_MESSAGE_TYPES.STREAM_PENDING;
const MSG_STREAM_RESUME_NONE = CHAT_MESSAGE_TYPES.STREAM_RESUME_NONE;
var PreStreamTurns = class {
constructor() {
this._accepted = /* @__PURE__ */ new Set();
this.awaitingConnections = /* @__PURE__ */ new Map();
this._latestRequestId = null;
}
/** Mark a freshly-accepted turn as in flight (pre-stream). */
begin(requestId) {
this._accepted.add(requestId);
this._latestRequestId = requestId;
}
/**
* 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) {
this._accepted.delete(requestId);
if (this._accepted.size === 0) {
this._latestRequestId = null;
return true;
}
return false;
}
/** Whether any accepted turn is still pre-stream. */
hasInFlight() {
return this._accepted.size > 0;
}
/** The request id to advertise in the keep-waiting frame, if known. */
get latestRequestId() {
return this._latestRequestId;
}
/**
* 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, probeId) {
if (!this.hasInFlight()) return false;
this.awaitingConnections.set(connection.id, connection);
sendIfOpen(connection, JSON.stringify({
type: MSG_STREAM_PENDING,
...this._latestRequestId ? { id: this._latestRequestId } : {},
...probeId ? { probeId } : {}
}));
return true;
}
/** Drop a single connection (e.g. on socket close) without releasing others. */
release(connectionId) {
this.awaitingConnections.delete(connectionId);
}
/**
* 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) {
for (const connection of this.awaitingConnections.values()) notify(connection);
this.awaitingConnections.clear();
}
/**
* 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() {
const msg = JSON.stringify({ type: MSG_STREAM_RESUME_NONE });
for (const connection of this.awaitingConnections.values()) sendIfOpen(connection, msg);
this.awaitingConnections.clear();
}
/** Drop all state (chat clear / destroy). Does not send any frames. */
reset() {
this._accepted.clear();
this.awaitingConnections.clear();
this._latestRequestId = null;
}
};
//#endregion
//#region src/chat/auto-continuation-controller.ts
var AutoContinuationController = class AutoContinuationController {
constructor(host) {
this.host = host;
this._timer = null;
this._barrierActive = false;
}
/**
* 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) {
const c = this.host.continuation;
if (c.pending?.pastCoalesce) {
c.deferred = {
connection: spec.connection,
connectionId: spec.connection.id,
clientTools: spec.clientTools,
body: spec.body,
errorPrefix: spec.errorPrefix,
prerequisite: null
};
return;
}
if (c.pending) {
c.pending.connection = spec.connection;
c.pending.connectionId = spec.connection.id;
c.pending.clientTools = spec.clientTools;
c.pending.body = spec.body;
c.pending.errorPrefix = spec.errorPrefix;
c.awaitingConnections.set(spec.connection.id, spec.connection);
this.armTimer();
return;
}
c.pending = {
connection: spec.connection,
connectionId: spec.connection.id,
requestId: this.host.generateRequestId(),
clientTools: spec.clientTools,
body: spec.body,
errorPrefix: spec.errorPrefix,
prerequisite: null,
pastCoalesce: false
};
c.awaitingConnections.set(spec.connection.id, spec.connection);
this.armTimer();
}
/**
* 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() {
const pending = this.host.continuation.pending;
if (!pending || pending.pastCoalesce) return;
this.armTimer();
}
/** (Re)arm the coalesce timer; on fire, run {@link fireWhenStable}. */
armTimer() {
if (this._timer) clearTimeout(this._timer);
this._timer = setTimeout(() => {
this._timer = null;
if (!this.host.continuation.pending) return;
this.fireWhenStable();
}, AutoContinuationController.COALESCE_MS);
}
/**
* 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() {
const c = this.host.continuation;
if (!c.pending) return;
if (c.pending.pastCoalesce) return;
if (this._barrierActive) return;
if (this.host.isStreamActive()) return;
if (!this.host.hasPendingInteraction() && !this.host.hasIncompleteToolBatch()) {
this.cancelTimer();
this.host.fire();
return;
}
this._barrierActive = true;
this.host.keepAliveWhile(() => this.host.drainInteractionApplies()).catch(() => {}).finally(() => {
this._barrierActive = false;
const pending = c.pending;
if (!pending || pending.pastCoalesce) return;
if (this.host.isStreamActive()) return;
if (this.host.hasIncompleteToolBatch()) return;
this.cancelTimer();
this.host.fire();
});
}
/**
* 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() {
if (!this.host.continuation.activateDeferred(() => this.host.generateRequestId())) return;
this.fireWhenStable();
}
/**
* 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() {
if (this._timer) {
clearTimeout(this._timer);
this._timer = null;
}
}
/**
* `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() {
return this._timer !== null || this._barrierActive;
}
/**
* 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() {
this.cancelTimer();
this._barrierActive = false;
}
};
AutoContinuationController.COALESCE_MS = 50;
//#endregion
//#region src/chat/abort-registry.ts
/**
* 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.
*/
const NOOP = () => {};
var AbortRegistry = class {
constructor() {
this.controllers = /* @__PURE__ */ new Map();
}
/**
* Get or create an AbortController for the given ID and return its signal.
* Creates the controller lazily on first access.
*/
getSignal(id) {
if (typeof id !== "string") return;
if (!this.controllers.has(id)) this.controllers.set(id, new AbortController());
return this.controllers.get(id).signal;
}
/**
* Get the signal for an existing controller without creating one.
* Returns undefined if no controller exists for this ID.
*/
getExistingSignal(id) {
return this.controllers.get(id)?.signal;
}
/**
* 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, reason) {
this.controllers.get(id)?.abort(reason);
}
/** Remove a controller after the request completes. */
remove(id) {
this.controllers.delete(id);
}
/**
* 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) {
for (const controller of this.controllers.values()) controller.abort(reason);
this.controllers.clear();
}
/** Check if a controller exists for the given ID. */
has(id) {
return this.controllers.has(id);
}
/** Number of tracked controllers. */
get size() {
return this.controllers.size;
}
/**
* 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, signal) {
if (!signal) return NOOP;
if (signal.aborted) {
this.getSignal(id);
this.cancel(id, signal.reason);
return NOOP;
}
const listener = () => this.cancel(id, signal.reason);
signal.addEventListener("abort", listener, { once: true });
return () => signal.removeEventListener("abort", listener);
}
};
//#endregion
//#region src/chat/async-helpers.ts
/**
* @internal Small async control-flow helpers shared by the chat hosts
* (`@cloudflare/ai-chat` and `@cloudflare/think`) — not a public API. Extracted
* so the host idle/stable waits and the interaction-apply completeness drain
* stay byte-identical across both. See `design/chat-shared-layer.md`.
*/
/**
* Sentinel returned by {@link awaitWithDeadline} when the deadline elapses
* before the awaited promise settles. A single shared symbol so both hosts
* compare against the same identity.
*/
const TIMED_OUT = Symbol("timed-out");
/**
* 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.
*/
async function awaitWithDeadline(promise, deadline) {
if (deadline == null) return promise;
const remainingMs = Math.max(0, deadline - Date.now());
let timer;
const result = await Promise.race([promise, new Promise((resolve) => {
timer = setTimeout(() => resolve(TIMED_OUT), remainingMs);
})]);
clearTimeout(timer);
return result;
}
/**
* 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.
*/
async function drainInteractionApplies(hasPending, getTail) {
let tail = getTail();
for (;;) {
if (!hasPending()) return;
try {
await tail;
} catch {}
if (getTail() === tail) return;
tail = getTail();
}
}
//#endregion
//#region src/chat/tool-state.ts
/**
* 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.
*/
function applyToolUpdate(parts, update) {
for (let i = 0; i < parts.length; i++) {
const part = parts[i];
if ("toolCallId" in part && part.toolCallId === update.toolCallId && "state" in part && update.matchStates.includes(part.state)) {
const updatedParts = [...parts];
updatedParts[i] = update.apply(part);
return {
parts: updatedParts,
index: i
};
}
}
return null;
}
/**
* 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).
*/
function toolResultUpdate(toolCallId, output, overrideState, errorText) {
return {
toolCallId,
matchStates: [
"input-available",
"approval-requested",
"approval-responded"
],
apply: (part) => ({
...part,
...overrideState === "output-error" ? {
state: "output-error",
errorText: errorText ?? "Tool execution denied by user"
} : {
state: "output-available",
output,
preliminary: false
}
})
};
}
/**
* Build an update descriptor for a terminal tool result that belongs to a
* tool part in a *different* (earlier) assistant message than the one
* currently being streamed.
*
* This is the "cross-message" case: an approved server tool executes during a
* continuation stream, but its tool part lives in the assistant message that
* originally requested it. `StreamAccumulator` surfaces this as a
* `cross-message-tool-update` action because the accumulator only owns the
* current turn's new content and cannot mutate a part from a prior message.
*
* Compared to {@link toolResultUpdate} this builder is deliberately more
* defensive, mirroring the equivalent fallback in `@cloudflare/ai-chat`:
*
* - It matches the broad set of pre-terminal **and** terminal states, so a
* provider that replays the entire prior tool round-trip during a
* continuation (notably the OpenAI Responses API — issue #1404) still
* resolves to the same part instead of silently missing it.
* - It is **first-write-wins**: a chunk arriving for a tool that already holds
* a terminal result is treated as a replay and the existing output is never
* overwritten. In that case `apply` returns the *same part reference*, which
* callers use as an idempotent-no-op signal to skip the durable write and a
* redundant `MESSAGE_UPDATED` broadcast.
* - It preserves a streamed `preliminary` flag when one is present, otherwise
* marks the result final (`preliminary: false`).
*/
function crossMessageToolResultUpdate(toolCallId, updateType, output, errorText, preliminary) {
return {
toolCallId,
matchStates: [
"input-streaming",
"input-available",
"approval-requested",
"approval-responded",
"output-available",
"output-error",
"output-denied"
],
apply: (part) => {
if (part.state === "output-available" || part.state === "output-error" || part.state === "output-denied") return part;
if (updateType === "output-error") return {
...part,
state: "output-error",
errorText: errorText ?? "Tool execution failed"
};
return {
...part,
state: "output-available",
output,
preliminary: preliminary ?? false
};
}
};
}
/**
* Build an update descriptor 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}.
*/
function pausedExecutionUpdate(toolCallId, executionId, output) {
return {
toolCallId,
matchStates: ["output-available"],
apply: (part) => {
const current = part.output;
if (current == null || typeof current !== "object" || current.status !== "paused" || current.executionId !== executionId) return part;
return {
...part,
output,
preliminary: false
};
}
};
}
/**
* 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).
*/
function toolApprovalUpdate(toolCallId, approved) {
return {
toolCallId,
matchStates: ["input-available", "approval-requested"],
apply: (part) => {
const approval = typeof part.approval === "object" && part.approval !== null && !Array.isArray(part.approval) ? part.approval : void 0;
const approvalId = typeof approval?.id === "string" ? approval.id : toolCallId;
return {
...part,
state: approved ? "approval-responded" : "output-denied",
approval: {
...approval,
id: approvalId,
approved
}
};
}
};
}
/** Extract a tool part's name from its `tool-<name>` / `dynamic-tool` shape. */
function toolPartName(record) {
const type = typeof record.type === "string" ? record.type : "";
if (type === "dynamic-tool") return typeof record.toolName === "string" ? record.toolName : void 0;
if (type.startsWith("tool-")) return type.slice(5);
}
/**
* 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.
*/
function partAwaitsClientInteraction(part, clientResolvable) {
if (typeof part !== "object" || part === null || !("state" in part)) return false;
const record = part;
const state = record.state;
if (state === "approval-requested") return true;
if (state !== "input-available") return false;
const toolName = toolPartName(record);
return toolName != null && clientResolvable.has(toolName);
}
/**
* 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.
*/
function clientResolvableToolNames(tools) {
const names = /* @__PURE__ */ new Set();
for (const tool of tools ?? []) if (tool?.name) names.add(tool.name);
return names;
}
/**
* `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.
*/
function hasIncompleteToolBatch(messages) {
let leaf;
for (let i = messages.length - 1; i >= 0; i--) if (messages[i].role === "assistant") {
leaf = messages[i];
break;
}
if (!leaf) return false;
let hasPending = false;
let hasSettled = false;
for (const part of leaf.parts) {
const record = part;
const state = record.state;
if (state === "input-available" || state === "approval-requested") hasPending = true;
else if (typeof record.type === "string" && (record.type.startsWith("tool-") || record.type === "dynamic-tool") && (state === "output-available" || state === "output-error" || state === "output-denied" || state === "approval-responded")) hasSettled = true;
if (hasPending && hasSettled) return true;
}
return false;
}
//#endregion
//#region src/chat/parse-protocol.ts
/**
* 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.
*/
/**
* 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": { ... }
* }
* ```
*/
function parseProtocolMessage(raw) {
let data;
try {
data = JSON.parse(raw);
} catch {
return null;
}
const wireType = data.type;
if (!wireType) return null;
switch (wireType) {
case CHAT_MESSAGE_TYPES.USE_CHAT_REQUEST: return {
type: "chat-request",
id: data.id,
init: data.init ?? {}
};
case CHAT_MESSAGE_TYPES.CHAT_CLEAR: return { type: "clear" };
case CHAT_MESSAGE_TYPES.CHAT_REQUEST_CANCEL: return {
type: "cancel",
id: data.id
};
case CHAT_MESSAGE_TYPES.TOOL_RESULT: return {
type: "tool-result",
toolCallId: data.toolCallId,
toolName: data.toolName ?? "",
output: data.output,
state: data.state,
errorText: data.errorText,
autoContinue: data.autoContinue,
clientTools: data.clientTools
};
case CHAT_MESSAGE_TYPES.TOOL_APPROVAL: return {
type: "tool-approval",
toolCallId: data.toolCallId,
approved: data.approved,
autoContinue: data.autoContinue
};
case CHAT_MESSAGE_TYPES.STREAM_RESUME_REQUEST: return {
type: "stream-resume-request",
...typeof data.probeId === "string" ? { probeId: data.probeId } : {}
};
case CHAT_MESSAGE_TYPES.STREAM_RESUME_ACK: return {
type: "stream-resume-ack",
id: data.id
};
case CHAT_MESSAGE_TYPES.CHAT_MESSAGES: return {
type: "messages",
messages: data.messages ?? []
};
default: return null;
}
}
//#endregion
//#region src/chat/message-reconciler.ts
/**
* 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
*/
function reconcileMessages(incoming, serverMessages, sanitizeForContentKey) {
return reconcileAssistantIds(mergeServerToolOutputs(incoming, serverMessages), serverMessages, sanitizeForContentKey);
}
/**
* 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.
*/
function resolveToolMergeId(message, serverMessages) {
if (message.role !== "assistant") return message;
for (const part of message.parts) if ("toolCallId" in part && part.toolCallId) {
const toolCallId = part.toolCallId;
const existing = findMessageByToolCallId(serverMessages, toolCallId);
if (existing && existing.id !== message.id) return {
...message,
id: existing.id
};
}
return message;
}
/**
* 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`.
*/
function reconcileOrphanPartial(existing, incoming) {
const existingToolCallIds = new Set(existing.parts.filter((p) => "toolCallId" in p).map((p) => p.toolCallId));
const newParts = incoming.parts.filter((p) => !("toolCallId" in p && existingToolCallIds.has(p.toolCallId)));
const merged = {
...incoming,
parts: [...existing.parts, ...newParts]
};
if (existing.metadata) merged.metadata = incoming.metadata ? {
...existing.metadata,
...incoming.metadata
} : existing.metadata;
return merged;
}
/**
* Content key for assistant messages used for dedup of identical short replies.
* Returns JSON of sanitized parts, or undefined for non-assistant messages.
*/
function assistantContentKey(message, sanitize) {
if (message.role !== "assistant") return;
const sanitized = sanitize ? sanitize(message) : message;
return JSON.stringify(sanitized.parts);
}
function mergeServerToolOutputs(incoming, serverMessages) {
const serverResolvedParts = /* @__PURE__ */ new Map();
for (const msg of serverMessages) {
if (msg.role !== "assistant") continue;
for (const part of msg.parts) {
const record = part;
if ("toolCallId" in record && "state" in record && (record.state === "output-available" || record.state === "output-error" || record.state === "output-denied")) serverResolvedParts.set(record.toolCallId, record);
}
}
if (serverResolvedParts.size === 0) return incoming;
return incoming.map((msg) => {
if (msg.role !== "assistant") return msg;
let hasChanges = false;
const updatedParts = msg.parts.map((part) => {
const record = part;
if ("toolCallId" in record && "state" in record && (record.state === "input-available" || record.state === "approval-requested" || record.state === "approval-responded") && serverResolvedParts.has(record.toolCallId)) {
hasChanges = true;
const server = serverResolvedParts.get(record.toolCallId);
const merged = {
...part,
state: server.state
};
if (server.state === "output-available") {
if ("output" in server) merged.output = server.output;
} else if (server.state === "output-error") {
if ("errorText" in server) merged.errorText = server.errorText;
} else if (server.state === "output-denied") {
if ("approval" in server) merged.approval = server.approval;
}
return merged;
}
return part;
});
return hasChanges ? {
...msg,
parts: updatedParts
} : msg;
});
}
function reconcileAssistantIds(incoming, serverMessages, sanitize) {
if (serverMessages.length === 0) return incoming;
const claimedServerIndices = /* @__PURE__ */ new Set();
const exactMatchMap = /* @__PURE__ */ new Map();
for (let i = 0; i < incoming.length; i++) {
const serverIdx = serverMessages.findIndex((sm, si) => !claimedServerIndices.has(si) && sm.id === incoming[i].id);
if (serverIdx !== -1) {
claimedServerIndices.add(serverIdx);
exactMatchMap.set(i, serverIdx);
}
}
return incoming.map((incomingMessage, incomingIdx) => {
if (exactMatchMap.has(incomingIdx)) return incomingMessage;
if (incomingMessage.role !== "assistant" || hasToolCallPart(incomingMessage)) return incomingMessage;
const incomingKey = assistantContentKey(incomingMessage, sanitize);
if (!incomingKey) return incomingMessage;
for (let i = 0; i < serverMessages.length; i++) {
if (claimedServerIndices.has(i)) continue;
const serverMessage = serverMessages[i];
if (serverMessage.role !== "assistant" || hasToolCallPart(serverMessage)) continue;
if (assistantContentKey(serverMessage, sanitize) === incomingKey) {
claimedServerIndices.add(i);
return {
...incomingMessage,
id: serverMessage.id
};
}
}
return incomingMessage;
});
}
function hasToolCallPart(message) {
return message.parts.some((part) => "toolCallId" in part);
}
function findMessageByToolCallId(messages, toolCallId) {
for (const msg of messages) {
if (msg.role !== "assistant") continue;
for (const part of msg.parts) if ("toolCallId" in part && part.toolCallId === toolCallId) return msg;
}
}
//#endregion
//#region src/chat/repair-transcript.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.
*/
function toolPartHasSettledResult(record) {
if ("output" in record || "result" in record) return true;
const state = typeof record.state === "string" ? record.state : "";
return state === "output-available" || state === "output-error" || state === "output-denied";
}
/**
* 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.
*/
function repairInterruptedToolParts(messages, options) {
const isSettled = options.isSettled ?? toolPartHasSettledResult;
const normalizeInput = options.normalizeInput ?? normalizeToolInput;
const { repairPart } = options;
const shouldRepair = options.shouldRepair ?? (() => true);
let removedToolCalls = 0;
let normalizedInputs = 0;
const toolCallIds = [];
const repaired = [];
for (const message of messages) {
const parts = [];
let messageChanged = false;
for (const part of message.parts) {
const record = part;
const toolCallId = typeof record.toolCallId === "string" ? record.toolCallId : void 0;
if (!(typeof record.type === "string" && (record.type.startsWith("tool-") || record.type === "dynamic-tool") && toolCallId)) {
parts.push(part);
continue;
}
if (!isSettled(record)) {
if ((typeof record.state === "string" ? record.state : "") === "approval-responded") {
parts.push(part);
continue;
}
if (!shouldRepair(part)) {
parts.push(part);
continue;
}
const normalized = normalizeInput("input" in record ? record.input : void 0);
parts.push(repairPart({
...part,
input: normalized.input
}));
if (normalized.changed) normalizedInputs++;
removedToolCalls++;
messageChanged = true;
toolCallIds.push(toolCallId);
continue;
}
const normalized = normalizeInput("input" in record ? record.input : void 0);
if (normalized.changed) {
parts.push({
...part,
input: normalized.input
});
normalizedInputs++;
messageChanged = true;
continue;
}
parts.push(part);
}
repaired.push(messageChanged ? {
...message,
parts
} : message);
}
return {
messages: repaired,
removedToolCalls,
normalizedInputs,
toolCallIds
};
}
//#endregion
//#region src/chat/orphan-persist.ts
/**
* 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`).
*/
async function persistReconstructedOrphan(chunks, options) {
if (chunks.length === 0) return false;
const accumulator = new StreamAccumulator({ messageId: options.fallbackId });
for (const chunk of chunks) try {
accumulator.applyChunk(JSON.parse(chunk.body));
} catch {}
if (accumulator.parts.length === 0) return false;
const prepared = options.prepare(accumulator.toMessage());
if (prepared === null) return false;
const existing = await options.store.getMessage(prepared.id);
if (existing) await options.store.updateMessage(options.merge(existing, prepared));
else await options.store.appendMessage(prepared);
return true;
}
//#endregion
//#region src/chat/recovery.ts
function createChatFiberSnapshot({ kind, requestId, recoveryRootRequestId, continuation, messages, lastBody, lastClientTools }) {
const latestMessage = messages.length > 0 ? messages[messages.length - 1] : void 0;
let latestUser;
for (let index = messages.length - 1; index >= 0; index--) if (messages[index].role === "user") {
latestUser = messages[index];
break;
}
return {
kind,
version: 1,
requestId,
recoveryRootRequestId,
continuation,
latestMessageId: latestMessage?.id,
latestMessageRole: latestMessage?.role,
latestUserMessageId: latestUser?.id,
startedAt: Date.now(),
lastBody,
lastClientTools
};
}
function wrapChatFiberSnapshot(key, snapshot, user) {
return {
[key]: snapshot,
user
};
}
function unwrapChatFiberSnapshot(key, value, expectedKind) {
if (typeof value !== "object" || value === null || !(key in value)) return {
snapshot: null,
user: value
};
const envelope = value;
const snapshot = envelope[key];
if (typeof snapshot !== "object" || snapshot === null) return {
snapshot: null,
user: value
};
const candidate = snapshot;
if (candidate.version !== 1 || expectedKind !== void 0 && candidate.kind !== expectedKind || typeof candidate.requestId !== "string" || typeof candidate.continuation !== "boolean") return {
snapshot: null,
user: value
};
return {
snapshot,
user: envelope.user ?? null
};
}
//#endregion
//#region src/chat/recovery-codec.ts
/**
* `ChatRecoveryCodec` — the streaming-codec seam the recovery engine replays an
* interrupted turn's durable buffer through to reconstruct its partial assistant
* state. The engine and hosts only ever see the wire-agnostic `RecoveryPartial`
* shape (`{ text, parts }`); the codec owns the chunk-vocabulary differences.
*
* Two implementations exist today: {@link AISDKRecoveryCodec} (AI SDK SSE chunks,
* used by `@cloudflare/ai-chat` and `@cloudflare/think`) and `PiRecoveryCodec`
* (the pi `AgentEvent` vocabulary, in the `experimental/pi-recovery` fixture).
* Formalizing the interface here is the proof that the codec — not the engine —
* carries the chunk-shape contract.
*
* @internal Shared chat-recovery internals; not a public API.
*/
/**
* Whether a reconstructed AI SDK `UIMessage` parts array carries any settled
* (provider-accepted) tool result — the completed, often non-idempotent work
* that a `{ persist: false }` recovery return would otherwise silently discard
* (#1631). A part counts as settled when it is a tool part (`tool-*` /
* `dynamic-tool`) carrying an `output`/`result`, or whose state reached a
* terminal `output-{available,error,denied}`.
*
* This is the AI SDK codec's implementation of the per-vocabulary "did this
* partial settle a tool?" question. It lives with {@link AISDKRecoveryCodec}
* (not in the engine) because the codec owns the part vocabulary — the engine
* only ever reads the precomputed `RecoveryPartial.hasSettledToolResults`
* boolean and never names a part type. Foreign codecs (e.g. AG-UI) compute the
* same boolean from their own chunk vocabulary without producing AI SDK parts.
*/
function partialHasSettledToolResults(parts) {
return parts.some((part) => {
const record = part;
const type = typeof record.type === "string" ? record.type : "";
if (!(type.startsWith("tool-") || type === "dynamic-tool")) return false;
if ("output" in record || "result" in record) return true;
const state = typeof record.state === "string" ? record.state : "";
return state === "output-available" || state === "output-error" || state === "output-denied";
});
}
/**
* 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})
* credits at most once per throttle window, so a long single segment still
* registers progress across crashes without writing storage per token;
* - anything else never credits.
*
* Finer than either host's prior cadence in the worst case and never coarser, so
* it can only delay/avoid a false `no_progress_timeout`, never hasten give-up.
*/
function shouldCreditStreamProgress(input) {
const { codec, type, throttle, now } = input;
if (codec.isProgressChunk(type)) return true;
if (codec.isStreamingContentChunk(type)) return throttle.shouldCredit(now);
return false;
}
/**
* The AI SDK codec: replays SSE chunk bodies through {@link getPartialStreamText}
* (`applyChunkToParts` under the hood). Stateless — share the
* {@link aiSdkRecoveryCodec} singleton rather than constructing per call.
*/
var AISDKRecoveryCodec = class {
toRecoveryPartial(bodies) {
const { text, parts } = getPartialStreamText(bodies.map((body) => ({ body })));
return {
text,
parts,
hasSettledToolResults: partialHasSettledToolResults(parts)
};
}
isProgressChunk(type) {
return type === "text-start" || type === "reasoning-start" || type === "tool-input-available" || type === "tool-output-available" || type === "tool-output-error" || type === "tool-output-denied";
}
isStreamingContentChunk(type) {
return type === "text-delta" || type === "reasoning-delta" || type === "tool-input-delta";
}
};
/** Shared stateless {@link AISDKRecoveryCodec} instance. */
const aiSdkRecoveryCodec = new AISDKRecoveryCodec();
//#endregion
//#region src/chat/resume-handshake.ts
/**
* Drives the server side of the stream-resume protocol over a
* {@link ResumeHandshakeHost}. Construct once per agent (the host wires its
* `ResumableStream` / `ContinuationState` / pending set in) and call the three
* public methods from the host's existing onConnect / onMessage wiring, so
* handler registration timing stays host-owned.
*/
var ResumeHandshake = class {
constructor(host) {
this.host = host;
}
/**
* Notify a connection that an active stream can be resumed; it should reply
* with `STREAM_RESUME_ACK` to receive the replay.
*
* A connection can legitimately be notified more than once for the same
* request — proactively from onConnect AND in response to its explicit
* `STREAM_RESUME_REQUEST` (#1733). This is intentional and must NOT be deduped
* here: an explicit request always deserves a response (else the client's
* `reconnectToStream` hangs to its timeout with no replay), and the proactive
* notify is required for clients that never send a request. The notify is one
* tiny frame; the client dedupes its ACK so the buffer is not replayed twice.
* Direct responses echo the opaque probe id; proactive notifications omit it.
*/
notifyStreamResuming(connection, probeId) {
const { resumableStream, pendingResumeConnections } = this.host;
if (!resumableStream.hasActiveStream()) return;
if (sendIfOpen(connection, JSON.stringify({
type: CHAT_MESSAGE_TYPES.STREAM_RESUMING,
id: resumableStream.activeRequestId,
...probeId ? { probeId } : {}
}))) pendingResumeConnections.add(connection.id);
}
/**
* Handle a client `STREAM_RESUME_REQUEST`. The client sends this after its
* message handler is registered, avoiding the race where a proactive
* `STREAM_RESUMING` from onConnect arrives before the handler is ready.
*/
async handleResumeRequest(connection, probeId) {
const { resumableStream, continuation, preStream } = this.host;
if (resumableStream.hasActiveStream()) if (continuation.activeRequestId === resumableStream.activeRequestId && continuation.activeConnectionId !== null && continuation.activeConnectionId !== connection.id && this._ownerStillPresent(continuation.activeConnectionId)) this._sendResumeNone(connection, STREAM_RESUME_NONE_REASONS.CONTINUATION_OWNED, probeId);
else this.notifyStreamResuming(connection, probeId);
else if (continuation.pending !== null && (continuation.pending.connectionId === null || continuation.pending.connectionId === connection.id)) {
continuation.awaitingConnections.set(connection.id, connection);
this._sendStreamPending(connection, continuation.pending.requestId, probeId);
} else if (await this._replayTerminalOnResume(connection, probeId)) {} else if (preStream?.park(connection, probeId)) {} else this._sendResumeNone(connection, STREAM_RESUME_NONE_REASONS.IDLE, probeId);
}
_sendResumeNone(connection, reason, probeId) {
sendIfOpen(connection, JSON.stringify({
type: CHAT_MESSAGE_TYPES.STREAM_RESUME_NONE,
reason,
...probeId ? { probeId } : {}
}));
}
/** Send a keep-waiting `STREAM_PENDING` frame (#1784). */
_sendStreamPending(connection, requestId, probeId) {
sendIfOpen(connection, JSON.stringify({
type: CHAT_MESSAGE_TYPES.STREAM_PENDING,
...requestId ? { id: requestId } : {},
...probeId ? { probeId } : {}
}));
}
/** Whether the active continuation's owner connection is still present. */
_ownerStillPresent(connectionId) {
return this.host.isConnectionPresent ? this.host.isConnectionPresent(connectionId) : true;
}
/** Handle a client `STREAM_RESUME_ACK` for `requestId`. */
async handleResumeAck(connection, requestId) {
const { resumableStream, pendingResumeConnections, responseMessageType } = this.host;
pendingResumeConnections.delete(connection.id);
if (resumableStream.hasActiveStream() && resumableStream.activeRequestId === requestId) {
const orphanedStreamId = resumableStream.replayChunks(connection, resumableStream.activeRequestId);
if (orphanedStreamId) await this.host.persistOrphanedStream(orphanedStreamId);
} else if (resumableStream.hasActiveStream()) {} else if (await this._replayTerminalOnAck(connection, requestId)) {} else if (!resumableStream.replayCompletedChunksByRequestId(connection, requestId)) sendIfOpen(connection, JSON.stringify({
body: "",
done: true,
id: requestId,
type: responseMessageType,
replay: true
}));
}
/**
* Replay a pending terminal outcome (#1645) over the resume handshake so a
* reconnecting client surfaces it exactly like a live exhaustion. The bare
* terminal frame is dropped by the client unless it arrives on a resumed
* stream — the only path that reaches the transport's stream reader and
* becomes `useChat.error` — so we drive `STREAM_RESUMING` here and deliver the
* error frame once the client ACKs (see {@link _replayTerminalOnAck}). Returns
* `true` if a terminal was pending (and `STREAM_RESUMING` was sent).
*/
async _replayTerminalOnResume(connection, probeId) {
const pending = await this.host.pendingChatTerminal();
if (!pending) return false;
sendIfOpen(connection, JSON.stringify({
type: CHAT_MESSAGE_TYPES.STREAM_RESUMING,
id: pending.requestId,
...probeId ? { probeId } : {}
}));
return true;
}
/**
* Deliver the pending terminal error frame on the resumed stream the client
* ACKed (#1645). The record is retained (not cleared) so concurrent reconnects
* (e.g. multiple tabs) each learn the outcome; it is cleared when a later turn
* supersedes it.
*/
async _replayTerminalOnAck(connection, requestId) {
const { resumableStream, responseMessageType } = this.host;
const pending = await this.host.pendingChatTerminal();
if (!pending || pending.requestId !== requestId) return false;
if (!resumableStream.replayErroredChunksByRequestId(connection, pending.requestId)) return true;
sendIfOpen(connection, JSON.stringify({
body: pending.body,
done: true,
error: true,
id: pending.requestId,
type: responseMessageType
}));
return true;
}
};
//#endregion
//#region src/chat/recovery-incident.ts
const CHAT_RECOVERY_INCIDENT_KEY_PREFIX = "cf:chat-recovery:incident:";
/**
* 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.
*/
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).
*/
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.
*/
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).
*/
const DEFAULT_CHAT_RECOVERY_MAX_ATTEMPTS = 10;
/**
* Runaway-loop guard default — the framework-imposed backstop on cumulative
* recovery WORK (produced content/tool units) since an incident opened.
*
* Originally `Infinity` (rfc-chat-recovery-work-budget): the SDK shipped the
* *mechanism* but no default cap, so a progressing turn was never terminated on
* its own. Production issue #1825 showed that this is a footgun: an isolate that
* OOMs mid-stream still credits a little progress before it dies, which resets
* BOTH progress-keyed bounds (the attempt cap and the no-progress window) on
* every wake — and a fast crash loop (each attempt inside the alarm-debounce
* window) pins the attempt counter too. With `maxRecoveryWork = Infinity` the
* ONLY instrument whose meter still climbs across such a loop is disabled, so
* recovery re-runs the turn (and its LLM calls) forever.
*
* A finite default closes that loop out of the box: work climbs regardless of
* debounce/progress resets, so a content-emitting runaway is always sealed with
* `reason="work_budget_exceeded"`. The value is deliberately generous — it
* bounds wasted re-run cost without clipping a normal interrupted turn (work
* only accrues from the first interruption until the turn completes, after which
* the incident is deleted). A very long agentic turn under heavy interruption
* that legitimately needs more should raise `maxRecoveryWork` (or set it to
* `Infinity` to restore the pre-#1825 unbounded behavior).
*
* 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.
*/
const DEFAULT_CHAT_RECOVERY_MAX_WORK = 1e4;
/**
* 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.
*/
const DEFAULT_CHAT_RECOVERY_MAX_OOM_RETRIES = 3;
const DEFAULT_CHAT_RECOVERY_STABLE_TIMEOUT_MS = 1e4;
/**
* 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.
*/
const CHAT_RECOVERY_STABLE_RETRY_DELAY_SECONDS = 3;
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.
*/
const CHAT_RECOVERY_INCIDENT_TTL_MS = 3600 * 1e3;
/** Max keys per Durable Object KV `delete([...])` call. */
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.
*/
const DEFAULT_CHAT_RECOVERY_NO_PROGRESS_TIMEOUT_MS = 300 * 1e3;
/**
* 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.
*/
const CHAT_RECOVERY_ALARM_DEBOUNCE_MS = 30 * 1e3;
/**
* 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.
*/
const CHAT_RECOVERING_FLAG_TTL_MS = 900 * 1e3;
/**
* 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.
*/
function resolveChatRecoveryConfig(raw) {
const custom = typeof raw === "object" && raw !== null ? raw : void 0;
return {
maxAttempts: Math.max(1, Math.floor(custom?.maxAttempts ?? 10)),
stableTimeoutMs: Math.max(0, Math.floor(custom?.stableTimeoutMs ?? 1e4)),
terminalMessage: custom?.terminalMessage ?? "The assistant was interrupted and could not recover. Please try again.",
noProgressTimeoutMs: Math.max(0, Math.floor(custom?.noProgressTimeoutMs ?? 3e5)),
maxRecoveryWork: typeof custom?.maxRecoveryWork === "number" && custom.maxRecoveryWork >= 0 ? custom.maxRecoveryWork : DEFAULT_CHAT_RECOVERY_MAX_WORK,
maxOomRetries: typeof custom?.maxOomRetries === "number" && custom.maxOomRetries >= 0 ? Math.floor(custom.maxOomRetries) : 3,
...custom?.shouldKeepRecovering ? { shouldKeepRecovering: custom.shouldKeepRecovering } : {},
...custom?.onExhausted ? { onExhausted: custom.onExhausted } : {}
};
}
/**
* Stable identifier for a recovery incident.
*
* `recoveryKind` is intentionally NOT part of the identity: a single
* interrupted turn can flip between "retry" (no chunks persisted) and
* "continue" (partial chunks exist) across restarts, and the attempt budget
* must be shared so recovery stays bounded by `maxAttempts`. This formula is a
* cutover invariant.
*/
function chatRecoveryIncidentId(input) {
return [input.recoveryRootRequestId ?? input.requestId, input.latestUserMessageId ?? ""].join(":");
}
/** Durable storage key for an incident record. */
function chatRecoveryIncidentKey(incidentId) {
return `${CHAT_RECOVERY_INCIDENT_KEY_PREFIX}${encodeURIComponent(incidentId)}`;
}
/**
* Select incident keys that have been inactive past the TTL. Pure over a map of
* stored incidents; the caller performs the batched delete.
*/
function selectStaleIncidentKeys(entries, now) {
const staleKeys = [];
for (const [key, incident] of entries) if (now - (incident?.lastAttemptAt ?? incident?.firstSeenAt ?? 0) > 36e5) staleKeys.push(key);
return staleKeys;
}
/**
* 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`.
*/
async function sweepStaleChatRecoveryIncidents(storage, now) {
const staleKeys = selectStaleIncidentKeys(await storage.list({ prefix: CHAT_RECOVERY_INCIDENT_KEY_PREFIX }), now);
for (let i = 0; i < staleKeys.length; i += 128) await storage.delete(staleKeys.slice(i, i + 128));
}
/**
* 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.
*/
async function listActiveChatRecoveryIncidents(storage) {
const entries = await storage.list({ prefix: CHAT_RECOVERY_INCIDENT_KEY_PREFIX });
const active = [];
for (const [key, incident] of entries) if (incident && (incident.status === "detected" || incident.status === "scheduled" || incident.status === "attempting")) active.push({
key,
incident
});
return active;
}
/**
* 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`.
*/
async function classifyAgentToolChildRecovery(storage) {
const entries = await storage.list({ prefix: CHAT_RECOVERY_INCIDENT_KEY_PREFIX });
let failed = false;
for (const incident of entries.values()) {
if (incident.status === "detected" || incident.status === "scheduled" || incident.status === "attempting") return "in-progress";
if (incident.status === "exhausted" || incident.status === "failed") failed = true;
}
return failed ? "failed" : "none";
}
/**
* Read the durable monotonic recovery-progress counter (0 when unset). The value
* feeds the no-progress budget decision; shared by `AIChatAgent` and `Think`.
*/
async function readChatRecoveryProgress(storage) {
return await storage.get("cf:chat-recovery:progress") ?? 0;
}
/**
* Advance the KV progress counter by one.
*
* @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.
*/
async function bumpChatRecoveryProgress(storage) {
const current = await storage.get("cf:chat-recovery:progress") ?? 0;
await storage.put(CHAT_RECOVERY_PROGRESS_KEY, current + 1);
}
/**
* 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.
*/
const AGENT_TOOL_STREAM_PROGRESS_BUMP_THROTTLE_MS = 5e3;
/**
* 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`.
*/
var AgentToolStreamProgressThrottle = class {
constructor() {
this._lastBumpAt = 0;
}
shouldCredit(now) {
if (now - this._lastBumpAt < 5e3) return false;
this._lastBumpAt = now;
return true;
}
};
/**
* 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.
*/
const CHAT_STREAM_PROGRESS_CREDIT_THROTTLE_MS = 5e3;
/**
* 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`.
*/
var StreamProgressCreditThrottle = class {
constructor() {
this._lastBumpAt = 0;
}
shouldCredit(now) {
if (now - this._lastBumpAt < 5e3) return false;
this._lastBumpAt = now;
return true;
}
};
/**
* 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.
*/
async function recordChatTerminal(storage, requestId, body) {
await storage.put(CHAT_LAST_TERMINAL_KEY, {
requestId,
body
});
}
/** Clear the durable terminal record once a later turn supersedes it (#1645). */
async function clearChatTerminal(storage) {
await storage.delete(CHAT_LAST_TERMINAL_KEY);
}
/** Read the pending terminal record, or `null` if none is stored (#1645). */
async function pendingChatTerminal(storage) {
return await storage.get("cf:chat:last-terminal") ?? 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.
*/
async function buildChatRecoveringFrame(storage, messageType, now) {
const recovering = await storage.get(CHAT_RECOVERING_KEY);
if (!recovering || now - (recovering.at ?? 0) >= 9e5) return null;
return {
type: messageType,
recovering: true,
...recovering.requestId ? { id: recovering.requestId } : {}
};
}
/**
* 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.
*/
async function setChatRecovering(active, requestId, deps) {
const { storage, messageType, broadcast, now } = deps;
const existing = await storage.get(CHAT_RECOVERING_KEY);
const activeExisting = existing && now - (existing.at ?? 0) < 9e5;
if (active) {
if (activeExisting) return;
await storage.put(CHAT_RECOVERING_KEY, {
...requestId ? { requestId } : {},
at: now
});
} else {
if (!existing) return;
await storage.delete(CHAT_RECOVERING_KEY);
requestId = requestId ?? existing.requestId;
}
broadcast({
type: messageType,
recovering: active,
...requestId ? { id: requestId } : {}
});
}
/**
* Compute the next recovery incident and budget decision.
*
* This is the durable recovery budget — a faithful extraction of
* `_beginChatRecoveryIncident` from both `AIChatAgent` and `Think`. The
* instruments are decoupled by what they catch:
*
* - STUCK — no-progress window: `lastProgressAt` resets on every
* progress-bearing attempt, so a turn that keeps producing content survives
* churn indefinitely; a stuck turn is sealed after `noProgressTimeoutMs`.
* - DEBOUNCE — alarms bunched within `CHAT_RECOVERY_ALARM_DEBOUNCE_MS` collapse
* into one attempt, so a single rollout's reconnect storm isn't N attempts.
* - ALARM-LOOP — the attempt cap (resets on progress) catches a tight
* no-progress alarm loop.
* - RUNAWAY — the work budget seals a loop that keeps emitting content but
* never converges. Keyed to WORK done, not wall-clock. Defaults to no cap.
* - CALLER — `shouldKeepRecovering` lets the integrator express a
* token/cost/step budget the SDK should not hardcode. Consulted only when no
* hard bound has already sealed the incident, and never on first detection.
*
* A turn parked on a pending client interaction is budget-free: every bound is
* suppressed and the no-progress clock kept fresh.
*/
async function evaluateChatRecoveryIncident(input) {
const { identity, config, existing, currentProgress, awaitingClientInteraction, now } = input;
const incidentId = chatRecoveryIncidentId(identity);
const recoveryRootRequestId = identity.recoveryRootRequestId ?? identity.requestId;
const prevProgress = existing?.progress ?? 0;
const madeProgress = existing != null && currentProgress > prevProgress;
const lastProgressAt = madeProgress || awaitingClientInteraction ? now : existing?.lastProgressAt ?? existing?.firstSeenAt ?? now;
const noProgressExceeded = existing != null && !awaitingClientInteraction && now - lastProgressAt > config.noProgressTimeoutMs;
const workBaseline = existing?.workBaseline ?? currentProgress;
const progress = Math.max(prevProgress, currentProgress);
const work = progress - workBaseline;
const workBudgetExceeded = existing != null && Number.isFinite(config.maxRecoveryWork) && work > config.maxRecoveryWork;
const oomAttempts = existing?.oomAttempts ?? 0;
const oomBudgetExceeded = existing != null && !awaitingClientInteraction && oomAttempts > config.maxOomRetries;
const debounced = existing != null && !madeProgress && now - existing.lastAttemptAt < 3e4;
const attempt = madeProgress ? 1 : debounced ? existing?.attempt ?? 1 : (existing?.attempt ?? 0) + 1;
let abortedByCaller = false;
if (existing != null && !awaitingClientInteraction && config.shouldKeepRecovering && !noProgressExceeded && !workBudgetExceeded && !oomBudgetExceeded && attempt <= config.maxAttempts) try {
const ctx = {
incidentId,
requestId: identity.requestId,
recoveryRootRequestId,
attempt,
maxAttempts: config.maxAttempts,
recoveryKind: identity.recoveryKind,
work,
ageMs: now - (existing.firstSeenAt ?? now)
};
abortedByCaller = await config.shouldKeepRecovering(ctx) === false;
} catch (error) {
input.onShouldKeepRecoveringError?.(error);
}
const exhausted = !awaitingClientInteraction && (oomBudgetExceeded || noProgressExceeded || workBudgetExceeded || abortedByCaller || attempt > config.maxAttempts);
const incident = {
incidentId,
requestId: identity.requestId,
recoveryRootRequestId,
recoveryKind: identity.recoveryKind,
attempt,
maxAttempts: config.maxAttempts,
status: exhausted ? "exhausted" : "attempting",
firstSeenAt: existing?.firstSeenAt ?? now,
lastAttemptAt: now,
lastProgressAt,
progress,
workBaseline,
...oomAttempts > 0 ? { oomAttempts } : {},
...exhausted ? { reason: oomBudgetExceeded ? "out_of_memory" : workBudgetExceeded ? "work_budget_exceeded" : noProgressExceeded ? "no_progress_timeout" : abortedByCaller ? "recovery_aborted" : "max_attempts_exceeded" } : {}
};
const events = [];
if (!existing) events.push({
type: "chat:recovery:detected",
incidentId,
requestId: identity.requestId,
attempt,
maxAttempts: config.maxAttempts,
recoveryKind: identity.recoveryKind
});
events.push({
type: "chat:recovery:attempt",
incidentId,
requestId: identity.requestId,
attempt,
maxAttempts: config.maxAttempts,
recoveryKind: identity.recoveryKind
});
return {
incident,
exhausted,
events
};
}
//#endregion
//#region src/chat/recovery-engine.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.
*/
var ChatRecoveryEngine = class {
constructor(adapter) {
this.adapter = adapter;
}
/**
* 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}.
*/
async handleNonChatFiber(ctx) {
return await this.adapter.tryHandleNonChatFiberRecovery?.(ctx) ?? false;
}
/**
* 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`.
*/
async handleChatFiberRecovery(ctx, wake) {
const { adapter } = this;
if (await this.handleNonChatFiber(ctx)) return true;
const chatPrefix = wake.chatFiberPrefix();
if (!ctx.name.startsWith(chatPrefix)) return false;
const requestId = ctx.name.slice(chatPrefix.length);
const { snapshot, recoveryData } = wake.unwrapRecoverySnapshot(ctx);
const { streamId, streamStillActive, streamStatus } = adapter.resolveRecoveryStream(requestId);
const partial = streamId ? adapter.getPartialStreamText(streamId) : {
text: "",
parts: [],
hasSettledToolResults: false
};
const { recoveryKind, detail } = await wake.classifyRecoveredTurn({
snapshot,
requestId,
streamId,
partial,
streamStillActive,
streamStatus
});
const recoveryRootRequestId = snapshot?.recoveryRootRequestId ?? requestId;
const { incident, config, exhausted } = await this.beginIncident({
requestId,
recoveryRootRequestId,
latestUserMessageId: snapshot?.latestUserMessageId,
recoveryKind
});
if (exhausted) {
if (await this._shouldPersistOrphanedPartial(wake, {
streamId,
streamStillActive,
streamStatus,
snapshot,
options: void 0,
partial
})) await wake.persistOrphanedStream(streamId);
await adapter.exhaustChatRecovery(incident, config, partial, streamId, ctx.createdAt);
return true;
}
try {
const options = await wake.invokeOnChatRecovery?.({
incident,
recoveryKind,
recoveryRootRequestId,
requestId,
streamId,
partial,
snapshot,
recoveryData,
createdAt: ctx.createdAt
}) ?? {};
if (await this._shouldPersistOrphanedPartial(wake, {
streamId,
streamStillActive,
streamStatus,
snapshot,
options,
partial
})) await wake.persistOrphanedStream(streamId);
if (streamStillActive) await wake.completeRecoveredStream(streamId);
await wake.dispatchRecoveredTurn({
incident,
config,
recoveryKind,
options,
snapshot,
requestId,
recoveryRootRequestId,
streamId,
streamStatus,
detail
});
return true;
} catch (error) {
await this.updateIncident(incident.incidentId, "failed", error instanceof Error ? error.message : String(error));
throw error;
}
}
/**
* 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.
*/
async _shouldPersistOrphanedPartial(wake, input) {
return await wake.shouldPersistOrphanedPartial({
streamId: input.streamId,
streamStillActive: input.streamStillActive,
streamStatus: input.streamStatus,
snapshot: input.snapshot
}) && (input.options?.persist !== false || input.partial.hasSettledToolResults);
}
async beginIncident(input) {
const { adapter } = this;
const config = adapter.resolveConfig();
const key = chatRecoveryIncidentKey(chatRecoveryIncidentId(input));
const now = input.nowMs ?? adapter.now();
await adapter.sweepStaleIncidents(now);
const existing = await adapter.getIncident(key);
adapter.ensureInteractionStateLoaded?.();
const { incident, exhausted, events } = await evaluateChatRecoveryIncident({
identity: input,
config,
existing,
currentProgress: await adapter.readProgress(),
awaitingClientInteraction: adapter.isAwaitingClientInteraction?.() ?? false,
now,
onShouldKeepRecoveringError: (error) => adapter.onShouldKeepRecoveringError?.(error)
});
await adapter.putIncident(key, incident);
for (const event of events) adapter.emitRecoveryEvent(event);
return {
incident,
config,
exhausted
};
}
/**
* 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.
*/
async scheduleRecovery(input) {
const { incident } = input;
await this.updateIncident(incident.incidentId, "scheduled");
this.adapter.emitRecoveryEvent({
type: "chat:recovery:scheduled",
incidentId: incident.incidentId,
requestId: incident.requestId,
attempt: incident.attempt,
maxAttempts: incident.maxAttempts,
recoveryKind: input.recoveryKind
});
await this.adapter.scheduleRecovery(input.callback, input.data, input.reason ?? "initial", 0);
}
/**
* 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).
*/
async rescheduleAfterStableTimeout(input) {
const { adapter } = this;
if (!input.incidentId) return false;
const key = chatRecoveryIncidentKey(input.incidentId);
const incident = await adapter.getIncident(key);
if (!incident) return false;
const attempt = incident.attempt ?? 0;
if (attempt >= (incident.maxAttempts ?? input.fallbackMaxAttempts)) return false;
await adapter.putIncident(key, {
...incident,
attempt: attempt + 1,
status: "scheduled",
lastAttemptAt: adapter.now(),
reason: "stable_timeout_retry"
});
await adapter.scheduleRecovery(input.callback, input.data ?? {}, "stable_timeout_retry", 3);
return true;
}
/**
* 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).
*/
async recordOomAndDecide(input) {
const { adapter } = this;
if (!input.incidentId) return "exhausted";
const key = chatRecoveryIncidentKey(input.incidentId);
const incident = await adapter.getIncident(key);
if (!incident) return "exhausted";
const oomAttempts = (incident.oomAttempts ?? 0) + 1;
if (oomAttempts > input.maxOomRetries) {
await adapter.putIncident(key, {
...incident,
oomAttempts,
lastAttemptAt: adapter.now(),
reason: "out_of_memory"
});
return "exhausted";
}
await adapter.putIncident(key, {
...incident,
oomAttempts,
status: "scheduled",
lastAttemptAt: adapter.now(),
reason: "oom_retry"
});
await adapter.scheduleRecovery(input.callback, input.data ?? {}, "stable_timeout_retry", 3);
return "rescheduled";
}
/**
* 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.
*/
async exhaustRecoveryGiveUp(input) {
const { adapter } = this;
const config = adapter.resolveConfig();
const incidentKey = input.data?.incidentId ? chatRecoveryIncidentKey(input.data.incidentId) : null;
let stored = null;
if (incidentKey) try {
stored = await adapter.getIncident(incidentKey);
} catch (readError) {
adapter.onGiveUpBookkeepingError("read", readError);
}
if (stored?.status === "exhausted") return;
const rootRequestId = input.data?.originalRequestId ?? input.data?.recoveredRequestId ?? adapter.activeChatRecoveryRootRequestId() ?? stored?.recoveryRootRequestId ?? stored?.requestId ?? "";
const incident = stored ? {
...stored,
status: "exhausted",
reason: input.reason
} : {
incidentId: input.data?.incidentId ?? crypto.randomUUID(),
requestId: rootRequestId,
recoveryRootRequestId: rootRequestId,
recoveryKind: input.callback === "_chatRecoveryRetry" ? "retry" : "continue",
attempt: config.maxAttempts,
maxAttempts: config.maxAttempts,
status: "exhausted",
firstSeenAt: adapter.now(),
lastAttemptAt: adapter.now(),
reason: input.reason
};
const { streamId } = adapter.resolveRecoveryStream(incident.recoveryRootRequestId ?? incident.requestId);
const partial = streamId ? adapter.getPartialStreamText(streamId) : {
text: "",
parts: [],
hasSettledToolResults: false
};
await adapter.exhaustChatRecovery(incident, config, partial, streamId, incident.firstSeenAt);
if (incidentKey) try {
await adapter.putIncident(incidentKey, incident);
} catch (writeError) {
adapter.onGiveUpBookkeepingError("seal", writeError);
}
}
/**
* 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.
*/
async updateIncident(incidentId, status, reason) {
if (!incidentId) return;
const { adapter } = this;
const key = chatRecoveryIncidentKey(incidentId);
const incident = await adapter.getIncident(key);
if (!incident) return;
if (status === "completed") await adapter.deleteIncident(key);
else await adapter.putIncident(key, {
...incident,
status,
...reason ? { reason } : {}
});
const eventType = status === "completed" ? "chat:recovery:completed" : status === "skipped" ? "chat:recovery:skipped" : status === "failed" ? "chat:recovery:failed" : void 0;
if (eventType) adapter.emitRecoveryEvent({
type: eventType,
incidentId,
requestId: incident.requestId,
attempt: incident.attempt,
maxAttempts: incident.maxAttempts,
recoveryKind: incident.recoveryKind,
...reason ? { reason } : {}
});
if (status === "scheduled") await adapter.setRecovering(true, incident.recoveryRootRequestId ?? incident.requestId);
else if (status === "completed" || status === "skipped" || status === "failed") await adapter.setRecovering(false);
}
};
/**
* Build the `ChatRecoveryExhaustedContext` delivered to `onExhausted` and the
* `chat:recovery:exhausted` event. Pure field-mapping shared by both packages;
* the `reason` falls back to `max_attempts_exceeded` when the incident did not
* record a more specific cause.
*/
function buildChatRecoveryExhaustedContext(input) {
const { incident, config } = input;
return {
incidentId: incident.incidentId,
requestId: incident.requestId,
recoveryRootRequestId: incident.recoveryRootRequestId ?? incident.requestId,
attempt: incident.attempt,
maxAttempts: incident.maxAttempts,
recoveryKind: incident.recoveryKind,
streamId: input.streamId,
createdAt: input.createdAt,
partialText: input.partialText,
partialParts: input.partialParts,
reason: incident.reason ?? "max_attempts_exceeded",
terminalMessage: config.terminalMessage
};
}
/**
* Run the shared exhaustion notification: emit `chat:recovery:exhausted`, then
* invoke the caller's `onExhausted` hook. A throwing hook is swallowed (and
* reported via `onError`) so it can NEVER prevent the caller from delivering
* terminal UX — a tested invariant in both packages. The terminal record /
* banner / submission writes that follow are intentionally package-owned (their
* ordering legitimately diverges), so they are NOT part of this helper.
*/
async function notifyChatRecoveryExhausted(ctx, hooks) {
hooks.emit(ctx);
try {
await hooks.onExhausted?.(ctx);
} catch (error) {
hooks.onError(error);
}
}
/**
* 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.
*/
async function runChatRecoveryExhaustion(input, hooks) {
const ctx = buildChatRecoveryExhaustedContext({
incident: input.incident,
config: input.config,
partialText: input.partialText,
partialParts: input.partialParts,
streamId: input.streamId,
createdAt: input.createdAt
});
await notifyChatRecoveryExhausted(ctx, {
emit: hooks.emit,
onExhausted: hooks.onExhausted,
onError: hooks.onError
});
await hooks.terminalize(ctx);
}
//#endregion
//#region src/chat/stall-watchdog.ts
/**
* Shared inactivity watchdog for UI-message streams.
*
* A model/transport stream can park indefinitely without ever throwing (a hung
* provider, a wedged transport). Left unguarded, the consumer read-loop waits
* forever. {@link iterateWithStallWatchdog} wraps such a stream so that a gap of
* `timeoutMs` between chunks aborts the upstream and throws
* {@link ChatStreamStalledError}, letting the consumer route the stall into
* bounded recovery (#1626) — a transient hang is retried within the existing
* recovery budget — while genuine in-band errors stay terminal.
*
* @internal Sibling-package support for `@cloudflare/ai-chat` and
* `@cloudflare/think`, not a public API. See
* `design/rfc-chat-recovery-foundation.md`.
*/
/**
* Thrown by {@link iterateWithStallWatchdog} when the inactivity watchdog fires
* (a model/transport stream that parks without ever throwing). Distinct from
* in-band model/stream errors so the read-loop catch can route a stall into
* bounded recovery (#1626) — a transient hang is retried within the existing
* recovery budget — while genuine errors stay terminal.
*/
var ChatStreamStalledError = class extends Error {
constructor(message) {
super(message);
this.isChatStreamStall = true;
this.name = "ChatStreamStalledError";
}
};
/**
* Wrap a UI-message stream with an inactivity watchdog. If no chunk arrives
* within `timeoutMs`, `onStall` runs (aborting the upstream model stream) and
* the iterator throws, so the consumer loop exits with a terminal error
* instead of parking forever on a hung provider/transport. `timeoutMs <= 0`
* passes the source through untouched.
*/
async function* iterateWithStallWatchdog(source, timeoutMs, onStall) {
if (!(timeoutMs > 0)) {
yield* source;
return;
}
const iterator = source[Symbol.asyncIterator]();
let selfAborted = false;
try {
while (true) {
let timer;
let stalled = false;
const stall = new Promise((_, reject) => {
timer = setTimeout(() => {
stalled = true;
reject(new ChatStreamStalledError(`Chat stream stalled: no activity for ${timeoutMs}ms; the turn was aborted by the stall watchdog.`));
}, timeoutMs);
});
const nextPromise = iterator.next();
nextPromise.catch(() => {});
let next;
try {
next = await Promise.race([nextPromise, stall]);
} catch (err) {
if (stalled) {
selfAborted = true;
onStall();
}
throw err;
} finally {
if (timer !== void 0) clearTimeout(timer);
}
if (next.done) return;
yield next.value;
}
} finally {
if (!selfAborted) await iterator.return?.(void 0).catch(() => {});
}
}
//#endregion
//#region src/chat/truncate-older-messages.ts
/**
* Read-time context truncation.
*
* Truncates older tool outputs and long text before sending to the LLM.
* Structured tool outputs keep their container shape so tool-specific
* `toModelOutput` handlers can safely replay older results.
* Does NOT mutate stored messages — operates on a copy.
*/
/**
* 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);
* }
* ```
*/
function truncateOlderMessages(messages, options) {
const keepRecent = options?.keepRecent ?? 4;
const maxToolOutput = options?.maxToolOutputChars ?? 500;
const maxText = options?.maxTextChars ?? 1e4;
if (messages.length <= keepRecent) return messages;
const cutoff = messages.length - keepRecent;
const result = [];
for (let i = 0; i < messages.length; i++) {
if (i >= cutoff) {
result.push(messages[i]);
continue;
}
const msg = messages[i];
let changed = false;
const truncatedParts = msg.parts.map((part) => {
if ((part.type.startsWith("tool-") || part.type === "dynamic-tool") && "output" in part) {
const output = part.output;
if (output !== void 0) {
const truncated = truncateToolOutput(output, maxToolOutput);
if (truncated.truncated) {
changed = true;
return {
...part,
output: truncated.output
};
}
}
}
if (part.type === "text" && "text" in part) {
const text = part.text;
if (text.length > maxText) {
changed = true;
return {
...part,
text: `${text.slice(0, maxText)}... [truncated ${text.length} chars]`
};
}
}
return part;
});
result.push(changed ? {
...msg,
parts: truncatedParts
} : msg);
}
return result;
}
//#endregion
export { AGENT_TOOL_STREAM_PROGRESS_BUMP_THROTTLE_MS, AbortRegistry, AgentToolProgressEmitter, AgentToolStreamProgressThrottle, AutoContinuationController, CHAT_LAST_TERMINAL_KEY, CHAT_MESSAGE_TYPES, CHAT_RECOVERING_FLAG_TTL_MS, CHAT_RECOVERING_KEY, CHAT_RECOVERY_ALARM_DEBOUNCE_MS, CHAT_RECOVERY_INCIDENT_KEY_PREFIX, CHAT_RECOVERY_INCIDENT_TTL_MS, CHAT_RECOVERY_PROGRESS_KEY, CHAT_RECOVERY_STABLE_RETRY_DELAY_SECONDS, CHAT_RECOVERY_TASK_NAME, CHAT_STREAM_PROGRESS_CREDIT_THROTTLE_MS, ChatRecoveryEngine, ChatStreamStalledError, ContinuationState, DEFAULT_CHAT_RECOVERY_MAX_ATTEMPTS, DEFAULT_CHAT_RECOVERY_MAX_OOM_RETRIES, DEFAULT_CHAT_RECOVERY_MAX_WORK, DEFAULT_CHAT_RECOVERY_NO_PROGRESS_TIMEOUT_MS, DEFAULT_CHAT_RECOVERY_STABLE_TIMEOUT_MS, DEFAULT_CHAT_RECOVERY_TERMINAL_MESSAGE, KV_DELETE_MAX_KEYS, MAX_BOUND_PARAMS, MessageType, PreStreamTurns, ROW_MAX_BYTES, ResumableStream, ResumeHandshake, STREAM_RESUME_NONE_REASONS, StreamAccumulator, StreamProgressCreditThrottle, SubmitConcurrencyController, TIMED_OUT, TextSegmentJoiner, TurnQueue, aiSdkRecoveryCodec, applyAgentToolEvent, applyChunkToParts, applyToolUpdate, awaitWithDeadline, transition as broadcastTransition, buildChatRecoveringFrame, buildInClauseStrings, bumpChatRecoveryProgress, byteLength, chatRecoveryTaskRunOptions, classifyAgentToolChildRecovery, clearChatTerminal, clientResolvableToolNames, createAgentToolEventState, createChatFiberSnapshot, createChatRecoveryTaskDefinition, createChatStreams, createChatTurnTaskDefinition, createToolsFromClientSchemas, crossMessageToolResultUpdate, dispatchChatRecoveryToHandoff, drainInteractionApplies, enforceRowSizeLimit, hasIncompleteToolBatch, interceptAgentToolBroadcast, isPlatformFailure, isReplayChunk, iterateWithStallWatchdog, listActiveChatRecoveryIncidents, normalizeToolInput, parseProtocolMessage, partAwaitsClientInteraction, pausedExecutionUpdate, pendingChatTerminal, persistReconstructedOrphan, readChatRecoveryProgress, reconcileMessages, reconcileOrphanPartial, recordChatTerminal, repairInterruptedToolParts, resolveChatRecoveryConfig, resolveToolMergeId, runChatRecoveryExhaustion, sanitizeMessage, sendIfOpen, setChatRecovering, shouldCreditStreamProgress, sweepStaleChatRecoveryIncidents, toolApprovalUpdate, toolPartHasSettledResult, toolResultUpdate, truncateOlderMessages, unwrapChatFiberSnapshot, wrapChatFiberSnapshot };
//# sourceMappingURL=index.js.map