agents 0.11.4 → 0.11.6

package/dist/{index-D9qo_Inc.d.ts → index-BM7Nk0QD.d.ts}

@@ -1,5 +1,5 @@
 import { n as AgentEmail } from "./internal_context-BvuGZieY.js";
-import { t as RetryOptions } from "./retries-JlwH9mnV.js";
+import { t as RetryOptions } from "./retries-fLD8cGNf.js";
 import {
   n as Observability,
   r as ObservabilityEvent,
@@ -67,6 +67,122 @@ import { Server as Server$1 } from "@modelcontextprotocol/sdk/server/index.js";
 import { Client as Client$1 } from "@modelcontextprotocol/sdk/client";
 import { EventStore } from "@modelcontextprotocol/sdk/server/streamableHttp.js";
 
+//#region src/sub-routing.d.ts
+/**
+ * URL segment marking a parent↔child boundary.
+ *
+ * Exposed as a constant so callers can build URLs symbolically, but
+ * not configurable — the routing layer matches on the literal `sub`
+ * token everywhere (parent fetch, client, helpers).
+ */
+declare const SUB_PREFIX = "sub";
+interface SubAgentPathMatch {
+  /** CamelCase class name of the child, as it appears in `ctx.exports`. */
+  childClass: string;
+  /** URL-decoded child name. */
+  childName: string;
+  /**
+   * Request path to forward to the child, with the
+   * `/sub/{class}/{name}` segment stripped. Always begins with `/`;
+   * may itself contain further `/sub/...` markers when a
+   * recursively nested sub-agent is being routed.
+   */
+  remainingPath: string;
+}
+/**
+ * Parse a URL and extract the first `/sub/{class}/{name}` segment,
+ * if any. Recursive nesting is handled naturally: callers parse one
+ * level at a time; the child then parses its own URL (which still
+ * contains any deeper `/sub/...` markers).
+ *
+ * Names are URL-decoded. Classes are kebab-to-CamelCase converted
+ * via a best-effort match against a provided lookup — pass
+ * `ctx.exports` keys to get exact CamelCase; pass `undefined` for
+ * a tolerant conversion without validation.
+ *
+ * Returns `null` when the URL doesn't contain the marker at a
+ * recognized position, or when the marker has no following
+ * class+name pair.
+ */
+declare function parseSubAgentPath(
+  url: string,
+  options?: {
+    /** CamelCase class names to match against (usually `ctx.exports` keys). */ knownClasses?: readonly string[];
+  }
+): SubAgentPathMatch | null;
+/**
+ * Route a request into a sub-agent via its parent DO.
+ *
+ * Use this in a custom fetch handler when your URL shape doesn't
+ * match the `/agents/{class}/{name}` default — you identify and
+ * fetch the parent yourself, then let this helper parse the
+ * `/sub/{child}/...` tail and forward it.
+ *
+ * Runs `onBeforeSubAgent` on the parent DO (authorization / request
+ * mutation / short-circuit response).
+ *
+ * For the default `/agents/...` URL shape, use `routeAgentRequest`
+ * instead — it handles the parent lookup and this dispatch in one
+ * call.
+ *
+ * @example
+ * ```ts
+ * export default {
+ *   async fetch(req, env) {
+ *     const { parentName, rest } = myCustomParse(req.url);
+ *     const parent = await getAgentByName(env.Inbox, parentName);
+ *     return routeSubAgentRequest(req, parent, { fromPath: rest });
+ *   }
+ * };
+ * ```
+ *
+ * @experimental The API surface may change before stabilizing.
+ */
+declare function routeSubAgentRequest(
+  req: Request,
+  parent: unknown,
+  options?: {
+    /**
+     * Path to route on. Defaults to `req.url`'s pathname. Useful
+     * when your outer URL is custom (e.g. `/api/v1/...`) and you
+     * want to route the sub-agent tail without rewriting the
+     * Request first.
+     */
+    fromPath?: string;
+  }
+): Promise<Response>;
+/**
+ * Get a typed RPC stub for a sub-agent from outside the parent DO.
+ *
+ * The returned stub proxies method calls through the parent via a
+ * stateless per-call bridge (caller → parent → facet), so each
+ * method invocation costs one extra RPC hop. Works across parent
+ * hibernation — no cached references to go stale.
+ *
+ * Limitations:
+ *   - RPC methods only. `.fetch()` is not supported (will throw).
+ *     Use `routeSubAgentRequest` for external HTTP/WS.
+ *   - Arguments and return values must be structured-cloneable,
+ *     same as any DO RPC call.
+ *   - Does not run `onBeforeSubAgent` on the parent — analogous to
+ *     `getAgentByName` not running `onBeforeConnect`. The caller is
+ *     assumed to have performed whatever access checks are needed.
+ *
+ * @example
+ * ```ts
+ * const inbox = await getAgentByName(env.MyInbox, userId);
+ * const chat = await getSubAgentByName(inbox, MyChat, chatId);
+ * await chat.addMessage({ role: "user", content: "hi" });
+ * ```
+ *
+ * @experimental The API surface may change before stabilizing.
+ */
+declare function getSubAgentByName<T extends Agent>(
+  parent: unknown,
+  cls: SubAgentClass<T>,
+  name: string
+): Promise<SubAgentStub<T>>;
+//#endregion
 //#region src/core/events.d.ts
 interface Disposable {
   dispose(): void;
@@ -729,7 +845,7 @@ declare class MCPClientConnection {
    */
   getTransport(
     transportType: BaseTransportType
-  ): RPCClientTransport | SSEClientTransport | StreamableHTTPClientTransport;
+  ): StreamableHTTPClientTransport | SSEClientTransport | RPCClientTransport;
   private tryConnect;
   private _capabilityErrorHandler;
 }
@@ -1796,6 +1912,13 @@ declare class Agent<
   private _persistenceHookMode;
   /** True when this agent runs as a facet (sub-agent) inside a parent. */
   private _isFacet;
+  /**
+   * Ancestor chain, root-first. Empty for top-level DOs; populated at
+   * facet init time from the parent's own `selfPath`. Exposed publicly
+   * via the `parentPath` getter.
+   * @internal
+   */
+  private _parentPath;
   /** True while user's onStart() is executing. Used to warn about non-idempotent schedule() calls. */
   private _insideOnStart;
   /** Tracks callbacks already warned about during this onStart() to avoid log spam. */
@@ -1903,18 +2026,6 @@ declare class Agent<
    * @param excludeIds Additional connection IDs to exclude (e.g. the source)
    */
   private _broadcastProtocol;
-  /**
-   * When running as a facet, the parent DO owns the WebSocket registry
-   * (`ctx.getWebSockets()`). Iterating from the child isolate throws
-   * "Cannot perform I/O on behalf of a different Durable Object".
-   * Downstream callers (e.g. chat-streaming paths) invoke
-   * `this.broadcast()` directly, bypassing `_broadcastProtocol`'s
-   * guard, so override at the base to catch every path.
-   */
-  broadcast(
-    msg: string | ArrayBuffer | ArrayBufferView,
-    without?: string[]
-  ): void;
   private _setStateInternal;
   /**
    * Update the Agent's state
@@ -2293,6 +2404,12 @@ declare class Agent<
    * alarm system, without creating schedule rows or emitting observability
    * events. Configure via `static options = { keepAliveIntervalMs: 5000 }`.
    *
+   * No-op on facets. Facets share the parent's isolate and don't
+   * need a separate alarm heartbeat — the parent's own activity,
+   * any open WebSocket to the facet, and any in-flight Promise
+   * already keep the shared machine alive for the duration of
+   * real work.
+   *
    * @example
    * ```ts
    * const dispose = await this.keepAlive();
@@ -2378,13 +2495,100 @@ declare class Agent<
    * Executes any scheduled tasks that are due.
    *
    * Calls super.alarm() first to ensure PartyServer's #ensureInitialized()
-   * runs, which hydrates this.name from storage and calls onStart() if needed.
+   * runs, which resolves this.name from ctx.id.name (including for
+   * facets, which are spawned with an explicit id so they have their
+   * own ctx.id.name; pre-2026-03-15 alarms fall back to the legacy
+   * __ps_name storage record) and calls onStart() if needed.
    *
    * @remarks
    * To schedule a task, please use the `this.schedule` method instead.
    * See {@link https://developers.cloudflare.com/agents/api-reference/schedule-tasks/}
    */
   alarm(): Promise<void>;
+  /**
+   * Intercept incoming HTTP/WS requests whose URL contains a
+   * `/sub/{child-class}/{child-name}` marker and forward them to
+   * the facet. The `onBeforeSubAgent` hook fires first (authorize,
+   * mutate, or short-circuit). If the hook doesn't return a
+   * Response, the framework resolves the facet and hands the
+   * request off.
+   *
+   * After a WebSocket upgrade completes, subsequent frames route
+   * directly to the child — the parent is only on the path for the
+   * initial request.
+   *
+   * @experimental The API surface may change before stabilizing.
+   */
+  fetch(request: Request): Promise<Response>;
+  /**
+   * Parent-side middleware hook. Fires before a request is
+   * forwarded into a facet sub-agent. Mirrors `onBeforeConnect` /
+   * `onBeforeRequest`.
+   *
+   *   - return `void` (default) → forward the original request
+   *   - return `Request`        → forward this (modified) request
+   *   - return `Response`       → return this response to the
+   *                               client; do not wake the child
+   *
+   * Default implementation: return void (permissive).
+   *
+   * The hook receives the **original** request with its URL intact —
+   * including the `/sub/{class}/{name}` segment. The routing
+   * decision for which facet to wake is fixed at parse time, so if
+   * you return a modified `Request`, its headers, body, method, and
+   * query string flow through to the child, but the **pathname**
+   * the child sees is always the tail after `/sub/{class}/{name}`.
+   * Customize via headers/body rather than URL-rewriting.
+   *
+   * WebSocket upgrade requests flow through this hook the same way as
+   * plain HTTP. If you return a mutated `Request`, make sure it still
+   * carries the original `Upgrade: websocket` and `Sec-WebSocket-*`
+   * headers — the simplest safe recipe is to clone the incoming
+   * request's headers (via `new Headers(req.headers)`) and only add
+   * or replace entries, rather than constructing a fresh `Headers`
+   * object from scratch.
+   *
+   * @experimental The API surface may change before stabilizing.
+   *
+   * @example
+   * ```ts
+   * class Inbox extends Agent {
+   *   override async onBeforeSubAgent(req, { className, name }) {
+   *     // Strict registry gate
+   *     if (!this.hasSubAgent(className, name)) {
+   *       return new Response("Not found", { status: 404 });
+   *     }
+   *   }
+   * }
+   * ```
+   */
+  onBeforeSubAgent(
+    _request: Request,
+    _child: {
+      className: string;
+      name: string;
+    }
+  ): Promise<Request | Response | void>;
+  /**
+   * Resolve the facet Fetcher for the match and forward the
+   * request to it with `/sub/{class}/{name}` stripped.
+   *
+   * @internal
+   */
+  private _cf_forwardToFacet;
+  /**
+   * Bridge method used by `getSubAgentByName`. Resolves the facet
+   * on each call (idempotent via `subAgent`) and dispatches one
+   * RPC method. Stateless — no cached references.
+   *
+   * @internal
+   */
+  _cf_invokeSubAgent(
+    className: string,
+    name: string,
+    method: string,
+    args: unknown[]
+  ): Promise<unknown>;
   /**
    * Initialize this agent as a facet in a single RPC.
    *
@@ -2395,14 +2599,104 @@ declare class Agent<
    * parent and triggered "Cannot perform I/O on behalf of a different
    * Durable Object" on the child.
    *
-   * Order matters: set `_isFacet` BEFORE triggering initialization, so
-   * the first `onStart()` run (which calls `broadcastMcpServers`) sees
-   * the flag and skips broadcasts that would touch the parent DO's
-   * WebSocket registry.
+   * We set `_isFacet` eagerly (before `__unsafe_ensureInitialized`
+   * runs `onStart()`) so any code that legitimately branches on it
+   * — e.g. skipping parent-owned alarms in schedule guards — sees
+   * the flag during the first `onStart()` run. Broadcast paths no
+   * longer special-case facets, since facets can be directly
+   * addressed via sub-agent routing and have their own WebSocket
+   * connections.
+   *
+   * The facet's name (and `this.name` getter) is handled entirely by
+   * partyserver via `ctx.id.name`, which is populated because the
+   * parent passed an explicit `id: parentNs.idFromName(name)` to
+   * `ctx.facets.get()` — see {@link _cf_resolveSubAgent}. No
+   * `setName()` call or `__ps_name` storage write is needed; the
+   * facet's name survives cold wake automatically because the
+   * factory re-runs and `idFromName` is deterministic.
    *
    * @internal Called by {@link subAgent}.
    */
-  _cf_initAsFacet(name: string): Promise<void>;
+  _cf_initAsFacet(
+    name: string,
+    parentPath?: ReadonlyArray<{
+      className: string;
+      name: string;
+    }>
+  ): Promise<void>;
+  /**
+   * Ancestor chain for this agent, root-first. Empty for top-level
+   * DOs. Populated at facet init time; survives hibernation.
+   *
+   * @example
+   * ```ts
+   * class Chat extends Agent {
+   *   onStart() {
+   *     console.log("chat started under:", this.parentPath);
+   *     // → [{ className: "Tenant", name: "acme" }, { className: "Inbox", name: "alice" }]
+   *   }
+   * }
+   * ```
+   *
+   * @experimental The API surface may change before stabilizing.
+   */
+  get parentPath(): ReadonlyArray<{
+    className: string;
+    name: string;
+  }>;
+  /**
+   * Ancestor chain + self, root-first. Convenient for logging.
+   *
+   * @experimental The API surface may change before stabilizing.
+   */
+  get selfPath(): ReadonlyArray<{
+    className: string;
+    name: string;
+  }>;
+  /**
+   * Resolve a typed RPC stub for this facet's **immediate** parent
+   * agent.
+   *
+   * Symmetric with `subAgent(Cls, name)`: while `subAgent` opens a
+   * stub from parent to child, `parentAgent` opens one from child
+   * to parent. Pass the direct parent's class reference — the
+   * framework verifies it matches the last entry of
+   * `this.parentPath` at runtime, then looks up `env[Cls.name]` to
+   * find the namespace binding.
+   *
+   * `this.parentPath` is root-first, so the direct parent is the
+   * **last** entry: `this.parentPath.at(-1)`. For grandparents and
+   * further ancestors, iterate `this.parentPath` and use
+   * `getAgentByName(env.X, this.parentPath[i].name)` directly.
+   *
+   * Assumes the standard "binding name matches class name" convention.
+   * If your `wrangler.jsonc` binds the parent under a different name
+   * (e.g. `{ class_name: "Inbox", name: "MY_INBOX" }`), call
+   * `getAgentByName(env.MY_INBOX, this.parentPath.at(-1)!.name)`
+   * directly instead.
+   *
+   * @experimental The API surface may change before stabilizing.
+   *
+   * @throws If this agent is not a facet (no parent).
+   * @throws If `Cls.name` doesn't match the recorded direct-parent
+   *         class (guards against accidentally reaching the wrong
+   *         DO, especially in nested Root → Mid → Leaf chains).
+   * @throws If no env binding named `Cls.name` is found.
+   *
+   * @example
+   * ```ts
+   * class Chat extends AIChatAgent<Env> {
+   *   async onChatMessage(...) {
+   *     const inbox = await this.parentAgent(Inbox);
+   *     const memory = await inbox.getSharedMemory("facts");
+   *     // ...
+   *   }
+   * }
+   * ```
+   */
+  parentAgent<T extends Agent>(
+    cls: SubAgentClass<T>
+  ): Promise<DurableObjectStub<T>>;
   /**
    * Get or create a named sub-agent — a child Durable Object (facet)
    * with its own isolated SQLite storage running on the same machine.
@@ -2427,6 +2721,16 @@ declare class Agent<
     cls: SubAgentClass<T>,
     name: string
   ): Promise<SubAgentStub<T>>;
+  /**
+   * Shared facet resolution — takes a CamelCase class name string
+   * (matching `ctx.exports`) rather than a class reference. Both
+   * `subAgent(cls, name)` and `_cf_invokeSubAgent(className, ...)`
+   * funnel through here so registry bookkeeping and the
+   * `_cf_initAsFacet` handshake are consistent.
+   *
+   * @internal
+   */
+  private _cf_resolveSubAgent;
   /**
    * Forcefully abort a running sub-agent. The child stops executing
    * immediately and will be restarted on next {@link subAgent} call.
@@ -2450,6 +2754,54 @@ declare class Agent<
    * @param name Name of the child to delete
    */
   deleteSubAgent(cls: SubAgentClass, name: string): void;
+  /** @internal */
+  private _subAgentRegistryReady;
+  /** @internal */
+  private _ensureSubAgentRegistry;
+  /** @internal */
+  private _recordSubAgent;
+  /** @internal */
+  private _forgetSubAgent;
+  /**
+   * Whether this agent has previously spawned (and not deleted) a
+   * sub-agent of the given class and name. Backed by an
+   * auto-maintained SQLite registry in the parent's storage.
+   *
+   * Intended for strict-registry access patterns in
+   * `onBeforeSubAgent` or similar gating logic.
+   *
+   * @experimental The API surface may change before stabilizing.
+   *
+   * @example
+   * ```ts
+   * async onBeforeSubAgent(req, { className, name }) {
+   *   if (!this.hasSubAgent(className, name)) {
+   *     return new Response("Not found", { status: 404 });
+   *   }
+   * }
+   * ```
+   */
+  hasSubAgent<T extends Agent>(cls: SubAgentClass<T>, name: string): boolean;
+  hasSubAgent(className: string, name: string): boolean;
+  /**
+   * List known sub-agents, optionally filtered by class. Reflects
+   * the registry rows written by {@link subAgent} and removed by
+   * {@link deleteSubAgent}.
+   *
+   * @experimental The API surface may change before stabilizing.
+   */
+  listSubAgents<T extends Agent>(
+    cls: SubAgentClass<T>
+  ): Array<{
+    className: string;
+    name: string;
+    createdAt: number;
+  }>;
+  listSubAgents(className?: string): Array<{
+    className: string;
+    name: string;
+    createdAt: number;
+  }>;
   /**
    * Destroy the Agent, removing all state and scheduled tasks
    */
@@ -3068,6 +3420,7 @@ export {
   RPCServerTransport as Y,
   RPC_DO_PREFIX as Z,
   MCPServerMessage as _,
+  parseSubAgentPath as _t,
   AgentNamespace as a,
   McpAuthContext as at,
   RPCRequest as b,
@@ -3079,7 +3432,9 @@ export {
   EmailRoutingOptions as f,
   McpClientOptions as ft,
   MCPServer as g,
+  getSubAgentByName as gt,
   FiberRecoveryContext as h,
+  SubAgentPathMatch as ht,
   AgentContext as i,
   experimental_createMcpHandler as it,
   getAgentByName as j,
@@ -3087,6 +3442,7 @@ export {
   Connection$1 as l,
   WorkerTransportOptions as lt,
   FiberContext as m,
+  SUB_PREFIX as mt,
   AddRpcMcpServerOptions as n,
   CreateMcpHandlerOptions as nt,
   AgentOptions as o,
@@ -3103,9 +3459,10 @@ export {
   ConnectionContext$1 as u,
   SSEEdgeClientTransport as ut,
   MCPServersState as v,
+  routeSubAgentRequest as vt,
   SqlError as w,
   RPCResponse as x,
   QueueItem as y,
   MCPClientOAuthResult as z
 };
-//# sourceMappingURL=index-D9qo_Inc.d.ts.map
+//# sourceMappingURL=index-BM7Nk0QD.d.ts.map

package/dist/index.d.ts

@@ -1,5 +1,4 @@
 import { r as __DO_NOT_USE_WILL_BREAK__agentContext } from "./internal_context-BvuGZieY.js";
-import { t as RetryOptions } from "./retries-JlwH9mnV.js";
 import {
   A as callable,
   C as SendEmailOptions,
@@ -13,18 +12,22 @@ import {
   S as Schedule,
   T as StateUpdateMessage,
   _ as MCPServerMessage,
+  _t as parseSubAgentPath,
   a as AgentNamespace,
   b as RPCRequest,
   c as CallableMetadata,
   d as DEFAULT_AGENT_STATIC_OPTIONS,
   f as EmailRoutingOptions,
   g as MCPServer,
+  gt as getSubAgentByName,
   h as FiberRecoveryContext,
+  ht as SubAgentPathMatch,
   i as AgentContext,
   j as getAgentByName,
   k as WSMessage,
   l as Connection,
   m as FiberContext,
+  mt as SUB_PREFIX,
   n as AddRpcMcpServerOptions,
   o as AgentOptions,
   p as EmailSendBinding,
@@ -34,10 +37,12 @@ import {
   t as AddMcpServerOptions,
   u as ConnectionContext,
   v as MCPServersState,
+  vt as routeSubAgentRequest,
   w as SqlError,
   x as RPCResponse,
   y as QueueItem
-} from "./index-D9qo_Inc.js";
+} from "./index-BM7Nk0QD.js";
+import { t as RetryOptions } from "./retries-fLD8cGNf.js";
 import {
   n as AgentsOAuthProvider,
   r as DurableObjectOAuthClientProvider,
@@ -72,12 +77,14 @@ export {
   RPCRequest,
   RPCResponse,
   RetryOptions,
+  SUB_PREFIX,
   Schedule,
   SendEmailOptions,
   SqlError,
   StateUpdateMessage,
   StreamingResponse,
   SubAgentClass,
+  SubAgentPathMatch,
   SubAgentStub,
   TransportType,
   WSMessage,
@@ -86,7 +93,10 @@ export {
   createHeaderBasedEmailResolver,
   getAgentByName,
   getCurrentAgent,
+  getSubAgentByName,
+  parseSubAgentPath,
   routeAgentEmail,
   routeAgentRequest,
+  routeSubAgentRequest,
   unstable_callable
 };