libfx 0.0.7-dev.632.g9fe8a30c19a7 → 0.0.8-dev.820.g1d9d3b63d6ea

package/node.js

@@ -1,8 +1,12 @@
 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 { 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 {
   createFxAgent as createWasmAgent,
   createFxTerminal as createWasmTerminal,
@@ -15,21 +19,29 @@ import {
 
 export { encodeXtermKeyEvent, fxSdkApiVersion, listModels, supportsJspi, xtermAdapter };
 export const libfxApiVersion = 2;
+const nativeCoreApiVersion = 3;
 
 const fetchOperationStale = 0;
 const fetchOperationApplied = 1;
 const fetchOperationBackpressure = 2;
 
-const require = createRequire(import.meta.url);
+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);
-const defaultNativeCandidates = [
-  "./libfx.node",
-  `./libfx.${process.platform}-${process.arch}.node`,
-];
 let nativeBackendPromise;
 const wasmFilePromises = new Map();
 
+const backendReasonCodes = {
+  unsupportedPlatform: "LIBFX_UNSUPPORTED_PLATFORM",
+  missingArtifact: "LIBFX_NATIVE_ARTIFACT_MISSING",
+  nativeLoad: "LIBFX_NATIVE_LOAD_FAILED",
+  nativeApi: "LIBFX_NATIVE_API_MISMATCH",
+  missingSurface: "LIBFX_NATIVE_SURFACE_MISSING",
+  disabledNative: "LIBFX_NATIVE_DISABLED",
+  jspiUnavailable: "LIBFX_JSPI_UNAVAILABLE",
+  wasmLoad: "LIBFX_WASM_LOAD_FAILED",
+};
+
 function jspiFallbackError(surface, nativeError) {
   const nativeDetail = nativeError ? ` Native loading failed: ${nativeError.message}.` : " No compatible native addon was found.";
   const error = new Error(
@@ -46,7 +58,8 @@ async function loadNativeCandidate(candidate) {
   if (candidate == null) return null;
   if (candidate instanceof URL) {
     if (candidate.protocol === "file:" && candidate.pathname.endsWith(".node")) {
-      return require(fileURLToPath(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);
     return imported.default ?? imported;
@@ -55,18 +68,36 @@ async function loadNativeCandidate(candidate) {
   if (typeof candidate !== "string") {
     throw new TypeError("nativeAddon must be a module, path, URL, false, or undefined");
   }
-  if (candidate.endsWith(".node")) return require(isAbsolute(candidate) ? candidate : resolve(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);
   return imported.default ?? imported;
 }
 
+function defaultNativeCandidate() {
+  if (process.platform === "linux" && process.arch === "x64") {
+    return new URL("./libfx.linux-x64.node", import.meta.url);
+  }
+  if (process.platform === "linux" && process.arch === "arm64") {
+    return new URL("./libfx.linux-arm64.node", import.meta.url);
+  }
+  if (process.platform === "darwin" && process.arch === "x64") {
+    return new URL("./libfx.darwin-x64.node", import.meta.url);
+  }
+  if (process.platform === "darwin" && process.arch === "arm64") {
+    return new URL("./libfx.darwin-arm64.node", import.meta.url);
+  }
+  return null;
+}
+
 function validateNativeBackend(backend) {
   if (!backend) return null;
   const hasLowLevelCore = typeof backend.createCore === "function";
-  if ((hasLowLevelCore && backend.libfxApiVersion !== libfxApiVersion) ||
-    (!hasLowLevelCore && backend.libfxApiVersion !== undefined && backend.libfxApiVersion !== libfxApiVersion)) {
+  const expectedVersion = hasLowLevelCore ? nativeCoreApiVersion : libfxApiVersion;
+  if ((hasLowLevelCore || backend.libfxApiVersion !== undefined) && backend.libfxApiVersion !== expectedVersion) {
     const actualVersion = backend.libfxApiVersion ?? "missing";
-    throw new Error(`native addon API version ${actualVersion} is incompatible with libfx API version ${libfxApiVersion}`);
+    throw new Error(`native addon API version ${actualVersion} is incompatible with expected API version ${expectedVersion}`);
   }
   if (typeof backend.createCore !== "function" && typeof backend.createFxTerminal !== "function") {
     throw new Error("native addon must export createCore() or createFxTerminal()");
@@ -74,52 +105,217 @@ function validateNativeBackend(backend) {
   return backend;
 }
 
+function missingArtifact(error) {
+  return error?.code === "ENOENT" || error?.code === "MODULE_NOT_FOUND" || error?.code === "ERR_MODULE_NOT_FOUND";
+}
+
+function nativeCandidateFilePath(candidate) {
+  if (candidate instanceof URL) return candidate.protocol === "file:" ? fileURLToPath(candidate) : null;
+  if (typeof candidate !== "string") return null;
+  if (candidate.startsWith("file:")) return fileURLToPath(new URL(candidate));
+  return URL.canParse(candidate) ? null : resolve(candidate);
+}
+
+async function nativeArtifactMissing(candidate) {
+  try {
+    const path = nativeCandidateFilePath(candidate);
+    if (path === null) return false;
+    await access(path);
+    return false;
+  } catch (error) {
+    return missingArtifact(error);
+  }
+}
+
+function validationFailure(error) {
+  return error?.message?.startsWith("native addon API version ") ? "api" : "surface";
+}
+
+async function loadAndValidateNativeCandidate(candidate, artifactMissing = false) {
+  let backend;
+  try {
+    backend = await loadNativeCandidate(candidate);
+  } catch (error) {
+    return { backend: null, error, failure: artifactMissing ? "missing" : "load" };
+  }
+  try {
+    return { backend: validateNativeBackend(backend), error: null, failure: null };
+  } catch (error) {
+    return { backend: null, error, failure: validationFailure(error) };
+  }
+}
+
 async function discoverNativeBackend() {
-  for (const relativePath of defaultNativeCandidates) {
-    const url = new URL(relativePath, import.meta.url);
-    try {
-      await access(fileURLToPath(url));
-    } catch (error) {
-      if (error?.code === "ENOENT") continue;
-      return { backend: null, error };
-    }
-    try {
-      return { backend: validateNativeBackend(await loadNativeCandidate(url)), error: null };
-    } catch (error) {
-      return { backend: null, error };
+  const candidate = defaultNativeCandidate();
+  if (!candidate) {
+    return { backend: null, error: null, failure: "unsupported" };
+  }
+  try {
+    await access(fileURLToPath(candidate));
+  } catch (error) {
+    if (missingArtifact(error)) {
+      return { backend: null, error: null, probeError: error, failure: "missing" };
     }
+    return { backend: null, error, failure: "load" };
   }
-  return { backend: null, error: null };
+  return loadAndValidateNativeCandidate(candidate);
 }
 
 async function resolveNativeBackend(nativeAddon) {
-  if (nativeAddon === false) return { backend: null, error: null };
+  if (nativeAddon === false) return { backend: null, error: null, failure: "disabled" };
   if (nativeAddon !== undefined) {
-    try {
-      return { backend: validateNativeBackend(await loadNativeCandidate(nativeAddon)), error: null };
-    } catch (error) {
-      return { backend: null, error };
-    }
+    return loadAndValidateNativeCandidate(nativeAddon, await nativeArtifactMissing(nativeAddon));
   }
   nativeBackendPromise ??= discoverNativeBackend();
   return nativeBackendPromise;
 }
 
-function wasmBytes(input) {
-  let path;
-  if (input instanceof URL && input.protocol === "file:") path = fileURLToPath(input);
-  else if (typeof input === "string" && !URL.canParse(input)) path = resolve(input);
-  else return input;
+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 pending = readFile(path);
+  const pendingRead = readFile(path);
+  let pending;
+  pending = withModuleFailure(pendingRead, () => {
+    if (wasmFilePromises.get(path) === pending) wasmFilePromises.delete(path);
+  });
   wasmFilePromises.set(path, pending);
-  pending.catch(() => {
+  pendingRead.catch(() => {
     if (wasmFilePromises.get(path) === pending) wasmFilePromises.delete(path);
   });
   return pending;
 }
 
+function wasmFilePath(input) {
+  if (input instanceof URL && 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 {
+    code,
+    message,
+    ...(typeof causeCode === "string" || typeof causeCode === "number" ? { causeCode } : {}),
+  };
+}
+
+function nativeFailureReason(result) {
+  const detailError = result.probeError ?? result.error;
+  switch (result.failure) {
+    case "unsupported":
+      return reason(
+        backendReasonCodes.unsupportedPlatform,
+        `native addon is not available for ${process.platform}-${process.arch}`,
+      );
+    case "missing":
+      return reason(
+        backendReasonCodes.missingArtifact,
+        `native addon artifact was not found${detailError?.message ? `: ${detailError.message}` : ""}`,
+        detailError,
+      );
+    case "load":
+      return reason(
+        backendReasonCodes.nativeLoad,
+        `native addon failed to load${result.error?.message ? `: ${result.error.message}` : ""}`,
+        result.error,
+      );
+    case "api":
+      return reason(backendReasonCodes.nativeApi, result.error.message, result.error);
+    case "surface":
+      return reason(backendReasonCodes.missingSurface, result.error.message, result.error);
+    case "disabled":
+      return reason(backendReasonCodes.disabledNative, "native addon loading is disabled");
+    default:
+      return reason(backendReasonCodes.nativeLoad, "native addon is unavailable", result.error);
+  }
+}
+
+function validateBackendInfoOptions(value) {
+  if (!value || typeof value !== "object" || Array.isArray(value)) {
+    throw new TypeError("getBackendInfo() options must be an object");
+  }
+  const options = { ...value };
+  for (const key of Object.keys(options)) {
+    if (!new Set(["surface", "backend", "nativeAddon", "wasm"]).has(key)) {
+      throw new TypeError(`getBackendInfo() does not accept ${key}`);
+    }
+  }
+  const surface = options.surface ?? "agent";
+  if (!new Set(["agent", "terminal"]).has(surface)) {
+    throw new TypeError('surface must be "agent" or "terminal"');
+  }
+  const backend = options.backend ?? "auto";
+  if (!new Set(["auto", "native", "wasm"]).has(backend)) {
+    throw new TypeError('backend must be "auto", "native", or "wasm"');
+  }
+  if (Object.hasOwn(options, "nativeAddon") && options.nativeAddon !== undefined && options.nativeAddon !== false &&
+    typeof options.nativeAddon !== "string" && !(options.nativeAddon instanceof URL) &&
+    (typeof options.nativeAddon !== "object" || options.nativeAddon === null)) {
+    throw new TypeError("nativeAddon must be a module, path, URL, false, or undefined");
+  }
+  const validWasm = options.wasm === undefined || typeof options.wasm === "string" || options.wasm instanceof URL ||
+    options.wasm instanceof Promise || options.wasm instanceof WebAssembly.Module || options.wasm instanceof Response ||
+    options.wasm instanceof ArrayBuffer || ArrayBuffer.isView(options.wasm);
+  if (Object.hasOwn(options, "wasm") && !validWasm) {
+    throw new TypeError("wasm must be a URL, Response, ArrayBuffer, typed array, or WebAssembly.Module");
+  }
+  return { ...options, surface, backend };
+}
+
+export async function getBackendInfo(value = {}) {
+  const { surface, backend, nativeAddon, wasm } = validateBackendInfoOptions(value);
+  const attempts = [];
+  if (backend !== "wasm") {
+    const native = await resolveNativeBackend(nativeAddon);
+    const nativeMethod = surface === "agent" ? "createCore" : "createFxTerminal";
+    if (typeof native.backend?.[nativeMethod] === "function") {
+      attempts.push({ backend: "native", available: true, reason: null });
+      return { surface, backend: "native", attempts };
+    }
+    const failureReason = native.backend
+      ? reason(backendReasonCodes.missingSurface, `native addon does not provide ${nativeMethod}()`)
+      : nativeFailureReason(native);
+    attempts.push({ backend: "native", available: false, reason: failureReason });
+    if (backend === "native") return { surface, backend: "unavailable", attempts };
+  }
+
+  if (!supportsJspi()) {
+    attempts.push({
+      backend: "wasm-jspi",
+      available: false,
+      reason: reason(
+        backendReasonCodes.jspiUnavailable,
+        "WebAssembly backend requires JavaScript Promise Integration (JSPI)",
+      ),
+    });
+    return { surface, backend: "unavailable", attempts };
+  }
+  const defaultWasm = surface === "agent" ? defaultCoreWasm : defaultTermWasm;
+  const wasmSource = wasm ?? defaultWasm;
+  try {
+    await loadModule(wasmInput(wasmSource));
+    attempts.push({ backend: "wasm-jspi", available: true, reason: null });
+    return { surface, backend: "wasm-jspi", attempts };
+  } catch (error) {
+    attempts.push({
+      backend: "wasm-jspi",
+      available: false,
+      reason: reason(
+        backendReasonCodes.wasmLoad,
+        `WebAssembly asset failed to load or compile: ${error?.message ?? String(error)}`,
+        error,
+      ),
+    });
+    return { surface, backend: "unavailable", attempts };
+  }
+}
+
 function createNativeCoreRuntime(addon, options) {
   const { apiKey, model, gatewayChatUrl } = options;
   const core = addon.createCore({
@@ -129,9 +325,24 @@ function createNativeCoreRuntime(addon, options) {
     ...(model === undefined ? {} : { model }),
     ...(gatewayChatUrl === undefined ? {} : { gatewayChatUrl }),
   });
+  let readyFd;
+  let readySocket;
+  try {
+    readyFd = addon.takeCoreReadyFd(core);
+    readySocket = new Socket({ fd: readyFd, readable: true, writable: false });
+  } catch (error) {
+    if (readyFd !== undefined) {
+      try { closeSync(readyFd); } catch {}
+    }
+    addon.destroyCore(core);
+    throw error;
+  }
+  const readyClosed = new Promise((resolve) => readySocket.once("close", resolve));
   let exitedResolve;
   let lineHandler = null;
-  let lineBuffer = "";
+  const output = new CoreOutput((message, size) => lineHandler(message, size));
+  let draining = false;
+  let outputError;
   let settled = false;
   let fetchState = null;
   const exited = new Promise((resolve) => { exitedResolve = resolve; });
@@ -139,13 +350,15 @@ function createNativeCoreRuntime(addon, options) {
     fetchState?.controller.abort();
     try { addon.abortCoreFetch(core); } catch {}
   };
-  const finish = (code) => {
+  const finish = (code, error) => {
     if (settled) return;
     settled = true;
-    clearInterval(timer);
+    outputError = error;
+    output.close();
     abortHostEffects();
     try { addon.destroyCore(core); } catch {}
-    exitedResolve(code);
+    readySocket.destroy();
+    void readyClosed.then(() => exitedResolve(code));
   };
   const pumpFetch = async (request) => {
     const controller = new AbortController();
@@ -189,10 +402,14 @@ function createNativeCoreRuntime(addon, options) {
         } catch {}
       }
     } finally {
-      if (fetchState === state) fetchState = null;
+      if (fetchState === state) {
+        fetchState = null;
+        queueMicrotask(drainReady);
+      }
     }
   };
-  const timer = setInterval(() => {
+  function drainReady() {
+    if (settled) return;
     try {
       if (fetchState) {
         if (!fetchState.controller.signal.aborted && !addon.coreFetchActive(core, fetchState.handle)) {
@@ -202,29 +419,55 @@ function createNativeCoreRuntime(addon, options) {
         const fetchRequest = addon.takeCoreFetch(core);
         if (fetchRequest) void pumpFetch(JSON.parse(fetchRequest.toString("utf8")));
       }
-      const chunk = addon.drainCore(core);
-      if (chunk.length && lineHandler) {
-        lineBuffer += chunk.toString("utf8");
-        for (;;) {
-          const newline = lineBuffer.indexOf("\n");
-          if (newline < 0) break;
-          const line = lineBuffer.slice(0, newline);
-          lineBuffer = lineBuffer.slice(newline + 1);
-          if (line) void Promise.resolve(lineHandler(JSON.parse(line))).catch(() => finish(1));
-        }
+      if (addon.coreExitCode(core) !== 0) {
+        finish(1, new Error("native output delivery failed"));
+        return;
+      }
+      void drainOutput();
+    } catch (error) {
+      finish(1, error);
+    }
+  }
+  async function drainOutput() {
+    if (draining || settled) return;
+    draining = true;
+    try {
+      while (!settled) {
+        const chunk = addon.drainCore(core);
+        if (!chunk.length) break;
+        const pending = output.write(chunk);
+        if (pending) await pending;
+      }
+      if (!settled && addon.coreExited(core)) {
+        output.finish();
+        finish(addon.coreExitCode(core));
       }
-      if (addon.coreExited(core)) finish(addon.coreExitCode(core));
-    } catch {
-      finish(1);
+    } catch (error) {
+      finish(1, error);
+    } finally {
+      draining = false;
     }
-  }, 2);
+  }
+
+  readySocket.on("data", drainReady);
+  readySocket.on("end", () => { drainReady(); if (!settled) finish(1); });
+  readySocket.on("error", () => finish(1));
+  readySocket.on("close", () => { if (!settled) finish(1); });
+  // Some runtimes defer descriptor adoption until connect().
+  if (readySocket.pending) {
+    try { readySocket.connect({ fd: readyFd }); } catch (error) { finish(1); throw error; }
+  }
 
   return {
     exited,
+    get error() { return outputError; },
     write(data) { addon.writeCore(core, Buffer.from(data)); },
     closeStdin() { addon.closeCore(core); },
     abortHostEffects,
-    abort() { abortHostEffects(); addon.closeCore(core); },
+    abort(error) {
+      if (error) finish(1, error);
+      else { abortHostEffects(); addon.closeCore(core); }
+    },
     setLineHandler(handler) { lineHandler = handler; },
   };
 }
@@ -270,10 +513,8 @@ async function createWithFallback(surface, nativeMethod, wasmFactory, defaultWas
     if (nativeAttempted) throw nativeError;
     throw jspiFallbackError(surface, nativeError);
   }
-  return wasmFactory({
-    ...runtimeOptions,
-    wasm: await wasmBytes(runtimeOptions.wasm ?? defaultWasm),
-  });
+  const wasmSource = runtimeOptions.wasm ?? defaultWasm;
+  return wasmFactory({ ...runtimeOptions, wasm: wasmInput(wasmSource) });
 }
 
 export async function createFxAgent(options = {}) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "libfx",
-  "version": "0.0.7-dev.632.g9fe8a30c19a7",
+  "version": "0.0.8-dev.820.g1d9d3b63d6ea",
   "description": "Embed fx agents and terminals in JavaScript hosts",
   "type": "module",
   "repository": {
@@ -17,11 +17,17 @@
   },
   "exports": {
     ".": {
-      "node": "./node.js",
+      "node": {
+        "import": "./node.js",
+        "require": "./node.cjs"
+      },
       "browser": "./browser.js",
       "default": "./browser.js"
     },
-    "./node": "./node.js",
+    "./node": {
+      "import": "./node.js",
+      "require": "./node.cjs"
+    },
     "./browser": "./browser.js",
     "./wasm": "./fx-sdk.js",
     "./mcp": "./mcp.js",

package/wasm-module.js

@@ -0,0 +1,50 @@
+const modulePromisesBySource = new Map();
+const modulePromisesByObject = new WeakMap();
+const moduleFailureSource = Symbol("libfx.moduleFailureSource");
+
+export function withModuleFailure(input, onFailure) {
+  return { [moduleFailureSource]: { input, onFailure } };
+}
+
+async function compileModule(input) {
+  const failureSource = input?.[moduleFailureSource];
+  if (failureSource) {
+    try {
+      return await compileModule(failureSource.input);
+    } catch (error) {
+      failureSource.onFailure();
+      throw error;
+    }
+  }
+  if (input instanceof WebAssembly.Module) return input;
+  if (typeof input === "string") input = fetch(input);
+  if (input instanceof Promise) input = await input;
+  if (input instanceof WebAssembly.Module) return input;
+  if (input instanceof Response) {
+    const contentType = input.headers.get("content-type")?.split(";", 1)[0].trim().toLowerCase();
+    if (contentType === "application/wasm" && typeof WebAssembly.compileStreaming === "function") {
+      return WebAssembly.compileStreaming(input);
+    }
+    const bytes = await input.arrayBuffer();
+    return WebAssembly.compile(bytes);
+  }
+  if (input instanceof ArrayBuffer || ArrayBuffer.isView(input)) {
+    return WebAssembly.compile(input);
+  }
+  throw new TypeError("wasm must be a URL, Response, ArrayBuffer, typed array, or WebAssembly.Module");
+}
+
+export function loadModule(input) {
+  if (input instanceof WebAssembly.Module) return Promise.resolve(input);
+  const isString = typeof input === "string";
+  if (!isString && (typeof input !== "object" || input === null)) return compileModule(input);
+  const cache = isString ? modulePromisesBySource : modulePromisesByObject;
+  const cached = cache.get(input);
+  if (cached) return cached;
+  const pending = compileModule(input);
+  cache.set(input, pending);
+  pending.catch(() => {
+    if (cache.get(input) === pending) cache.delete(input);
+  });
+  return pending;
+}