agents 0.12.4 → 0.13.1

package/README.md

@@ -110,7 +110,7 @@ State changes sync to all connected clients automatically. Call methods like the
 Core         State sync · Routing · HTTP & WebSockets · @callable RPC · Sub-agents (facets)
 Clients      React hook · Vanilla JS · Real-time state sync
 Channels     WebSocket · HTTP · Email · (coming: SMS, Voice, Messengers)
-Background   Queue · Scheduling · Workflows · Human-in-the-loop
+Background   Queue · Scheduling · Managed fibers · Workflows · Human-in-the-loop
 AI           Chat agents · Agent tools · Tool calling · MCP servers & clients
 Platform     Observability · Cross-domain auth · Resumable streams
 ```
@@ -380,7 +380,7 @@ Workflows provide:
 - **Long-running tasks** — run for days or weeks
 - **Progress tracking** — report status back to the agent
 
-See [Workflows](./docs/workflows.md) and [Human in the Loop](./docs/human-in-the-loop.md).
+See [Workflows](../../docs/workflows.md) and [Human in the Loop](../../docs/human-in-the-loop.md).
 
 ---
 
@@ -511,12 +511,12 @@ export default {
 
 ## Learn More
 
-[Getting Started](./docs/getting-started.md) ·
-[State Management](./docs/state.md) ·
-[Scheduling](./docs/scheduling.md) ·
-[Callable Methods](./docs/callable-methods.md) ·
-[MCP Integration](./docs/mcp-client.md) ·
-[Full Documentation](./docs/index.md)
+[Getting Started](../../docs/getting-started.md) ·
+[State Management](../../docs/state.md) ·
+[Scheduling](../../docs/scheduling.md) ·
+[Callable Methods](../../docs/callable-methods.md) ·
+[MCP Integration](../../docs/mcp-client.md) ·
+[Full Documentation](../../docs/index.md)
 
 ---
 

package/dist/{agent-tool-types-CM_50fcV.d.ts → agent-tool-types-Dn9n-3SI.d.ts}

@@ -441,10 +441,15 @@ declare abstract class McpAgent<
     extraInfo?: MessageExtraInfo
   ): Promise<Error | null>;
   /** Elicit user input with a message and schema */
-  elicitInput(params: {
-    message: string;
-    requestedSchema: unknown;
-  }): Promise<ElicitResult>;
+  elicitInput(
+    params: {
+      message: string;
+      requestedSchema: unknown;
+    },
+    options?: {
+      relatedRequestId?: RequestId;
+    }
+  ): Promise<ElicitResult>;
   /** Handle elicitation responses via in-memory resolver */
   private _handleElicitationResponse;
   /**
@@ -847,7 +852,7 @@ declare class MCPClientConnection {
    */
   getTransport(
     transportType: BaseTransportType
-  ): RPCClientTransport | SSEClientTransport | StreamableHTTPClientTransport;
+  ): StreamableHTTPClientTransport | SSEClientTransport | RPCClientTransport;
   private tryConnect;
   private _capabilityErrorHandler;
 }
@@ -1820,19 +1825,85 @@ type ScheduleCriteria = {
  * and identity for durable execution.
  */
 type FiberContext = {
-  /** Unique identifier for this fiber execution. */ id: string /** Checkpoint data during execution. Synchronous SQLite write. */;
+  /** Unique identifier for this fiber execution. */ id: string /** Cooperative cancellation signal for managed fiber callers. */;
+  signal: AbortSignal /** Checkpoint data during execution. Synchronous SQLite write. */;
   stash(
     data: unknown
-  ): void /** Last checkpoint data (null on first run, populated on recovery re-invocation). */;
+  ): void /** Currently null during execution; recovered snapshots are passed to onFiberRecovered(). */;
   snapshot: unknown | null;
 };
+type FiberStatus =
+  | "pending"
+  | "running"
+  | "completed"
+  | "aborted"
+  | "interrupted"
+  | "error";
+type StartFiberOptions = {
+  fiberId?: string;
+  idempotencyKey?: string;
+  metadata?: Record<string, unknown>;
+  waitForCompletion?: boolean;
+};
+type FiberInspection = {
+  fiberId: string;
+  name: string;
+  idempotencyKey?: string;
+  status: FiberStatus;
+  snapshot?: unknown;
+  error?: string;
+  metadata?: Record<string, unknown>;
+  createdAt: number;
+  startedAt?: number;
+  settledAt?: number;
+};
+type StartFiberResult = FiberInspection & {
+  accepted: boolean;
+};
+type FiberRecoveryResult =
+  | {
+      status: "completed";
+      snapshot?: unknown;
+      metadata?: Record<string, unknown>;
+    }
+  | {
+      status: "error";
+      error?: unknown;
+      snapshot?: unknown;
+    }
+  | {
+      status: "aborted";
+      reason?: string;
+      snapshot?: unknown;
+    }
+  | {
+      status: "interrupted";
+      reason?: string;
+      snapshot?: unknown;
+    };
+type ListFibersOptions = {
+  status?: FiberStatus | FiberStatus[];
+  name?: string;
+  limit?: number;
+};
+type DeleteFibersOptions = {
+  status?: FiberStatus | FiberStatus[];
+  settledBefore?: Date;
+  limit?: number;
+};
 /**
  * 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. */;
+  name: string /** Status for managed fibers recovered through the retained ledger. */;
+  status?: FiberStatus /** Idempotency key for managed fibers, if one was supplied. */;
+  idempotencyKey?: string /** Metadata for managed fibers, if one was supplied. */;
+  metadata?: Record<
+    string,
+    unknown
+  > | null /** Last checkpoint data from `stash()`, or null if never stashed. */;
   snapshot: unknown | null;
   /**
    * Epoch milliseconds when the fiber row was inserted (when `runFiber`
@@ -2028,6 +2099,12 @@ declare class Agent<
   private _facetKeepAliveTokens;
   /** @internal In-memory set of fiber IDs running in this process. */
   private _runFiberActiveFibers;
+  /** @internal In-memory abort controllers for managed running fibers. */
+  private _managedFiberAbortControllers;
+  /** @internal In-memory executions for callers that want to await accepted work. */
+  private _managedFiberExecutions;
+  /** @internal In-memory waiters for managed fibers reaching terminal ledger state. */
+  private _managedFiberTerminalWaiters;
   /** @internal Prevents re-entrant recovery from overlapping alarm ticks. */
   private _runFiberRecoveryInProgress;
   private _ParentClass;
@@ -2710,6 +2787,33 @@ declare class Agent<
    * ```
    */
   keepAliveWhile<T>(fn: () => Promise<T>): Promise<T>;
+  private _isTerminalFiberStatus;
+  private _notifyManagedFiberTerminal;
+  private _waitForManagedFiberTerminal;
+  private _normalizeFiberStatusFilter;
+  private _parseFiberJsonObject;
+  private _parseFiberSnapshot;
+  private _fiberErrorMessage;
+  private _stringifyFiberSnapshot;
+  private _fiberRecoveryErrorMessage;
+  private _applyManagedFiberRecoveryResult;
+  private _settleManagedFiberExecution;
+  private _parseFiberRecoverySnapshot;
+  private _runFiberRecoveryHook;
+  private _fiberInspectionFromRow;
+  private _waitForManagedFiber;
+  private _readFiber;
+  private _readFiberByKey;
+  private _listFiberRows;
+  private _listFiberRowsByStatus;
+  inspectFiber(fiberId: string): Promise<FiberInspection | null>;
+  inspectFiberByKey(idempotencyKey: string): Promise<FiberInspection | null>;
+  listFibers(options?: ListFibersOptions): Promise<FiberInspection[]>;
+  cancelFiber(fiberId: string, reason?: string): Promise<boolean>;
+  cancelFiberByKey(idempotencyKey: string, reason?: string): Promise<boolean>;
+  resolveFiber(fiberId: string, result: FiberRecoveryResult): Promise<boolean>;
+  deleteFibers(options?: DeleteFibersOptions): Promise<number>;
+  private _listTerminalFiberRowsForDelete;
   /**
    * Run a function as a durable fiber. The fiber is registered in SQLite
    * before execution, checkpointable during execution via `ctx.stash()`,
@@ -2724,6 +2828,13 @@ declare class Agent<
    * @returns The return value of fn
    */
   runFiber<T>(name: string, fn: (ctx: FiberContext) => Promise<T>): Promise<T>;
+  startFiber(
+    name: string,
+    fn: (ctx: FiberContext) => Promise<void>,
+    options?: StartFiberOptions
+  ): Promise<StartFiberResult>;
+  private _executeManagedFiber;
+  private _runFiberInternal;
   /**
    * Checkpoint data for the currently executing fiber.
    * Uses AsyncLocalStorage to identify the correct fiber,
@@ -2741,7 +2852,9 @@ declare class Agent<
    *
    * Default: logs a warning.
    */
-  onFiberRecovered(_ctx: FiberRecoveryContext): Promise<void>;
+  onFiberRecovered(
+    _ctx: FiberRecoveryContext
+  ): Promise<void | FiberRecoveryResult>;
   /**
    * Override point for subclasses to handle internal (framework) fibers
    * before the user's recovery hook fires. Return `true` if handled.
@@ -2980,6 +3093,23 @@ declare class Agent<
     method: string,
     args: unknown[]
   ): Promise<unknown>;
+  /**
+   * Bridge method used by `parentAgent()` when the requested parent is
+   * itself a facet (and therefore has no top-level env namespace).
+   * The root receives the full root-first target path, then each hop
+   * delegates to the next facet using that facet's own `ctx.facets`.
+   *
+   * @internal
+   */
+  _cf_invokeSubAgentPath(
+    path: ReadonlyArray<{
+      className: string;
+      name: string;
+    }>,
+    method: string,
+    args: unknown[]
+  ): Promise<unknown>;
+  private _cf_invokeStubMethod;
   /**
    * Initialize this agent as a facet in a single RPC.
    *
@@ -3000,11 +3130,11 @@ declare class Agent<
    *
    * 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
+   * parent passed an explicit named Durable Object id 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.
+   * facet's name survives cold wake automatically because the factory
+   * re-runs and `idFromName` is deterministic.
    *
    * @internal Called by {@link subAgent}.
    */
@@ -3045,26 +3175,33 @@ declare class Agent<
     name: string;
   }>;
   /**
-   * Resolve a typed RPC stub for this facet's **immediate** parent
+   * Resolve a typed parent 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` at runtime. If the parent is a top-level
+   * Durable Object, the framework returns the normal namespace stub.
+   * If the parent is itself a facet, the framework returns a bridge
+   * proxy that routes method calls through the root/supervisor and
+   * then down the recorded facet path.
    *
    * `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.
+   * For top-level parents, the framework first checks `env[Cls.name]`,
+   * then falls back to the Worker `exports` object. This supports
+   * custom binding names as long as the parent class is exported under
+   * its class name.
+   *
+   * Facet-parent stubs route normal HTTP `.fetch()` calls through the
+   * same root bridge as RPC methods. WebSocket upgrade requests are
+   * not supported yet because WebSocket handles cannot be serialized
+   * over RPC.
    *
    * @experimental The API surface may change before stabilizing.
    *
@@ -3072,7 +3209,8 @@ declare class Agent<
    * @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.
+   * @throws If no namespace is found for a top-level parent, or no
+   *         root namespace is available for a facet parent bridge.
    *
    * @example
    * ```ts
@@ -3088,6 +3226,10 @@ declare class Agent<
   parentAgent<T extends Agent>(
     cls: SubAgentClass<T>
   ): Promise<DurableObjectStub<T>>;
+  private _cf_getTopLevelNamespaceByClassName;
+  private _cf_asDurableObjectNamespace;
+  private _cf_parentAgentFacetProxy;
+  private _cf_isWebSocketUpgradeRequest;
   /**
    * Get or create a named sub-agent — a child Durable Object (facet)
    * with its own isolated SQLite storage running on the same machine.
@@ -3997,95 +4139,102 @@ type AgentToolEventState = {
 };
 //#endregion
 export {
-  unstable_callable as $,
-  FiberContext as A,
-  McpClientOptions as At,
-  ScheduleCriteria as B,
+  SubAgentStub as $,
+  EmailSendBinding as A,
+  McpAuthContext as At,
+  QueueItem as B,
+  SubAgentPathMatch as Bt,
   AgentStaticOptions as C,
-  McpAuthContext as Ct,
+  ElicitRequest$1 as Ct,
   DEFAULT_AGENT_STATIC_OPTIONS as D,
-  WorkerTransportOptions as Dt,
+  CreateMcpHandlerOptions as Dt,
   ConnectionContext$1 as E,
-  WorkerTransport as Et,
-  QueueItem as F,
-  parseSubAgentPath as Ft,
-  SubAgentClass as G,
-  SqlError as H,
-  RPCRequest as I,
-  routeSubAgentRequest as It,
-  callable as J,
-  SubAgentStub as K,
-  RPCResponse as L,
-  MCPServer as M,
-  SUB_PREFIX as Mt,
-  MCPServerMessage as N,
-  SubAgentPathMatch as Nt,
-  EmailRoutingOptions as O,
-  SSEEdgeClientTransport as Ot,
-  MCPServersState as P,
-  getSubAgentByName as Pt,
-  routeAgentRequest as Q,
-  RoutingRetryOptions as R,
+  McpAgent as Et,
+  FiberStatus as F,
+  SSEEdgeClientTransport as Ft,
+  ScheduleCriteria as G,
+  RPCResponse as H,
+  parseSubAgentPath as Ht,
+  ListFibersOptions as I,
+  StreamableHTTPEdgeClientTransport as It,
+  StartFiberOptions as J,
+  SendEmailOptions as K,
+  MCPServer as L,
+  McpClientOptions as Lt,
+  FiberInspection as M,
+  TransportState as Mt,
+  FiberRecoveryContext as N,
+  WorkerTransport as Nt,
+  DeleteFibersOptions as O,
+  createMcpHandler as Ot,
+  FiberRecoveryResult as P,
+  WorkerTransportOptions as Pt,
+  SubAgentClass as Q,
+  MCPServerMessage as R,
+  TransportType as Rt,
   AgentOptions as S,
-  experimental_createMcpHandler as St,
+  RPC_DO_PREFIX as St,
   Connection$1 as T,
-  TransportState as Tt,
-  StateUpdateMessage as U,
-  SendEmailOptions as V,
-  StreamingResponse as W,
-  getCurrentAgent as X,
-  getAgentByName as Y,
-  routeAgentEmail as Z,
+  ElicitResult$1 as Tt,
+  RoutingRetryOptions as U,
+  routeSubAgentRequest as Ut,
+  RPCRequest as V,
+  getSubAgentByName as Vt,
+  Schedule as W,
+  StateUpdateMessage as X,
+  StartFiberResult as Y,
+  StreamingResponse as Z,
   AddRpcMcpServerOptions as _,
-  ElicitRequestSchema$1 as _t,
+  getNamespacedData as _t,
   AgentToolEventState as a,
-  MCPDiscoverResult as at,
+  routeAgentRequest as at,
   AgentGetOptions as b,
-  CreateMcpHandlerOptions as bt,
+  RPCServerTransport as bt,
   AgentToolRunInspection as c,
-  MCPServerOptions as ct,
+  MCPClientManagerOptions as ct,
   AgentToolStoredChunk as d,
-  RPCClientTransport as dt,
-  MCPClientManager as et,
+  MCPConnectionResult as dt,
+  WSMessage$1 as et,
   AgentToolTerminalStatus as f,
-  RPCClientTransportOptions as ft,
+  MCPDiscoverResult as ft,
   AddMcpServerOptions as g,
-  ElicitRequest$1 as gt,
+  RegisterServerOptions as gt,
   RunAgentToolResult as h,
-  RPC_DO_PREFIX as ht,
+  MCPServerOptions as ht,
   AgentToolEventMessage as i,
-  MCPConnectionResult as it,
-  FiberRecoveryContext as j,
-  TransportType as jt,
-  EmailSendBinding as k,
-  StreamableHTTPEdgeClientTransport as kt,
+  routeAgentEmail as it,
+  FiberContext as j,
+  getMcpAuthContext as jt,
+  EmailRoutingOptions as k,
+  experimental_createMcpHandler as kt,
   AgentToolRunState as l,
-  RegisterServerOptions as lt,
+  MCPClientOAuthCallbackConfig as lt,
   RunAgentToolOptions as m,
-  RPCServerTransportOptions as mt,
+  MCPServerFilter as mt,
   AgentToolDisplayMetadata as n,
-  MCPClientOAuthCallbackConfig as nt,
+  getAgentByName as nt,
   AgentToolLifecycleResult as o,
-  MCPOAuthCallbackResult as ot,
+  unstable_callable as ot,
   ChatCapableAgentClass as p,
-  RPCServerTransport as pt,
-  WSMessage$1 as q,
+  MCPOAuthCallbackResult as pt,
+  SqlError as q,
   AgentToolEvent as r,
-  MCPClientOAuthResult as rt,
+  getCurrentAgent as rt,
   AgentToolRunInfo as s,
-  MCPServerFilter as st,
+  MCPClientManager as st,
   AgentToolChildAdapter as t,
-  MCPClientManagerOptions as tt,
+  callable as tt,
   AgentToolRunStatus as u,
-  getNamespacedData as ut,
+  MCPClientOAuthResult as ut,
   Agent as v,
-  ElicitResult$1 as vt,
+  RPCClientTransport as vt,
   CallableMetadata as w,
-  getMcpAuthContext as wt,
+  ElicitRequestSchema$1 as wt,
   AgentNamespace as x,
-  createMcpHandler as xt,
+  RPCServerTransportOptions as xt,
   AgentContext as y,
-  McpAgent as yt,
-  Schedule as z
+  RPCClientTransportOptions as yt,
+  MCPServersState as z,
+  SUB_PREFIX as zt
 };
-//# sourceMappingURL=agent-tool-types-CM_50fcV.d.ts.map
+//# sourceMappingURL=agent-tool-types-Dn9n-3SI.d.ts.map

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

@@ -14,7 +14,7 @@ import {
   s as AgentToolRunInfo,
   t as AgentToolChildAdapter,
   u as AgentToolRunStatus
-} from "./agent-tool-types-CM_50fcV.js";
+} from "./agent-tool-types-Dn9n-3SI.js";
 export {
   AgentToolChildAdapter,
   AgentToolDisplayMetadata,

package/dist/{agent-tools-BylX6WXG.d.ts → agent-tools-B1ttU-pq.d.ts}

@@ -1,7 +1,7 @@
 import {
   a as AgentToolEventState,
   i as AgentToolEventMessage
-} from "./agent-tool-types-CM_50fcV.js";
+} from "./agent-tool-types-Dn9n-3SI.js";
 
 //#region src/chat/agent-tools.d.ts
 declare function createAgentToolEventState(): AgentToolEventState;
@@ -11,4 +11,4 @@ declare function applyAgentToolEvent(
 ): AgentToolEventState;
 //#endregion
 export { createAgentToolEventState as n, applyAgentToolEvent as t };
-//# sourceMappingURL=agent-tools-BylX6WXG.d.ts.map
+//# sourceMappingURL=agent-tools-B1ttU-pq.d.ts.map