agents 0.8.7 → 0.10.0

package/dist/chat/index.d.ts

@@ -0,0 +1,603 @@
+import { JSONSchema7, Tool, ToolSet, UIMessage } from "ai";
+import { Connection } from "agents";
+
+//#region src/chat/message-builder.d.ts
+/** The parts array type from UIMessage */
+type MessageParts = UIMessage["parts"];
+/** A single part from the UIMessage parts array */
+type MessagePart = MessageParts[number];
+/**
+ * Parsed chunk data from an AI SDK stream event.
+ * This is the JSON-parsed body of a CF_AGENT_USE_CHAT_RESPONSE message,
+ * or the `data:` payload of an SSE line.
+ */
+type StreamChunkData = {
+  type: string;
+  id?: string;
+  delta?: string;
+  text?: string;
+  mediaType?: string;
+  url?: string;
+  sourceId?: string;
+  title?: string;
+  filename?: string;
+  toolCallId?: string;
+  toolName?: string;
+  input?: unknown;
+  inputTextDelta?: string;
+  output?: unknown;
+  state?: string;
+  errorText?: string; /** When true, the output is preliminary (may be updated by a later chunk) */
+  preliminary?: boolean; /** Approval ID for tools with needsApproval */
+  approvalId?: string;
+  providerMetadata?: Record<string, unknown>; /** Whether the tool was executed by the provider (e.g. Gemini code execution) */
+  providerExecuted?: boolean; /** Payload for data-* parts (developer-defined typed JSON) */
+  data?: unknown; /** When true, data parts are ephemeral and not persisted to message.parts */
+  transient?: boolean; /** Message ID assigned by the server at stream start */
+  messageId?: string; /** Per-message metadata attached by start/finish/message-metadata chunks */
+  messageMetadata?: unknown;
+  [key: string]: unknown;
+};
+/**
+ * Applies a stream chunk to a mutable parts array, building up the message
+ * incrementally. Returns true if the chunk was handled, false if it was
+ * an unrecognized type (caller may handle it with additional logic).
+ *
+ * Handles all common chunk types that both server and client need:
+ * - text-start / text-delta / text-end
+ * - reasoning-start / reasoning-delta / reasoning-end
+ * - file
+ * - source-url / source-document
+ * - tool-input-start / tool-input-delta / tool-input-available / tool-input-error
+ * - tool-output-available / tool-output-error
+ * - step-start (aliased from start-step)
+ * - data-* (developer-defined typed JSON blobs)
+ *
+ * @param parts - The mutable parts array to update
+ * @param chunk - The parsed stream chunk data
+ * @returns true if handled, false if the chunk type is not recognized
+ */
+declare function applyChunkToParts(parts: MessagePart[], chunk: StreamChunkData): boolean;
+//#endregion
+//#region src/chat/sanitize.d.ts
+/** Maximum serialized message size before compaction (bytes). 1.8MB with headroom below SQLite's 2MB limit. */
+declare const ROW_MAX_BYTES = 1800000;
+/** Measure UTF-8 byte length of a string. */
+declare function byteLength(s: string): number;
+/**
+ * Sanitize a message for persistence by removing ephemeral provider-specific
+ * data that should not be stored or sent back in subsequent requests.
+ *
+ * 1. Strips OpenAI ephemeral fields (itemId, reasoningEncryptedContent)
+ * 2. Filters truly empty reasoning parts (no text, no remaining providerMetadata)
+ */
+declare function sanitizeMessage(message: UIMessage): UIMessage;
+/**
+ * Enforce SQLite row size limits by compacting tool outputs and text parts
+ * when a serialized message exceeds the safety threshold (1.8MB).
+ *
+ * Compaction strategy:
+ * 1. Compact tool outputs over 1KB (replace with summary)
+ * 2. If still too big, truncate text parts from oldest to newest
+ */
+declare function enforceRowSizeLimit(message: UIMessage): UIMessage;
+//#endregion
+//#region src/chat/stream-accumulator.d.ts
+interface StreamAccumulatorOptions {
+  messageId: string;
+  continuation?: boolean;
+  existingParts?: UIMessage["parts"];
+  existingMetadata?: Record<string, unknown>;
+}
+type ChunkAction = {
+  type: "start";
+  messageId?: string;
+  metadata?: Record<string, unknown>;
+} | {
+  type: "finish";
+  finishReason?: string;
+  metadata?: Record<string, unknown>;
+} | {
+  type: "message-metadata";
+  metadata: Record<string, unknown>;
+} | {
+  type: "tool-approval-request";
+  toolCallId: string;
+} | {
+  type: "cross-message-tool-update";
+  updateType: "output-available" | "output-error";
+  toolCallId: string;
+  output?: unknown;
+  errorText?: string;
+  preliminary?: boolean;
+} | {
+  type: "error";
+  error: string;
+};
+interface ChunkResult {
+  handled: boolean;
+  action?: ChunkAction;
+}
+declare class StreamAccumulator {
+  messageId: string;
+  readonly parts: UIMessage["parts"];
+  metadata?: Record<string, unknown>;
+  private _isContinuation;
+  constructor(options: StreamAccumulatorOptions);
+  applyChunk(chunk: StreamChunkData): ChunkResult;
+  /** Snapshot the current state as a UIMessage. */
+  toMessage(): UIMessage;
+  /**
+   * Merge this accumulator's message into an existing message array.
+   * Handles continuation (walk backward for last assistant), replacement
+   * (update existing by messageId), or append (new message).
+   */
+  mergeInto(messages: UIMessage[]): UIMessage[];
+}
+//#endregion
+//#region src/chat/turn-queue.d.ts
+/**
+ * TurnQueue — serial async queue with generation-based invalidation.
+ *
+ * Serializes async work via a promise chain, tracks which request is
+ * currently active, and lets callers invalidate all queued work by
+ * advancing a generation counter.
+ *
+ * Used by @cloudflare/ai-chat (full concurrency policy spectrum) and
+ * @cloudflare/think (simple serial queue) to prevent overlapping
+ * chat turns.
+ */
+type TurnResult<T> = {
+  status: "completed";
+  value: T;
+} | {
+  status: "stale";
+};
+interface EnqueueOptions {
+  /**
+   * Generation to bind this turn to. Defaults to the current generation
+   * at the time of the `enqueue` call. If the queue's generation has
+   * advanced past this value by the time the turn reaches the front,
+   * `fn` is not called and `{ status: "stale" }` is returned.
+   */
+  generation?: number;
+}
+declare class TurnQueue {
+  private _queue;
+  private _generation;
+  private _activeRequestId;
+  private _countsByGeneration;
+  get generation(): number;
+  get activeRequestId(): string | null;
+  get isActive(): boolean;
+  enqueue<T>(requestId: string, fn: () => Promise<T>, options?: EnqueueOptions): Promise<TurnResult<T>>;
+  /**
+   * Advance the generation counter. All turns enqueued under older
+   * generations will be skipped when they reach the front of the queue.
+   */
+  reset(): void;
+  /**
+   * Wait until the queue is fully drained (no pending or active turns).
+   */
+  waitForIdle(): Promise<void>;
+  /**
+   * Number of active + queued turns for a given generation.
+   * Defaults to the current generation.
+   */
+  queuedCount(generation?: number): number;
+  private _decrementCount;
+}
+//#endregion
+//#region src/chat/broadcast-state.d.ts
+type BroadcastStreamState = {
+  status: "idle";
+} | {
+  status: "observing";
+  streamId: string;
+  accumulator: StreamAccumulator;
+};
+type BroadcastStreamEvent = {
+  type: "response";
+  streamId: string; /** Fallback message ID for a new accumulator (ignored if one exists for this stream). */
+  messageId: string;
+  chunkData?: unknown;
+  done?: boolean;
+  error?: boolean;
+  replay?: boolean;
+  replayComplete?: boolean;
+  continuation?: boolean; /** Required when continuation=true so the accumulator can pick up existing parts. */
+  currentMessages?: UIMessage[];
+} | {
+  type: "resume-fallback";
+  streamId: string;
+  messageId: string;
+} | {
+  type: "clear";
+};
+interface TransitionResult {
+  state: BroadcastStreamState;
+  messagesUpdate?: (prev: UIMessage[]) => UIMessage[];
+  isStreaming: boolean;
+}
+declare function transition(state: BroadcastStreamState, event: BroadcastStreamEvent): TransitionResult;
+//#endregion
+//#region src/chat/resumable-stream.d.ts
+/**
+ * Minimal SQL interface matching Agent's this.sql tagged template.
+ * Allows ResumableStream to work with the Agent's SQLite without
+ * depending on the full Agent class.
+ */
+type SqlTaggedTemplate = {
+  <T = Record<string, unknown>>(strings: TemplateStringsArray, ...values: (string | number | boolean | null)[]): T[];
+};
+declare class ResumableStream {
+  private sql;
+  private _activeStreamId;
+  private _activeRequestId;
+  private _streamChunkIndex;
+  /**
+   * Whether the active stream was started in this instance (true) or
+   * restored from SQLite after hibernation/restart (false). An orphaned
+   * stream has no live LLM reader — the ReadableStream was lost when the
+   * DO was evicted.
+   */
+  private _isLive;
+  private _chunkBuffer;
+  private _isFlushingChunks;
+  private _lastCleanupTime;
+  constructor(sql: SqlTaggedTemplate);
+  get activeStreamId(): string | null;
+  get activeRequestId(): string | null;
+  hasActiveStream(): boolean;
+  /**
+   * Whether the active stream has a live LLM reader (started in this
+   * instance) vs being restored from SQLite after hibernation (orphaned).
+   */
+  get isLive(): boolean;
+  /**
+   * Start tracking a new stream for resumable streaming.
+   * Creates metadata entry in SQLite and sets up tracking state.
+   * @param requestId - The unique ID of the chat request
+   * @returns The generated stream ID
+   */
+  start(requestId: string): string;
+  /**
+   * Mark a stream as completed and flush any pending chunks.
+   * @param streamId - The stream to mark as completed
+   */
+  complete(streamId: string): void;
+  /**
+   * Mark a stream as errored and clean up state.
+   * @param streamId - The stream to mark as errored
+   */
+  markError(streamId: string): void;
+  /** Maximum chunk body size before skipping storage (bytes). Prevents SQLite row limit crash. */
+  private static CHUNK_MAX_BYTES;
+  /**
+   * Buffer a stream chunk for batch write to SQLite.
+   * 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: string, body: string): void;
+  /**
+   * Flush buffered chunks to SQLite in a single batch.
+   * Uses a lock to prevent concurrent flush operations.
+   */
+  flushBuffer(): void;
+  /**
+   * 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.
+   * - **Completed during replay** (defensive): sends chunks + `done`.
+   *
+   * @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: Connection, requestId: string): string | null;
+  /**
+   * 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(): void;
+  /**
+   * Clear all stream data (called on chat history clear).
+   */
+  clearAll(): void;
+  /**
+   * Drop all stream tables (called on destroy).
+   */
+  destroy(): void;
+  private _maybeCleanupOldStreams;
+  /** @internal For testing only */
+  getStreamChunks(streamId: string): Array<{
+    body: string;
+    chunk_index: number;
+  }>;
+  /** @internal For testing only */
+  getStreamMetadata(streamId: string): {
+    status: string;
+    request_id: string;
+  } | null;
+  /** @internal For testing only */
+  getAllStreamMetadata(): Array<{
+    id: string;
+    status: string;
+    request_id: string;
+    created_at: number;
+  }>;
+  /** @internal For testing only */
+  insertStaleStream(streamId: string, requestId: string, ageMs: number): void;
+}
+//#endregion
+//#region src/chat/client-tools.d.ts
+/**
+ * Wire-format tool schema sent from the client.
+ * Uses `parameters` (JSONSchema7) rather than AI SDK's `inputSchema`
+ * because Zod schemas cannot be serialized over the wire.
+ */
+type ClientToolSchema = {
+  /** Unique name for the tool */name: string; /** Human-readable description of what the tool does */
+  description?: Tool["description"]; /** JSON Schema defining the tool's input parameters */
+  parameters?: JSONSchema7;
+};
+/**
+ * Converts client tool schemas to AI SDK tool format.
+ *
+ * These tools have no `execute` function — when the AI model calls them,
+ * the tool call is sent back to the client for execution.
+ *
+ * @param clientTools - Array of tool schemas from the client
+ * @returns Record of AI SDK tools that can be spread into your tools object
+ */
+declare function createToolsFromClientSchemas(clientTools?: ClientToolSchema[]): ToolSet;
+//#endregion
+//#region src/chat/protocol.d.ts
+/**
+ * Wire protocol message type constants for the cf_agent_chat_* protocol.
+ *
+ * These are the string values used on the wire between agent servers and
+ * clients. Both @cloudflare/ai-chat (via its MessageType enum) and
+ * @cloudflare/think use these values.
+ */
+declare const CHAT_MESSAGE_TYPES: {
+  readonly CHAT_MESSAGES: "cf_agent_chat_messages";
+  readonly USE_CHAT_REQUEST: "cf_agent_use_chat_request";
+  readonly USE_CHAT_RESPONSE: "cf_agent_use_chat_response";
+  readonly CHAT_CLEAR: "cf_agent_chat_clear";
+  readonly CHAT_REQUEST_CANCEL: "cf_agent_chat_request_cancel";
+  readonly STREAM_RESUMING: "cf_agent_stream_resuming";
+  readonly STREAM_RESUME_ACK: "cf_agent_stream_resume_ack";
+  readonly STREAM_RESUME_REQUEST: "cf_agent_stream_resume_request";
+  readonly STREAM_RESUME_NONE: "cf_agent_stream_resume_none";
+  readonly TOOL_RESULT: "cf_agent_tool_result";
+  readonly TOOL_APPROVAL: "cf_agent_tool_approval";
+  readonly MESSAGE_UPDATED: "cf_agent_message_updated";
+};
+//#endregion
+//#region src/chat/continuation-state.d.ts
+/**
+ * Minimal connection interface for sending WebSocket messages.
+ * Matches the Connection type from agents without importing it.
+ * Uses a permissive send signature so Connection (which extends
+ * WebSocket with its own send overload) is structurally assignable.
+ */
+interface ContinuationConnection {
+  readonly id: string;
+  send(message: string): void;
+}
+interface ContinuationPending {
+  connection: ContinuationConnection;
+  connectionId: string;
+  requestId: string;
+  clientTools?: ClientToolSchema[];
+  body?: Record<string, unknown>;
+  errorPrefix: string | null;
+  prerequisite: Promise<boolean> | null;
+  pastCoalesce: boolean;
+}
+interface ContinuationDeferred {
+  connection: ContinuationConnection;
+  connectionId: string;
+  clientTools?: ClientToolSchema[];
+  body?: Record<string, unknown>;
+  errorPrefix: string;
+  prerequisite: Promise<boolean> | null;
+}
+declare class ContinuationState {
+  pending: ContinuationPending | null;
+  deferred: ContinuationDeferred | null;
+  activeRequestId: string | null;
+  activeConnectionId: string | null;
+  awaitingConnections: Map<string, ContinuationConnection>;
+  /** Clear pending state and awaiting connections (without sending RESUME_NONE). */
+  clearPending(): void;
+  clearDeferred(): void;
+  clearAll(): void;
+  /**
+   * Send STREAM_RESUME_NONE to all connections waiting for a
+   * continuation stream to start, then clear the map.
+   */
+  sendResumeNone(): void;
+  /**
+   * Flush awaiting connections by notifying each one via the provided
+   * callback (typically sends STREAM_RESUMING), then clear.
+   */
+  flushAwaitingConnections(notify: (conn: ContinuationConnection) => void): void;
+  /**
+   * Transition pending → active. Called when the continuation stream
+   * actually starts. Moves request/connection IDs to active slots,
+   * clears pending fields.
+   */
+  activatePending(): void;
+  /**
+   * Transition deferred → pending. Called when a continuation turn
+   * completes and there's a deferred follow-up waiting.
+   *
+   * Returns the new pending state (so the host can enqueue the turn),
+   * or null if there was nothing deferred.
+   */
+  activateDeferred(generateRequestId: () => string): ContinuationPending | null;
+}
+//#endregion
+//#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