libfx 0.0.13 → 0.0.14

package/node.js

@@ -2,14 +2,20 @@ import { access, readFile } from "node:fs/promises";
 import { closeSync } from "node:fs";
 import { createRequire } from "node:module";
 import { Socket } from "node:net";
-import { homedir } from "node:os";
+import { homedir, tmpdir } from "node:os";
 import { isAbsolute, resolve } from "node:path";
 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, wakeHandler } from "./durable.js";
+import { fxHarness } from "./fx-harness.js";
 import {
-  createFxAgent as createWasmAgent,
+  createFxEngine as createWasmAgent,
   createFxTerminal as createWasmTerminal,
+  createMemoryPersistence,
+  FxFencedError,
+  FxJournalVersionError,
   encodeXtermKeyEvent,
   fxSdkApiVersion,
   listModels,
@@ -18,8 +24,8 @@ import {
   xtermAdapter,
 } from "./fx-sdk.js";
 
-export { encodeXtermKeyEvent, fxSdkApiVersion, listModels, 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;
@@ -346,14 +352,22 @@ export async function getBackendInfo(value = {}) {
 }
 
 function createNativeCoreRuntime(addon, options) {
-  const { apiKey, model, effort, fast, ultrafast, gatewayChatUrl } = options;
+  const { apiKey, providerName: provider, customProvider, model, effort, fast, ultrafast, gatewayChatUrl } = options;
   if (ultrafast !== undefined && addon.supportsUltrafast !== true) {
     const error = new Error("native addon does not support the ultrafast option");
     error.code = "LIBFX_NATIVE_CAPABILITY_UNAVAILABLE";
     throw error;
   }
+  const capability = customProvider ? "supportsConfiguredProvider" : { codex: "supportsCodex", grok: "supportsGrok" }[provider];
+  if (capability && addon[capability] !== true) {
+    const error = new Error(`native addon does not support the ${provider} provider`);
+    error.code = "LIBFX_NATIVE_CAPABILITY_UNAVAILABLE";
+    throw error;
+  }
   const core = addon.createCore({
-    apiKey,
+    ...(apiKey === undefined ? {} : { apiKey }),
+    ...(provider === undefined ? {} : { provider }),
+    ...(customProvider === undefined ? {} : { configuredProviders: customProvider.json }),
     home: options.home ?? homedir(),
     workspaceRoot: options.workspaceRoot ?? process.cwd(),
     ...(model === undefined ? {} : { model }),
@@ -383,76 +397,154 @@ function createNativeCoreRuntime(addon, options) {
   let settled = false;
   let fetchState = null;
   const exited = new Promise((resolve) => { exitedResolve = resolve; });
+  function refreshFetch(state) {
+    if (settled) return;
+    if (typeof addon.coreFetchDisposition !== "function") {
+      state.active = addon.coreFetchActive(core, state.handle);
+      return;
+    }
+    // One native lock observes consumption and retirement together.
+    const disposition = addon.coreFetchDisposition(core, state.handle);
+    if (disposition !== 0 && disposition !== 1 && disposition !== 2) {
+      throw new Error(`invalid native fetch disposition ${disposition}`);
+    }
+    state.consumed ||= disposition === 2;
+    state.active = disposition === 1;
+  }
+  function cleanupAction(state) {
+    return fetchCleanupAction({ ...state, alive: !settled,
+      age: state.drainStarted === null ? 0 : performance.now() - state.drainStarted });
+  }
+  function beginDrain(state) {
+    if (state.drainStarted !== null) return;
+    state.drainStarted = performance.now();
+    state.timer = setTimeout(() => state.controller.abort(), cleanupTimeoutMs);
+  }
   const abortHostEffects = () => {
-    fetchState?.controller.abort();
-    try { addon.abortCoreFetch(core); } catch {}
+    if (fetchState) {
+      fetchState.canceled = true;
+      fetchState.controller.abort();
+    }
+    if (!settled) { try { addon.abortCoreFetch(core); } catch {} }
   };
   const finish = (code, error) => {
     if (settled) return;
+    const state = fetchState;
+    if (state) {
+      refreshFetch(state);
+      state.closing = true;
+      state.failed ||= code !== 0 || error !== undefined;
+    }
     settled = true;
     outputError = error;
     output.close();
-    abortHostEffects();
-    try { addon.destroyCore(core); } catch {}
-    readySocket.destroy();
-    void readyClosed.then(() => exitedResolve(code));
+    const destroy = () => {
+      try { addon.destroyCore(core); } catch {}
+      readySocket.destroy();
+      void readyClosed.then(() => exitedResolve(code));
+    };
+    if (state && cleanupAction(state) === "drain") {
+      beginDrain(state);
+      void state.done.then(destroy);
+    } else {
+      if (state && cleanupAction(state) !== "done") state.controller.abort();
+      destroy();
+    }
   };
   const pumpFetch = async (request, body) => {
     const controller = new AbortController();
-    const state = { handle: request.handle, controller };
+    let complete, reader;
+    const state = { handle: request.handle, controller, consumed: false, active: true,
+      canceled: false, failed: false, closing: false, eof: false, discarded: 0,
+      drainStarted: null, timer: null, done: new Promise(resolve => { complete = resolve; }) };
     fetchState = state;
+    let onAbort;
+    const aborted = new Promise((_, reject) => {
+      onAbort = () => reject(new DOMException("Aborted", "AbortError"));
+      controller.signal.addEventListener("abort", onAbort, { once: true });
+    });
+    void aborted.catch(() => {});
+    const wait = task => Promise.race([task, aborted]);
     try {
-      const response = await (options.fetch ?? globalThis.fetch)(request.url, {
+      const responseTask = Promise.resolve().then(() => (options.fetch ?? globalThis.fetch)(request.url, {
         method: request.method,
         headers: new Headers(JSON.parse(request.headers).map(({ name, value }) => [name, value])),
         body: body.length ? body : undefined,
         signal: controller.signal,
+      })).then(response => {
+        if (controller.signal.aborted) {
+          void response.body?.cancel().catch(() => {});
+          throw new DOMException("Aborted", "AbortError");
+        }
+        return response;
       });
-      const started = addon.startCoreFetchResponse(core, state.handle, response.status);
-      if (started === fetchOperationStale) return;
-      if (started !== fetchOperationApplied) throw new Error(`invalid native fetch start result ${started}`);
-      if (response.body) {
-        for await (const chunk of response.body) {
-          const buffer = Buffer.from(chunk);
-          options.onTransportChunk?.(buffer.length);
-          let offset = 0;
-          while (offset < buffer.length) {
-            const end = Math.min(offset + 64 * 1024, buffer.length);
-            const pushed = addon.pushCoreFetchResponse(core, state.handle, buffer.subarray(offset, end));
-            if (pushed === fetchOperationApplied) {
-              offset = end;
-              continue;
-            }
-            if (pushed === fetchOperationStale) return;
-            if (pushed !== fetchOperationBackpressure) throw new Error(`invalid native fetch push result ${pushed}`);
-            await new Promise((resolve) => setTimeout(resolve, 2));
+      const response = await wait(responseTask);
+      if (settled && !state.consumed) throw new DOMException("Aborted", "AbortError");
+      const started = settled ? fetchOperationStale : addon.startCoreFetchResponse(core, state.handle, response.status);
+      if (started !== fetchOperationApplied && started !== fetchOperationStale) throw new Error(`invalid native fetch start result ${started}`);
+      state.active = started === fetchOperationApplied;
+      reader = response.body?.getReader();
+      while (reader) {
+        refreshFetch(state);
+        const action = cleanupAction(state);
+        if (action === "abort") { controller.abort(); throw new DOMException("Aborted", "AbortError"); }
+        if (action === "drain") beginDrain(state);
+        const { done, value } = await wait(reader.read());
+        if (done) break;
+        const buffer = Buffer.from(value);
+        options.onTransportChunk?.(buffer.length);
+        let offset = 0;
+        while (offset < buffer.length) {
+          refreshFetch(state);
+          const next = cleanupAction(state);
+          if (next === "drain") {
+            beginDrain(state);
+            state.discarded += buffer.length - offset;
+            if (state.discarded >= cleanupByteLimit) controller.abort();
+            break;
+          }
+          if (next !== "forward") { controller.abort(); throw new DOMException("Aborted", "AbortError"); }
+          const end = Math.min(offset + 64 * 1024, buffer.length);
+          const pushed = addon.pushCoreFetchResponse(core, state.handle, buffer.subarray(offset, end));
+          if (pushed === fetchOperationApplied) { offset = end; continue; }
+          if (pushed === fetchOperationStale) {
+            refreshFetch(state);
+            if (cleanupAction(state) === "drain") continue;
+            controller.abort(); throw new DOMException("Aborted", "AbortError");
           }
+          if (pushed !== fetchOperationBackpressure) throw new Error(`invalid native fetch push result ${pushed}`);
+          await wait(new Promise(resolve => setTimeout(resolve, 2)));
         }
       }
-      const finished = addon.finishCoreFetch(core, state.handle);
-      if (finished !== fetchOperationApplied && finished !== fetchOperationStale) {
-        throw new Error(`invalid native fetch finish result ${finished}`);
+      state.eof = true;
+      if (!settled && state.active) {
+        const finished = addon.finishCoreFetch(core, state.handle);
+        if (finished !== fetchOperationApplied && finished !== fetchOperationStale) throw new Error(`invalid native fetch finish result ${finished}`);
       }
     } catch (error) {
-      if (error?.name !== "AbortError" || !controller.signal.aborted) {
-        try {
-          if (addon.coreFetchActive(core, state.handle)) addon.failCoreFetch(core, state.handle);
-        } catch {}
+      if (!settled && !controller.signal.aborted) {
+        state.failed = true;
+        try { if (addon.coreFetchActive(core, state.handle)) addon.failCoreFetch(core, state.handle); } catch {}
       }
     } finally {
-      if (fetchState === state) {
-        fetchState = null;
-        queueMicrotask(drainReady);
+      clearTimeout(state.timer);
+      controller.signal.removeEventListener("abort", onAbort);
+      if (reader) {
+        if (!state.eof) { try { void reader.cancel().catch(() => {}); } catch {} }
+        try { reader.releaseLock(); } catch {}
       }
+      complete();
+      if (fetchState === state) { fetchState = null; queueMicrotask(drainReady); }
     }
   };
   function drainReady() {
     if (settled) return;
     try {
       if (fetchState) {
-        if (!fetchState.controller.signal.aborted && !addon.coreFetchActive(core, fetchState.handle)) {
-          fetchState.controller.abort();
-        }
+        refreshFetch(fetchState);
+        const action = cleanupAction(fetchState);
+        if (action === "drain") beginDrain(fetchState);
+        if (action === "abort") fetchState.controller.abort();
       } else {
         // The core hands over JSON metadata and the raw request body separately.
         const fetchRequest = addon.takeCoreFetch(core);
@@ -546,7 +638,8 @@ async function createWithFallback(surface, nativeMethod, wasmFactory, defaultWas
       } catch (error) {
         nativeError = error;
         if (backend === "native" || error?.code === "LIBFX_MODEL_UNSUPPORTED_FAST" ||
-          error?.code === "LIBFX_MODEL_UNSUPPORTED_EFFORT") throw error;
+          error?.code === "LIBFX_MODEL_UNSUPPORTED_EFFORT" ||
+          typeof error?.code === "string" && error.code.startsWith("LIBFX_MODEL_METADATA_")) throw error;
       }
     }
     if (backend === "native") {
@@ -564,7 +657,12 @@ async function createWithFallback(surface, nativeMethod, wasmFactory, defaultWas
   return wasmFactory({ ...runtimeOptions, wasm: await wasmInput(wasmSource) });
 }
 
-export async function createFxAgent(options = {}) {
+/**
+ * One fx session on the native core, or on WebAssembly when the native
+ * addon is unavailable, with no durability of its own. `createFxAgent`
+ * runs durable sessions on these.
+ */
+export async function createFxEngine(options = {}) {
   return createWithFallback(
     "agent",
     "createCore",
@@ -574,6 +672,56 @@ export async function createFxAgent(options = {}) {
   );
 }
 
+// The durability a session gets when the caller names none: Vercel's World
+// 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.
+// 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 (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 });
+}
+
+/**
+ * An agent whose sessions survive crashes, timeouts and redeployments. It
+ * does no I/O until a session is used.
+ */
+export const createFxAgent = createDurableAgentFactory({
+  name: "createFxAgent",
+  label: "fx agent",
+  defaultDurability: environmentDurability,
+  // One durability per environment, so agents created without one share it.
+  defaultShared: true,
+  harness: fxHarness({
+    createEngine: createFxEngine,
+    // An explicit key, then the durability's own credential, such as a
+    // Vercel deployment's OIDC token, then the one in the environment.
+    defaultApiKey: async (durability) => process.env.AI_GATEWAY_API_KEY ||
+      (await Promise.resolve(durability?.gatewayKey?.()).catch(() => undefined)) ||
+      process.env.VERCEL_OIDC_TOKEN || undefined,
+  }),
+});
+
 export function createFxTerminal(options = {}) {
   return createWithFallback("terminal", "createFxTerminal", createWasmTerminal, defaultTermWasm, options);
 }

package/oauth.js

@@ -0,0 +1,64 @@
+// Pieces the subscription sign-ins share: PKCE secrets, reading a pasted
+// redirect address, and waiting between device code polls.
+
+const maxAddressBytes = 16 * 1024;
+const encoder = new TextEncoder();
+
+export function signInError(code, message, fields = {}) {
+  const error = new Error(message);
+  error.code = code;
+  return Object.assign(error, fields);
+}
+
+const base64url = (bytes) => btoa(String.fromCharCode(...bytes)).replace(/\+/g, "-").replace(/\//g, "_").replace(/=+$/, "");
+
+/** A random URL-safe secret, for a PKCE verifier or an OAuth state. */
+export const randomSecret = () => base64url(crypto.getRandomValues(new Uint8Array(32)));
+
+/** The S256 challenge for a PKCE verifier. */
+export async function pkceChallenge(verifier) {
+  return base64url(new Uint8Array(await crypto.subtle.digest("SHA-256", encoder.encode(verifier))));
+}
+
+export const hostFetch = (fetch) => fetch ?? globalThis.fetch?.bind(globalThis);
+
+/**
+ * Reads the sign-in result from a pasted address: the whole address, its query,
+ * or either wrapped in quotes, backticks or angle brackets. `prefix` names the
+ * error codes, `issuer` the sign-in page, and `redirectUri` the address the
+ * user should have copied.
+ */
+export function readSignInAddress(text, { prefix, issuer, redirectUri }) {
+  if (typeof text !== "string" || encoder.encode(text).length > maxAddressBytes) {
+    throw signInError(`${prefix}_SIGN_IN_INVALID_ADDRESS`, `Paste the address of the page ${issuer} opened after you signed in.`);
+  }
+  const trimmed = text.trim().replace(/^[`'"<\s]+|[`'">\s]+$/g, "");
+  let params;
+  try {
+    params = new URL(trimmed).searchParams;
+  } catch {
+    params = new URLSearchParams(trimmed.includes("?") ? trimmed.slice(trimmed.indexOf("?") + 1) : trimmed);
+  }
+  const error = params.get("error");
+  if (error) {
+    throw signInError(`${prefix}_SIGN_IN_DENIED`, `${issuer} did not sign you in: ${params.get("error_description") || error}`, { reason: error });
+  }
+  const code = params.get("code");
+  if (!code) {
+    throw signInError(
+      `${prefix}_SIGN_IN_INVALID_ADDRESS`,
+      `That address has no sign-in code. Copy the whole address of the page ${issuer} opened after you signed in; it starts with ${redirectUri}?code=`,
+    );
+  }
+  return { code, state: params.get("state") };
+}
+
+/** Resolves after `ms`, or rejects when `signal` aborts first. */
+export function wait(ms, signal) {
+  return new Promise((resolve, reject) => {
+    if (signal?.aborted) return reject(signal.reason ?? new DOMException("Aborted", "AbortError"));
+    const timer = setTimeout(() => { signal?.removeEventListener("abort", onAbort); resolve(); }, ms);
+    const onAbort = () => { clearTimeout(timer); reject(signal.reason ?? new DOMException("Aborted", "AbortError")); };
+    signal?.addEventListener("abort", onAbort, { once: true });
+  });
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "libfx",
-  "version": "0.0.13",
+  "version": "0.0.14",
   "description": "Embed fx agents and terminals in JavaScript hosts",
   "type": "module",
   "repository": {
@@ -18,21 +18,74 @@
   "exports": {
     ".": {
       "node": {
-        "import": "./node.js",
-        "require": "./node.cjs"
+        "import": {
+          "types": "./types/node.d.ts",
+          "default": "./node.js"
+        },
+        "require": {
+          "types": "./types/node.d.cts",
+          "default": "./node.cjs"
+        }
       },
-      "browser": "./browser.js",
-      "default": "./browser.js"
+      "browser": {
+        "types": "./types/browser.d.ts",
+        "default": "./browser.js"
+      },
+      "default": {
+        "types": "./types/browser.d.ts",
+        "default": "./browser.js"
+      }
     },
     "./node": {
-      "import": "./node.js",
-      "require": "./node.cjs"
-    },
-    "./browser": "./browser.js",
-    "./wasm": "./fx-sdk.js",
-    "./mcp": "./mcp.js",
-    "./skills": "./skills.js",
-    "./skills/node": "./skills-node.js"
+      "import": {
+        "types": "./types/node.d.ts",
+        "default": "./node.js"
+      },
+      "require": {
+        "types": "./types/node.d.cts",
+        "default": "./node.cjs"
+      }
+    },
+    "./browser": {
+      "types": "./types/browser.d.ts",
+      "default": "./browser.js"
+    },
+    "./wasm": {
+      "types": "./types/wasm.d.ts",
+      "default": "./fx-sdk.js"
+    },
+    "./durable-local": {
+      "types": "./types/durable-local.d.ts",
+      "default": "./durable/local.mjs"
+    },
+    "./durable-vercel": {
+      "types": "./types/durable-vercel.d.ts",
+      "default": "./durable/vercel.mjs"
+    },
+    "./durable-world": {
+      "types": "./types/durable-world.d.ts",
+      "default": "./durable/world.mjs"
+    },
+    "./chatgpt": {
+      "types": "./types/chatgpt.d.ts",
+      "default": "./chatgpt-sign-in.js"
+    },
+    "./grok": {
+      "types": "./types/grok.d.ts",
+      "default": "./grok-sign-in.js"
+    },
+    "./mcp": {
+      "types": "./types/mcp.d.ts",
+      "default": "./mcp.js"
+    },
+    "./skills": {
+      "types": "./types/skills.d.ts",
+      "default": "./skills.js"
+    },
+    "./skills/node": {
+      "types": "./types/skills-node.d.ts",
+      "default": "./skills-node.js"
+    }
   },
   "engines": {
     "node": ">=20"