agents 0.24.0 → 0.25.0

package/dist/wire-types-CrjKvDyi.d.ts

@@ -0,0 +1,300 @@
+import { JSONSchema7, Tool, ToolSet, UIMessage } from "ai";
+
+//#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;
+};
+/**
+ * Executes a client-defined tool and returns its output.
+ *
+ * Used for the RPC path (e.g. a parent agent delegating to a Think sub-agent)
+ * where the caller can run the client tools itself, rather than the
+ * browser/WebSocket path where results are sent back asynchronously.
+ */
+type ClientToolExecutor = (call: {
+  /** The name of the client tool the model called. */ toolName: string /** The model-generated input for the tool call. */;
+  input: unknown /** The AI SDK tool-call id for the invocation. */;
+  toolCallId: string;
+}) => unknown | Promise<unknown>;
+/**
+ * Converts client tool schemas to AI SDK tool format.
+ *
+ * By default these tools have no `execute` function — when the AI model calls
+ * them, the tool call is sent back to the client for execution.
+ *
+ * When `options.execute` is provided, each tool is built WITH an `execute` that
+ * delegates to it. This is used by the RPC path (e.g. a parent agent driving a
+ * Think sub-agent) so the model's client-tool call is resolved inline within
+ * the same turn.
+ *
+ * @param clientTools - Array of tool schemas from the client
+ * @param options - Optional `execute` delegate to run the tools inline
+ * @returns Record of AI SDK tools that can be spread into your tools object
+ */
+declare function createToolsFromClientSchemas(
+  clientTools?: ClientToolSchema[],
+  options?: {
+    execute?: ClientToolExecutor;
+  }
+): ToolSet;
+//#endregion
+//#region src/chat/protocol.d.ts
+/**
+ * Wire protocol message type constants for the cf_agent_chat_* protocol.
+ *
+ * These are the string values used on the wire between agent servers and
+ * clients. Both @cloudflare/ai-chat (via its MessageType enum) and
+ * @cloudflare/think use these values.
+ */
+declare const STREAM_RESUME_NONE_REASONS: {
+  /** No active, pending, or terminal stream exists for this agent. */ readonly IDLE: "idle" /** An active tool continuation is owned by another live connection. */;
+  readonly CONTINUATION_OWNED: "continuation-owned";
+};
+type StreamResumeNoneReason =
+  (typeof STREAM_RESUME_NONE_REASONS)[keyof typeof STREAM_RESUME_NONE_REASONS];
+declare const CHAT_MESSAGE_TYPES: {
+  readonly CHAT_MESSAGES: "cf_agent_chat_messages";
+  readonly USE_CHAT_REQUEST: "cf_agent_use_chat_request";
+  readonly USE_CHAT_RESPONSE: "cf_agent_use_chat_response";
+  readonly CHAT_CLEAR: "cf_agent_chat_clear";
+  readonly CHAT_REQUEST_CANCEL: "cf_agent_chat_request_cancel";
+  readonly STREAM_RESUMING: "cf_agent_stream_resuming";
+  readonly STREAM_RESUME_ACK: "cf_agent_stream_resume_ack";
+  readonly STREAM_RESUME_REQUEST: "cf_agent_stream_resume_request";
+  readonly STREAM_RESUME_NONE: "cf_agent_stream_resume_none";
+  readonly STREAM_PENDING: "cf_agent_stream_pending";
+  readonly TOOL_RESULT: "cf_agent_tool_result";
+  readonly TOOL_APPROVAL: "cf_agent_tool_approval";
+  readonly MESSAGE_UPDATED: "cf_agent_message_updated";
+  readonly CHAT_RECOVERING: "cf_agent_chat_recovering";
+};
+//#endregion
+//#region src/chat/wire-types.d.ts
+/**
+ * How a chat request ended.
+ *
+ * - `completed`: the turn finished normally.
+ * - `error`: the turn failed.
+ * - `aborted`: the turn was cancelled while it ran.
+ * - `skipped`: the turn never ran, because a newer send superseded it or the
+ *   concurrency policy dropped it.
+ * - `recovering`: this request stopped, but recovery continues the same turn
+ *   under a new request that carries the same `messageIds`.
+ */
+type ChatTurnOutcome =
+  | "completed"
+  | "error"
+  | "aborted"
+  | "skipped"
+  | "recovering";
+/**
+ * Enum for message types to improve type safety and maintainability
+ */
+declare enum MessageType {
+  CF_AGENT_CHAT_MESSAGES = "cf_agent_chat_messages",
+  CF_AGENT_USE_CHAT_REQUEST = "cf_agent_use_chat_request",
+  CF_AGENT_USE_CHAT_RESPONSE = "cf_agent_use_chat_response",
+  CF_AGENT_CHAT_CLEAR = "cf_agent_chat_clear",
+  CF_AGENT_CHAT_REQUEST_CANCEL = "cf_agent_chat_request_cancel",
+  /** Sent by server when client connects and there's an active stream to resume */
+  CF_AGENT_STREAM_RESUMING = "cf_agent_stream_resuming",
+  /** Sent by client to acknowledge stream resuming notification and request chunks */
+  CF_AGENT_STREAM_RESUME_ACK = "cf_agent_stream_resume_ack",
+  /** Sent by client after message handler is ready, requesting stream resume check */
+  CF_AGENT_STREAM_RESUME_REQUEST = "cf_agent_stream_resume_request",
+  /** Sent by server when client requests resume but no active stream exists */
+  CF_AGENT_STREAM_RESUME_NONE = "cf_agent_stream_resume_none",
+  /**
+   * Sent by server when a turn is accepted but its resumable stream has not
+   * started yet (queued / debouncing / waiting on MCP / async setup). Tells a
+   * reconnecting client to keep waiting rather than resolve its resume probe to
+   * "no stream". Resolved by a later `CF_AGENT_STREAM_RESUMING` (stream started)
+   * or `CF_AGENT_STREAM_RESUME_NONE` (settled without streaming). See #1784.
+   */
+  CF_AGENT_STREAM_PENDING = "cf_agent_stream_pending",
+  /** Client sends tool result to server (for client-side tools) */
+  CF_AGENT_TOOL_RESULT = "cf_agent_tool_result",
+  /** Server notifies client that a message was updated (e.g., tool result applied) */
+  CF_AGENT_MESSAGE_UPDATED = "cf_agent_message_updated",
+  /** Client sends tool approval response to server (for tools with needsApproval) */
+  CF_AGENT_TOOL_APPROVAL = "cf_agent_tool_approval",
+  /**
+   * Server→client progress hint: a durable chat turn is being recovered
+   * (interrupted by a deploy/eviction or a stream-stall watchdog abort and now
+   * resuming). Sent when a recovery continuation is scheduled and cleared on
+   * every terminal outcome. (`@cloudflare/think` also replays it on connect;
+   * `@cloudflare/ai-chat` broadcasts the live signal only — see #1645.)
+   * Backward-compatible — clients that don't understand it ignore it. See #1620.
+   */
+  CF_AGENT_CHAT_RECOVERING = "cf_agent_chat_recovering"
+}
+/**
+ * Types of messages sent from the Agent to clients
+ */
+type OutgoingMessage<ChatMessage extends UIMessage = UIMessage> =
+  | {
+      /** Indicates this message is a command to clear chat history */ type: MessageType.CF_AGENT_CHAT_CLEAR;
+    }
+  | {
+      /** Indicates this message contains updated chat messages */ type: MessageType.CF_AGENT_CHAT_MESSAGES /** Array of chat messages */;
+      messages: readonly ChatMessage[];
+      /**
+       * Set on the transcript a server sends to a newly connected client. It
+       * predates any request the client buffered while disconnected, so the
+       * client keeps those optimistic sends; any other snapshot is
+       * authoritative (#1983).
+       */
+      connect?: boolean;
+    }
+  | {
+      /** Indicates this message is a response to a chat request */ type: MessageType.CF_AGENT_USE_CHAT_RESPONSE /** Unique ID of the request this response corresponds to */;
+      id: string /** Content body of the response */;
+      body: string /** Whether this is the final chunk of the response */;
+      done: boolean /** Whether this response contains an error */;
+      error?: boolean /** Whether this is a continuation (append to last assistant message) */;
+      continuation?: boolean /** Whether this chunk is being replayed from storage (stream resumption) */;
+      replay?: boolean /** Signals that replay of stored chunks is complete (stream is still active) */;
+      replayComplete?: boolean;
+      /**
+       * Index of this chunk within its stream. A live chunk carries the index
+       * its replay will carry, so a client can skip replayed chunks it has
+       * already applied.
+       */
+      seq?: number;
+      /**
+       * IDs of the user messages the originating request carried (the
+       * trailing user messages of its `messages`). Set on terminal frames
+       * (`done` or `error`), live and replayed, when the server knows them,
+       * so a client can settle exactly the sends a completion, error, or
+       * cancellation belongs to.
+       */
+      messageIds?: string[];
+      /**
+       * How the request ended, on its terminal `done` frame. Absent means
+       * `"error"` when the frame (or an earlier frame for the request) carried
+       * `error`, and `"completed"` otherwise.
+       */
+      outcome?: ChatTurnOutcome;
+    }
+  | {
+      /** Indicates the server is resuming an active stream */ type: MessageType.CF_AGENT_STREAM_RESUMING /** The request ID of the stream being resumed */;
+      id: string /** Present when this offer directly answers a client resume probe. */;
+      probeId?: string;
+    }
+  | {
+      /** Server notifies client that a message was updated (e.g., tool result applied) */ type: MessageType.CF_AGENT_MESSAGE_UPDATED /** The updated message */;
+      message: ChatMessage;
+    }
+  | {
+      /** Server responds to a resume request with no stream for this client. */ type: MessageType.CF_AGENT_STREAM_RESUME_NONE;
+      /**
+       * Why no stream was offered. Only `idle` proves global inactivity;
+       * omitted by older servers and by non-authoritative delayed releases.
+       */
+      reason?: StreamResumeNoneReason /** Correlates an authoritative response to its client resume probe. */;
+      probeId?: string;
+    }
+  | {
+      /**
+       * Server signals an accepted turn whose resumable stream has not started
+       * yet — the client should keep waiting for `STREAM_RESUMING` (or a later
+       * `STREAM_RESUME_NONE`) rather than give up. See #1784.
+       */
+      type: MessageType.CF_AGENT_STREAM_PENDING /** The accepted request id, when known. */;
+      id?: string /** Correlates a direct keep-waiting response to its client probe. */;
+      probeId?: string;
+    }
+  | {
+      /**
+       * Progress hint: a durable chat turn is being recovered (`recovering:
+       * true`) or recovery has resolved (`recovering: false`). Purely advisory;
+       * a client renders a "recovering…" indicator while true.
+       */
+      type: MessageType.CF_AGENT_CHAT_RECOVERING /** Whether recovery is in progress (true) or has resolved (false). */;
+      recovering: boolean /** The recovery-root request id of the turn being recovered, if known. */;
+      id?: string;
+    };
+/**
+ * Types of messages sent from clients to the Agent
+ */
+type IncomingMessage<ChatMessage extends UIMessage = UIMessage> =
+  | {
+      /** Indicates this message is a command to clear chat history */ type: MessageType.CF_AGENT_CHAT_CLEAR;
+    }
+  | {
+      /** Indicates this message is a request to the chat API */ type: MessageType.CF_AGENT_USE_CHAT_REQUEST /** Unique ID for this request */;
+      id: string /** Request initialization options */;
+      init: Pick<
+        RequestInit,
+        | "method"
+        | "keepalive"
+        | "headers"
+        | "body"
+        | "redirect"
+        | "integrity"
+        | "credentials"
+        | "mode"
+        | "referrer"
+        | "referrerPolicy"
+        | "window"
+      >;
+    }
+  | {
+      /** Indicates this message contains updated chat messages */ type: MessageType.CF_AGENT_CHAT_MESSAGES /** Array of chat messages */;
+      messages: ChatMessage[];
+    }
+  | {
+      /** Indicates the user wants to stop generation of this message */ type: MessageType.CF_AGENT_CHAT_REQUEST_CANCEL;
+      id: string;
+    }
+  | {
+      /** Client acknowledges stream resuming notification and is ready to receive chunks */ type: MessageType.CF_AGENT_STREAM_RESUME_ACK /** The request ID of the stream being resumed */;
+      id: string;
+    }
+  | {
+      /** Client requests stream resume check after message handler is registered */ type: MessageType.CF_AGENT_STREAM_RESUME_REQUEST /** Opaque correlation id echoed by direct server responses. */;
+      probeId?: string;
+    }
+  | {
+      /** Client sends tool result to server (for client-side tools) */ type: MessageType.CF_AGENT_TOOL_RESULT /** The tool call ID this result is for */;
+      toolCallId: string /** The name of the tool */;
+      toolName: string /** The output from the tool execution */;
+      output: unknown /** Override the tool part state (e.g. "output-error" for custom denial) */;
+      state?:
+        | "output-available"
+        | "output-error" /** Error message when state is "output-error" */;
+      errorText?: string /** Whether server should auto-continue the conversation after applying result */;
+      autoContinue?: boolean /** Client tool schemas for continuation (client is source of truth) */;
+      clientTools?: Array<{
+        name: string;
+        description?: string;
+        parameters?: JSONSchema7;
+      }>;
+    }
+  | {
+      /** Client sends tool approval response to server (for tools with needsApproval) */ type: MessageType.CF_AGENT_TOOL_APPROVAL /** The tool call ID this approval is for */;
+      toolCallId: string /** Whether the tool execution was approved */;
+      approved: boolean /** Whether server should auto-continue the conversation after applying approval */;
+      autoContinue?: boolean;
+    };
+//#endregion
+export {
+  CHAT_MESSAGE_TYPES as a,
+  ClientToolExecutor as c,
+  OutgoingMessage as i,
+  ClientToolSchema as l,
+  IncomingMessage as n,
+  STREAM_RESUME_NONE_REASONS as o,
+  MessageType as r,
+  StreamResumeNoneReason as s,
+  ChatTurnOutcome as t,
+  createToolsFromClientSchemas as u
+};
+//# sourceMappingURL=wire-types-CrjKvDyi.d.ts.map

package/dist/workflow-types.d.ts

@@ -1,29 +1,29 @@
 import {
-  Ct as WorkflowQueryCriteria,
-  Et as WorkflowTrackingRow,
-  St as WorkflowProgressCallback,
-  Tt as WorkflowStatus,
-  _t as WorkflowErrorCallback,
-  at as AgentWorkflowOrigin,
-  bt as WorkflowInfo,
-  ct as AgentWorkflowStep,
-  dt as RunWorkflowOptions,
-  ft as WaitForApprovalOptions,
-  gt as WorkflowCompleteCallback,
-  ht as WorkflowCallbackType,
-  it as AgentWorkflowInternalParams,
-  lt as ApprovalEventPayload,
-  mt as WorkflowCallbackBase,
-  ot as AgentWorkflowParams,
-  pt as WorkflowCallback,
-  rt as AgentWorkflowEvent,
-  st as AgentWorkflowPathStep,
-  ut as DefaultProgress,
-  vt as WorkflowEventCallback,
-  wt as WorkflowRejectedError,
-  xt as WorkflowPage,
-  yt as WorkflowEventPayload
-} from "./agent-routing-B2XLNMxq.js";
+  Ct as WorkflowInfo,
+  Dt as WorkflowRejectedError,
+  Et as WorkflowQueryCriteria,
+  Ot as WorkflowStatus,
+  St as WorkflowEventPayload,
+  Tt as WorkflowProgressCallback,
+  _t as WorkflowCallbackBase,
+  bt as WorkflowErrorCallback,
+  ct as AgentWorkflowOrigin,
+  dt as AgentWorkflowStep,
+  ft as ApprovalEventPayload,
+  gt as WorkflowCallback,
+  ht as WaitForApprovalOptions,
+  kt as WorkflowTrackingRow,
+  lt as AgentWorkflowParams,
+  mt as RunWorkflowOptions,
+  ot as AgentWorkflowEvent,
+  pt as DefaultProgress,
+  st as AgentWorkflowInternalParams,
+  ut as AgentWorkflowPathStep,
+  vt as WorkflowCallbackType,
+  wt as WorkflowPage,
+  xt as WorkflowEventCallback,
+  yt as WorkflowCompleteCallback
+} from "./agent-routing-0DR0Tk2v.js";
 export {
   AgentWorkflowEvent,
   AgentWorkflowInternalParams,

package/dist/workflows.d.ts

@@ -1,26 +1,26 @@
 import {
-  Ct as WorkflowQueryCriteria,
-  Et as WorkflowTrackingRow,
-  St as WorkflowProgressCallback,
-  Tt as WorkflowStatus,
-  _t as WorkflowErrorCallback,
-  bt as WorkflowInfo,
+  Ct as WorkflowInfo,
+  Dt as WorkflowRejectedError,
+  Et as WorkflowQueryCriteria,
+  Ot as WorkflowStatus,
+  St as WorkflowEventPayload,
+  Tt as WorkflowProgressCallback,
+  bt as WorkflowErrorCallback,
   c as Agent,
-  ct as AgentWorkflowStep,
-  dt as RunWorkflowOptions,
-  ft as WaitForApprovalOptions,
-  gt as WorkflowCompleteCallback,
-  ht as WorkflowCallbackType,
-  lt as ApprovalEventPayload,
-  ot as AgentWorkflowParams,
-  pt as WorkflowCallback,
-  rt as AgentWorkflowEvent,
-  ut as DefaultProgress,
-  vt as WorkflowEventCallback,
-  wt as WorkflowRejectedError,
-  xt as WorkflowPage,
-  yt as WorkflowEventPayload
-} from "./agent-routing-B2XLNMxq.js";
+  dt as AgentWorkflowStep,
+  ft as ApprovalEventPayload,
+  gt as WorkflowCallback,
+  ht as WaitForApprovalOptions,
+  kt as WorkflowTrackingRow,
+  lt as AgentWorkflowParams,
+  mt as RunWorkflowOptions,
+  ot as AgentWorkflowEvent,
+  pt as DefaultProgress,
+  vt as WorkflowCallbackType,
+  wt as WorkflowPage,
+  xt as WorkflowEventCallback,
+  yt as WorkflowCompleteCallback
+} from "./agent-routing-0DR0Tk2v.js";
 import { WorkflowEntrypoint, WorkflowEvent } from "cloudflare:workers";
 
 //#region src/workflows.d.ts

package/dist/workflows.js

@@ -1,6 +1,6 @@
 import { isInternalJsStubProp } from "./utils.js";
 import { getAgentByName } from "./agent-routing.js";
-import "./src-BNU3ZiJM.js";
+import "./src-BZeu-SCD.js";
 import { WorkflowRejectedError } from "./workflow-types.js";
 import { WorkflowEntrypoint } from "cloudflare:workers";
 //#region src/workflows.ts

package/dist/{ws-chat-transport-UNRIS2xl.d.ts → ws-chat-transport-BbT1A5Lc.d.ts}

@@ -1,5 +1,35 @@
 import { ChatTransport, UIMessage, UIMessageChunk } from "ai";
 
+//#region src/chat/replay-dedupe.d.ts
+/**
+ * Replay de-duplication for continuation streams (#1951).
+ *
+ * A continuation appends to an assistant message this client may already have
+ * rendered live. After a reconnect the server replays the continuation's
+ * whole buffer, and applying it on top of the live-rendered bytes would
+ * duplicate them. Every live and replayed chunk frame carries its index in
+ * the stream (`seq`), so a client that records how far it applied each
+ * stream can drop the replayed chunks it already has.
+ *
+ * Non-continuation replays are left alone: the client resets the message and
+ * rebuilds it from chunk 0 for those.
+ */
+type ChunkFrame = {
+  body?: string;
+  continuation?: boolean;
+  replay?: boolean;
+  seq?: number;
+};
+/** Highest chunk `seq` this client applied, per request id. */
+declare class AppliedChunkLedger {
+  private readonly applied;
+  record(requestId: string, seq: number | undefined): void;
+  /** Whether `frame` replays a continuation chunk this client already applied. */
+  isAppliedReplay(requestId: string, frame: ChunkFrame): boolean;
+  forget(requestId: string): void;
+  clear(): void;
+}
+//#endregion
 //#region src/chat/ws-chat-transport.d.ts
 /**
  * Agent-like interface for sending/receiving WebSocket messages.
@@ -7,7 +37,7 @@ import { ChatTransport, UIMessage, UIMessageChunk } from "ai";
  * `useAgent` from `agents/react`.
  */
 interface AgentConnection {
-  send: (data: string) => void;
+  send: (data: string) => boolean | void;
   addEventListener: (
     type: string,
     listener: (event: MessageEvent) => void,
@@ -44,6 +74,13 @@ type WebSocketChatTransportOptions<ChatMessage extends UIMessage = UIMessage> =
      * @default false
      */
     cancelOnClientAbort?: boolean;
+    /**
+     * Called when a `submit-message` request frame was buffered rather than sent
+     * immediately (the socket was not OPEN, so PartySocket queued it for the next
+     * reconnect). The hook uses this to preserve the optimistic message across the
+     * reconnect transcript replay. `messageId` is the submitted user message's id.
+     */
+    onRequestBuffered?: (messageId: string | undefined) => void;
   };
 /**
  * ChatTransport that sends messages over WebSocket and returns a
@@ -61,7 +98,13 @@ declare class WebSocketChatTransport<
   private prepareBody?;
   private activeRequestIds?;
   private cancelOnClientAbort;
+  private onRequestBuffered?;
   private _resumeResolver;
+  /**
+   * Continuation chunks this client applied, shared with the hook's fallback
+   * observer so a replay after reconnect skips them on either path (#1951).
+   */
+  readonly appliedChunks: AppliedChunkLedger;
   private _resumeNoneResolver;
   private _onStreamPending;
   private _retryResumeProbe;
@@ -84,6 +127,12 @@ declare class WebSocketChatTransport<
    * clients can detach locally without stopping server work.
    */
   cancelActiveServerTurn(): boolean;
+  /**
+   * The server turn this transport last attached to that has not reported a
+   * terminal frame. A socket close ends the local stream but keeps this set,
+   * since the server keeps running the turn.
+   */
+  get activeServerTurnId(): string | null;
   private sendCancelFrame;
   private setActiveServerTurn;
   private clearActiveServerTurn;
@@ -181,4 +230,4 @@ export {
   WebSocketChatTransportOptions as r,
   AgentConnection as t
 };
-//# sourceMappingURL=ws-chat-transport-UNRIS2xl.d.ts.map
+//# sourceMappingURL=ws-chat-transport-BbT1A5Lc.d.ts.map