agents 0.13.0 → 0.13.2

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/chat-sdk/index.d.ts

@@ -0,0 +1,135 @@
+import {
+  $ as SubAgentStub,
+  Q as SubAgentClass,
+  v as Agent
+} from "../agent-tool-types-Dn9n-3SI.js";
+import { Lock, QueueEntry, StateAdapter } from "chat";
+
+//#region src/chat-sdk/agent.d.ts
+interface StoredLock {
+  threadId: string;
+  token: string;
+  expiresAt: number;
+}
+declare class ChatSdkStateAgent extends Agent {
+  onStart(): void;
+  subscribe(threadId: string): void;
+  unsubscribe(threadId: string): void;
+  isSubscribed(threadId: string): boolean;
+  acquireLock(threadId: string, ttlMs: number): Promise<StoredLock | null>;
+  releaseLock(threadId: string, token: string): void;
+  extendLock(threadId: string, token: string, ttlMs: number): Promise<boolean>;
+  forceReleaseLock(threadId: string): void;
+  enqueue(threadId: string, value: string, maxSize: number): Promise<number>;
+  popQueue(threadId: string): string | null;
+  queueDepth(threadId: string): number;
+  listAppend(
+    key: string,
+    value: string,
+    maxLength?: number,
+    ttlMs?: number
+  ): Promise<void>;
+  listGet(key: string): string[];
+  cacheGet(key: string): string | null;
+  cacheSet(key: string, value: string, ttlMs?: number): Promise<void>;
+  cacheSetIfNotExists(
+    key: string,
+    value: string,
+    ttlMs?: number
+  ): Promise<boolean>;
+  cacheDelete(key: string): void;
+  cleanupExpired(payload?: { expiresAt?: number }): Promise<void>;
+  private migrate;
+  private readCacheValue;
+  private upsertCacheValue;
+  private scheduleCleanupForExpiry;
+  private scheduleNextCleanup;
+  private ensureCleanupScheduled;
+  private nextExpiry;
+  private readCleanupMetadata;
+  private writeCleanupMetadata;
+  private clearCleanupMetadata;
+}
+//#endregion
+//#region src/chat-sdk/types.d.ts
+interface ChatSdkStateParent {
+  subAgent<T extends ChatSdkStateAgent>(
+    agentClass: SubAgentClass<T>,
+    name: string
+  ): Promise<SubAgentStub<T>>;
+}
+interface ChatSdkStateAdapterOptions {
+  agent?: SubAgentClass<ChatSdkStateAgent>;
+  parent?: ChatSdkStateParent;
+  name?: string;
+  keyShard?: (key: string) => string | undefined;
+  shardKey?: (threadId: string) => string;
+}
+//#endregion
+//#region src/chat-sdk/adapter.d.ts
+declare function defaultThreadShard(threadId: string): string;
+declare function defaultKeyShard(
+  key: string,
+  shardThread?: (threadId: string) => string
+): string | undefined;
+declare class ChatSdkStateAdapter implements StateAdapter {
+  private readonly parent;
+  private readonly agentClass;
+  private readonly defaultName;
+  private readonly keyShard?;
+  private readonly shardKey;
+  private connected;
+  constructor(options?: ChatSdkStateAdapterOptions);
+  connect(): Promise<void>;
+  disconnect(): Promise<void>;
+  subscribe(threadId: string): Promise<void>;
+  unsubscribe(threadId: string): Promise<void>;
+  isSubscribed(threadId: string): Promise<boolean>;
+  acquireLock(threadId: string, ttlMs: number): Promise<Lock | null>;
+  releaseLock(lock: Lock): Promise<void>;
+  extendLock(lock: Lock, ttlMs: number): Promise<boolean>;
+  forceReleaseLock(threadId: string): Promise<void>;
+  enqueue(
+    threadId: string,
+    entry: QueueEntry,
+    maxSize: number
+  ): Promise<number>;
+  dequeue(threadId: string): Promise<QueueEntry | null>;
+  queueDepth(threadId: string): Promise<number>;
+  appendToList(
+    key: string,
+    value: unknown,
+    options?: {
+      maxLength?: number;
+      ttlMs?: number;
+    }
+  ): Promise<void>;
+  getList<T = unknown>(key: string): Promise<T[]>;
+  get<T = unknown>(key: string): Promise<T | null>;
+  set<T = unknown>(key: string, value: T, ttlMs?: number): Promise<void>;
+  setIfNotExists<T = unknown>(
+    key: string,
+    value: T,
+    ttlMs?: number
+  ): Promise<boolean>;
+  delete(key: string): Promise<void>;
+  private stateAgent;
+  private stateAgentForKey;
+  private ensureConnected;
+}
+//#endregion
+//#region src/chat-sdk/index.d.ts
+declare function createChatSdkState(
+  options?: ChatSdkStateAdapterOptions
+): ChatSdkStateAdapter;
+//#endregion
+export {
+  ChatSdkStateAdapter,
+  type ChatSdkStateAdapterOptions,
+  ChatSdkStateAgent,
+  type ChatSdkStateParent,
+  createChatSdkState,
+  defaultKeyShard,
+  defaultThreadShard
+};
+//# sourceMappingURL=index.d.ts.map