libfx 0.0.13-dev.1472.g2c7a4f83f06f → 0.0.13-dev.1510.ga878d4900a6a

package/node.js

@@ -8,7 +8,7 @@ import { fileURLToPath, pathToFileURL } from "node:url";
 import { CoreOutput } from "./core-output.js";
 import { loadModule, withModuleFailure } from "./wasm-module.js";
 import { fetchCleanupAction, cleanupTimeoutMs, cleanupByteLimit } from "./fetch-cleanup.js";
-import { createDurableAgentFactory, memory } from "./durable.js";
+import { createDurableAgentFactory, memory, wakeHandler } from "./durable.js";
 import { fxHarness } from "./fx-harness.js";
 import {
   createFxEngine as createWasmAgent,
@@ -24,8 +24,8 @@ import {
   xtermAdapter,
 } from "./fx-sdk.js";
 
-export { createMemoryPersistence, encodeXtermKeyEvent, FxFencedError, FxJournalVersionError, fxSdkApiVersion, listModels, memory, supportsJspi, xtermAdapter };
-export const libfxApiVersion = 2;
+export { createMemoryPersistence, encodeXtermKeyEvent, FxFencedError, FxJournalVersionError, fxSdkApiVersion, listModels, memory, supportsJspi, wakeHandler, xtermAdapter };
+export const libfxApiVersion = 3;
 const nativeCoreApiVersion = 4;
 
 const fetchOperationStale = 0;
@@ -676,14 +676,30 @@ export async function createFxEngine(options = {}) {
 // on Vercel, otherwise files in the temporary directory. Each is its own
 // module, loaded only here: a bundler copies the file the URL names and
 // leaves the import itself to Node.
-async function environmentDurability() {
+// Agents created without a durability share one for each place sessions
+// live, as agents passed one durability do, so they can send each other's
+// prompts on.
+const environments = new Map();
+function environmentDurability() {
+  const dir = process.env.VERCEL ? null : process.env.FX_SESSIONS_DIR || resolve(tmpdir(), "libfx", "sessions");
+  const key = dir ?? "vercel";
+  if (!environments.has(key)) {
+    environments.set(key, chooseEnvironmentDurability(dir).catch((error) => {
+      environments.delete(key);
+      throw error;
+    }));
+  }
+  return environments.get(key);
+}
+
+async function chooseEnvironmentDurability(dir) {
   const load = (asset) => import(/* webpackIgnore: true */ /* turbopackIgnore: true */ (asset.protocol === "" ? bundledAssetUrl(asset) : asset).href);
-  if (process.env.VERCEL) {
+  if (dir === null) {
     const { vercel } = await load(new URL("./durable/vercel.mjs", import.meta.url));
     return vercel();
   }
   const { local } = await load(new URL("./durable/local.mjs", import.meta.url));
-  return local({ dir: process.env.FX_SESSIONS_DIR || resolve(tmpdir(), "libfx", "sessions") });
+  return local({ dir });
 }
 
 /**

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "libfx",
-  "version": "0.0.13-dev.1472.g2c7a4f83f06f",
+  "version": "0.0.13-dev.1510.ga878d4900a6a",
   "description": "Embed fx agents and terminals in JavaScript hosts",
   "type": "module",
   "repository": {

package/types/browser.d.ts

@@ -26,7 +26,11 @@ export type {
   FxAccepted,
   FxAgent,
   FxAgentEvent,
+  FxAgentHostTool,
+  FxAgentKeyedTool,
   FxAgentOptions,
+  FxAgentTool,
+  FxAgentTools,
   FxApiKeyCredentials,
   FxBrowserBackendOptions,
   FxBytes,
@@ -130,4 +134,4 @@ export declare function createFxEngine(options: FxBrowserEngineOptions): Promise
 export declare function createFxTerminal(options: FxBrowserTerminalOptions): Promise<FxTerminal>;
 
 /** The version of the libfx agent API. */
-export declare const libfxApiVersion: 2;
+export declare const libfxApiVersion: 3;

package/types/durable-vercel.d.ts

@@ -8,9 +8,15 @@ export type { Durability } from "./libfx.cjs";
 export interface VercelOptions {
   /** How long before the function's deadline each delivery stops. Default 30000. */
   reserveMs?: number;
-  /** How long a lease lasts after its worker took or last renewed it, so how long a function that died holds its session. At least 1000. Default 15000. */
+  /**
+   * Renew a lease of this length in the session's log while a turn runs, every third of it, so a function that stopped
+   * frees its session this long after its last renewal. Without it, nothing is renewed: a function holds its session
+   * for as long as Vercel Queues keeps the turn's message for it, and a function that died frees its session when the
+   * queue delivers that message again, about a second after its process exits, or once the queue's hold on it runs
+   * out. At least 1000.
+   */
   leaseMs?: number;
 }
 
-/** Keeps sessions in Vercel's World. Each worker renews a short lease while it runs, so a function that dies frees its session soon after. */
+/** Keeps sessions in Vercel's World. A function holds its session while Vercel Queues keeps its message for it, and the next delivery of that message continues a turn whose function died. */
 export declare function vercel(options?: VercelOptions): Durability;

package/types/durable-world.d.ts

@@ -45,6 +45,22 @@ export type WorldOptions = {
   queueDurable?: boolean;
   /** How often a waiting worker reads the session again. Default 1000. */
   pollMs?: number;
+  /**
+   * The queue keeps a message from every other delivery while one handles it, and delivers it again once that
+   * delivery's process is gone, as Vercel Queues does. Without liveness, a worker then holds its session for as long as
+   * its delivery runs, up to its deadline, and renews nothing: the next delivery of the same message takes the session
+   * over. The World must pass each handler call the queue's `messageId` and delivery `attempt`. A worker with no
+   * deadline renews its lease all the same. Default false.
+   */
+  queueLeases?: boolean;
+  /**
+   * With `queueLeases`: a prompt runs in the request that took it when no worker holds the session, and the queue keeps
+   * the prompt as a backstop it delivers only after that request's deadline. The request's lease names the backstop, so
+   * if the request died, the backstop takes the session over. Default true with `queueLeases`.
+   */
+  runInRequest?: boolean;
+  /** Keeps the request alive until `work`, a turn it runs after its response, settles, such as Vercel's `waitUntil` or Next's `after()`. */
+  waitUntil?(work: Promise<void>): void;
   /** Without liveness, how long a lease lasts after its worker took or last renewed it; renewed every third of that. At least 1000. Default 15000. */
   leaseMs?: number;
   /** Each delivery stops `reserveMs` before `maxDurationMs`, or before the World's `getRuntimeDeadline()`. No limit by default. */

package/types/libfx.d.cts

@@ -170,13 +170,19 @@ export interface FxHostTool<Input = any> {
   inputSchema: FxJsonSchema;
   /** Runs one call. A string is sent as is, an `FxToolResult` as rich content, and any other value as JSON text. */
   execute: (input: Input, context: FxToolContext) => unknown;
-  /** Running a call twice is safe, so a call cut off by a crash runs again. */
+  /** Running a call twice is safe, so a call cut off by a crash runs again. Default `false`. */
   idempotent?: boolean;
-  /** Calls must not overlap others: one starts after every earlier call in the response finishes. */
+  /** Calls must not overlap others: one starts after every earlier call in the response finishes. Defaults to `!idempotent`. */
   writes?: boolean;
   providerExecuted?: false;
 }
 
+/** A tool the JavaScript host runs for `createFxAgent()`, which must say whether a call is safe to run twice. */
+export interface FxAgentHostTool<Input = any> extends FxHostTool<Input> {
+  /** `true` when running a call twice is harmless, `false` when it is not. Required. */
+  idempotent: boolean;
+}
+
 /** A tool the provider runs, such as Gateway web search. `web_search` is currently the supported name. */
 export interface FxProviderTool {
   name: "web_search";
@@ -195,6 +201,17 @@ export type FxKeyedTool =
 /** At most 64 tools: an array of descriptors, or an object keyed by tool name. */
 export type FxTools = readonly FxTool[] | { readonly [name: string]: FxKeyedTool };
 
+/** A tool descriptor for `createFxAgent()`. */
+export type FxAgentTool = FxAgentHostTool | FxProviderTool;
+
+/** A `createFxAgent()` tool descriptor in an object keyed by tool name. */
+export type FxAgentKeyedTool =
+  | (Omit<FxAgentHostTool, "name"> & { name?: string })
+  | (Omit<FxProviderTool, "name"> & { name?: "web_search" });
+
+/** At most 64 `createFxAgent()` tools: an array of descriptors, or an object keyed by tool name. */
+export type FxAgentTools = readonly FxAgentTool[] | { readonly [name: string]: FxAgentKeyedTool };
+
 // ---------------------------------------------------------------------------
 // Turn events and results
 
@@ -275,6 +292,8 @@ export type FxEngineEvent = FxEventBase & (
 export type FxSessionEvent = FxEventBase & (
   | { type: "session.error"; sessionId: string; error: FxErrorSummary }
   | { type: "session.fenced"; sessionId: string; epoch: number }
+  /** A message for a session of the agent `agent` reached this one, which sent it on. */
+  | { type: "session.forwarded"; sessionId: string; agent: string }
   /** `cutoffs`: the times in a row the deadline cut off the same step, this one included. */
   | { type: "session.deadline"; sessionId: string; epoch: number; cutoffs: number }
   | { type: "ui.error"; sessionId: string; error: string }
@@ -341,16 +360,31 @@ export interface JournalRecord {
 export interface PersistenceLoadResult {
   checkpoint?: { data: FxBytes; through: string };
   journal?: Iterable<{ cursor: string; data: FxBytes }> | AsyncIterable<{ cursor: string; data: FxBytes }>;
+  /** The cursor the next `append()` names as `expected`, for a store whose log holds entries of its own after the last record. Defaults to the last record's cursor, or the checkpoint's `through`. */
+  head?: string | null;
 }
 
+/** What one record tells a store that set `marks: true` about turns: a turn started, ended or yielded, or an input was accepted. Other marks may appear; a store keeps or ignores them. */
+export type FxJournalMark =
+  | { start: string }
+  | { end: true }
+  | { yield: true }
+  | { accepted: string }
+  | { step: string };
+
 /** A store for one session's records and checkpoints. libfx writes opaque bytes; the store never parses them. */
 export interface Persistence {
   /** Called once by `createFxEngine()`. Resolve to `{}` for a session with nothing stored. */
   load(): Promise<PersistenceLoadResult>;
-  /** Stores one record and resolves to its cursor. Reject with an `FxFencedError` when `expected` is not the last stored record's cursor. */
-  append(input: { expected: string | null; idempotencyKey: string; data: Uint8Array }): Promise<{ cursor: string }>;
+  /**
+   * Stores one record and resolves to its cursor. Reject with an `FxFencedError` when `expected` is not the last stored record's cursor.
+   * `barrier` is true when libfx waits for the record before it goes on, such as before a tool call with effects. A store may resolve a record with `barrier: false` before it is durable, if it keeps records in order and resolves one with `barrier: true` only once it and every record before it are durable.
+   */
+  append(input: { expected: string | null; idempotencyKey: string; data: Uint8Array; barrier: boolean; marks?: FxJournalMark[] }): Promise<{ cursor: string }>;
   /** Stores a checkpoint covering the records through `through`. */
   saveCheckpoint?(input: { through: string; data: Uint8Array }): Promise<void>;
+  /** Set to receive each record's `marks`, for a store that tracks turns and accepted inputs without reading records. */
+  marks?: boolean;
 }
 
 /** The persistence store `createMemoryPersistence()` returns. */
@@ -370,7 +404,7 @@ export declare class FxFencedError extends Error {
   code: "FX_FENCED";
 }
 
-/** The journal was written by a newer libfx than this one. Its `code` is `FX_JOURNAL_VERSION`. */
+/** The journal, or the `checkpoint` option, was written by a newer libfx than this one. Its `code` is `FX_JOURNAL_VERSION`. */
 export declare class FxJournalVersionError extends Error {
   constructor(message?: string);
   name: "FxJournalVersionError";
@@ -393,12 +427,16 @@ export interface FxEnginePromptOptions {
   /** The turn's id, so a retried prompt continues or answers the same turn. 1 to 128 letters, digits, `.`, `_`, or `-`. */
   turnId?: string;
   onAmbiguous?: FxOnAmbiguous;
+  /** With `persistence`: a time, in milliseconds since the epoch, after which the turn stops before its next model request with the stop reason `yielded`. The journal keeps it open, and the next `resume()` continues it without telling the model it was interrupted. */
+  yieldAt?: number;
 }
 
 /** Options for an engine's `resume()`. */
 export interface FxResumeOptions {
   signal?: AbortSignal;
   onAmbiguous?: FxOnAmbiguous;
+  /** As `FxEnginePromptOptions.yieldAt`. */
+  yieldAt?: number;
 }
 
 /** How an engine turn ended. */
@@ -570,13 +608,21 @@ export declare function memory(options?: MemoryOptions): Durability;
 // Durable agents
 
 /** Options for `createFxAgent()`. */
-export type FxAgentOptions = FxSharedOptions<FxAgentEvent> & FxModelChoice & (FxGatewayProvider | FxCodexProvider | FxGrokProvider | FxCustomProvider) & {
+export type FxAgentOptions = Omit<FxSharedOptions<FxAgentEvent>, "tools"> & FxModelChoice & (FxGatewayProvider | FxCodexProvider | FxGrokProvider | FxCustomProvider) & {
+  /** Every host tool sets `idempotent`. */
+  tools?: FxAgentTools;
   /** The AI Gateway credential. Without it, libfx uses `AI_GATEWAY_API_KEY`, then on Vercel the deployment's OIDC token. */
   apiKey?: string | undefined;
   /** Where sessions live. Without it, libfx picks one from the environment. */
   durability?: Durability | undefined;
   /** Checkpoint bytes the agent's new sessions start from. */
   checkpoint?: FxBytes;
+  /**
+   * The agent's name, 1 to 64 letters, digits, `.`, `_` or `-`, starting with a letter or digit. Default `"default"`.
+   * A session's turns run only on agents with the name of the agent that created it, so an app can have several
+   * durable agents. Agents with the same name are copies of one agent and share its sessions' turns.
+   */
+  name?: string;
 };
 
 /** Options for `agent.session()`. Each applies to the turns this session object starts. */
@@ -626,7 +672,7 @@ export interface FxIdleResult {
 /** A turn event as a durable session delivers it, with the lease epoch of the worker that wrote it. */
 export type FxSessionTurnEvent = FxTurnEvent & { epoch?: number };
 
-/** A view of one durable turn. Dropping it cancels nothing; call `session.cancel()` to stop the turn. */
+/** A view of one durable turn. It reads the session stream only once its events, `readable` or `result` are used. Dropping it cancels nothing; call `session.cancel()` to stop the turn. */
 export interface FxTurnView<Result> {
   /** Resolves once the prompt is stored, or at once for a prompt whose signal had already aborted. */
   readonly accepted: Promise<FxAccepted>;
@@ -691,6 +737,8 @@ export interface FxSession {
 
 /** An agent: the configuration its sessions run under. Create one per server and open a session per conversation. */
 export interface FxAgent {
+  /** The agent's name, `"default"` unless `createFxAgent()` gave one. */
+  readonly name: string;
   /** Opens the session `id`, or starts a new one without it. Any other value, `null` included, throws. */
   session(id?: string, options?: FxSessionOptions): FxSession;
   /** An id for a new session, before its first prompt. */
@@ -701,12 +749,18 @@ export interface FxAgent {
   prompt(input: FxSessionPromptInput, options?: FxPromptOptions): FxTurn;
   /** The history of the session `agent.prompt()` uses, as opaque bytes. */
   checkpoint(): Promise<Uint8Array>;
-  /** The request handler a deployment mounts for queue deliveries. */
+  /** The request handler a deployment mounts for queue deliveries; it delivers to whichever agent in the process a message names. */
   wakeHandler(): (request: Request) => Promise<Response>;
   /** Waits for the turns this process is running, then lets their sessions go. */
   close(): Promise<void>;
 }
 
+/**
+ * The request handler a deployment mounts for queue deliveries, for every durable agent in the process: each
+ * delivery goes to the agent its message names. One route and one queue trigger serve any number of agents.
+ */
+export declare function wakeHandler(): (request: Request) => Promise<Response>;
+
 // ---------------------------------------------------------------------------
 // Backend diagnostics (Node.js)
 

package/types/mcp.d.ts

@@ -1,5 +1,5 @@
 // `libfx/mcp` (mcp.js): tools and instructions from a host-owned MCP client.
-import type { FxHostTool } from "./libfx.cjs";
+import type { FxAgentHostTool } from "./libfx.cjs";
 
 /**
  * The parts of an MCP client the adapter calls, with the MCP TypeScript SDK
@@ -30,7 +30,8 @@ export interface McpAdapterOptions {
 
 /** What `createMcpAdapter()` resolves to. Pass `tools` and `instructions` to the agent. */
 export interface McpAdapter {
-  tools: FxHostTool[];
+  /** Each tool has `idempotent: false`; set it to `true` on a tool known to be safe to run twice. */
+  tools: FxAgentHostTool[];
   instructions: string;
   /** Closes the client once. */
   close(): Promise<void>;

package/types/node.d.cts

@@ -21,6 +21,7 @@ export {
   listModels,
   memory,
   supportsJspi,
+  wakeHandler,
   xtermAdapter,
 } from "./libfx.cjs";
 
@@ -29,7 +30,11 @@ export type {
   FxAccepted,
   FxAgent,
   FxAgentEvent,
+  FxAgentHostTool,
+  FxAgentKeyedTool,
   FxAgentOptions,
+  FxAgentTool,
+  FxAgentTools,
   FxApiKeyCredentials,
   FxBackendAttempt,
   FxBackendChoice,
@@ -148,4 +153,4 @@ export declare function createFxTerminal(options: FxNodeTerminalOptions): Promis
 export declare function getBackendInfo(options?: FxBackendInfoOptions): Promise<FxBackendInfo>;
 
 /** The version of the libfx agent API. */
-export declare const libfxApiVersion: 2;
+export declare const libfxApiVersion: 3;

package/types/skills-node.d.ts

@@ -1,6 +1,6 @@
 // `libfx/skills/node` (skills-node.js): loads a `SKILL.md` explicitly in
 // Node.js or Bun.
-import type { FxTool } from "./libfx.cjs";
+import type { FxAgentTool } from "./libfx.cjs";
 import type { SkillRecord, SkillResource } from "./skills.js";
 
 export { createSkillsAdapter } from "./skills.js";
@@ -11,14 +11,14 @@ export interface LoadSkillFileOptions {
   /** Replaces `fs.promises.readFile`. */
   readFile?: (path: string, encoding: "utf8") => string | Promise<string>;
   resources?: readonly SkillResource[];
-  tools?: readonly FxTool[];
+  tools?: readonly FxAgentTool[];
 }
 
 /** A skill read from a `SKILL.md`: its frontmatter `name` and `description`, and its body as instructions. */
 export interface LoadedSkill extends SkillRecord {
   description: string;
   resources: readonly SkillResource[];
-  tools: readonly FxTool[];
+  tools: readonly FxAgentTool[];
 }
 
 /** Reads one `SKILL.md`. Without a frontmatter `name`, the file name is the skill's name. */

package/types/skills.d.ts

@@ -1,6 +1,6 @@
 // `libfx/skills` (skills.js): instructions and tools from already-loaded
 // skill records.
-import type { FxTool } from "./libfx.cjs";
+import type { FxAgentTool } from "./libfx.cjs";
 
 /** A resource whose text joins its skill's instructions. */
 export interface SkillResource {
@@ -14,13 +14,14 @@ export interface SkillRecord {
   instructions: string;
   description?: string;
   resources?: readonly SkillResource[];
-  tools?: readonly FxTool[];
+  /** Each host tool sets `idempotent`, as `createFxAgent()` requires. */
+  tools?: readonly FxAgentTool[];
 }
 
 /** What `createSkillsAdapter()` returns: spread it into the agent options. */
 export interface SkillsAdapter {
   instructions: string;
-  tools: FxTool[];
+  tools: FxAgentTool[];
 }
 
 /** Turns up to 64 skill records into instructions and tools. */