libfx 0.0.13 → 0.0.14-dev.1561.g1a070af32cdf

package/subscription.js

@@ -0,0 +1,253 @@
+// Subscription credentials for libfx agents: Codex on a ChatGPT plan, Grok on
+// a Grok plan. The engine sends these providers' requests without credentials;
+// this module adds them at the fetch edge, from the host's `credentials`
+// callback, refreshing near expiry and once after a rejection. Credentials
+// never enter the engine or a session's saved records, and are masked in the
+// body of a failed response.
+//
+// A provider spec supplies what differs: which requests it authorizes, how its
+// credentials are checked and refreshed, and which headers carry them.
+//
+// TLA+ model: `tests/tla/sdk/ProviderAuth.tla`.
+
+const refreshSkewMs = 5 * 60 * 1000;
+const maxRememberedCredentials = 256;
+const maxTokenBytes = 64 * 1024;
+const maxErrorBodyBytes = 64 * 1024;
+const encoder = new TextEncoder();
+
+/** A non-empty, bounded credential field, or undefined when optional and absent. */
+export function tokenString(value, name, required, label) {
+  if (value === undefined && !required) return undefined;
+  if (typeof value !== "string" || value.length === 0) {
+    throw new TypeError(`${label} credentials ${name} must be a non-empty string`);
+  }
+  if (encoder.encode(value).length > maxTokenBytes) {
+    throw new RangeError(`${label} credentials ${name} exceeds ${maxTokenBytes} bytes`);
+  }
+  return value;
+}
+
+/** The claims of a JWT, or null when it is not one. Does not verify it. */
+export function jwtClaims(token) {
+  const part = typeof token === "string" ? token.split(".")[1] : undefined;
+  if (!part) return null;
+  try {
+    const base64 = part.replace(/-/g, "+").replace(/_/g, "/").padEnd(Math.ceil(part.length / 4) * 4, "=");
+    const binary = atob(base64);
+    const bytes = Uint8Array.from(binary, (char) => char.charCodeAt(0));
+    const claims = JSON.parse(new TextDecoder().decode(bytes));
+    return claims && typeof claims === "object" ? claims : null;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Validates credentials from the host. `accountId` and `expiresAt` default to
+ * the access token's claims, `accountClaim(claims)` picking the account.
+ * Returns a new object.
+ */
+export function normalizeCredentials(value, { label, accountClaim }) {
+  if (!value || typeof value !== "object" || Array.isArray(value)) {
+    throw new TypeError("credentials() must return { accessToken, refreshToken?, accountId?, expiresAt? }");
+  }
+  const accessToken = tokenString(value.accessToken, "accessToken", true, label);
+  const refreshToken = tokenString(value.refreshToken, "refreshToken", false, label);
+  const claims = jwtClaims(accessToken);
+  const accountId = value.accountId === undefined ? accountClaim(claims) : tokenString(value.accountId, "accountId", true, label);
+  if (typeof accountId !== "string" || accountId.length === 0) {
+    throw new TypeError(`${label} credentials need an accountId; it was not in the access token`);
+  }
+  let expiresAt = value.expiresAt;
+  if (expiresAt === undefined && Number.isFinite(claims?.exp)) expiresAt = claims.exp * 1000;
+  if (expiresAt !== undefined && !Number.isFinite(expiresAt)) {
+    throw new TypeError(`${label} credentials expiresAt must be milliseconds since the epoch`);
+  }
+  return { accessToken, ...(refreshToken === undefined ? {} : { refreshToken }), accountId, ...(expiresAt === undefined ? {} : { expiresAt }) };
+}
+
+/**
+ * A failed response whose body cannot repeat the credentials its request
+ * carried. Some servers quote the bearer token back in an error, and the
+ * engine shows and saves error details, so this edge, the only code that knows
+ * the token, masks it the way fx masks error details from its own providers.
+ * JSON is normalized first, so an escaped copy cannot survive.
+ */
+async function withoutCredentials(response, credentials) {
+  if (response.status < 400) return response;
+  const raw = await boundedText(response, maxErrorBodyBytes);
+  let body = raw ?? "Provider error details exceeded the local limit";
+  if (raw !== null && /^\s*[[{"]/.test(raw)) {
+    try {
+      body = JSON.stringify(JSON.parse(raw));
+    } catch {
+      body = "Provider error details could not be decoded";
+    }
+  }
+  for (const secret of [credentials.accessToken, credentials.refreshToken]) {
+    if (!secret) continue;
+    for (const form of new Set([secret, JSON.stringify(secret).slice(1, -1)])) body = body.split(form).join("*".repeat(form.length));
+  }
+  const headers = new Headers(response.headers);
+  headers.delete("content-length");
+  headers.delete("content-encoding");
+  return new Response(body, { status: response.status, statusText: response.statusText, headers });
+}
+
+/** The body as text, or null once it exceeds `limit` bytes. */
+async function boundedText(response, limit) {
+  if (!response.body) return "";
+  const reader = response.body.getReader();
+  const decoder = new TextDecoder();
+  let size = 0;
+  let text = "";
+  for (;;) {
+    const { done, value } = await reader.read();
+    if (done) return text + decoder.decode();
+    size += value.byteLength;
+    if (size > limit) {
+      await reader.cancel().catch(() => {});
+      return null;
+    }
+    text += decoder.decode(value, { stream: true });
+  }
+}
+
+/** True when the credentials can and should be refreshed before use. */
+export function needsRefresh(credentials, nowMs) {
+  return credentials.refreshToken !== undefined &&
+    credentials.expiresAt !== undefined &&
+    credentials.expiresAt - refreshSkewMs <= nowMs;
+}
+
+/** The engine option that carries an agent's `createCredentialMemory()`. */
+export const credentialMemory = Symbol.for("libfx.credentialMemory");
+
+/**
+ * Refresh state for `createSubscriptionAuthorizer()`. An agent gives the same
+ * memory to every session's engine, so its sessions refresh an account once.
+ */
+export function createCredentialMemory() {
+  return { descendants: new Map(), refreshing: new Map(), saved: new WeakMap() };
+}
+
+/**
+ * The fetch edge for subscription requests. `credentials({ provider, sessionId })`
+ * supplies credentials; `onCredentials(next, { provider, sessionId })` receives
+ * refreshed ones once for each session that uses them, so the host can save them.
+ * `refreshLock({ provider, sessionId }, refresh)` runs `refresh` while the host
+ * holds a lock on the account, for a host with several servers.
+ *
+ * Each spec: `{ provider, matches(endpoint), sessionId(headers), normalize(value),
+ * refresh(credentials, { fetch, signal }), authorize(headers, endpoint, credentials) }`.
+ */
+export function createSubscriptionAuthorizer(specs, { credentials, onCredentials, refreshLock, fetch, now = Date.now, memory = createCredentialMemory() }) {
+  if (typeof credentials !== "function") throw new TypeError("a subscription provider needs a credentials() function");
+  if (onCredentials !== undefined && typeof onCredentials !== "function") {
+    throw new TypeError("onCredentials must be a function");
+  }
+  if (refreshLock !== undefined && typeof refreshLock !== "function") {
+    throw new TypeError("refreshLock must be a function");
+  }
+  // Each access token the host supplied maps to the newest credentials refreshed
+  // from it, so a host that has not saved a rotation yet never spends the old
+  // refresh token twice. Engines that share `memory` share this.
+  const { descendants, refreshing, saved } = memory;
+  const keyOf = (spec, token) => `${spec.provider}\u0000${token}`;
+
+  const remember = (spec, supplied, next) => {
+    const key = keyOf(spec, supplied.accessToken);
+    descendants.delete(key);
+    descendants.set(key, next);
+    if (descendants.size > maxRememberedCredentials) descendants.delete(descendants.keys().next().value);
+  };
+
+  // A host that keeps credentials per session must also save a rotation that
+  // another session's request made.
+  const savedBy = (next) => {
+    let sessions = saved.get(next);
+    if (!sessions) saved.set(next, (sessions = new Set()));
+    return sessions;
+  };
+  const save = async (spec, next, sessionId) => {
+    if (!onCredentials) return;
+    const sessions = savedBy(next);
+    if (sessions.has(sessionId)) return;
+    sessions.add(sessionId);
+    await onCredentials(next, { provider: spec.provider, sessionId });
+  };
+
+  const redeem = async (spec, supplied, current, sessionId, signal) => {
+    if (refreshLock) {
+      // Another server may have refreshed and saved them while this one waited.
+      const latest = spec.normalize(await credentials({ provider: spec.provider, sessionId }));
+      if (latest.accessToken !== current.accessToken && latest.accessToken !== supplied.accessToken && !needsRefresh(latest, now())) {
+        remember(spec, supplied, latest);
+        savedBy(latest).add(sessionId);
+        return latest;
+      }
+    }
+    const next = await spec.refresh(current, { fetch, signal });
+    remember(spec, supplied, next);
+    await save(spec, next, sessionId);
+    return next;
+  };
+
+  // With `refreshLock`, the host holds a lock on the account while the refresh
+  // runs, so its servers refresh one at a time.
+  const locked = async (spec, supplied, current, sessionId, signal) => {
+    let next;
+    await refreshLock({ provider: spec.provider, sessionId }, async () => {
+      next = await redeem(spec, supplied, current, sessionId, signal);
+    });
+    if (next === undefined) throw new Error("refreshLock must run and await the refresh it is given");
+    return next;
+  };
+
+  const refresh = async (spec, supplied, current, sessionId, signal) => {
+    const key = keyOf(spec, current.refreshToken);
+    let task = refreshing.get(key);
+    if (!task) {
+      task = (refreshLock ? locked : redeem)(spec, supplied, current, sessionId, signal).finally(() => refreshing.delete(key));
+      refreshing.set(key, task);
+    }
+    const next = await task;
+    if (sessionId !== undefined) await save(spec, next, sessionId);
+    return next;
+  };
+
+  const current = async (spec, sessionId, signal) => {
+    const supplied = spec.normalize(await credentials({ provider: spec.provider, sessionId }));
+    const best = descendants.get(keyOf(spec, supplied.accessToken)) ?? supplied;
+    const used = needsRefresh(best, now()) ? await refresh(spec, supplied, best, sessionId, signal) : best;
+    if (used !== supplied && sessionId !== undefined) await save(spec, used, sessionId);
+    return { supplied, used };
+  };
+
+  const withCredentials = (spec, endpoint, init, used) => {
+    const headers = new Headers(init.headers);
+    spec.authorize(headers, endpoint, used);
+    return { ...init, headers };
+  };
+
+  return {
+    /** The spec that authorizes requests to `endpoint` (origin and path), if any. */
+    specFor: (endpoint) => specs.find((spec) => spec.matches(endpoint)),
+    /** Sends one request with credentials, refreshing once after a 401. */
+    async fetch(spec, endpoint, hostFetch, input, init = {}) {
+      const sessionId = spec.sessionId(new Headers(init.headers)) || undefined;
+      const { used } = await current(spec, sessionId, init.signal);
+      const response = await hostFetch(input, withCredentials(spec, endpoint, init, used));
+      if (response.status !== 401 || used.refreshToken === undefined) return withoutCredentials(response, used);
+      await response.body?.cancel().catch(() => {});
+      // Another request may have replaced these credentials while this one was
+      // out. Only a rejection of the newest ones spends a refresh token.
+      const latest = await current(spec, sessionId, init.signal);
+      const next = latest.used.accessToken !== used.accessToken
+        ? latest.used
+        : await refresh(spec, latest.supplied, used, sessionId, init.signal);
+      return withoutCredentials(await hostFetch(input, withCredentials(spec, endpoint, init, next)), next);
+    },
+  };
+}

package/tool-observation.js

@@ -0,0 +1,185 @@
+// Observations of host-owned effects. Helpers call the effect exactly once,
+// preserve its value/error, and never await an instrumentation callback.
+export function toolObservation(scope, callId, hooks, emit, signal) {
+  const report = (error) => {
+    try {
+      Promise.resolve(hooks.onError?.(error)).catch(() => {});
+    } catch {}
+  };
+  let next = 0;
+  const id = () => `host:${scope.executionId}:${callId}:${++next}`;
+  const publish = (type, data, content = {}) =>
+    emit({
+      ...scope,
+      type,
+      data,
+      timestamp: Date.now(),
+      contentCaptured: hooks.captureContent === true,
+      contentTruncated: content.truncated === true,
+    });
+  const capture = () => {
+    let remaining = 64 * 1024;
+    return {
+      truncated: false,
+      text(value) {
+        if (hooks.captureContent !== true || value == null) return undefined;
+        value = String(value);
+        let prefix = value.slice(0, remaining);
+        if (prefix.length && /[\uD800-\uDBFF]/.test(prefix.at(-1))) prefix = prefix.slice(0, -1);
+        const bytes = new TextEncoder().encode(prefix);
+        let end = Math.min(bytes.length, remaining);
+        while (end > 0 && end < bytes.length && (bytes[end] & 0xc0) === 0x80) end--;
+        remaining -= end;
+        this.truncated ||= prefix.length < value.length || end < bytes.length;
+        return new TextDecoder().decode(bytes.subarray(0, end));
+      },
+    };
+  };
+  function terminal(end) {
+    let ended = false;
+    const finish = (...args) => {
+      if (ended) return;
+      ended = true;
+      signal.removeEventListener("abort", abort);
+      try {
+        end(...args);
+      } catch (error) {
+        report(error);
+      }
+    };
+    const abort = () => finish("cancelled", undefined);
+    signal.addEventListener("abort", abort, { once: true });
+    if (signal.aborted) abort();
+    return finish;
+  }
+  return {
+    async wait(request, run) {
+      if (
+        !request ||
+        !["approval", "question", "mcp_form", "mcp_url"].includes(request.kind) ||
+        typeof run !== "function"
+      )
+        throw new TypeError("wait needs an input request and an effect");
+      if (signal.aborted) return run();
+      const requestId = id();
+      const content = capture();
+      content.truncated ||=
+        (request.questions?.length ?? 0) > 128 ||
+        (request.questions ?? [])
+          .slice(0, 128)
+          .some((question) => (question.options?.length ?? 0) > 128);
+      publish(
+        "wait.start",
+        {
+          requestId,
+          kind: request.kind,
+          callId,
+          externalId: request.externalId ?? null,
+          server: request.server ?? null,
+          schemaJson: content.text(request.schemaJson),
+          prompt: content.text(request.prompt),
+          questionCount: request.questions?.length ?? 0,
+          ...(hooks.captureContent === true
+            ? {
+                questions: (request.questions ?? []).slice(0, 128).map((question) => ({
+                  question: content.text(question.question),
+                  options: (question.options ?? []).slice(0, 128).map((option) => ({
+                    label: content.text(option.label),
+                    description: content.text(option.description),
+                  })),
+                })),
+              }
+            : {}),
+        },
+        content,
+      );
+      const finish = terminal((outcome, result, error) => {
+        const content = capture();
+        content.truncated ||= (result?.answers?.length ?? 0) > 128;
+        publish(
+          "wait.end",
+          {
+            requestId,
+            outcome,
+            error: error?.name ?? null,
+            ...(hooks.captureContent === true
+              ? {
+                  answers: (result?.answers ?? [])
+                    .slice(0, 128)
+                    .map((answer) => content.text(answer)),
+                }
+              : {}),
+          },
+          content,
+        );
+      });
+      try {
+        const result = await run();
+        let outcome = "accepted";
+        try {
+          outcome = result?.outcome ?? outcome;
+        } catch (error) {
+          report(error);
+        }
+        finish(outcome, result);
+        return result;
+      } catch (error) {
+        finish(
+          signal.aborted || error?.name === "AbortError"
+            ? "cancelled"
+            : error?.name === "TimeoutError"
+              ? "timed_out"
+              : "failed",
+          undefined,
+          error,
+        );
+        throw error;
+      }
+    },
+    async mcp(identity, run) {
+      if (signal.aborted) return run({ correlationId: identity.correlationId });
+      const operationId = id();
+      publish("mcp.start", {
+        operationId,
+        callId,
+        server: identity.server ?? null,
+        tool: identity.tool,
+        transport: null,
+      });
+      if (identity.correlationId !== undefined)
+        publish("mcp.request", {
+          operationId,
+          requestId: identity.correlationId,
+          requestIdKind: "correlation",
+        });
+      const finish = terminal((status, error) =>
+        publish("mcp.end", { operationId, status, error: error?.name ?? null }),
+      );
+      try {
+        const result = await run({ correlationId: identity.correlationId });
+        let status = "unknown";
+        try {
+          status = result?.isError ? "failure" : "success";
+        } catch (error) {
+          report(error);
+        }
+        finish(status);
+        return result;
+      } catch (error) {
+        finish(signal.aborted || error?.name === "AbortError" ? "cancelled" : "failure", error);
+        throw error;
+      }
+    },
+    childHooks() {
+      return {
+        ...hooks,
+        parent: {
+          rootSessionId: scope.rootSessionId,
+          sessionId: scope.sessionId,
+          turnId: scope.turnId,
+          callId,
+        },
+      };
+    },
+  };
+}

package/types/browser.d.ts

@@ -0,0 +1,146 @@
+// `libfx` in browsers and other non-Node hosts, and `libfx/browser` (browser.js).
+import type {
+  FxAgent,
+  FxAgentOptions,
+  FxBrowserBackendOptions,
+  FxEngine,
+  FxEngineOptions,
+  FxTerminal,
+  FxTerminalOptions,
+} from "./libfx.cjs";
+
+export {
+  createMemoryPersistence,
+  encodeXtermKeyEvent,
+  FxFencedError,
+  FxJournalVersionError,
+  fxSdkApiVersion,
+  listModels,
+  memory,
+  supportsJspi,
+  xtermAdapter,
+} from "./libfx.cjs";
+
+export type {
+  Durability,
+  FxAccepted,
+  FxAgent,
+  FxAgentEvent,
+  FxAgentHostTool,
+  FxAgentKeyedTool,
+  FxAgentOptions,
+  FxAgentTool,
+  FxAgentTools,
+  FxApiKeyCredentials,
+  FxBrowserBackendOptions,
+  FxBytes,
+  FxCheckpointMeta,
+  FxCodexProvider,
+  FxCustomProvider,
+  FxCustomProviderDefinition,
+  FxCustomProviderModel,
+  FxEffort,
+  FxEngine,
+  FxEngineEvent,
+  FxEngineOptions,
+  FxEnginePromptOptions,
+  FxEngineStorage,
+  FxEngineTurn,
+  FxEngineTurnResult,
+  FxErrorSummary,
+  FxFetch,
+  FxFollowUp,
+  FxGatewayProvider,
+  FxGrokProvider,
+  FxHostTool,
+  FxHooks,
+  FxHookEvent,
+  FxHookMessage,
+  FxHookToolCall,
+  FxIdleResult,
+  FxImageBlock,
+  FxJsonSchema,
+  FxKeyedTool,
+  FxKeyEventLike,
+  FxListModelsOptions,
+  FxModelCatalogEntry,
+  FxModelChoice,
+  FxModelOptions,
+  FxOnAmbiguous,
+  FxPromptBlock,
+  FxPromptInput,
+  FxPromptOptions,
+  FxProviderCredentials,
+  FxProviderTool,
+  FxResizedImage,
+  FxResourceBlock,
+  FxResumeOptions,
+  FxResumeTurn,
+  FxSession,
+  FxSessionEvent,
+  FxSessionImageBlock,
+  FxSessionOptions,
+  FxSessionPromptInput,
+  FxSessionTurnEvent,
+  FxSharedOptions,
+  FxSteer,
+  FxSteerOptions,
+  FxSteered,
+  FxSteeringInput,
+  FxStopReason,
+  FxStreamLine,
+  FxTerminal,
+  FxTerminalAdapter,
+  FxTerminalEvent,
+  FxTerminalOptions,
+  FxTextBlock,
+  FxTool,
+  FxToolContext,
+  FxToolObservation,
+  FxWaitRequest,
+  FxWaitResponse,
+  FxToolImage,
+  FxToolResult,
+  FxTools,
+  FxTurn,
+  FxTurnEvent,
+  FxTurnResult,
+  FxTurnView,
+  FxUsage,
+  FxWasmModule,
+  FxWasmSource,
+  FxWorkspace,
+  FxWorkspaceExecResult,
+  FxXtermLike,
+  JournalRecord,
+  JsonObject,
+  JsonValue,
+  MemoryOptions,
+  MemoryPersistence,
+  Persistence,
+  PersistenceLoadResult,
+} from "./libfx.cjs";
+
+/** Options for `createFxAgent()` in browsers. */
+export type FxBrowserAgentOptions = FxAgentOptions & FxBrowserBackendOptions;
+
+/** Options for `createFxEngine()` in browsers. */
+export type FxBrowserEngineOptions = FxEngineOptions & FxBrowserBackendOptions;
+
+/** Options for `createFxTerminal()` in browsers. */
+export type FxBrowserTerminalOptions = FxTerminalOptions & FxBrowserBackendOptions;
+
+/**
+ * An agent whose sessions live in this page unless `durability` says
+ * otherwise. It returns at once and does no I/O until a session runs a turn.
+ */
+export declare function createFxAgent(options?: FxBrowserAgentOptions): FxAgent;
+
+/** One fx session on WebAssembly, with no durability of its own. `apiKey` is required. */
+export declare function createFxEngine(options: FxBrowserEngineOptions): Promise<FxEngine>;
+
+/** The interactive terminal harness. Connect it to xterm.js with `xtermAdapter()`. */
+export declare function createFxTerminal(options: FxBrowserTerminalOptions): Promise<FxTerminal>;
+
+/** The version of the libfx agent API. */
+export declare const libfxApiVersion: 3;

package/types/chatgpt.d.ts

@@ -0,0 +1,58 @@
+// `libfx/chatgpt` (chatgpt-sign-in.js): sign in with ChatGPT for a Codex agent.
+import type { FxProviderCredentials, FxFetch } from "./libfx.cjs";
+
+/** Options every network step accepts. */
+export interface ChatgptRequestOptions {
+  /** Replaces the global `fetch` for OpenAI's sign-in endpoints. */
+  fetch?: FxFetch;
+  signal?: AbortSignal;
+}
+
+/** A sign-in in progress. Keep it on the server: `verifier` is secret. */
+export interface ChatgptSignIn {
+  /** Where the user signs in. Afterwards OpenAI opens an address at localhost:1455 that does not load; the user pastes it back. */
+  readonly url: string;
+  readonly state: string;
+  readonly verifier: string;
+}
+
+/** A device code sign-in in progress. Plain data, so a later request can poll it. */
+export interface ChatgptDeviceSignIn {
+  /** Where the user enters `userCode`. */
+  readonly verificationUrl: string;
+  readonly userCode: string;
+  readonly deviceAuthId: string;
+  /** How often to poll, in milliseconds. */
+  readonly intervalMs: number;
+  /** Milliseconds since the epoch. */
+  readonly expiresAt: number;
+}
+
+/** The `code` of an error from this module. */
+export type ChatgptSignInErrorCode =
+  | "LIBFX_CHATGPT_SIGN_IN_INVALID_ADDRESS"
+  | "LIBFX_CHATGPT_SIGN_IN_STATE_MISMATCH"
+  | "LIBFX_CHATGPT_SIGN_IN_DENIED"
+  | "LIBFX_CHATGPT_SIGN_IN_EXPIRED"
+  | "LIBFX_CHATGPT_SIGN_IN_FAILED"
+  | "LIBFX_CHATGPT_DEVICE_CODE_UNAVAILABLE"
+  | "LIBFX_CHATGPT_DEVICE_CODE_EXPIRED"
+  | "LIBFX_CHATGPT_REFRESH_FAILED";
+
+/** Starts a sign-in where the user pastes back the address OpenAI opens. */
+export declare function startSignIn(): Promise<ChatgptSignIn>;
+
+/** Finishes a sign-in from the pasted address, its query, or either wrapped in quotes or backticks. */
+export declare function finishSignIn(signIn: ChatgptSignIn, address: string, options?: ChatgptRequestOptions): Promise<FxProviderCredentials>;
+
+/** Starts a device code sign-in. The account or workspace must allow device code sign-in. */
+export declare function startDeviceSignIn(options?: ChatgptRequestOptions): Promise<ChatgptDeviceSignIn>;
+
+/** Checks once: credentials after the user entered the code, otherwise null. */
+export declare function pollDeviceSignIn(device: ChatgptDeviceSignIn, options?: ChatgptRequestOptions): Promise<FxProviderCredentials | null>;
+
+/** Waits until the user enters the code, polling at OpenAI's interval. */
+export declare function completeDeviceSignIn(device: ChatgptDeviceSignIn, options?: ChatgptRequestOptions): Promise<FxProviderCredentials>;
+
+/** Refreshes credentials. Codex agents refresh on their own; this is for hosts. */
+export declare function refreshCredentials(credentials: FxProviderCredentials, options?: ChatgptRequestOptions): Promise<FxProviderCredentials>;

package/types/durable-local.d.ts

@@ -0,0 +1,18 @@
+// `libfx/durable-local` (durable/local.mjs): sessions in files on this
+// machine, through the Workflow local World libfx bundles.
+import type { Durability } from "./libfx.cjs";
+
+export type { Durability } from "./libfx.cjs";
+
+/** Options for `local()`. */
+export interface LocalOptions {
+  /** Where the sessions live. */
+  dir?: string;
+  /** Each delivery runs as if its function stopped after this long, as on Vercel. No limit by default. */
+  maxDurationMs?: number;
+  /** How long before the deadline each delivery stops. Default 30000. */
+  reserveMs?: number;
+}
+
+/** Keeps sessions in files on this machine. A session held by a process that died is free at once. */
+export declare function local(options?: LocalOptions): Durability;

package/types/durable-vercel.d.ts

@@ -0,0 +1,22 @@
+// `libfx/durable-vercel` (durable/vercel.mjs): sessions in Vercel's World,
+// the store and queue behind Vercel Workflow, which libfx bundles.
+import type { Durability } from "./libfx.cjs";
+
+export type { Durability } from "./libfx.cjs";
+
+/** Options for `vercel()`. */
+export interface VercelOptions {
+  /** How long before the function's deadline each delivery stops. Default 30000. */
+  reserveMs?: number;
+  /**
+   * 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. 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;