libfx 0.0.13 → 0.0.14-dev.1534.g6afa7c33dac5

package/subscription.js

@@ -0,0 +1,251 @@
+// 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.
+
+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/types/browser.d.ts

@@ -0,0 +1,139 @@
+// `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,
+  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,
+  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;

package/types/durable-world.d.ts

@@ -0,0 +1,89 @@
+// `libfx/durable-world` (durable/world.mjs): sessions kept in a World the app
+// supplies, such as Workflow's Postgres World.
+import type { Durability } from "./libfx.cjs";
+
+export type { Durability } from "./libfx.cjs";
+
+/**
+ * What libfx uses of a World: its events, streams, and queue. Workflow's
+ * Worlds fit. Methods are typed loosely so any conforming World is accepted.
+ */
+export interface World {
+  readonly specVersion?: number;
+  readonly events: {
+    create(runId: string, data: unknown, params?: unknown): unknown;
+    list(params: unknown): unknown;
+  };
+  readonly streams: {
+    write(runId: string, name: string, chunk: string): unknown;
+    writeMulti?(runId: string, name: string, chunks: string[]): unknown;
+    get(runId: string, name: string, startIndex?: number): unknown;
+    getInfo(runId: string, name: string): unknown;
+  };
+  queue(queueName: string, message: unknown, options?: unknown): unknown;
+  createQueueHandler(prefix: string, handler: (message: unknown, meta: any) => Promise<unknown>): (request: Request) => Promise<Response>;
+  /** A World with `registerHandler` delivers to the agent in its process; any other delivers over HTTP to `agent.wakeHandler()`. */
+  registerHandler?(prefix: string, handler: (request: Request) => Promise<Response>): unknown;
+  getRuntimeDeadline?(): unknown;
+  getDeploymentId?(): unknown;
+  createRunId?(options?: Readonly<Record<string, unknown>>): string;
+  start?(): unknown;
+  close?(): unknown;
+}
+
+/** A lease as `alive()` sees it: the fields `holderInfo()` returned when it was taken, beside libfx's own. */
+export type WorldLease = Readonly<Record<string, unknown>>;
+
+/** A World, or a function that creates one. libfx starts and closes a World it creates; a World passed in stays the app's. */
+export type WorldSource = World | (() => World | Promise<World>);
+
+/** What `world()` cannot learn from the World itself. */
+export type WorldOptions = {
+  /** The durability's name in errors. Default `"world"`. */
+  name?: string;
+  /** The queue keeps a message until a delivery acknowledges it, across crashes. When false, `prompt()` stores the prompt first. Default false. */
+  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. */
+  maxDurationMs?: number;
+  /** Default 30000. */
+  reserveMs?: number;
+  /** What a worker puts in each lease it takes, for `alive()` to read. */
+  holderInfo?(): Record<string, unknown>;
+  /** The AI Gateway credential when the agent has no `apiKey`. */
+  gatewayKey?(): string | Promise<string>;
+} & (
+  | {
+    /** `alive(lease)` answers whether a lease's holder still runs, so a crashed worker's session frees at once. */
+    livenessKnown: true;
+    /** True when the holder runs, false when it does not, and null when unknown. */
+    alive(lease: WorldLease): boolean | null;
+  }
+  | {
+    /** Without liveness, a worker renews its lease while it runs, and the session of one that died frees `leaseMs` after its last renewal. */
+    livenessKnown?: false;
+    alive?(lease: WorldLease): boolean | null;
+  }
+);
+
+/** Keeps sessions in a World the app supplies: its store, streams, and queue. */
+export declare function world(source: WorldSource, options?: WorldOptions): Durability;

package/types/grok.d.ts

@@ -0,0 +1,61 @@
+// `libfx/grok` (grok-sign-in.js): sign in with a Grok plan for a Grok agent.
+import type { FxProviderCredentials, FxFetch } from "./libfx.cjs";
+
+/** Options every network step accepts. */
+export interface GrokRequestOptions {
+  /** Replaces the global `fetch` for xAI's sign-in endpoints. */
+  fetch?: FxFetch;
+  signal?: AbortSignal;
+}
+
+/** A sign-in in progress. Keep it on the server: `verifier` is secret. */
+export interface GrokSignIn {
+  /** Where the user signs in. Afterwards xAI opens an address at `redirectUri` that does not load; the user pastes it back. */
+  readonly url: string;
+  readonly state: string;
+  readonly verifier: string;
+  readonly redirectUri: string;
+}
+
+/** A device code sign-in in progress. Plain data, so a later request can poll it. */
+export interface GrokDeviceSignIn {
+  /** Where the user enters `userCode`. */
+  readonly verificationUrl: string;
+  readonly userCode: string;
+  readonly deviceCode: 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 GrokSignInErrorCode =
+  | "LIBFX_GROK_SIGN_IN_INVALID_ADDRESS"
+  | "LIBFX_GROK_SIGN_IN_STATE_MISMATCH"
+  | "LIBFX_GROK_SIGN_IN_DENIED"
+  | "LIBFX_GROK_SIGN_IN_EXPIRED"
+  | "LIBFX_GROK_SIGN_IN_FAILED"
+  | "LIBFX_GROK_DEVICE_CODE_UNAVAILABLE"
+  | "LIBFX_GROK_DEVICE_CODE_EXPIRED"
+  | "LIBFX_GROK_ACCOUNT_UNAVAILABLE"
+  | "LIBFX_GROK_ACCOUNT_CHANGED"
+  | "LIBFX_GROK_REFRESH_FAILED";
+
+/** Starts a sign-in where the user pastes back the address xAI opens. */
+export declare function startSignIn(): Promise<GrokSignIn>;
+
+/** Finishes a sign-in from the pasted address, its query, or either wrapped in quotes or backticks. */
+export declare function finishSignIn(signIn: GrokSignIn, address: string, options?: GrokRequestOptions): Promise<FxProviderCredentials>;
+
+/** Starts a device code sign-in. */
+export declare function startDeviceSignIn(options?: GrokRequestOptions): Promise<GrokDeviceSignIn>;
+
+/** Checks once: credentials after the user entered the code, otherwise null. */
+export declare function pollDeviceSignIn(device: GrokDeviceSignIn, options?: GrokRequestOptions): Promise<FxProviderCredentials | null>;
+
+/** Waits until the user enters the code, polling at xAI's interval. */
+export declare function completeDeviceSignIn(device: GrokDeviceSignIn, options?: GrokRequestOptions): Promise<FxProviderCredentials>;
+
+/** Refreshes credentials. Grok agents refresh on their own; this is for hosts. */
+export declare function refreshCredentials(credentials: FxProviderCredentials, options?: GrokRequestOptions): Promise<FxProviderCredentials>;