agents 0.17.3 → 0.17.4

package/dist/{agent-tool-types-CNyE1iz_.d.ts → agent-tool-types-OhWqAbCp.d.ts}

@@ -41,6 +41,7 @@ import {
 import {
   CallToolRequest,
   CallToolResultSchema,
+  ClientCapabilities,
   CompatibilityCallToolResultSchema,
   ElicitRequest,
   ElicitRequest as ElicitRequest$1,
@@ -808,11 +809,30 @@ type MCPDiscoveryResult = {
   success: boolean;
   error?: string;
 };
+/**
+ * Handler for server-initiated `elicitation/create` requests.
+ * Held in memory only — never persisted — so it must be re-supplied when a
+ * connection is recreated (e.g. after Durable Object hibernation).
+ */
+type MCPElicitationHandler = (request: ElicitRequest) => Promise<ElicitResult>;
+type MCPElicitationHandlers = {
+  form?: MCPElicitationHandler;
+  url?: MCPElicitationHandler;
+};
 declare class MCPClientConnection {
   url: URL;
+  private readonly _info;
   options: {
     transport: MCPTransportOptions;
     client: McpClientOptions;
+    elicitationHandlers?: MCPElicitationHandlers;
+    /**
+     * Client capabilities persisted from a previous session, advertised
+     * until handlers are reconfigured after a hibernation restore. Cleared
+     * by {@link configureElicitationHandlers} — reconfigured handlers are
+     * the source of truth. Explicit `client.capabilities` win per key.
+     */
+    capabilitySeed?: ClientCapabilities;
   };
   client: Client;
   connectionState: MCPConnectionState;
@@ -839,14 +859,41 @@ declare class MCPClientConnection {
   private _discoveryAbortController;
   private readonly _onObservabilityEvent;
   readonly onObservabilityEvent: Event<MCPObservabilityEvent>;
+  /**
+   * Whether the connection advertised the elicitation capability. The SDK
+   * client refuses to register an `elicitation/create` request handler when
+   * the capability was not declared, so handler registration is gated on
+   * this.
+   */
+  private _elicitationEnabled;
   constructor(
     url: URL,
-    info: ConstructorParameters<typeof Client>[0],
+    _info: ConstructorParameters<typeof Client>[0],
     options?: {
       transport: MCPTransportOptions;
       client: McpClientOptions;
+      elicitationHandlers?: MCPElicitationHandlers;
+      /**
+       * Client capabilities persisted from a previous session, advertised
+       * until handlers are reconfigured after a hibernation restore. Cleared
+       * by {@link configureElicitationHandlers} — reconfigured handlers are
+       * the source of truth. Explicit `client.capabilities` win per key.
+       */
+      capabilitySeed?: ClientCapabilities;
     }
   );
+  private createClient;
+  /**
+   * Configure the handler used for server-initiated elicitation requests.
+   *
+   * If the connection has not been initialized yet, rebuild the SDK client so
+   * handler-driven elicitation capabilities are reflected in the initial
+   * handshake. A rebuild (rather than `Client.registerCapabilities`) is
+   * required because SDK capability registration is merge-only — it cannot
+   * un-advertise a mode when handlers are cleared before connecting. Active
+   * connections keep their negotiated capabilities until they reconnect.
+   */
+  configureElicitationHandlers(handlers?: MCPElicitationHandlers): void;
   /**
    * Initialize a client connection, if authentication is required, the connection will be in the AUTHENTICATING state
    * Sets connection state based on the result and emits observability events
@@ -1047,10 +1094,14 @@ declare class MCPClientConnection {
     }[]
   >;
   /**
-   * Handle elicitation request from server
-   * Automatically uses the Agent's built-in elicitation handling if available
+   * Handle elicitation request from server.
+   *
+   * Delegates to the `elicitationHandlers` connection option when provided.
+   *
+   * @deprecated Overriding or instance-patching this method directly is
+   * deprecated — pass the `elicitationHandlers` connection option instead.
    */
-  handleElicitationRequest(_request: ElicitRequest): Promise<ElicitResult>;
+  handleElicitationRequest(request: ElicitRequest): Promise<ElicitResult>;
   private isResumedStreamableHttpSession;
   get sessionId(): string | undefined;
   private getTransportName;
@@ -1135,6 +1186,12 @@ type MCPServerOptions = {
     sessionId?: string;
   } /** Retry options for connection and reconnection attempts */;
   retry?: RetryOptions;
+  /**
+   * Client capabilities advertised from configured handlers (currently the
+   * elicitation modes). Handlers are functions and cannot be persisted, so
+   * this records what they advertised for restores after hibernation.
+   */
+  capabilities?: ClientCapabilities;
 };
 /**
  * Result of an OAuth callback request
@@ -1207,6 +1264,14 @@ type MCPClientOAuthResult =
       authSuccess: false /** May contain untrusted content from external OAuth providers. Escape appropriately for your output context. */;
       authError: string;
     };
+type MCPClientElicitationHandler = (
+  request: ElicitRequest,
+  serverId: string
+) => Promise<ElicitResult>;
+type MCPClientElicitationHandlers = {
+  form?: MCPClientElicitationHandler;
+  url?: MCPClientElicitationHandler;
+};
 type MCPClientManagerOptions = {
   storage: DurableObjectStorage;
   createAuthProvider?: (callbackUrl: string) => AgentMcpOAuthProvider;
@@ -1238,6 +1303,7 @@ declare class MCPClientManager {
   private _createAuthProviderFn?;
   private _isRestored;
   private _pendingConnections;
+  private _elicitationHandlers?;
   /** @internal Protected for testing purposes. */
   protected readonly _onObservabilityEvent: Emitter<MCPObservabilityEvent>;
   readonly onObservabilityEvent: Event<MCPObservabilityEvent>;
@@ -1257,6 +1323,12 @@ declare class MCPClientManager {
     _version: string,
     options: MCPClientManagerOptions
   );
+  /**
+   * Scope the manager-level elicitation handler to a single connection.
+   * Returns undefined when no handler is configured so the connection keeps
+   * its default throwing behavior.
+   */
+  private scopedElicitationHandlers;
   private sql;
   private saveServerToStorage;
   private removeServerFromStorage;
@@ -1287,6 +1359,19 @@ declare class MCPClientManager {
   private _renameInMemoryConnection;
   private getServersFromStorage;
   private filterConnections;
+  /**
+   * Get the parsed server_options for a stored server, if any.
+   */
+  private getStoredServerOptions;
+  /**
+   * Clear the capabilities persisted on a stored server row. Called once a
+   * seeded connection's handshake completes (see `createConnection`): the
+   * stamp is valid for one successful restore — sessions that configure
+   * handlers re-stamp every row, so a deploy that stops configuring them
+   * stops advertising stale modes after its first connected wake instead of
+   * forever, while wakes that never handshake don't burn the stamp.
+   */
+  private clearStoredCapabilities;
   /**
    * Get the retry options for a server from stored server_options
    */
@@ -1445,6 +1530,33 @@ declare class MCPClientManager {
    * @param config OAuth callback configuration
    */
   configureOAuthCallback(config: MCPClientOAuthCallbackConfig): void;
+  /**
+   * Configure handling for server-initiated `elicitation/create` requests.
+   *
+   * The handler is held in memory only and applied to every MCP connection
+   * created or restored by this manager. Call this before registering
+   * connections when you want the initial MCP handshake to advertise
+   * handler-driven form- and url-mode elicitation. Existing active connections
+   * keep their negotiated capabilities until they reconnect.
+   *
+   * The advertised modes are persisted with each stored server, so
+   * connections restored after hibernation re-advertise them at the handshake
+   * even when this is called later in the wake-up (e.g. from onStart) — the
+   * handlers attach to the live connections as soon as this runs.
+   *
+   * Pass undefined to clear the handler.
+   *
+   * @param handlers Elicitation handlers keyed by mode, each scoped with the server id that sent the request
+   */
+  configureElicitationHandlers(handlers?: MCPClientElicitationHandlers): void;
+  /** Client capabilities advertised from the currently configured handlers. */
+  private advertisedHandlerCapabilities;
+  /**
+   * Record the handler-derived capabilities on every stored server row so a
+   * restore after hibernation re-advertises them before the handlers
+   * themselves are reconfigured.
+   */
+  private persistAdvertisedCapabilities;
   /**
    * Get the current OAuth callback configuration
    * @returns The current OAuth callback configuration
@@ -1743,9 +1855,7 @@ declare class MCPClientManager {
                   uri: string;
                   text: string;
                   mimeType?: string | undefined;
-                  _meta /** Include only connections matching this server ID (or IDs). */?/** Include only connections matching this server ID (or IDs). */ :
-                    | Record<string, unknown>
-                    | undefined;
+                  _meta?: Record<string, unknown> | undefined;
                 }
               | {
                   uri: string;
@@ -1784,11 +1894,7 @@ declare class MCPClientManager {
             icons?:
               | {
                   src: string;
-                  mimeType?/**
-                   * Event that fires whenever any MCP server state changes (registered, connected, removed, etc.)
-                   * This is useful for broadcasting server state to clients.
-                   */
-                  : string | undefined;
+                  mimeType?: string | undefined;
                   sizes?: string[] | undefined;
                   theme?: "light" | "dark" | undefined;
                 }[]
@@ -4663,6 +4769,7 @@ declare class Agent<
         state: typeof MCPConnectionState.READY;
       }
   >;
+  private _isAbsoluteHttpUrl;
   removeMcpServer(id: string): Promise<void>;
   getMcpServers(): MCPServersState;
   /**
@@ -5275,71 +5382,72 @@ type AgentToolEventState<Part extends AgentToolRunPart = AgentToolRunPart> = {
 //#endregion
 export {
   RoutingRetryOptions as $,
-  McpClientOptions as $t,
+  WorkerTransport as $t,
   AgentGetOptions as A,
-  getNamespacedData as At,
+  MCP_SERVER_ID_MAX_LENGTH as At,
   EmailSendBinding as B,
-  McpAgent as Bt,
+  RPC_DO_PREFIX as Bt,
   DetachedRunAgentToolResult as C,
-  MCPConnectionResult as Ct,
+  MCPClientOAuthCallbackConfig as Ct,
   AddRpcMcpServerOptions as D,
-  MCPServerOptions as Dt,
+  MCPOAuthCallbackResult as Dt,
   AddMcpServerOptions as E,
-  MCPServerFilter as Et,
+  MCPDiscoverResult as Et,
   Connection$1 as F,
-  RPCServerTransportOptions as Ft,
+  MCPElicitationHandlers as Ft,
   FiberStatus as G,
-  experimental_createMcpHandler as Gt,
+  ClearableEventStore as Gt,
   FiberInspection as H,
-  DurableObjectEventStore as Ht,
+  ElicitRequestSchema$1 as Ht,
   ConnectionContext$1 as I,
-  RPC_DO_PREFIX as It,
+  RPCClientTransport as It,
   MCPServerMessage as J,
-  TransportState as Jt,
+  createMcpHandler as Jt,
   ListFibersOptions as K,
-  McpAuthContext as Kt,
+  DurableObjectEventStore as Kt,
   DEFAULT_AGENT_STATIC_OPTIONS as L,
-  ElicitRequest$1 as Lt,
+  RPCClientTransportOptions as Lt,
   AgentOptions as M,
-  RPCClientTransport as Mt,
+  getNamespacedData as Mt,
   AgentStaticOptions as N,
-  RPCClientTransportOptions as Nt,
+  normalizeServerId as Nt,
   Agent as O,
-  MCP_SERVER_ID_MAX_LENGTH as Ot,
+  MCPServerFilter as Ot,
   CallableMetadata as P,
-  RPCServerTransport as Pt,
+  MCPElicitationHandler as Pt,
   RPCResponse as Q,
-  StreamableHTTPEdgeClientTransport as Qt,
+  TransportState as Qt,
   DeleteFibersOptions as R,
-  ElicitRequestSchema$1 as Rt,
+  RPCServerTransport as Rt,
   DetachedAgentToolConfig as S,
-  MCPClientOAuthResult as St,
+  MCPClientManagerOptions as St,
   RunAgentToolResult as T,
-  MCPOAuthCallbackResult as Tt,
+  MCPConnectionResult as Tt,
   FiberRecoveryContext as U,
-  CreateMcpHandlerOptions as Ut,
+  ElicitResult$1 as Ut,
   FiberContext as V,
-  ClearableEventStore as Vt,
+  ElicitRequest$1 as Vt,
   FiberRecoveryResult as W,
-  createMcpHandler as Wt,
+  McpAgent as Wt,
   QueueItem as X,
-  WorkerTransportOptions as Xt,
+  McpAuthContext as Xt,
   MCPServersState as Y,
-  WorkerTransport as Yt,
+  experimental_createMcpHandler as Yt,
   RPCRequest as Z,
-  SSEEdgeClientTransport as Zt,
+  getMcpAuthContext as Zt,
   AgentToolRunState as _,
   MCPAITool as _t,
   AgentToolEvent as a,
-  routeSubAgentRequest as an,
+  SUB_PREFIX as an,
   StartFiberResult as at,
   AgentToolTerminalStatus as b,
-  MCPClientManagerOptions as bt,
+  MCPClientElicitationHandlers as bt,
   AgentToolFailure as c,
+  parseSubAgentPath as cn,
   SubAgentClass as ct,
   AgentToolMilestone as d,
   callable as dt,
-  TransportType as en,
+  WorkerTransportOptions as en,
   Schedule as et,
   AgentToolProgress as f,
   getAgentByName as ft,
@@ -5348,44 +5456,47 @@ export {
   AgentToolRunInspection as h,
   routeAgentRequest as ht,
   AgentToolDisplayMetadata as i,
-  parseSubAgentPath as in,
+  TransportType as in,
   StartFiberOptions as it,
   AgentNamespace as j,
-  normalizeServerId as jt,
+  RegisterServerOptions as jt,
   AgentContext as k,
-  RegisterServerOptions as kt,
+  MCPServerOptions as kt,
   AgentToolInterruptedReason as l,
+  routeSubAgentRequest as ln,
   SubAgentStub as lt,
   AgentToolRunInfo as m,
   routeAgentEmail as mt,
   AGENT_TOOL_PROGRESS_PART as n,
-  SubAgentPathMatch as nn,
+  StreamableHTTPEdgeClientTransport as nn,
   SendEmailOptions as nt,
   AgentToolEventMessage as o,
+  SubAgentPathMatch as on,
   StateUpdateMessage as ot,
   AgentToolProgressSnapshot as p,
   getCurrentAgent as pt,
   MCPServer as q,
-  getMcpAuthContext as qt,
+  CreateMcpHandlerOptions as qt,
   AgentToolChildAdapter as r,
-  getSubAgentByName as rn,
+  McpClientOptions as rn,
   SqlError as rt,
   AgentToolEventState as s,
+  getSubAgentByName as sn,
   StreamingResponse as st,
   AGENT_TOOL_MILESTONE_PART as t,
-  SUB_PREFIX as tn,
+  SSEEdgeClientTransport as tn,
   ScheduleCriteria as tt,
   AgentToolLifecycleResult as u,
   WSMessage$1 as ut,
   AgentToolRunStatus as v,
   MCPAIToolSet as vt,
   RunAgentToolOptions as w,
-  MCPDiscoverResult as wt,
+  MCPClientOAuthResult as wt,
   ChatCapableAgentClass as x,
-  MCPClientOAuthCallbackConfig as xt,
+  MCPClientManager as xt,
   AgentToolStoredChunk as y,
-  MCPClientManager as yt,
+  MCPClientElicitationHandler as yt,
   EmailRoutingOptions as z,
-  ElicitResult$1 as zt
+  RPCServerTransportOptions as zt
 };
-//# sourceMappingURL=agent-tool-types-CNyE1iz_.d.ts.map
+//# sourceMappingURL=agent-tool-types-OhWqAbCp.d.ts.map

package/dist/agent-tool-types.d.ts

@@ -24,7 +24,7 @@ import {
   w as RunAgentToolOptions,
   x as ChatCapableAgentClass,
   y as AgentToolStoredChunk
-} from "./agent-tool-types-CNyE1iz_.js";
+} from "./agent-tool-types-OhWqAbCp.js";
 export {
   AGENT_TOOL_MILESTONE_PART,
   AGENT_TOOL_PROGRESS_PART,

package/dist/{agent-tools-BeOheFBK.d.ts → agent-tools-LdNKGZT9.d.ts}

@@ -4,7 +4,7 @@ import {
   o as AgentToolEventMessage,
   s as AgentToolEventState,
   y as AgentToolStoredChunk
-} from "./agent-tool-types-CNyE1iz_.js";
+} from "./agent-tool-types-OhWqAbCp.js";
 
 //#region src/chat/agent-tools.d.ts
 type AgentToolProgressEmitResult = "emitted" | "coalesced" | "inactive";
@@ -130,4 +130,4 @@ export {
   interceptAgentToolBroadcast as s,
   AgentToolBroadcastHooks as t
 };
-//# sourceMappingURL=agent-tools-BeOheFBK.d.ts.map
+//# sourceMappingURL=agent-tools-LdNKGZT9.d.ts.map

package/dist/agent-tools.d.ts

@@ -19,7 +19,7 @@ import {
   w as RunAgentToolOptions,
   x as ChatCapableAgentClass,
   y as AgentToolStoredChunk
-} from "./agent-tool-types-CNyE1iz_.js";
+} from "./agent-tool-types-OhWqAbCp.js";
 import { Tool } from "ai";
 
 //#region src/agent-tools.d.ts

package/dist/chat/index.d.ts

@@ -4,7 +4,7 @@ import {
   a as AgentToolEvent,
   o as AgentToolEventMessage,
   s as AgentToolEventState
-} from "../agent-tool-types-CNyE1iz_.js";
+} from "../agent-tool-types-OhWqAbCp.js";
 import {
   n as ClientToolSchema,
   r as createToolsFromClientSchemas,
@@ -18,7 +18,7 @@ import {
   r as AgentToolProgressEmitResult,
   s as interceptAgentToolBroadcast,
   t as AgentToolBroadcastHooks
-} from "../agent-tools-BeOheFBK.js";
+} from "../agent-tools-LdNKGZT9.js";
 import { JSONSchema7, UIMessage } from "ai";
 import { Connection } from "agents";
 

package/dist/chat-sdk/index.d.ts

@@ -2,7 +2,7 @@ import {
   O as Agent,
   ct as SubAgentClass,
   lt as SubAgentStub
-} from "../agent-tool-types-CNyE1iz_.js";
+} from "../agent-tool-types-OhWqAbCp.js";
 import { Lock, QueueEntry, StateAdapter } from "chat";
 
 //#region src/chat-sdk/agent.d.ts