libfx 0.0.15 → 0.0.17

package/node.js

@@ -1,28 +1,26 @@
-import { access, readFile } from "node:fs/promises";
+import { access } from "node:fs/promises";
 import { closeSync } from "node:fs";
 import { createRequire } from "node:module";
 import { Socket } from "node:net";
 import { homedir, tmpdir } from "node:os";
 import { isAbsolute, resolve } from "node:path";
 import { fileURLToPath, pathToFileURL } from "node:url";
+import { bundledAssetUrl } from "./bundled-asset.js";
 import { CoreOutput } from "./core-output.js";
-import { loadModule, withModuleFailure } from "./wasm-module.js";
-import { fetchCleanupAction, cleanupTimeoutMs, cleanupByteLimit } from "./fetch-cleanup.js";
+import { fetchCleanupAction, cleanupTimeoutMs, cleanupByteLimit, retryAfterSeconds } from "./fetch-cleanup.js";
 import { createDurableAgentFactory, memory, wakeHandler } from "./durable.js";
 import { fxHarness } from "./fx-harness.js";
 import {
-  createFxEngine as createWasmAgent,
-  createFxTerminal as createWasmTerminal,
+  createFxEngine as createEngine,
   createMemoryPersistence,
   FxFencedError,
   FxJournalVersionError,
-  encodeXtermKeyEvent,
   fxSdkApiVersion,
   listModels,
   normalizeAgentOptions,
   supportsJspi,
-  xtermAdapter,
-} from "./fx-sdk.js";
+} from "./engine.js";
+import { encodeXtermKeyEvent, xtermAdapter } from "./xterm.js";
 
 export { createMemoryPersistence, encodeXtermKeyEvent, FxFencedError, FxJournalVersionError, fxSdkApiVersion, listModels, memory, supportsJspi, wakeHandler, xtermAdapter };
 export const libfxApiVersion = 3;
@@ -33,10 +31,7 @@ const fetchOperationApplied = 1;
 const fetchOperationBackpressure = 2;
 
 const nodeRequire = createRequire(import.meta.url);
-const defaultCoreWasm = new URL("./fx-core.wasm", import.meta.url);
-const defaultTermWasm = new URL("./fx-term.wasm", import.meta.url);
 let nativeBackendPromise;
-const wasmFilePromises = new Map();
 
 const backendReasonCodes = {
   unsupportedPlatform: "LIBFX_UNSUPPORTED_PLATFORM",
@@ -49,25 +44,24 @@ const backendReasonCodes = {
   wasmLoad: "LIBFX_WASM_LOAD_FAILED",
 };
 
-function bundledAssetUrl(asset) {
-  if (asset.protocol !== "" || typeof asset.href !== "string" ||
-      typeof __webpack_base_uri__ === "undefined" || typeof __webpack_public_path__ !== "string" ||
-      !asset.href.startsWith(__webpack_public_path__)) {
-    throw new TypeError("Bundled asset URL has no filesystem mapping");
-  }
-  // Webpack's relative URL is a public asset address, not a Node URL instance.
-  return new URL(asset.href.slice(__webpack_public_path__.length), __webpack_base_uri__);
+function sentence(message) {
+  return `${message[0].toUpperCase()}${message.slice(1)}.`;
 }
 
-function jspiFallbackError(surface, nativeError) {
-  const nativeDetail = nativeError ? ` Native loading failed: ${nativeError.message}.` : " No compatible native addon was found.";
+function jspiFallbackError(surface, native, nativeError) {
+  const missingPackage = !nativeError && native?.failure === "missing" ? native.nativePackage : undefined;
+  const nativeDetail = nativeError ? ` Native loading failed: ${nativeError.message}.`
+    : missingPackage ? ` ${sentence(nativeFailureReason(native).message)}`
+    : " No compatible native addon was found.";
+  const remedy = missingPackage
+    ? `Install ${missingPackage}, which libfx lists as an optional dependency, or run Node with --experimental-wasm-jspi.`
+    : "Run Node with --experimental-wasm-jspi or install a libfx package containing a compatible native addon.";
   const error = new Error(
     `libfx could not start the ${surface} backend.${nativeDetail} ` +
-    "The WebAssembly fallback requires JavaScript Promise Integration (JSPI). " +
-    "Run Node with --experimental-wasm-jspi or install a libfx package containing a compatible native addon.",
+    `The WebAssembly fallback requires JavaScript Promise Integration (JSPI). ${remedy}`,
   );
   error.code = "LIBFX_JSPI_REQUIRED";
-  error.cause = nativeError;
+  error.cause = nativeError ?? native?.probeError;
   return error;
 }
 
@@ -79,7 +73,8 @@ async function loadNativeCandidate(candidate) {
       // Bundlers trace the asset URL; Node must load the native file at runtime.
       return Reflect.apply(nodeRequire, undefined, [fileURLToPath(candidate)]);
     }
-    const imported = await import(candidate.href);
+    // A module the caller names is its own file, which Node loads as is.
+    const imported = await import(/* webpackIgnore: true */ /* turbopackIgnore: true */ candidate.href);
     return imported.default ?? imported;
   }
   if (typeof candidate === "object") return candidate.default ?? candidate;
@@ -89,37 +84,54 @@ async function loadNativeCandidate(candidate) {
   if (candidate.endsWith(".node")) {
     return Reflect.apply(nodeRequire, undefined, [isAbsolute(candidate) ? candidate : resolve(candidate)]);
   }
-  const imported = await import(candidate.startsWith("file:") ? candidate : pathToFileURL(candidate).href);
+  const imported = await import(/* webpackIgnore: true */ /* turbopackIgnore: true */ candidate.startsWith("file:") ? candidate : pathToFileURL(candidate).href);
   return imported.default ?? imported;
 }
 
-function defaultNativeCandidate() {
-  // Local path bindings let deployment tracers retain these assets in the generated CommonJS entry.
-  if (process.platform === "linux" && process.arch === "x64") {
-    const asset = new URL("./libfx.linux-x64.node", import.meta.url);
-    if (asset.protocol === "") return fileURLToPath(bundledAssetUrl(asset));
-    const path = fileURLToPath(asset);
-    return path;
-  }
-  if (process.platform === "linux" && process.arch === "arm64") {
-    const asset = new URL("./libfx.linux-arm64.node", import.meta.url);
-    if (asset.protocol === "") return fileURLToPath(bundledAssetUrl(asset));
-    const path = fileURLToPath(asset);
-    return path;
-  }
-  if (process.platform === "darwin" && process.arch === "x64") {
-    const asset = new URL("./libfx.darwin-x64.node", import.meta.url);
-    if (asset.protocol === "") return fileURLToPath(bundledAssetUrl(asset));
-    const path = fileURLToPath(asset);
-    return path;
-  }
-  if (process.platform === "darwin" && process.arch === "arm64") {
-    const asset = new URL("./libfx.darwin-arm64.node", import.meta.url);
-    if (asset.protocol === "") return fileURLToPath(bundledAssetUrl(asset));
-    const path = fileURLToPath(asset);
-    return path;
-  }
-  return null;
+// Each platform's addon ships in a package of its own, which libfx lists as
+// an optional dependency, so a package manager installs only the one for its
+// machine. The package's index.js names the addon with a literal
+// `new URL("./libfx.node", import.meta.url)`, so a bundler that bundles
+// libfx copies that one addon and traces it.
+const nativePackages = {
+  "darwin-arm64": "@libfx/libfx-darwin-arm64",
+  "darwin-x64": "@libfx/libfx-darwin-x64",
+  "linux-arm64": "@libfx/libfx-linux-arm64-gnu",
+  "linux-x64": "@libfx/libfx-linux-x64-gnu",
+};
+
+// Each specifier is a literal, so Node, Turbopack, and file tracers find the
+// installed package. A missing one fails here at run time, and inside `try`
+// it does not fail a Turbopack build. webpack folds the `typeof` test and
+// sees only a context over the platform packages that are installed, so it
+// does not warn about the ones that are missing.
+async function importNativePackage(name) {
+  try {
+    if (typeof __webpack_require__ === "function") {
+      return await import(
+        /* webpackInclude: /[\\/]libfx-(darwin|linux)-[a-z0-9-]+[\\/]index\.js$/ */
+        `@libfx/libfx-${name.slice("@libfx/libfx-".length)}`
+      );
+    } else {
+      if (name === "@libfx/libfx-darwin-arm64") return await import("@libfx/libfx-darwin-arm64");
+      if (name === "@libfx/libfx-darwin-x64") return await import("@libfx/libfx-darwin-x64");
+      if (name === "@libfx/libfx-linux-arm64-gnu") return await import("@libfx/libfx-linux-arm64-gnu");
+      if (name === "@libfx/libfx-linux-x64-gnu") return await import("@libfx/libfx-linux-x64-gnu");
+    }
+  } catch (error) {
+    return { error };
+  }
+  return { error: new Error(`${name} is not a libfx native addon package`) };
+}
+
+// The path of the addon the platform package names, or the error that kept
+// the package from loading.
+async function defaultNativeCandidate(name) {
+  const imported = await importNativePackage(name);
+  if (imported.error) return imported;
+  const asset = imported.default;
+  if (!(asset instanceof URL)) return { error: new TypeError(`${name} does not export its addon's URL`) };
+  return { candidate: fileURLToPath(asset.protocol === "" ? bundledAssetUrl(asset) : asset) };
 }
 
 function validateNativeBackend(backend) {
@@ -180,10 +192,17 @@ async function loadAndValidateNativeCandidate(candidate, artifactMissing = false
 }
 
 async function discoverNativeBackend() {
-  const candidate = defaultNativeCandidate();
-  if (!candidate) {
+  const nativePackage = nativePackages[`${process.platform}-${process.arch}`];
+  if (!nativePackage) {
     return { backend: null, error: null, failure: "unsupported" };
   }
+  // The package's index.js only names its addon, so a package that cannot be
+  // found is not installed or not part of the bundle.
+  const { candidate, error: packageError } = await defaultNativeCandidate(nativePackage);
+  if (packageError) {
+    if (missingArtifact(packageError)) return { backend: null, error: null, probeError: packageError, failure: "missing", nativePackage };
+    return { backend: null, error: packageError, failure: "load" };
+  }
   try {
     await access(candidate);
   } catch (error) {
@@ -204,35 +223,6 @@ async function resolveNativeBackend(nativeAddon) {
   return nativeBackendPromise;
 }
 
-function wasmInput(input) {
-  const path = wasmFilePath(input);
-  if (path === null) {
-    if (input instanceof URL) return input.href;
-    return input;
-  }
-  const cached = wasmFilePromises.get(path);
-  if (cached) return cached;
-  const pendingRead = readFile(path);
-  let pending;
-  pending = withModuleFailure(pendingRead, () => {
-    if (wasmFilePromises.get(path) === pending) wasmFilePromises.delete(path);
-  });
-  wasmFilePromises.set(path, pending);
-  pendingRead.catch(() => {
-    if (wasmFilePromises.get(path) === pending) wasmFilePromises.delete(path);
-  });
-  return pending;
-}
-
-function wasmFilePath(input) {
-  if (input instanceof URL) {
-    if (input.protocol === "") input = bundledAssetUrl(input);
-    if (input.protocol === "file:") return fileURLToPath(input);
-  }
-  if (typeof input === "string" && !URL.canParse(input)) return resolve(input);
-  return null;
-}
-
 function reason(code, message, error) {
   const causeCode = error?.code;
   return {
@@ -253,7 +243,9 @@ function nativeFailureReason(result) {
     case "missing":
       return reason(
         backendReasonCodes.missingArtifact,
-        `native addon artifact was not found${detailError?.message ? `: ${detailError.message}` : ""}`,
+        result.nativePackage
+          ? `the native addon package ${result.nativePackage} for ${process.platform}-${process.arch} is not installed`
+          : `native addon artifact was not found${detailError?.message ? `: ${detailError.message}` : ""}`,
         detailError,
       );
     case "load":
@@ -326,15 +318,14 @@ export async function getBackendInfo(value = {}) {
       available: false,
       reason: reason(
         backendReasonCodes.jspiUnavailable,
-        "WebAssembly backend requires JavaScript Promise Integration (JSPI)",
+        "WebAssembly backend requires JavaScript Promise Integration (JSPI); run Node with --experimental-wasm-jspi",
       ),
     });
     return { surface, backend: "unavailable", attempts };
   }
-  const defaultWasm = surface === "agent" ? defaultCoreWasm : defaultTermWasm;
-  const wasmSource = wasm ?? defaultWasm;
   try {
-    await loadModule(await wasmInput(wasmSource));
+    const { probeWasm } = await import("./node-wasm.js");
+    await probeWasm(surface, wasm);
     attempts.push({ backend: "wasm-jspi", available: true, reason: null });
     return { surface, backend: "wasm-jspi", attempts };
   } catch (error) {
@@ -480,7 +471,11 @@ function createNativeCoreRuntime(addon, options) {
       });
       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);
+      const started = settled
+        ? fetchOperationStale
+        : typeof addon.startCoreFetchResponseWithRetryAfter === "function"
+          ? addon.startCoreFetchResponseWithRetryAfter(core, state.handle, response.status, retryAfterSeconds(response.headers))
+          : 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();
@@ -610,7 +605,7 @@ function createNativeCoreRuntime(addon, options) {
 }
 
 function createNativeAgent(addon, options) {
-  return createWasmAgent({
+  return createEngine({
     ...options,
     runtimeFactory(runtimeOptions) {
       return createNativeCoreRuntime(addon, runtimeOptions);
@@ -618,17 +613,18 @@ function createNativeAgent(addon, options) {
   });
 }
 
-async function createWithFallback(surface, nativeMethod, wasmFactory, defaultWasm, options) {
+async function createWithFallback(surface, nativeMethod, options) {
   const { nativeAddon, backend = "auto", ...unvalidatedOptions } = options ?? {};
   if (!new Set(["auto", "native", "wasm"]).has(backend)) {
     throw new TypeError('backend must be "auto", "native", or "wasm"');
   }
   const runtimeOptions = surface === "agent" ? normalizeAgentOptions(unvalidatedOptions) : unvalidatedOptions;
 
+  let native = null;
   let nativeError;
   let nativeAttempted = false;
   if (backend !== "wasm") {
-    const native = await resolveNativeBackend(nativeAddon);
+    native = await resolveNativeBackend(nativeAddon);
     nativeError = native.error;
     if (typeof native.backend?.[nativeMethod] === "function") {
       nativeAttempted = true;
@@ -643,7 +639,12 @@ async function createWithFallback(surface, nativeMethod, wasmFactory, defaultWas
       }
     }
     if (backend === "native") {
-      const error = nativeError ?? new Error(`native addon does not provide ${nativeMethod}()`);
+      const missingPackage = native.failure === "missing" ? native.nativePackage : undefined;
+      const error = nativeError ?? new Error(native.backend
+        ? `native addon does not provide ${nativeMethod}()`
+        : missingPackage
+          ? `${sentence(nativeFailureReason(native).message)} Install ${missingPackage}, which libfx lists as an optional dependency.`
+          : nativeFailureReason(native).message, native.probeError ? { cause: native.probeError } : undefined);
       error.code ??= "LIBFX_NATIVE_UNAVAILABLE";
       throw error;
     }
@@ -651,10 +652,10 @@ async function createWithFallback(surface, nativeMethod, wasmFactory, defaultWas
 
   if (!supportsJspi()) {
     if (nativeAttempted) throw nativeError;
-    throw jspiFallbackError(surface, nativeError);
+    throw jspiFallbackError(surface, native, nativeError);
   }
-  const wasmSource = runtimeOptions.wasm ?? defaultWasm;
-  return wasmFactory({ ...runtimeOptions, wasm: await wasmInput(wasmSource) });
+  const wasmBackend = await import("./node-wasm.js");
+  return surface === "agent" ? wasmBackend.createWasmEngine(runtimeOptions) : wasmBackend.createWasmTerminal(runtimeOptions);
 }
 
 /**
@@ -663,13 +664,7 @@ async function createWithFallback(surface, nativeMethod, wasmFactory, defaultWas
  * runs durable sessions on these.
  */
 export async function createFxEngine(options = {}) {
-  return createWithFallback(
-    "agent",
-    "createCore",
-    createWasmAgent,
-    defaultCoreWasm,
-    options,
-  );
+  return createWithFallback("agent", "createCore", options);
 }
 
 // The durability a session gets when the caller names none: Vercel's World
@@ -723,5 +718,5 @@ export const createFxAgent = createDurableAgentFactory({
 });
 
 export function createFxTerminal(options = {}) {
-  return createWithFallback("terminal", "createFxTerminal", createWasmTerminal, defaultTermWasm, options);
+  return createWithFallback("terminal", "createFxTerminal", options);
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "libfx",
-  "version": "0.0.15",
+  "version": "0.0.17",
   "description": "Embed fx agents and terminals in JavaScript hosts",
   "type": "module",
   "repository": {
@@ -87,12 +87,19 @@
       "default": "./skills-node.js"
     }
   },
+  "sideEffects": false,
   "engines": {
-    "node": ">=20"
+    "node": "^20.19.0 || >=22.12.0"
   },
   "publishConfig": {
     "access": "public",
     "registry": "https://registry.npmjs.org/"
   },
-  "license": "Apache-2.0"
+  "license": "Apache-2.0",
+  "optionalDependencies": {
+    "@libfx/libfx-linux-x64-gnu": "0.0.17",
+    "@libfx/libfx-linux-arm64-gnu": "0.0.17",
+    "@libfx/libfx-darwin-x64": "0.0.17",
+    "@libfx/libfx-darwin-arm64": "0.0.17"
+  }
 }

package/types/libfx.d.cts

@@ -46,7 +46,7 @@ export interface FxModelOptions {
   effort?: FxEffort;
   /** Enables the fast lane for models that advertise one. */
   fast?: boolean;
-  /** Requests Ultra mode, the higher-cost service tier, for models whose metadata advertises it. Disables Fast. */
+  /** Requests Ultrafast mode, the higher-cost service tier, for models whose metadata advertises it. Disables Fast. */
   ultrafast?: boolean;
 }
 
@@ -261,8 +261,8 @@ export interface FxUsage {
   reasoningTokens?: number;
 }
 
-/** Why an engine turn ended. */
-export type FxStopReason = "end_turn" | "max_output_tokens" | "max_model_turns" | "refused" | "cancelled";
+/** Why an engine turn ended. `yielded`: it stopped at its `yieldAt` and stays open for `resume()`. */
+export type FxStopReason = "end_turn" | "max_output_tokens" | "max_model_turns" | "refused" | "cancelled" | "yielded";
 
 // ---------------------------------------------------------------------------
 // Diagnostics
@@ -304,7 +304,8 @@ export type FxEngineEvent = FxEventBase & (
   | { type: "permission.request"; request: unknown }
   | { type: "permission.resolve"; optionId: unknown }
   | { type: "journal.open"; events: number; checkpoint: boolean; turns: unknown; resumable: boolean }
-  | { type: "journal.append"; events: number }
+  /** `barrier`: the record's `barrier`, as `Persistence.append` receives it. */
+  | { type: "journal.append"; events: number; barrier: boolean }
   | { type: "journal.error"; error: string }
   | { type: "checkpoint.save"; through: string; bytes: number }
   | { type: "checkpoint.error"; error: string; message: string }
@@ -423,7 +424,7 @@ export type FxHookEvent = FxHookEnvelope & (
   | { type: "mcp.start"; data: { operationId: number | string; callId: string | null; server: string | null; tool: string; transport: string | null } }
   | { type: "mcp.request"; data: { operationId: number | string; requestId: number | string; requestIdKind: "jsonrpc" | "engine" | "correlation" } }
   | { type: "mcp.end"; data: { operationId: number | string; status: "success" | "failure" | "cancelled" | "input_required" | "unavailable" | "unknown"; error: string | null } }
-  | { type: "delegation"; data: { callId: string; childSessionId: string; workId: string; operationId: string | null; phase: "dispatched" | "completed" | "yielded" | "replayed" | "failed" | "cancelled" | "feedback_queued" | "feedback_applied" | "feedback_not_applied" } }
+  | { type: "delegation"; data: { callId: string; childSessionId: string; workId: string; operationId: string | null; phase: "dispatched" | "completed" | "replayed" | "failed" | "cancelled" | "feedback_queued" | "feedback_applied" | "feedback_not_applied" } }
   /** Emitted only after append resolves and its cursor validates. */
   | { type: "journal.commit"; data: { cursor: string; firstSeq: number | null; lastSeq: number | null; eventCount: number } }
   | { type: "journal.restore"; data: { cursor: string | null; lastSeq: number; resumable: boolean; openTurnId: string | null; lastTurnId: string | null } }
@@ -669,6 +670,12 @@ export interface FxCustomProviderModel {
   maxOutputTokens?: number;
   supportsToolUse?: boolean;
   supportsVision?: boolean;
+  /** The request field that carries the output limit. Defaults to `"max_tokens"`. */
+  outputLimitField?: "max_tokens" | "max_completion_tokens";
+  /** Fields sent in the body of every request for the model, such as `{ temperature: 0.2 }`. A field fx writes itself, such as `messages`, is refused. */
+  request?: Record<string, unknown>;
+  /** The effort levels the model offers, in order, each with the request fields that choose it, such as `{ high: { reasoning_effort: "high" } }`. A level the model does not list is not sent. */
+  reasoningEfforts?: Record<string, Record<string, unknown>>;
 }
 
 /** A server that speaks OpenAI Chat Completions, such as a local model server or a router. */
@@ -679,6 +686,12 @@ export interface FxCustomProviderDefinition {
   baseUrl: string;
   /** The models it serves, by id. */
   models?: Record<string, FxCustomProviderModel>;
+  /** Fields for every model, including one `models` does not list, where the model sets none itself. */
+  modelDefaults?: FxCustomProviderModel;
+  /** The model that names a session from its first prompt. Without it, a session keeps the title derived from the prompt. */
+  titleModel?: string;
+  /** The model that reads images for a model that cannot. Without it, the provider has no image fallback. */
+  visionModel?: string;
 }
 
 /** A custom provider's API key. */
@@ -796,8 +809,8 @@ export interface FxAccepted {
 /** How a durable turn ended. */
 export interface FxTurnResult {
   messageId: string;
-  /** `error` when the turn failed, with the reason in `error`; `unknown` when the process that ran it stopped before writing how it ended. */
-  stopReason: FxStopReason | "error" | "unknown";
+  /** `error` when the turn failed, with the reason in `error`; `unknown` when the process that ran it stopped before writing how it ended. A yielded turn continues, so it never ends `yielded`. */
+  stopReason: Exclude<FxStopReason, "yielded"> | "error" | "unknown";
   /** Absent when the result is a failure read from the session's log rather than from the turn's end. */
   usage?: FxUsage;
   error?: FxErrorSummary;
@@ -848,7 +861,7 @@ export type FxStreamLine = (
   | {
     type: "turn_end";
     messageId: string;
-    stopReason: FxStopReason | "error" | "unknown";
+    stopReason: Exclude<FxStopReason, "yielded"> | "error" | "unknown";
     usage?: FxUsage;
     error?: FxErrorSummary;
     repeated?: true;

package/types/node.d.ts

@@ -1,3 +1,3 @@
 // `libfx` and `libfx/node` on Node.js, for `import` (node.js). The CommonJS
-// entry, node.cjs, is built from node.js, so both declare the same exports.
+// entry, node.cjs, exports node.js itself, so both declare the same exports.
 export * from "./node.cjs";