agents 0.8.7 → 0.10.0

package/dist/{index-C-6EMK-E.d.ts → index-BPkkIqMn.d.ts}

@@ -1,11 +1,11 @@
-import { n as AgentEmail } from "./internal_context-DT8RxmAN.js";
-import { t as RetryOptions } from "./retries-DXMQGhG3.js";
+import { n as AgentEmail } from "./internal_context-DuQZFvWI.js";
+import { t as RetryOptions } from "./retries-B_CN5KM9.js";
 import {
   n as Observability,
   r as ObservabilityEvent,
   s as MCPObservabilityEvent
-} from "./index-Ua2Nfvbm.js";
-import { t as AgentMcpOAuthProvider } from "./do-oauth-client-provider-C2jurFjW.js";
+} from "./index-DDSX-g7W.js";
+import { t as AgentMcpOAuthProvider } from "./do-oauth-client-provider-31gqR33H.js";
 import {
   _ as WorkflowPage,
   g as WorkflowInfo,
@@ -13,9 +13,10 @@ import {
   l as WorkflowCallback,
   s as RunWorkflowOptions,
   y as WorkflowQueryCriteria
-} from "./workflow-types-CZNXKj_D.js";
-import { t as MessageType } from "./types-C-m0II8i.js";
-import { r as EmailResolver } from "./email-DwPlM0bQ.js";
+} from "./workflow-types-XmOkuI7A.js";
+import { t as MessageType } from "./types-B9A8AU7B.js";
+import { r as EmailResolver } from "./email-Cql45SKP.js";
+import { RpcTarget } from "cloudflare:workers";
 import {
   Connection,
   Connection as Connection$1,
@@ -55,8 +56,8 @@ import {
   ServerCapabilities,
   Tool
 } from "@modelcontextprotocol/sdk/types.js";
-import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { ToolSet } from "ai";
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { RequestOptions } from "@modelcontextprotocol/sdk/shared/protocol.js";
 import {
   Transport,
@@ -499,10 +500,13 @@ declare class MCPClientConnection {
   lastConnectedTransport: BaseTransportType | undefined;
   instructions?: string;
   tools: Tool[];
+  private _transport?;
   prompts: Prompt[];
   resources: Resource[];
   resourceTemplates: ResourceTemplate[];
   serverCapabilities: ServerCapabilities | undefined;
+  /** True when resuming a streamable-http session without cached capabilities */
+  private _probingCapabilities;
   /** Tracks in-flight discovery to allow cancellation */
   private _discoveryAbortController;
   private readonly _onObservabilityEvent;
@@ -629,6 +633,7 @@ declare class MCPClientConnection {
       name: string;
       description?: string | undefined;
       mimeType?: string | undefined;
+      size?: number | undefined;
       annotations?:
         | {
             audience?: ("user" | "assistant")[] | undefined;
@@ -713,6 +718,10 @@ declare class MCPClientConnection {
    * Automatically uses the Agent's built-in elicitation handling if available
    */
   handleElicitationRequest(_request: ElicitRequest): Promise<ElicitResult>;
+  private isResumedStreamableHttpSession;
+  get sessionId(): string | undefined;
+  private getTransportName;
+  close(): Promise<void>;
   /**
    * Get the transport for the client
    * @param transportType - The transport type to get
@@ -720,7 +729,7 @@ declare class MCPClientConnection {
    */
   getTransport(
     transportType: BaseTransportType
-  ): StreamableHTTPClientTransport | SSEClientTransport | RPCClientTransport;
+  ): RPCClientTransport | SSEClientTransport | StreamableHTTPClientTransport;
   private tryConnect;
   private _capabilityErrorHandler;
 }
@@ -749,6 +758,7 @@ type MCPServerOptions = {
   transport?: {
     headers?: HeadersInit;
     type?: TransportType;
+    sessionId?: string;
   } /** Retry options for connection and reconnection attempts */;
   retry?: RetryOptions;
 };
@@ -827,6 +837,19 @@ type MCPClientManagerOptions = {
   storage: DurableObjectStorage;
   createAuthProvider?: (callbackUrl: string) => AgentMcpOAuthProvider;
 };
+/**
+ * Filter options for scoping tools, prompts, resources, and resource templates
+ * to a subset of connected MCP servers. All specified criteria are AND'd together.
+ */
+type MCPServerFilter = {
+  /** Include only connections matching this server ID (or IDs). */ serverId?:
+    | string
+    | string[] /** Include only connections whose stored name matches (or is in) this value. */;
+  serverName?:
+    | string
+    | string[] /** Include only connections currently in this state (or states). */;
+  state?: MCPConnectionState | MCPConnectionState[];
+};
 /**
  * Utility class that aggregates multiple MCP clients into one
  */
@@ -864,11 +887,13 @@ declare class MCPClientManager {
   private saveServerToStorage;
   private removeServerFromStorage;
   private getServersFromStorage;
+  private filterConnections;
   /**
    * Get the retry options for a server from stored server_options
    */
   private getServerRetryOptions;
   private clearServerAuthUrl;
+  private updateStoredSessionId;
   private failConnection;
   /**
    * Create an auth provider for a server
@@ -1022,18 +1047,21 @@ declare class MCPClientManager {
    */
   getOAuthCallbackConfig(): MCPClientOAuthCallbackConfig | undefined;
   /**
+   * @param filter - Optional filter to scope results to specific servers
    * @returns namespaced list of tools
    */
-  listTools(): NamespacedData["tools"];
+  listTools(filter?: MCPServerFilter): NamespacedData["tools"];
   /**
+   * @param filter - Optional filter to scope results to specific servers
    * @returns a set of tools that you can use with the AI SDK
    */
-  getAITools(): ToolSet;
+  getAITools(filter?: MCPServerFilter): ToolSet;
   /**
    * @deprecated this has been renamed to getAITools(), and unstable_getAITools will be removed in the next major version
+   * @param filter - Optional filter to scope results to specific servers
    * @returns a set of tools that you can use with the AI SDK
    */
-  unstable_getAITools(): ToolSet;
+  unstable_getAITools(filter?: MCPServerFilter): ToolSet;
   /**
    * Closes all active in-memory connections to MCP servers.
    *
@@ -1044,6 +1072,7 @@ declare class MCPClientManager {
    * Use removeServer() instead if you want to fully clean up a server
    * (closes connection AND removes from storage).
    */
+  private cleanupClosedConnection;
   closeAllConnections(): Promise<void>;
   /**
    * Closes a connection to an MCP server
@@ -1063,17 +1092,22 @@ declare class MCPClientManager {
    */
   dispose(): Promise<void>;
   /**
+   * @param filter - Optional filter to scope results to specific servers
    * @returns namespaced list of prompts
    */
-  listPrompts(): NamespacedData["prompts"];
+  listPrompts(filter?: MCPServerFilter): NamespacedData["prompts"];
   /**
-   * @returns namespaced list of tools
+   * @param filter - Optional filter to scope results to specific servers
+   * @returns namespaced list of resources
    */
-  listResources(): NamespacedData["resources"];
+  listResources(filter?: MCPServerFilter): NamespacedData["resources"];
   /**
+   * @param filter - Optional filter to scope results to specific servers
    * @returns namespaced list of resource templates
    */
-  listResourceTemplates(): NamespacedData["resourceTemplates"];
+  listResourceTemplates(
+    filter?: MCPServerFilter
+  ): NamespacedData["resourceTemplates"];
   /**
    * Namespaced version of callTool
    */
@@ -1157,6 +1191,7 @@ declare class MCPClientManager {
               type: "resource_link";
               description?: string | undefined;
               mimeType?: string | undefined;
+              size?: number | undefined;
               annotations?:
                 | {
                     audience?: ("user" | "assistant")[] | undefined;
@@ -1327,6 +1362,7 @@ declare class MCPClientManager {
             type: "resource_link";
             description?: string | undefined;
             mimeType?: string | undefined;
+            size?: number | undefined;
             annotations?:
               | {
                   audience?: ("user" | "assistant")[] | undefined;
@@ -1527,6 +1563,27 @@ type Schedule<T = string> = {
       intervalSeconds: number;
     }
 );
+/**
+ * Context passed to the `runFiber` callback. Provides checkpoint
+ * and identity for durable execution.
+ */
+type FiberContext = {
+  /** Unique identifier for this fiber execution. */ id: string /** Checkpoint data during execution. Synchronous SQLite write. */;
+  stash(
+    data: unknown
+  ): void /** Last checkpoint data (null on first run, populated on recovery re-invocation). */;
+  snapshot: unknown | null;
+};
+/**
+ * Context passed to the `onFiberRecovered` hook when an interrupted
+ * fiber is detected after DO restart.
+ */
+type FiberRecoveryContext = {
+  /** Fiber ID. */ id: string /** Name passed to `runFiber`. */;
+  name: string /** Last checkpoint data from `stash()`, or null if never stashed. */;
+  snapshot: unknown | null;
+  [key: string]: unknown;
+};
 /**
  * MCP Server state update message from server -> Client
  */
@@ -1596,7 +1653,12 @@ declare const DEFAULT_AGENT_STATIC_OPTIONS: {
    * and force-reset. Increase this if you have callbacks that legitimately
    * take longer than 30 seconds.
    */
-  hungScheduleTimeoutSeconds: number /** Default retry options for schedule(), queue(), and this.retry() */;
+  hungScheduleTimeoutSeconds: number;
+  /**
+   * Interval in milliseconds for keepAlive() alarm heartbeats.
+   * Lower values mean faster recovery after eviction but more frequent alarms.
+   */
+  keepAliveIntervalMs: number /** Default retry options for schedule(), queue(), and this.retry() */;
   retry: {
     maxAttempts: number;
     baseDelayMs: number;
@@ -1613,6 +1675,12 @@ interface AgentStaticOptions {
   hibernate?: boolean;
   sendIdentityOnConnect?: boolean;
   hungScheduleTimeoutSeconds?: number;
+  /**
+   * Interval in milliseconds for keepAlive() alarm heartbeats.
+   * Default: 30000 (30 seconds). Lower values mean faster recovery
+   * after eviction but more frequent alarms.
+   */
+  keepAliveIntervalMs?: number;
   /** Default retry options for schedule(), queue(), and this.retry(). */
   retry?: RetryOptions;
 }
@@ -1671,12 +1739,16 @@ declare class Agent<
   private _warnedScheduleInOnStart;
   /**
    * Number of active keepAlive() callers. When > 0, `_scheduleNextAlarm()`
-   * caps the next alarm at KEEP_ALIVE_INTERVAL_MS so the DO stays alive.
+   * caps the next alarm at `keepAliveIntervalMs` so the DO stays alive.
    * Purely in-memory — lost on eviction, which is correct because the
    * in-memory work keepAlive was protecting is also lost.
    * @internal
    */
   _keepAliveRefs: number;
+  /** @internal In-memory set of fiber IDs running in this process. */
+  private _runFiberActiveFibers;
+  /** @internal Prevents re-entrant recovery from overlapping alarm ticks. */
+  private _runFiberRecoveryInProgress;
   private _ParentClass;
   readonly mcp: MCPClientManager;
   /**
@@ -1913,9 +1985,16 @@ declare class Agent<
   /**
    * Called when the Agent receives an email via routeAgentEmail()
    * Override this method to handle incoming emails
-   * @param email Email message to process
+   * @param payload Internal wire format — plain data + RpcTarget bridge
    */
-  _onEmail(email: AgentEmail): Promise<void>;
+  _onEmail(payload: {
+    from: string;
+    to: string;
+    headers: Headers;
+    rawSize: number;
+    _secureRouted?: boolean;
+    _bridge: EmailBridge;
+  }): Promise<void>;
   /**
    * Reply to an email
    * @param email The email to reply to
@@ -2113,8 +2192,9 @@ declare class Agent<
    *
    * Use this when you have long-running work and need to prevent the
    * DO from going idle (eviction after ~70-140s of inactivity).
-   * The heartbeat fires every 30 seconds via the alarm system, without
-   * creating schedule rows or emitting observability events.
+   * The heartbeat fires every `keepAliveIntervalMs` (default 30s) via the
+   * alarm system, without creating schedule rows or emitting observability
+   * events. Configure via `static options = { keepAliveIntervalMs: 5000 }`.
    *
    * @example
    * ```ts
@@ -2145,11 +2225,48 @@ declare class Agent<
    */
   keepAliveWhile<T>(fn: () => Promise<T>): Promise<T>;
   /**
-   * Hook invoked on every alarm cycle, after schedule processing.
-   * Override in subclasses (e.g. the fiber mixin) to run
-   * housekeeping — such as detecting fibers interrupted by eviction.
+   * Run a function as a durable fiber. The fiber is registered in SQLite
+   * before execution, checkpointable during execution via `ctx.stash()`,
+   * and recoverable after eviction via `onFiberRecovered`.
+   *
+   * - Row created in `cf_agents_runs` at start, deleted on completion
+   * - `keepAlive()` held for the duration — prevents idle eviction
+   * - Inline (await result) or fire-and-forget (`void this.runFiber(...)`)
+   *
+   * @param name Informational name for debugging and recovery filtering
+   * @param fn Async function to execute. Receives a FiberContext with stash/snapshot.
+   * @returns The return value of fn
+   */
+  runFiber<T>(name: string, fn: (ctx: FiberContext) => Promise<T>): Promise<T>;
+  /**
+   * Checkpoint data for the currently executing fiber.
+   * Uses AsyncLocalStorage to identify the correct fiber,
+   * so it works correctly even with concurrent fibers.
+   *
+   * Throws if called outside a `runFiber` callback.
+   */
+  stash(data: unknown): void;
+  /**
+   * Called when an interrupted fiber is detected after restart.
+   * Override to implement recovery (re-invoke work, notify clients, etc.).
+   *
+   * Internal framework fibers are filtered by `_handleInternalFiberRecovery`
+   * before this hook runs — users only see their own fibers.
+   *
+   * Default: logs a warning.
+   */
+  onFiberRecovered(_ctx: FiberRecoveryContext): Promise<void>;
+  /**
+   * Override point for subclasses to handle internal (framework) fibers
+   * before the user's recovery hook fires. Return `true` if handled.
    * @internal
    */
+  protected _handleInternalFiberRecovery(
+    _ctx: FiberRecoveryContext
+  ): Promise<boolean>;
+  /** @internal Detect fibers left by a dead process (runFiber system). */
+  private _checkRunFibers;
+  /** @internal */
   _onAlarmHousekeeping(): Promise<void>;
   private _scheduleNextAlarm;
   /**
@@ -2735,6 +2852,19 @@ type EmailRoutingOptions<Env> = AgentOptions<Env> & {
    */
   onNoRoute?: (email: ForwardableEmailMessage) => void | Promise<void>;
 };
+declare class EmailBridge extends RpcTarget {
+  #private;
+  constructor(email: ForwardableEmailMessage);
+  getRaw(): Promise<Uint8Array>;
+  setReject(reason: string): void;
+  forward(rcptTo: string, headers?: Headers): Promise<EmailSendResult>;
+  reply(options: {
+    from: string;
+    to: string;
+    raw: string;
+  }): Promise<EmailSendResult>;
+  [Symbol.dispose](): void;
+}
 /**
  * Route an email to the appropriate Agent
  * @param email The email to route
@@ -2802,67 +2932,70 @@ declare class StreamingResponse {
 }
 //#endregion
 export {
-  experimental_createMcpHandler as $,
-  routeAgentRequest as A,
-  RegisterServerOptions as B,
-  SubAgentClass as C,
-  getAgentByName as D,
-  callable as E,
-  MCPClientOAuthResult as F,
-  RPCServerTransportOptions as G,
-  RPCClientTransport as H,
-  MCPConnectionResult as I,
-  ElicitRequestSchema$1 as J,
-  RPC_DO_PREFIX as K,
-  MCPDiscoverResult as L,
-  MCPClientManager as M,
-  MCPClientManagerOptions as N,
-  getCurrentAgent as O,
-  MCPClientOAuthCallbackConfig as P,
-  createMcpHandler as Q,
-  MCPOAuthCallbackResult as R,
-  StreamingResponse as S,
-  WSMessage as T,
-  RPCClientTransportOptions as U,
-  getNamespacedData as V,
-  RPCServerTransport as W,
-  McpAgent as X,
-  ElicitResult$1 as Y,
-  CreateMcpHandlerOptions as Z,
-  RPCRequest as _,
+  McpAgent as $,
+  getCurrentAgent as A,
+  MCPOAuthCallbackResult as B,
+  StateUpdateMessage as C,
+  WSMessage as D,
+  SubAgentStub as E,
+  MCPClientManagerOptions as F,
+  RPCClientTransport as G,
+  MCPServerOptions as H,
+  MCPClientOAuthCallbackConfig as I,
+  RPCServerTransportOptions as J,
+  RPCClientTransportOptions as K,
+  MCPClientOAuthResult as L,
+  routeAgentRequest as M,
+  unstable_callable as N,
+  callable as O,
+  MCPClientManager as P,
+  ElicitResult$1 as Q,
+  MCPConnectionResult as R,
+  SqlError as S,
+  SubAgentClass as T,
+  RegisterServerOptions as U,
+  MCPServerFilter as V,
+  getNamespacedData as W,
+  ElicitRequest$1 as X,
+  RPC_DO_PREFIX as Y,
+  ElicitRequestSchema$1 as Z,
+  MCPServersState as _,
   AgentNamespace as a,
-  SSEEdgeClientTransport as at,
-  SqlError as b,
+  TransportState as at,
+  RPCResponse as b,
   CallableMetadata as c,
-  TransportType as ct,
+  SSEEdgeClientTransport as ct,
   DEFAULT_AGENT_STATIC_OPTIONS as d,
-  McpAuthContext as et,
+  TransportType as dt,
+  CreateMcpHandlerOptions as et,
   EmailRoutingOptions as f,
-  QueueItem as g,
-  MCPServersState as h,
+  MCPServerMessage as g,
+  MCPServer as h,
   AgentContext as i,
-  WorkerTransportOptions as it,
-  unstable_callable as j,
-  routeAgentEmail as k,
+  getMcpAuthContext as it,
+  routeAgentEmail as j,
+  getAgentByName as k,
   Connection$1 as l,
-  MCPServerMessage as m,
+  StreamableHTTPEdgeClientTransport as lt,
+  FiberRecoveryContext as m,
   AddRpcMcpServerOptions as n,
-  TransportState as nt,
+  experimental_createMcpHandler as nt,
   AgentOptions as o,
-  StreamableHTTPEdgeClientTransport as ot,
-  MCPServer as p,
-  ElicitRequest$1 as q,
+  WorkerTransport as ot,
+  FiberContext as p,
+  RPCServerTransport as q,
   Agent as r,
-  WorkerTransport as rt,
+  McpAuthContext as rt,
   AgentStaticOptions as s,
-  McpClientOptions as st,
+  WorkerTransportOptions as st,
   AddMcpServerOptions as t,
-  getMcpAuthContext as tt,
+  createMcpHandler as tt,
   ConnectionContext$1 as u,
-  RPCResponse as v,
-  SubAgentStub as w,
-  StateUpdateMessage as x,
-  Schedule as y,
-  MCPServerOptions as z
+  McpClientOptions as ut,
+  QueueItem as v,
+  StreamingResponse as w,
+  Schedule as x,
+  RPCRequest as y,
+  MCPDiscoverResult as z
 };
-//# sourceMappingURL=index-C-6EMK-E.d.ts.map
+//# sourceMappingURL=index-BPkkIqMn.d.ts.map

package/dist/{index-Ua2Nfvbm.d.ts → index-DDSX-g7W.d.ts}

@@ -67,6 +67,16 @@ type MCPObservabilityEvent =
         error?: string;
         capability?: string;
       }
+    >
+  | BaseEvent<
+      "mcp:client:close",
+      {
+        url: string;
+        transport?: string;
+        state: string;
+        error?: string;
+        phase?: "terminate-session" | "client-close";
+      }
     >;
 //#endregion
 //#region src/observability/agent.d.ts
@@ -403,4 +413,4 @@ export {
   MCPObservabilityEvent as s,
   ChannelEventMap as t
 };
-//# sourceMappingURL=index-Ua2Nfvbm.d.ts.map
+//# sourceMappingURL=index-DDSX-g7W.d.ts.map

package/dist/index.d.ts

@@ -1,46 +1,48 @@
-import { r as __DO_NOT_USE_WILL_BREAK__agentContext } from "./internal_context-DT8RxmAN.js";
-import { t as RetryOptions } from "./retries-DXMQGhG3.js";
+import { r as __DO_NOT_USE_WILL_BREAK__agentContext } from "./internal_context-DuQZFvWI.js";
+import { t as RetryOptions } from "./retries-B_CN5KM9.js";
 import {
-  A as routeAgentRequest,
-  C as SubAgentClass,
-  D as getAgentByName,
-  E as callable,
-  O as getCurrentAgent,
-  S as StreamingResponse,
-  T as WSMessage,
-  _ as RPCRequest,
+  A as getCurrentAgent,
+  C as StateUpdateMessage,
+  D as WSMessage,
+  E as SubAgentStub,
+  M as routeAgentRequest,
+  N as unstable_callable,
+  O as callable,
+  S as SqlError,
+  T as SubAgentClass,
+  _ as MCPServersState,
   a as AgentNamespace,
-  b as SqlError,
+  b as RPCResponse,
   c as CallableMetadata,
-  ct as TransportType,
   d as DEFAULT_AGENT_STATIC_OPTIONS,
+  dt as TransportType,
   f as EmailRoutingOptions,
-  g as QueueItem,
-  h as MCPServersState,
+  g as MCPServerMessage,
+  h as MCPServer,
   i as AgentContext,
-  j as unstable_callable,
-  k as routeAgentEmail,
+  j as routeAgentEmail,
+  k as getAgentByName,
   l as Connection,
-  m as MCPServerMessage,
+  m as FiberRecoveryContext,
   n as AddRpcMcpServerOptions,
   o as AgentOptions,
-  p as MCPServer,
+  p as FiberContext,
   r as Agent,
   s as AgentStaticOptions,
   t as AddMcpServerOptions,
   u as ConnectionContext,
-  v as RPCResponse,
-  w as SubAgentStub,
-  x as StateUpdateMessage,
-  y as Schedule
-} from "./index-C-6EMK-E.js";
+  v as QueueItem,
+  w as StreamingResponse,
+  x as Schedule,
+  y as RPCRequest
+} from "./index-BPkkIqMn.js";
 import {
   n as AgentsOAuthProvider,
   r as DurableObjectOAuthClientProvider,
   t as AgentMcpOAuthProvider
-} from "./do-oauth-client-provider-C2jurFjW.js";
-import { t as MessageType } from "./types-C-m0II8i.js";
-import { l as createHeaderBasedEmailResolver } from "./email-DwPlM0bQ.js";
+} from "./do-oauth-client-provider-31gqR33H.js";
+import { t as MessageType } from "./types-B9A8AU7B.js";
+import { l as createHeaderBasedEmailResolver } from "./email-Cql45SKP.js";
 export {
   AddMcpServerOptions,
   AddRpcMcpServerOptions,
@@ -57,6 +59,8 @@ export {
   DEFAULT_AGENT_STATIC_OPTIONS,
   DurableObjectOAuthClientProvider,
   EmailRoutingOptions,
+  FiberContext,
+  FiberRecoveryContext,
   MCPServer,
   MCPServerMessage,
   MCPServersState,