agents 0.30.0 → 0.31.0

package/dist/mcp/index.d.ts

@@ -1,46 +1,579 @@
 import {
-  $t as RPCServerTransport,
+  S as ConnectionContext,
+  x as Connection
+} from "../capability-runner-BiVUtjqC.js";
+import {
+  $t as RPCClientTransportOptions,
   Bt as MCPConnectionResult,
   Ft as MCPClientElicitationHandlers,
   Gt as MCP_SERVER_ID_MAX_LENGTH,
   Jt as normalizeServerId,
   Pt as MCPClientElicitationHandler,
-  Qt as RPCClientTransportOptions,
+  Qt as RPCClientTransport,
   Rt as MCPClientOAuthCallbackConfig,
   Vt as MCPDiscoverResult,
   Wt as MCPServerOptions,
   Xt as MCPElicitationHandlers,
   Yt as MCPElicitationHandler,
-  Zt as RPCClientTransport,
-  _n as WorkerTransportOptions,
-  an as McpAgent,
-  cn as createMcpHandler,
-  dn as CreateMcpHandlerOptions,
-  en as RPCServerTransportOptions,
-  fn as LegacyMcpHandler,
-  gn as WorkerTransport,
-  hn as TransportState,
-  in as ElicitResult,
-  ln as experimental_createMcpHandler,
-  mn as MCPStorageApi,
-  nn as ElicitRequest,
-  on as ClearableEventStore,
-  pn as createLegacyMcpHandler,
-  rn as ElicitRequestSchema,
-  sn as DurableObjectEventStore,
-  tn as RPC_DO_PREFIX,
-  un as CreateLegacyMcpHandlerOptions,
-  vn as SSEEdgeClientTransport,
-  yn as StreamableHTTPEdgeClientTransport,
+  c as Agent,
+  en as RPC_DO_PREFIX,
   zt as MCPClientOAuthResult
-} from "../agent-routing-CDbpVjYq.js";
+} from "../agent-routing-wS1TimZ_.js";
+import {
+  a as ServeOptions,
+  i as McpClientOptions,
+  n as CORSOptions,
+  r as MaybePromise,
+  t as BaseTransportType
+} from "../types-D2naO3rA.js";
 import {
   a as McpAuthContext,
   n as StatelessMcpHandler,
   o as getMcpAuthContext,
-  t as CreateStatelessMcpHandlerOptions,
-  u as McpClientOptions
-} from "../handler-stateless-DxYpJ_XF.js";
+  t as CreateStatelessMcpHandlerOptions
+} from "../handler-stateless-C90kD5_R.js";
+import {
+  ElicitRequest,
+  ElicitResult,
+  SSEClientTransport,
+  SSEClientTransportOptions,
+  StreamableHTTPClientTransport,
+  StreamableHTTPClientTransportOptions
+} from "@modelcontextprotocol/client";
+import {
+  ElicitRequestSchema,
+  ElicitResult as ElicitResult$2,
+  InitializeRequestParams,
+  JSONRPCMessage as JSONRPCMessage$1,
+  MessageExtraInfo as MessageExtraInfo$1,
+  RequestId
+} from "@modelcontextprotocol/sdk/types.js";
+import { McpServerFactory } from "@modelcontextprotocol/server";
+import { McpServer as McpServer$1 } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { Server as Server$1 } from "@modelcontextprotocol/sdk/server/index.js";
+import {
+  EventStore as EventStore$1,
+  StreamId as StreamId$1,
+  WebStandardStreamableHTTPServerTransport as WebStandardStreamableHTTPServerTransport$1,
+  WebStandardStreamableHTTPServerTransportOptions
+} from "@modelcontextprotocol/sdk/server/webStandardStreamableHttp.js";
+import {
+  EventId,
+  EventStore,
+  StreamId
+} from "@modelcontextprotocol/sdk/server/streamableHttp.js";
+import {
+  Transport as Transport$1,
+  TransportSendOptions as TransportSendOptions$1
+} from "@modelcontextprotocol/sdk/shared/transport.js";
+import { AuthInfo } from "@modelcontextprotocol/sdk/server/auth/types.js";
+
+//#region src/mcp/rpc-server.d.ts
+interface RPCServerTransportOptions {
+  timeout?: number;
+}
+declare class RPCServerTransport implements Transport$1 {
+  private _started;
+  private _protocolVersion?;
+  private _timeout;
+  private _pendingRequests;
+  private _pendingContinuations;
+  sessionId?: string;
+  onclose?: () => void;
+  onerror?: (error: Error) => void;
+  onmessage?: (message: JSONRPCMessage$1, extra?: MessageExtraInfo$1) => void;
+  constructor(options?: RPCServerTransportOptions);
+  setProtocolVersion(version: string): void;
+  getProtocolVersion(): string | undefined;
+  start(): Promise<void>;
+  close(): Promise<void>;
+  private _makeTimeout;
+  private _appendPending;
+  private _completePending;
+  private _completeRequest;
+  private _appendRequest;
+  private _completeContinuation;
+  private _appendContinuation;
+  send(
+    message: JSONRPCMessage$1,
+    options?: TransportSendOptions$1
+  ): Promise<void>;
+  /**
+   * @internal Called by McpAgent.handleMcpMessage() — not for external use.
+   *
+   * Wait for the next unmatched send() call that expects a client response or
+   * completes a resumed tool call.
+   *
+   * Used after resolving an elicitation response: the original tool call has
+   * already returned the elicitation request to the RPC client, and the resumed
+   * tool handler will eventually send the final tool result. That final response
+   * has the original tool request id, so there is no active handle() waiter left
+   * for id-based routing; this continuation waiter receives it instead.
+   */
+  _awaitPendingResponse(): Promise<
+    JSONRPCMessage$1 | JSONRPCMessage$1[] | undefined
+  >;
+  handle(
+    message: JSONRPCMessage$1 | JSONRPCMessage$1[]
+  ): Promise<JSONRPCMessage$1 | JSONRPCMessage$1[] | undefined>;
+}
+//#endregion
+//#region src/mcp/client/transports.d.ts
+/**
+ * @deprecated Use SSEClientTransport from @modelcontextprotocol/client instead. This alias will be removed in the next major version.
+ */
+declare class SSEEdgeClientTransport extends SSEClientTransport {
+  constructor(url: URL, options: SSEClientTransportOptions);
+}
+/**
+ * @deprecated Use StreamableHTTPClientTransport from @modelcontextprotocol/client instead. This alias will be removed in the next major version.
+ */
+declare class StreamableHTTPEdgeClientTransport extends StreamableHTTPClientTransport {
+  constructor(url: URL, options: StreamableHTTPClientTransportOptions);
+}
+//#endregion
+//#region src/mcp/server/worker-transport.d.ts
+/**
+ * Pluggable storage adapter for persisting `WorkerTransport` state across
+ * Durable Object hibernation / restart cycles.
+ *
+ * A typical implementation reads/writes a single key on `this.ctx.storage`
+ * inside a Durable Object or Agent.
+ */
+interface MCPStorageApi {
+  get(): Promise<TransportState | undefined> | TransportState | undefined;
+  set(state: TransportState): Promise<void> | void;
+}
+/** Shape of the persisted transport state. */
+interface TransportState {
+  sessionId?: string;
+  initialized: boolean;
+  initializeParams?: InitializeRequestParams;
+}
+interface WorkerTransportOptions extends WebStandardStreamableHTTPServerTransportOptions {
+  /**
+   * CORS options applied to every response and to OPTIONS preflight.
+   * Defaults: `origin: *`, expose `mcp-session-id`, allow the standard MCP
+   * methods/headers, max-age 86400.
+   */
+  corsOptions?: CORSOptions;
+  /**
+   * Optional storage adapter for persisting transport state across DO
+   * hibernation / restart. Use this to keep an MCP session alive across
+   * Durable Object wake-ups.
+   */
+  storage?: MCPStorageApi;
+}
+declare class WorkerTransport extends WebStandardStreamableHTTPServerTransport$1 {
+  private readonly _corsOptions?;
+  private readonly _storage?;
+  private _stateRestored;
+  private _capturedInitializeParams?;
+  private _userOnSessionInitialized?;
+  private _bridgeInstalled;
+  /**
+   * Request ids whose SSE stream was deliberately torn down via
+   * `closeSSEStream`. The SDK's `send()` throws "No connection established"
+   * when a request id has no stream — a race that surfaces whenever the
+   * server's tool handler resolves *after* the caller closed the stream
+   * (e.g. polling-style early-close, or test fixtures closing mid-flight).
+   * We swallow `send()` for these ids so the rejection doesn't bubble out
+   * of the protocol layer as an unhandled rejection. Mirrors the
+   * silent-noop behaviour of the pre-refactor `WorkerTransport`.
+   */
+  private readonly _closedRequestIds;
+  constructor(options?: WorkerTransportOptions);
+  /**
+   * Backwards-compatible alias for the SDK's internal `_started` flag.
+   * Several callers and tests check `transport.started` directly.
+   */
+  get started(): boolean;
+  /**
+   * Top-level request entry point. Handles CORS preflight, restores any
+   * persisted state on first invocation, then delegates to the SDK transport
+   * and finally appends CORS headers to whatever response comes back.
+   */
+  handleRequest(
+    request: Request,
+    options?: {
+      parsedBody?: unknown;
+      authInfo?: AuthInfo;
+    }
+  ): Promise<Response>;
+  /**
+   * The SDK's 405 responses advertise `Allow: GET, POST, DELETE` because
+   * OPTIONS is handled outside the SDK. Since our wrapper *does* handle
+   * OPTIONS, advertise it in `Allow` so clients can probe accurately.
+   */
+  private normalizeAllowHeader;
+  closeSSEStream(requestId: RequestId): void;
+  close(): Promise<void>;
+  /**
+   * Swallow two classes of message that would otherwise surface as
+   * unhandled rejections from the SDK transport's `send()`:
+   *
+   *   1. Replayed initialize responses (the `RESTORE_REQUEST_ID` sentinel)
+   *      — we synthesise these in `restoreState()` to rebuild server
+   *      capabilities; there's no real client waiting for the response.
+   *   2. Sends for a request id whose SSE stream has been deliberately
+   *      closed via `closeSSEStream`. The protocol layer's tool-handler
+   *      promise may settle after the close, and the SDK's `send()` throws
+   *      "No connection established" — a race the pre-refactor transport
+   *      silently swallowed.
+   *
+   * Everything else is delegated. We use `await super.send(...)` rather
+   * than `return super.send(...)` so any rejection is observed inside this
+   * async frame; without the await, the test runner's
+   * unhandled-rejection tracker can fire before the caller's own `await`
+   * observes it.
+   */
+  send(
+    message: JSONRPCMessage$1,
+    options?: TransportSendOptions$1
+  ): Promise<void>;
+  private getCorsHeaders;
+  private withCorsHeaders;
+  private installOnSessionInitializedBridge;
+  private captureInitializeParams;
+  private restoreState;
+  private saveState;
+}
+//#endregion
+//#region src/mcp/server/handler-legacy.d.ts
+/** Options for the retained SDK v1, sessionful handler. */
+interface CreateLegacyMcpHandlerOptions extends WorkerTransportOptions {
+  /** Exact route handled by this handler. @default "/mcp" */
+  route?: string;
+  /** Application props exposed through {@link getMcpAuthContext}. */
+  authContext?: McpAuthContext;
+  /** Pre-created sessionful transport. */
+  transport?: WorkerTransport;
+}
+type CreateMcpHandlerOptions = CreateLegacyMcpHandlerOptions;
+type LegacyMcpHandler = (
+  request: Request,
+  env: unknown,
+  ctx: ExecutionContext
+) => Promise<Response>;
+/**
+ * Create a sessionful Legacy MCP handler backed by SDK v1.
+ *
+ * New Stateless servers should use `createMcpHandler` from
+ * `agents/mcp/server` instead.
+ */
+declare function createLegacyMcpHandler(
+  server: McpServer$1 | Server$1,
+  options?: CreateLegacyMcpHandlerOptions
+): LegacyMcpHandler;
+//#endregion
+//#region src/mcp/server/handler-compat.d.ts
+/**
+ * @deprecated Passing an SDK v1 server to createMcpHandler is deprecated and
+ * will be removed in the next major version. Pass an SDK v2 factory to
+ * createMcpHandler. Use createLegacyMcpHandler only to temporarily retain
+ * sessionful SDK v1 behavior while migrating.
+ */
+declare function createMcpHandler(
+  server: McpServer$1 | Server$1,
+  options?: CreateMcpHandlerOptions
+): LegacyMcpHandler;
+declare function createMcpHandler(
+  factory: McpServerFactory,
+  options?: CreateStatelessMcpHandlerOptions
+): StatelessMcpHandler;
+/**
+ * @deprecated Pass an SDK v2 factory to createMcpHandler.
+ * experimental_createMcpHandler will be removed in the next major version.
+ * Use createLegacyMcpHandler only to temporarily retain sessionful SDK v1
+ * behavior while migrating.
+ */
+declare function experimental_createMcpHandler(
+  server: McpServer$1 | Server$1,
+  options?: CreateMcpHandlerOptions
+): LegacyMcpHandler;
+//#endregion
+//#region src/mcp/server/event-store.d.ts
+/**
+ * Durable Object–backed {@link EventStore} for SSE resumability.
+ *
+ * Default for `McpAgent`. Override `McpAgent.getEventStore()` to swap
+ * or disable.
+ *
+ * ## Storage layout
+ *
+ * Events are stored under `__mcp_event__:<streamId>:<seqHex>`, where
+ * `<seqHex>` is a 16-char zero-padded counter so events in a stream
+ * sort lexicographically and `getStreamIdForEventId` can recover the
+ * stream from `eventId` without a storage hit.
+ *
+ * ## Lifecycle
+ *
+ * Each POST tool-call stream's events live only until the final
+ * response is delivered. The transport calls {@link clearStream}
+ * immediately after writing the close frame, so storage growth is
+ * bounded by the in-flight POST streams plus the standalone GET
+ * stream. There is no background sweep — quiescent agents do no work,
+ * and the DO itself dies with the session.
+ *
+ * Standalone GET stream events (`_GET_stream`) are *not* cleared
+ * automatically; they accumulate for the lifetime of the DO. Bounded
+ * by session length in practice.
+ *
+ * Trade-off: if the client TCP connection dies *after* the close
+ * frame has been enqueued on the WS but before the bytes reach the
+ * client, the final message is unreplayable. Every earlier event in
+ * the stream is still replayable while the in-flight stream is open.
+ *
+ * ## Stream id constraints
+ *
+ * `streamId` MUST NOT contain `:`. `storeEvent` asserts this so
+ * embedders using custom stream ids fail loudly rather than risk
+ * prefix-scan collisions (e.g. clearing `a` accidentally hitting
+ * `a:b`). Default ids (`connection.id` UUIDs and the literal
+ * `_GET_stream`) already satisfy this.
+ */
+declare class DurableObjectEventStore implements EventStore {
+  private static readonly EVENT_KEY_PREFIX;
+  private static readonly SEQ_PAD;
+  /** DO storage caps multi-key delete at 128. */
+  private static readonly DELETE_CHUNK;
+  /** Defensive ceiling on a single replay batch. A live stream's
+   *  event count is small (progress notifications + final result);
+   *  this is here so a pathological history can't OOM the DO. */
+  private static readonly REPLAY_LIMIT;
+  private readonly storage;
+  /** In-memory seq counters per stream, rehydrated lazily from storage. */
+  private readonly seqByStream;
+  private readonly seqInit;
+  constructor(storage: DurableObjectStorage);
+  storeEvent(streamId: StreamId, message: JSONRPCMessage$1): Promise<EventId>;
+  getStreamIdForEventId(eventId: EventId): Promise<StreamId | undefined>;
+  replayEventsAfter(
+    lastEventId: EventId,
+    {
+      send
+    }: {
+      send: (eventId: EventId, message: JSONRPCMessage$1) => Promise<void>;
+    }
+  ): Promise<StreamId>;
+  /**
+   * Drop the event log for a single stream. Called by the transport
+   * immediately after a POST's final response has been written to the
+   * wire — no future `Last-Event-ID` for this stream is expected to
+   * resolve.
+   *
+   * Lists and deletes in chunks of {@link DELETE_CHUNK} (128, the DO
+   * storage cap) so we never load the entire event log into memory.
+   * After deleting, the next `list` call won't see the deleted keys,
+   * so passing `start: <prefix>` again is enough — no cursor bookkeeping.
+   */
+  clearStream(streamId: StreamId): Promise<void>;
+  private ensureSeqLoaded;
+}
+//#endregion
+//#region src/mcp/server/transport.d.ts
+/**
+ * An {@link EventStore} that supports dropping all events for a single
+ * stream id. Implemented by {@link DurableObjectEventStore}.
+ */
+interface ClearableEventStore extends EventStore$1 {
+  clearStream(streamId: StreamId$1): Promise<void>;
+}
+//#endregion
+//#region src/mcp/server/legacy-agent.d.ts
+/**
+ * @deprecated McpAgent is feature-frozen. Migrate to an SDK v2 factory with
+ * createMcpHandler from agents/mcp/server. When sessionful features prevent an
+ * immediate migration, run the stateless route beside the existing McpAgent
+ * route until clients transition and sessions drain.
+ */
+declare abstract class McpAgent<
+  Env extends Cloudflare.Env = Cloudflare.Env,
+  State = unknown,
+  Props extends Record<string, unknown> = Record<string, unknown>
+> extends Agent<Env, State, Props> {
+  private _transport?;
+  private _pendingElicitations;
+  props?: Props;
+  shouldSendProtocolMessages(
+    _connection: Connection,
+    ctx: ConnectionContext
+  ): boolean;
+  abstract server: MaybePromise<McpServer$1 | Server$1>;
+  abstract init(): Promise<void>;
+  setInitializeRequest(initializeRequest: JSONRPCMessage$1): Promise<void>;
+  getInitializeRequest(): Promise<JSONRPCMessage$1 | undefined>;
+  /**
+   * End a streamable HTTP session (`DELETE`). Teardown is deferred to the
+   * agent's alarm (#1625), so the stored initialize request is cleared too:
+   * every route treats a session without one as unknown, which makes requests
+   * carrying the terminated session ID get 404 as the spec requires. Teardown
+   * is scheduled first, so a failure part-way leaves a session the client can
+   * `DELETE` again rather than one that is never cleaned up.
+   *
+   * @internal
+   */
+  _cf_terminateSession(): Promise<void>;
+  /**
+   * Storage key prefix for the `streamId -> requestIds` mapping used
+   * to support POST stream resumption across WebSocket reconnects.
+   *
+   * @internal
+   */
+  private static readonly STREAM_REQS_KEY_PREFIX;
+  /** Persist the `requestIds` for a POST stream. @internal */
+  setStreamRequestIds(streamId: string, requestIds: RequestId[]): Promise<void>;
+  /** Read the persisted `requestIds` for a POST stream. @internal */
+  getStreamRequestIds(streamId: string): Promise<RequestId[] | undefined>;
+  /** Drop the persisted `requestIds` for a POST stream. @internal */
+  deleteStreamRequestIds(streamId: string): Promise<void>;
+  /**
+   * Reverse lookup: find which POST stream a given `requestId` belongs
+   * to, and return the stream's full `requestIds` list in the same
+   * pass. Used by the transport when the originating WS has dropped,
+   * so `send()` can still record events for replay and decide whether
+   * the stream is fully responded — mirrors the SDK's
+   * `_requestToStreamMapping` which outlives connection loss.
+   *
+   * Returning `requestIds` alongside `streamId` lets `send()` skip a
+   * second `getStreamRequestIds` read on the same key.
+   *
+   * O(n) in the number of in-flight POST streams — single-digit in
+   * practice since each stream is cleaned up on its final response.
+   * The `limit` is a defensive ceiling so an abandoned-POST leak can't
+   * unbounded-load this scan; if you hit it, something else has gone
+   * wrong and `send()` will throw `No active stream found`.
+   *
+   * @internal
+   */
+  getStreamForRequestId(requestId: RequestId): Promise<
+    | {
+        streamId: string;
+        requestIds: RequestId[];
+      }
+    | undefined
+  >;
+  /** Read the transport type for this agent.
+   * This relies on the naming scheme being `sse:${sessionId}`,
+   * `streamable-http:${sessionId}`, or `rpc:${sessionId}`.
+   */
+  getTransportType(): BaseTransportType;
+  /** Read the sessionId for this agent.
+   * This relies on the naming scheme being `sse:${sessionId}`
+   * or `streamable-http:${sessionId}`.
+   */
+  getSessionId(): string;
+  /** Get the unique WebSocket. SSE transport only. */
+  getWebSocket(): Connection<unknown> | null;
+  /**
+   * Returns options for configuring the RPC server transport.
+   * Override this method to customize RPC transport behavior (e.g., timeout).
+   *
+   * @example
+   * ```typescript
+   * class MyMCP extends McpAgent {
+   *   protected getRpcTransportOptions() {
+   *     return { timeout: 120000 }; // 2 minutes
+   *   }
+   * }
+   * ```
+   */
+  protected getRpcTransportOptions(): RPCServerTransportOptions;
+  /**
+   * Returns the {@link EventStore} for SSE resumability. Defaults to a
+   * {@link DurableObjectEventStore} backed by this agent's storage,
+   * letting clients reconnect with `Last-Event-ID` after the Cloudflare
+   * edge closes an idle SSE stream (~5 minute watchdog) instead of
+   * relying on a server-side keepalive that would block hibernation.
+   *
+   * Per-stream events are cleared by the transport immediately after
+   * the final response is written to the wire, so there's no
+   * background cleanup — storage cost is bounded by the in-flight
+   * streams alone.
+   *
+   * Override to disable (`return undefined`) or swap implementations.
+   */
+  protected getEventStore(): EventStore | undefined;
+  /** Returns a new transport matching the type of the Agent. */
+  private initTransport;
+  /** Update and store the props */
+  updateProps(props?: Props): Promise<void>;
+  reinitializeServer(): Promise<void>;
+  /** Sets up the MCP transport and server every time the Agent is started.*/
+  onStart(props?: Props): Promise<void>;
+  /** Validates new WebSocket connections. */
+  onConnect(
+    conn: Connection,
+    { request: req }: ConnectionContext
+  ): Promise<void>;
+  /** Handles MCP Messages for the legacy SSE transport. */
+  onSSEMcpMessage(
+    _sessionId: string,
+    messageBody: unknown,
+    extraInfo?: MessageExtraInfo$1
+  ): Promise<Error | null>;
+  /** Elicit user input with a message and schema */
+  elicitInput(
+    params: {
+      message: string;
+      requestedSchema: unknown;
+    },
+    options?: {
+      relatedRequestId?: RequestId;
+    }
+  ): Promise<ElicitResult$2>;
+  /** Handle elicitation responses via in-memory resolver */
+  private _handleElicitationResponse;
+  /**
+   * Handle an RPC message for MCP
+   * This method is called by the RPC stub to process MCP messages
+   * @param message The JSON-RPC message(s) to handle
+   * @returns The response message(s) or undefined
+   */
+  handleMcpMessage(
+    message: JSONRPCMessage$1 | JSONRPCMessage$1[]
+  ): Promise<JSONRPCMessage$1 | JSONRPCMessage$1[] | undefined>;
+  /** Return a handler for the given path for this MCP.
+   * Defaults to Streamable HTTP transport.
+   */
+  static serve(
+    path: string,
+    { binding, corsOptions, transport, jurisdiction }?: ServeOptions
+  ): {
+    fetch<Env>(
+      this: void,
+      request: Request,
+      env: Env,
+      ctx: ExecutionContext
+    ): Promise<Response>;
+  };
+  /**
+   * Legacy api
+   **/
+  static mount(
+    path: string,
+    opts?: Omit<ServeOptions, "transport">
+  ): {
+    fetch<Env>(
+      this: void,
+      request: Request,
+      env: Env,
+      ctx: ExecutionContext
+    ): Promise<Response>;
+  };
+  static serveSSE(
+    path: string,
+    opts?: Omit<ServeOptions, "transport">
+  ): {
+    fetch<Env>(
+      this: void,
+      request: Request,
+      env: Env,
+      ctx: ExecutionContext
+    ): Promise<Response>;
+  };
+}
+//#endregion
 export {
   type ClearableEventStore,
   type CreateLegacyMcpHandlerOptions,
@@ -82,3 +615,4 @@ export {
   getMcpAuthContext,
   normalizeServerId
 };
+//# sourceMappingURL=index.d.ts.map