agents/dist/wire-types-Cv0iwjk5.d.ts

A home for your AI agents

import { JSONSchema7, UIMessage } from "ai";

//#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,
  OutgoingMessage as i,
  IncomingMessage as n,
  STREAM_RESUME_NONE_REASONS as o,
  MessageType as r,
  StreamResumeNoneReason as s,
  ChatTurnOutcome as t
};
//# sourceMappingURL=wire-types-Cv0iwjk5.d.ts.map