agents 0.7.5 → 0.7.7

package/dist/{index-p1XLNvwQ.d.ts → index-DBW341gU.d.ts}

@@ -268,6 +268,7 @@ declare abstract class McpAgent<
   Props extends Record<string, unknown> = Record<string, unknown>
 > extends Agent<Env, State, Props> {
   private _transport?;
+  private _pendingElicitations;
   props?: Props;
   shouldSendProtocolMessages(
     _connection: Connection$1,
@@ -326,9 +327,7 @@ declare abstract class McpAgent<
     message: string;
     requestedSchema: unknown;
   }): Promise<ElicitResult>;
-  /** Wait for elicitation response through storage polling */
-  private _waitForElicitationResponse;
-  /** Handle elicitation responses */
+  /** Handle elicitation responses via in-memory resolver */
   private _handleElicitationResponse;
   /**
    * Handle an RPC message for MCP
@@ -708,7 +707,7 @@ declare class MCPClientConnection {
    */
   getTransport(
     transportType: BaseTransportType
-  ): RPCClientTransport | SSEClientTransport | StreamableHTTPClientTransport;
+  ): SSEClientTransport | StreamableHTTPClientTransport | RPCClientTransport;
   private tryConnect;
   private _capabilityErrorHandler;
 }
@@ -1126,13 +1125,7 @@ declare class MCPClientManager {
                     lastModified?: string | undefined;
                   }
                 | undefined;
-              _meta /**
-               * We need to delay loading ai sdk, because putting it in module scope is
-               * causing issues with startup time.
-               * The only place it's used is in getAITools, which only matters after
-               * .connect() is called on at least one server.
-               * So it's safe to delay loading it until .connect() is called.
-               */?: Record<string, unknown> | undefined;
+              _meta?: Record<string, unknown> | undefined;
             }
           | {
               type: "resource";
@@ -1444,6 +1437,38 @@ declare class SqlError extends Error {
   readonly query: string;
   constructor(query: string, cause: unknown);
 }
+/**
+ * Constructor type for a sub-agent class.
+ * Used by {@link Agent.subAgent} to reference the child class
+ * via `ctx.exports`.
+ *
+ * The class name (`cls.name`) must match the export name in the
+ * worker entry point — re-exports under a different name
+ * (e.g. `export { Foo as Bar }`) are not supported.
+ */
+type SubAgentClass<T extends Agent = Agent> = {
+  new (ctx: DurableObjectState, env: never): T;
+};
+/**
+ * Wraps `T` in a `Promise` unless it already is one.
+ */
+type Promisify<T> = T extends Promise<unknown> ? T : Promise<T>;
+/**
+ * A typed RPC stub for a sub-agent. Exposes all public instance methods
+ * as callable RPC methods with Promise-wrapped return types.
+ *
+ * Methods inherited from `Agent` / `Server` / `DurableObject` internals
+ * are excluded — only user-defined methods on the subclass are exposed.
+ */
+type SubAgentStub<T extends Agent> = {
+  [K in keyof T as K extends keyof Agent
+    ? never
+    : T[K] extends (...args: never[]) => unknown
+      ? K
+      : never]: T[K] extends (...args: infer A) => infer R
+    ? (...args: A) => Promisify<R>
+    : never;
+};
 /**
  * Decorator that marks a method as callable by clients
  * @param metadata Optional metadata about the callable method
@@ -1638,6 +1663,8 @@ declare class Agent<
    * - "none" → neither hook is overridden, skip entirely
    */
   private _persistenceHookMode;
+  /** True when this agent runs as a facet (sub-agent) inside a parent. */
+  private _isFacet;
   private _ParentClass;
   readonly mcp: MCPClientManager;
   /**
@@ -1688,6 +1715,16 @@ declare class Agent<
     strings: TemplateStringsArray,
     ...values: (string | number | boolean | null)[]
   ): T[];
+  /**
+   * Create all internal tables and run migrations if needed.
+   * Called by the constructor on every wake. Idempotent — skips DDL when
+   * the stored schema version matches CURRENT_SCHEMA_VERSION.
+   *
+   * Protected so that test agents can re-run the real migration path
+   * after manipulating DB state (since ctx.abort() is unavailable in
+   * local dev and the constructor only runs once per DO instance).
+   */
+  protected _ensureSchema(): void;
   constructor(ctx: AgentContext, env: Env);
   /**
    * Check for workflows referencing unknown bindings and warn with migration suggestion.
@@ -1736,6 +1773,34 @@ declare class Agent<
    * @returns True if the connection is readonly
    */
   isConnectionReadonly(connection: Connection): boolean;
+  /**
+   * ⚠️ INTERNAL — DO NOT USE IN APPLICATION CODE. ⚠️
+   *
+   * Read an internal `_cf_`-prefixed flag from the raw connection state,
+   * bypassing the user-facing state wrapper that strips internal keys.
+   *
+   * This exists for framework mixins (e.g. voice) that need to persist
+   * flags in the connection attachment across hibernation. Application
+   * code should use `connection.state` and `connection.setState()` instead.
+   *
+   * @internal
+   */
+  _unsafe_getConnectionFlag(connection: Connection, key: string): unknown;
+  /**
+   * ⚠️ INTERNAL — DO NOT USE IN APPLICATION CODE. ⚠️
+   *
+   * Write an internal `_cf_`-prefixed flag to the raw connection state,
+   * bypassing the user-facing state wrapper. The key must be registered
+   * in `CF_INTERNAL_KEYS` so it is preserved across user `setState` calls
+   * and hidden from `connection.state`.
+   *
+   * @internal
+   */
+  _unsafe_setConnectionFlag(
+    connection: Connection,
+    key: string,
+    value: unknown
+  ): void;
   /**
    * Override this method to determine if a connection should be readonly on connect
    * @param _connection The connection that is being established
@@ -2066,6 +2131,60 @@ declare class Agent<
    * See {@link https://developers.cloudflare.com/agents/api-reference/schedule-tasks/}
    */
   alarm(): Promise<void>;
+  /**
+   * Marks this agent as running inside a facet (sub-agent). Once set,
+   * scheduling methods throw a clear error instead of crashing on
+   * `setAlarm()` (which is not supported in facets).
+   * @internal
+   */
+  _cf_markAsFacet(): Promise<void>;
+  /**
+   * Get or create a named sub-agent — a child Durable Object (facet)
+   * with its own isolated SQLite storage running on the same machine.
+   *
+   * The child class must extend `Agent` and be exported from the worker
+   * entry point. The first call for a given name triggers the child's
+   * `onStart()`. Subsequent calls return the existing instance.
+   *
+   * @experimental Requires the `"experimental"` compatibility flag.
+   *
+   * @param cls The Agent subclass (must be exported from the worker)
+   * @param name Unique name for this child instance
+   * @returns A typed RPC stub for calling methods on the child
+   *
+   * @example
+   * ```typescript
+   * const searcher = await this.subAgent(SearchAgent, "main-search");
+   * const results = await searcher.search("cloudflare agents");
+   * ```
+   */
+  subAgent<T extends Agent>(
+    cls: SubAgentClass<T>,
+    name: string
+  ): Promise<SubAgentStub<T>>;
+  /**
+   * Forcefully abort a running sub-agent. The child stops executing
+   * immediately and will be restarted on next {@link subAgent} call.
+   * Pending RPC calls receive the reason as an error.
+   * Transitively aborts the child's own children.
+   *
+   * @experimental Requires the `"experimental"` compatibility flag.
+   *
+   * @param cls The Agent subclass used when creating the child
+   * @param name Name of the child to abort
+   * @param reason Error thrown to pending/future RPC callers
+   */
+  abortSubAgent(cls: SubAgentClass, name: string, reason?: unknown): void;
+  /**
+   * Delete a sub-agent: abort it if running, then permanently wipe its
+   * storage. Transitively deletes the child's own children.
+   *
+   * @experimental Requires the `"experimental"` compatibility flag.
+   *
+   * @param cls The Agent subclass used when creating the child
+   * @param name Name of the child to delete
+   */
+  deleteSubAgent(cls: SubAgentClass, name: string): void;
   /**
    * Destroy the Agent, removing all state and scheduled tasks
    */
@@ -2394,9 +2513,9 @@ declare class Agent<
    * @param progress - Typed progress data (default: DefaultProgress)
    */
   onWorkflowProgress(
-    _workflowName: string,
-    _workflowId: string,
-    _progress: unknown
+    workflowName: string,
+    workflowId: string,
+    progress: unknown
   ): Promise<void>;
   /**
    * Called when a workflow completes successfully.
@@ -2407,9 +2526,9 @@ declare class Agent<
    * @param result - Optional result data
    */
   onWorkflowComplete(
-    _workflowName: string,
-    _workflowId: string,
-    _result?: unknown
+    workflowName: string,
+    workflowId: string,
+    result?: unknown
   ): Promise<void>;
   /**
    * Called when a workflow encounters an error.
@@ -2420,9 +2539,9 @@ declare class Agent<
    * @param error - Error message
    */
   onWorkflowError(
-    _workflowName: string,
-    _workflowId: string,
-    _error: string
+    workflowName: string,
+    workflowId: string,
+    error: string
   ): Promise<void>;
   /**
    * Called when a workflow sends a custom event.
@@ -2433,9 +2552,9 @@ declare class Agent<
    * @param event - Custom event payload
    */
   onWorkflowEvent(
-    _workflowName: string,
-    _workflowId: string,
-    _event: unknown
+    workflowName: string,
+    workflowId: string,
+    event: unknown
   ): Promise<void>;
   /**
    * Handle a workflow callback via RPC.
@@ -2655,65 +2774,67 @@ declare class StreamingResponse {
 }
 //#endregion
 export {
-  getMcpAuthContext as $,
-  MCPClientManager as A,
-  RPCClientTransport as B,
-  WSMessage as C,
-  routeAgentEmail as D,
-  getCurrentAgent as E,
-  MCPDiscoverResult as F,
-  ElicitRequest$1 as G,
-  RPCServerTransport as H,
-  MCPOAuthCallbackResult as I,
-  McpAgent as J,
-  ElicitRequestSchema$1 as K,
-  MCPServerOptions as L,
-  MCPClientOAuthCallbackConfig as M,
-  MCPClientOAuthResult as N,
-  routeAgentRequest as O,
-  MCPConnectionResult as P,
-  McpAuthContext as Q,
-  RegisterServerOptions as R,
+  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,
-  getAgentByName as T,
-  RPCServerTransportOptions as U,
-  RPCClientTransportOptions as V,
-  RPC_DO_PREFIX as W,
-  createMcpHandler as X,
-  CreateMcpHandlerOptions as Y,
-  experimental_createMcpHandler as Z,
+  WSMessage as T,
+  RPCClientTransportOptions as U,
+  getNamespacedData as V,
+  RPCServerTransport as W,
+  McpAgent as X,
+  ElicitResult$1 as Y,
+  CreateMcpHandlerOptions as Z,
   RPCRequest as _,
   AgentNamespace as a,
-  McpClientOptions as at,
+  SSEEdgeClientTransport as at,
   SqlError as b,
   CallableMetadata as c,
+  TransportType as ct,
   DEFAULT_AGENT_STATIC_OPTIONS as d,
-  TransportState as et,
+  McpAuthContext as et,
   EmailRoutingOptions as f,
   QueueItem as g,
   MCPServersState as h,
   AgentContext as i,
-  StreamableHTTPEdgeClientTransport as it,
-  MCPClientManagerOptions as j,
-  unstable_callable as k,
+  WorkerTransportOptions as it,
+  unstable_callable as j,
+  routeAgentEmail as k,
   Connection$1 as l,
   MCPServerMessage as m,
   AddRpcMcpServerOptions as n,
-  WorkerTransportOptions as nt,
+  TransportState as nt,
   AgentOptions as o,
-  TransportType as ot,
+  StreamableHTTPEdgeClientTransport as ot,
   MCPServer as p,
-  ElicitResult$1 as q,
+  ElicitRequest$1 as q,
   Agent as r,
-  SSEEdgeClientTransport as rt,
+  WorkerTransport as rt,
   AgentStaticOptions as s,
+  McpClientOptions as st,
   AddMcpServerOptions as t,
-  WorkerTransport as tt,
+  getMcpAuthContext as tt,
   ConnectionContext$1 as u,
   RPCResponse as v,
-  callable as w,
+  SubAgentStub as w,
   StateUpdateMessage as x,
   Schedule as y,
-  getNamespacedData as z
+  MCPServerOptions as z
 };
-//# sourceMappingURL=index-p1XLNvwQ.d.ts.map
+//# sourceMappingURL=index-DBW341gU.d.ts.map

package/dist/index.d.ts

@@ -2,37 +2,39 @@ import { r as __DO_NOT_USE_WILL_BREAK__agentContext } from "./internal_context-D
 import { l as createHeaderBasedEmailResolver } from "./email-U_MG7UET.js";
 import { t as RetryOptions } from "./retries-DXMQGhG3.js";
 import {
-  C as WSMessage,
-  D as routeAgentEmail,
-  E as getCurrentAgent,
-  O as routeAgentRequest,
+  A as routeAgentRequest,
+  C as SubAgentClass,
+  D as getAgentByName,
+  E as callable,
+  O as getCurrentAgent,
   S as StreamingResponse,
-  T as getAgentByName,
+  T as WSMessage,
   _ as RPCRequest,
   a as AgentNamespace,
   b as SqlError,
   c as CallableMetadata,
+  ct as TransportType,
   d as DEFAULT_AGENT_STATIC_OPTIONS,
   f as EmailRoutingOptions,
   g as QueueItem,
   h as MCPServersState,
   i as AgentContext,
-  k as unstable_callable,
+  j as unstable_callable,
+  k as routeAgentEmail,
   l as Connection,
   m as MCPServerMessage,
   n as AddRpcMcpServerOptions,
   o as AgentOptions,
-  ot as TransportType,
   p as MCPServer,
   r as Agent,
   s as AgentStaticOptions,
   t as AddMcpServerOptions,
   u as ConnectionContext,
   v as RPCResponse,
-  w as callable,
+  w as SubAgentStub,
   x as StateUpdateMessage,
   y as Schedule
-} from "./index-p1XLNvwQ.js";
+} from "./index-DBW341gU.js";
 import {
   n as AgentsOAuthProvider,
   r as DurableObjectOAuthClientProvider,
@@ -65,6 +67,8 @@ export {
   SqlError,
   StateUpdateMessage,
   StreamingResponse,
+  SubAgentClass,
+  SubAgentStub,
   TransportType,
   WSMessage,
   __DO_NOT_USE_WILL_BREAK__agentContext,