agents 0.9.0 → 0.10.0

package/dist/chat/index.d.ts

@@ -307,7 +307,8 @@ declare class ResumableStream {
   replayChunks(connection: Connection, requestId: string): string | null;
   /**
    * Restore active stream state if the agent was restarted during streaming.
-   * Validates stream freshness to avoid sending stale resume notifications.
+   * All streams are restored regardless of age — stale cleanup happens
+   * lazily in _maybeCleanupOldStreams after recovery has had its chance.
    */
   restore(): void;
   /**
@@ -450,5 +451,153 @@ declare class ContinuationState {
   activateDeferred(generateRequestId: () => string): ContinuationPending | null;
 }
 //#endregion
-export { type BroadcastStreamEvent, type BroadcastStreamState, type TransitionResult as BroadcastTransitionResult, CHAT_MESSAGE_TYPES, type ChunkAction, type ChunkResult, type ClientToolSchema, type ContinuationConnection, type ContinuationDeferred, type ContinuationPending, ContinuationState, type EnqueueOptions, type MessagePart, type MessageParts, ROW_MAX_BYTES, ResumableStream, type SqlTaggedTemplate, StreamAccumulator, type StreamAccumulatorOptions, type StreamChunkData, TurnQueue, type TurnResult, applyChunkToParts, transition as broadcastTransition, byteLength, createToolsFromClientSchemas, enforceRowSizeLimit, sanitizeMessage };
+//#region src/chat/abort-registry.d.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.
+ */
+declare class AbortRegistry {
+  private controllers;
+  /**
+   * Get or create an AbortController for the given ID and return its signal.
+   * Creates the controller lazily on first access.
+   */
+  getSignal(id: string): AbortSignal | undefined;
+  /**
+   * Get the signal for an existing controller without creating one.
+   * Returns undefined if no controller exists for this ID.
+   */
+  getExistingSignal(id: string): AbortSignal | undefined;
+  /** Cancel a specific request by aborting its controller. */
+  cancel(id: string): void;
+  /** Remove a controller after the request completes. */
+  remove(id: string): void;
+  /** Abort all pending requests and clear the registry. */
+  destroyAll(): void;
+  /** Check if a controller exists for the given ID. */
+  has(id: string): boolean;
+  /** Number of tracked controllers. */
+  get size(): number;
+}
+//#endregion
+//#region src/chat/tool-state.d.ts
+/**
+ * Tool State — shared update builders and applicator for tool part state changes.
+ *
+ * Used by both AIChatAgent and Think to apply tool results and approvals
+ * to message parts. Each agent handles find-message, persist, and broadcast
+ * in their own way; this module provides the state matching and update logic.
+ */
+/**
+ * Describes an update to apply to a tool part.
+ */
+type ToolPartUpdate = {
+  toolCallId: string;
+  matchStates: string[];
+  apply: (part: Record<string, unknown>) => Record<string, unknown>;
+};
+/**
+ * Apply a tool part update to a parts array.
+ * Finds the first part matching `update.toolCallId` in one of `update.matchStates`,
+ * applies the update immutably, and returns the new parts array with the index.
+ *
+ * Returns `null` if no matching part was found.
+ */
+declare function applyToolUpdate(parts: Array<Record<string, unknown>>, update: ToolPartUpdate): {
+  parts: Array<Record<string, unknown>>;
+  index: number;
+} | 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).
+ */
+declare function toolResultUpdate(toolCallId: string, output: unknown, overrideState?: "output-error", errorText?: string): ToolPartUpdate;
+/**
+ * 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).
+ */
+declare function toolApprovalUpdate(toolCallId: string, approved: boolean): ToolPartUpdate;
+//#endregion
+//#region src/chat/parse-protocol.d.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.
+ */
+/**
+ * Discriminated union of all incoming chat protocol events.
+ *
+ * Each agent handles the events it cares about and ignores the rest.
+ * Returns `null` for non-JSON messages or unrecognized types.
+ */
+type ChatProtocolEvent = {
+  type: "chat-request";
+  id: string;
+  init: {
+    method?: string;
+    body?: string;
+    [key: string]: unknown;
+  };
+} | {
+  type: "clear";
+} | {
+  type: "cancel";
+  id: string;
+} | {
+  type: "tool-result";
+  toolCallId: string;
+  toolName: string;
+  output: unknown;
+  state?: string;
+  errorText?: string;
+  autoContinue?: boolean;
+  clientTools?: Array<{
+    name: string;
+    description?: string;
+    parameters?: unknown;
+  }>;
+} | {
+  type: "tool-approval";
+  toolCallId: string;
+  approved: boolean;
+  autoContinue?: boolean;
+} | {
+  type: "stream-resume-request";
+} | {
+  type: "stream-resume-ack";
+  id: string;
+} | {
+  type: "messages";
+  messages: unknown[];
+};
+/**
+ * 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": { ... }
+ * }
+ * ```
+ */
+declare function parseProtocolMessage(raw: string): ChatProtocolEvent | null;
+//#endregion
+export { AbortRegistry, type BroadcastStreamEvent, type BroadcastStreamState, type TransitionResult as BroadcastTransitionResult, CHAT_MESSAGE_TYPES, type ChatProtocolEvent, type ChunkAction, type ChunkResult, type ClientToolSchema, type ContinuationConnection, type ContinuationDeferred, type ContinuationPending, ContinuationState, type EnqueueOptions, type MessagePart, type MessageParts, ROW_MAX_BYTES, ResumableStream, type SqlTaggedTemplate, StreamAccumulator, type StreamAccumulatorOptions, type StreamChunkData, type ToolPartUpdate, TurnQueue, type TurnResult, applyChunkToParts, applyToolUpdate, transition as broadcastTransition, byteLength, createToolsFromClientSchemas, enforceRowSizeLimit, parseProtocolMessage, sanitizeMessage, toolApprovalUpdate, toolResultUpdate };
 //# sourceMappingURL=index.d.ts.map

package/dist/chat/index.js

@@ -657,8 +657,6 @@ const CHAT_MESSAGE_TYPES = {
 const CHUNK_BUFFER_SIZE = 10;
 /** Maximum buffer size to prevent memory issues on rapid reconnections */
 const CHUNK_BUFFER_MAX_SIZE = 100;
-/** Maximum age for a "streaming" stream before considering it stale (ms) - 5 minutes */
-const STREAM_STALE_THRESHOLD_MS = 300 * 1e3;
 /** Default cleanup interval for old streams (ms) - every 10 minutes */
 const CLEANUP_INTERVAL_MS = 600 * 1e3;
 /** Default age threshold for cleaning up completed streams (ms) - 24 hours */
@@ -870,7 +868,8 @@ var ResumableStream = class ResumableStream {
 	}
 	/**
 	* Restore active stream state if the agent was restarted during streaming.
-	* Validates stream freshness to avoid sending stale resume notifications.
+	* All streams are restored regardless of age — stale cleanup happens
+	* lazily in _maybeCleanupOldStreams after recovery has had its chance.
 	*/
 	restore() {
 		const activeStreams = this.sql`
@@ -881,13 +880,6 @@ var ResumableStream = class ResumableStream {
     `;
 		if (activeStreams && activeStreams.length > 0) {
 			const stream = activeStreams[0];
-			const streamAge = Date.now() - stream.created_at;
-			if (streamAge > STREAM_STALE_THRESHOLD_MS) {
-				this.sql`delete from cf_ai_chat_stream_chunks where stream_id = ${stream.id}`;
-				this.sql`delete from cf_ai_chat_stream_metadata where id = ${stream.id}`;
-				console.warn(`[ResumableStream] Deleted stale stream ${stream.id} (age: ${Math.round(streamAge / 1e3)}s)`);
-				return;
-			}
 			this._activeStreamId = stream.id;
 			this._activeRequestId = stream.request_id;
 			const lastChunk = this.sql`
@@ -934,6 +926,17 @@ var ResumableStream = class ResumableStream {
 		this.sql`
       delete from cf_ai_chat_stream_metadata 
       where status in ('completed', 'error') and completed_at < ${cutoff}
+    `;
+		this.sql`
+      delete from cf_ai_chat_stream_chunks
+      where stream_id in (
+        select id from cf_ai_chat_stream_metadata
+        where status = 'streaming' and created_at < ${cutoff}
+      )
+    `;
+		this.sql`
+      delete from cf_ai_chat_stream_metadata
+      where status = 'streaming' and created_at < ${cutoff}
     `;
 	}
 	/** @internal For testing only */
@@ -1081,6 +1084,202 @@ var ContinuationState = class {
 	}
 };
 //#endregion
-export { CHAT_MESSAGE_TYPES, ContinuationState, ROW_MAX_BYTES, ResumableStream, StreamAccumulator, TurnQueue, applyChunkToParts, transition as broadcastTransition, byteLength, createToolsFromClientSchemas, enforceRowSizeLimit, sanitizeMessage };
+//#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.
+*/
+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. */
+	cancel(id) {
+		this.controllers.get(id)?.abort();
+	}
+	/** Remove a controller after the request completes. */
+	remove(id) {
+		this.controllers.delete(id);
+	}
+	/** Abort all pending requests and clear the registry. */
+	destroyAll() {
+		for (const controller of this.controllers.values()) controller.abort();
+		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;
+	}
+};
+//#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 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) => ({
+			...part,
+			state: approved ? "approval-responded" : "output-denied",
+			approval: {
+				...part.approval,
+				approved
+			}
+		})
+	};
+}
+//#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" };
+		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
+export { AbortRegistry, CHAT_MESSAGE_TYPES, ContinuationState, ROW_MAX_BYTES, ResumableStream, StreamAccumulator, TurnQueue, applyChunkToParts, applyToolUpdate, transition as broadcastTransition, byteLength, createToolsFromClientSchemas, enforceRowSizeLimit, parseProtocolMessage, sanitizeMessage, toolApprovalUpdate, toolResultUpdate };
 
 //# sourceMappingURL=index.js.map