agents 0.13.0 → 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
 ```

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

@@ -1825,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`
@@ -2033,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;
@@ -2715,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()`,
@@ -2729,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,
@@ -2746,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.
@@ -4031,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-BVgYyKO9.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-BVgYyKO9.js";
+} from "./agent-tool-types-Dn9n-3SI.js";
 export {
   AgentToolChildAdapter,
   AgentToolDisplayMetadata,

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

@@ -1,7 +1,7 @@
 import {
   a as AgentToolEventState,
   i as AgentToolEventMessage
-} from "./agent-tool-types-BVgYyKO9.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-C-Ch8Thl.d.ts.map
+//# sourceMappingURL=agent-tools-B1ttU-pq.d.ts.map

package/dist/agent-tools.d.ts

@@ -14,7 +14,7 @@ import {
   s as AgentToolRunInfo,
   t as AgentToolChildAdapter,
   u as AgentToolRunStatus
-} from "./agent-tool-types-BVgYyKO9.js";
+} from "./agent-tool-types-Dn9n-3SI.js";
 import { Tool } from "ai";
 
 //#region src/agent-tools.d.ts

package/dist/chat/index.d.ts

@@ -3,11 +3,11 @@ import {
   i as AgentToolEventMessage,
   l as AgentToolRunState,
   r as AgentToolEvent
-} from "../agent-tool-types-BVgYyKO9.js";
+} from "../agent-tool-types-Dn9n-3SI.js";
 import {
   n as createAgentToolEventState,
   t as applyAgentToolEvent
-} from "../agent-tools-C-Ch8Thl.js";
+} from "../agent-tools-B1ttU-pq.js";
 import { JSONSchema7, Tool, ToolSet, UIMessage } from "ai";
 import { Connection } from "agents";
 

package/dist/client.d.ts

@@ -1,4 +1,4 @@
-import { v as Agent } from "./agent-tool-types-BVgYyKO9.js";
+import { v as Agent } from "./agent-tool-types-Dn9n-3SI.js";
 import {
   ClientParameters,
   Method,

package/dist/index.d.ts

@@ -1,65 +1,72 @@
 import { r as __DO_NOT_USE_WILL_BREAK__agentContext } from "./internal_context-BZrMS0B5.js";
 import {
-  $ as unstable_callable,
-  A as FiberContext,
-  B as ScheduleCriteria,
+  $ as SubAgentStub,
+  A as EmailSendBinding,
+  B as QueueItem,
+  Bt as SubAgentPathMatch,
   C as AgentStaticOptions,
   D as DEFAULT_AGENT_STATIC_OPTIONS,
   E as ConnectionContext,
-  F as QueueItem,
-  Ft as parseSubAgentPath,
-  G as SubAgentClass,
-  H as SqlError,
-  I as RPCRequest,
-  It as routeSubAgentRequest,
-  J as callable,
-  K as SubAgentStub,
-  L as RPCResponse,
-  M as MCPServer,
-  Mt as SUB_PREFIX,
-  N as MCPServerMessage,
-  Nt as SubAgentPathMatch,
-  O as EmailRoutingOptions,
-  P as MCPServersState,
-  Pt as getSubAgentByName,
-  Q as routeAgentRequest,
-  R as RoutingRetryOptions,
+  F as FiberStatus,
+  G as ScheduleCriteria,
+  H as RPCResponse,
+  Ht as parseSubAgentPath,
+  I as ListFibersOptions,
+  J as StartFiberOptions,
+  K as SendEmailOptions,
+  L as MCPServer,
+  M as FiberInspection,
+  N as FiberRecoveryContext,
+  O as DeleteFibersOptions,
+  P as FiberRecoveryResult,
+  Q as SubAgentClass,
+  R as MCPServerMessage,
+  Rt as TransportType,
   S as AgentOptions,
   T as Connection,
-  U as StateUpdateMessage,
-  V as SendEmailOptions,
-  W as StreamingResponse,
-  X as getCurrentAgent,
-  Y as getAgentByName,
-  Z as routeAgentEmail,
+  U as RoutingRetryOptions,
+  Ut as routeSubAgentRequest,
+  V as RPCRequest,
+  Vt as getSubAgentByName,
+  W as Schedule,
+  X as StateUpdateMessage,
+  Y as StartFiberResult,
+  Z as StreamingResponse,
   _ as AddRpcMcpServerOptions,
   a as AgentToolEventState,
+  at as routeAgentRequest,
   b as AgentGetOptions,
   c as AgentToolRunInspection,
   d as AgentToolStoredChunk,
+  et as WSMessage,
   f as AgentToolTerminalStatus,
   g as AddMcpServerOptions,
   h as RunAgentToolResult,
   i as AgentToolEventMessage,
-  j as FiberRecoveryContext,
-  jt as TransportType,
-  k as EmailSendBinding,
+  it as routeAgentEmail,
+  j as FiberContext,
+  k as EmailRoutingOptions,
   l as AgentToolRunState,
   m as RunAgentToolOptions,
   n as AgentToolDisplayMetadata,
+  nt as getAgentByName,
   o as AgentToolLifecycleResult,
+  ot as unstable_callable,
   p as ChatCapableAgentClass,
-  q as WSMessage,
+  q as SqlError,
   r as AgentToolEvent,
+  rt as getCurrentAgent,
   s as AgentToolRunInfo,
   t as AgentToolChildAdapter,
+  tt as callable,
   u as AgentToolRunStatus,
   v as Agent,
   w as CallableMetadata,
   x as AgentNamespace,
   y as AgentContext,
-  z as Schedule
-} from "./agent-tool-types-BVgYyKO9.js";
+  z as MCPServersState,
+  zt as SUB_PREFIX
+} from "./agent-tool-types-Dn9n-3SI.js";
 import { t as RetryOptions } from "./retries-BVdRl5ZE.js";
 import {
   n as AgentsOAuthProvider,
@@ -96,11 +103,16 @@ export {
   type Connection,
   type ConnectionContext,
   DEFAULT_AGENT_STATIC_OPTIONS,
+  DeleteFibersOptions,
   DurableObjectOAuthClientProvider,
   EmailRoutingOptions,
   EmailSendBinding,
   FiberContext,
+  FiberInspection,
   FiberRecoveryContext,
+  FiberRecoveryResult,
+  FiberStatus,
+  ListFibersOptions,
   MCPServer,
   MCPServerMessage,
   MCPServersState,
@@ -117,6 +129,8 @@ export {
   ScheduleCriteria,
   SendEmailOptions,
   SqlError,
+  StartFiberOptions,
+  StartFiberResult,
   StateUpdateMessage,
   StreamingResponse,
   SubAgentClass,