libfx 0.0.8-dev.820.g1d9d3b63d6ea → 0.0.8

package/README.md

@@ -256,6 +256,11 @@ creates a separate WebAssembly instance for every Agent. Agent memory, history,
 tools, cancellation, and shutdown remain isolated. Workers and separate
 processes maintain their own module caches, as do the ESM and CommonJS entries.
 
+Node factories and `getBackendInfo()` also accept a `wasm` Promise resolving
+to an HTTP(S) URL string, a `Response`, Wasm bytes, or a compiled
+`WebAssembly.Module`. Asset resolver failures propagate from factories and
+appear as `LIBFX_WASM_LOAD_FAILED` in diagnostics.
+
 Node.js 20+ is supported. Browser WebAssembly requires a JSPI-capable browser.
 The Linux x64 and arm64 native addons require glibc 2.34 or newer. Native
 agents do not require JSPI or experimental Node flags.
@@ -268,8 +273,14 @@ JIT tier-up.
 
 Create agents in a server route using the Node.js runtime. Import `libfx`
 normally; the package includes its native assets and exposes both ESM and
-CommonJS Node entrypoints. No `serverExternalPackages` setting or manual native
-file inclusion is required.
+CommonJS Node entrypoints. Native agents support Next.js 15 with webpack and
+Next.js 16 with webpack or Turbopack, without `serverExternalPackages` or manual
+native-file inclusion. Webpack's emitted assets are resolved relative to the
+server bundle, including standalone builds with a custom `distDir` or `assetPrefix`.
+
+This native setup does not require JSPI. Explicit WebAssembly use still needs
+JSPI and available Wasm assets; Next.js's standalone tracer excludes `.wasm`
+files, so a standalone Wasm host must supply those assets separately.
 
 ```js
 import { createFxAgent } from "libfx";

package/fx-sdk.js

@@ -996,7 +996,10 @@ async function instantiate(options) {
       runtime.setInstance(null);
       if (options.args?.[0] === "acp" && !String(error).includes("proc_exit")) runtime.abort(error);
       else {
-        if (!String(error).includes("proc_exit")) console.error(error);
+        if (!String(error).includes("proc_exit")) {
+          runtime.abortHostEffects();
+          console.error(error);
+        }
         runtime.markExited(runtime.aborted ? 130 : 1);
       }
     },
@@ -1040,13 +1043,13 @@ export async function createFxTerminal(options) {
     if (interruptKey && data.includes(interruptKey)) runtime.abortHostEffects();
     runtime.write(data);
   };
-  const unsubscribeData = options.terminal.onData(forwardData);
-  const unsubscribeKeyData = options.terminal.onKeyData?.(forwardData) ?? (() => {});
   const signalResize = () => {
     emit("terminal.resize", { cols: options.terminal.cols, rows: options.terminal.rows });
     runtime.wake();
   };
-  const unsubscribeResize = options.terminal.onResize(signalResize);
+  let unsubscribeData;
+  let unsubscribeKeyData;
+  let unsubscribeResize;
   let subscriptionsReleased = false;
   const releaseSubscriptions = () => {
     if (subscriptionsReleased) return;
@@ -1059,6 +1062,17 @@ export async function createFxTerminal(options) {
     releaseSubscriptions();
     emit("runtime.exit", { surface: "terminal", code });
   });
+  try {
+    unsubscribeData = options.terminal.onData(forwardData);
+    unsubscribeKeyData = options.terminal.onKeyData?.(forwardData);
+    unsubscribeResize = options.terminal.onResize(signalResize);
+  } catch (error) {
+    // The rejected factory never transfers this promise to a caller.
+    interactive.catch(() => {});
+    releaseSubscriptions();
+    runtime.abort();
+    throw error;
+  }
   return {
     interactive,
     exited: runtime.exited,

package/node.cjs

@@ -1329,8 +1329,10 @@ async function instantiate(options) {
     if (options.args?.[0] === "acp" && !String(error).includes("proc_exit"))
       runtime.abort(error);
     else {
-      if (!String(error).includes("proc_exit"))
+      if (!String(error).includes("proc_exit")) {
+        runtime.abortHostEffects();
         console.error(error);
+      }
       runtime.markExited(runtime.aborted ? 130 : 1);
     }
   });
@@ -1378,13 +1380,13 @@ async function createFxTerminal(options) {
       runtime.abortHostEffects();
     runtime.write(data);
   };
-  const unsubscribeData = options.terminal.onData(forwardData);
-  const unsubscribeKeyData = options.terminal.onKeyData?.(forwardData) ?? (() => {});
   const signalResize = () => {
     emit("terminal.resize", { cols: options.terminal.cols, rows: options.terminal.rows });
     runtime.wake();
   };
-  const unsubscribeResize = options.terminal.onResize(signalResize);
+  let unsubscribeData;
+  let unsubscribeKeyData;
+  let unsubscribeResize;
   let subscriptionsReleased = false;
   const releaseSubscriptions = () => {
     if (subscriptionsReleased)
@@ -1410,6 +1412,16 @@ async function createFxTerminal(options) {
     releaseSubscriptions();
     emit("runtime.exit", { surface: "terminal", code });
   });
+  try {
+    unsubscribeData = options.terminal.onData(forwardData);
+    unsubscribeKeyData = options.terminal.onKeyData?.(forwardData);
+    unsubscribeResize = options.terminal.onResize(signalResize);
+  } catch (error) {
+    interactive.catch(() => {});
+    releaseSubscriptions();
+    runtime.abort();
+    throw error;
+  }
   return {
     interactive,
     exited: runtime.exited,
@@ -2050,6 +2062,12 @@ var backendReasonCodes = {
   jspiUnavailable: "LIBFX_JSPI_UNAVAILABLE",
   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");
+  }
+  return new URL(asset.href.slice(__webpack_public_path__.length), __webpack_base_uri__);
+}
 function jspiFallbackError(surface, nativeError) {
   const nativeDetail = nativeError ? ` Native loading failed: ${nativeError.message}.` : " No compatible native addon was found.";
   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.");
@@ -2061,6 +2079,8 @@ async function loadNativeCandidate(candidate) {
   if (candidate == null)
     return null;
   if (candidate instanceof URL) {
+    if (candidate.protocol === "")
+      candidate = bundledAssetUrl(candidate);
     if (candidate.protocol === "file:" && candidate.pathname.endsWith(".node")) {
       return Reflect.apply(nodeRequire, undefined, [import_node_url.fileURLToPath(candidate)]);
     }
@@ -2080,16 +2100,32 @@ async function loadNativeCandidate(candidate) {
 }
 function defaultNativeCandidate() {
   if (process.platform === "linux" && process.arch === "x64") {
-    return new URL("./libfx.linux-x64.node", __libfxModuleUrl);
+    const asset = new URL("./libfx.linux-x64.node", __libfxModuleUrl);
+    if (asset.protocol === "")
+      return import_node_url.fileURLToPath(bundledAssetUrl(asset));
+    const path = import_node_url.fileURLToPath(asset);
+    return path;
   }
   if (process.platform === "linux" && process.arch === "arm64") {
-    return new URL("./libfx.linux-arm64.node", __libfxModuleUrl);
+    const asset = new URL("./libfx.linux-arm64.node", __libfxModuleUrl);
+    if (asset.protocol === "")
+      return import_node_url.fileURLToPath(bundledAssetUrl(asset));
+    const path = import_node_url.fileURLToPath(asset);
+    return path;
   }
   if (process.platform === "darwin" && process.arch === "x64") {
-    return new URL("./libfx.darwin-x64.node", __libfxModuleUrl);
+    const asset = new URL("./libfx.darwin-x64.node", __libfxModuleUrl);
+    if (asset.protocol === "")
+      return import_node_url.fileURLToPath(bundledAssetUrl(asset));
+    const path = import_node_url.fileURLToPath(asset);
+    return path;
   }
   if (process.platform === "darwin" && process.arch === "arm64") {
-    return new URL("./libfx.darwin-arm64.node", __libfxModuleUrl);
+    const asset = new URL("./libfx.darwin-arm64.node", __libfxModuleUrl);
+    if (asset.protocol === "")
+      return import_node_url.fileURLToPath(bundledAssetUrl(asset));
+    const path = import_node_url.fileURLToPath(asset);
+    return path;
   }
   return null;
 }
@@ -2111,8 +2147,11 @@ 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)
+  if (candidate instanceof URL) {
+    if (candidate.protocol === "")
+      candidate = bundledAssetUrl(candidate);
     return candidate.protocol === "file:" ? import_node_url.fileURLToPath(candidate) : null;
+  }
   if (typeof candidate !== "string")
     return null;
   if (candidate.startsWith("file:"))
@@ -2152,7 +2191,7 @@ async function discoverNativeBackend() {
     return { backend: null, error: null, failure: "unsupported" };
   }
   try {
-    await import_promises.access(import_node_url.fileURLToPath(candidate));
+    await import_promises.access(candidate);
   } catch (error) {
     if (missingArtifact(error)) {
       return { backend: null, error: null, probeError: error, failure: "missing" };
@@ -2194,8 +2233,12 @@ function wasmInput(input) {
   return pending;
 }
 function wasmFilePath(input) {
-  if (input instanceof URL && input.protocol === "file:")
-    return import_node_url.fileURLToPath(input);
+  if (input instanceof URL) {
+    if (input.protocol === "")
+      input = bundledAssetUrl(input);
+    if (input.protocol === "file:")
+      return import_node_url.fileURLToPath(input);
+  }
   if (typeof input === "string" && !URL.canParse(input))
     return import_node_path.resolve(input);
   return null;
@@ -2231,28 +2274,26 @@ function validateBackendInfoOptions(value) {
   if (!value || typeof value !== "object" || Array.isArray(value)) {
     throw new TypeError("getBackendInfo() options must be an object");
   }
-  const options = { ...value };
+  const { nativeAddon, backend = "auto", surface = "agent", ...options } = value;
   for (const key of Object.keys(options)) {
-    if (!new Set(["surface", "backend", "nativeAddon", "wasm"]).has(key)) {
+    if (key !== "wasm") {
       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)) {
+  if (nativeAddon !== undefined && nativeAddon !== false && typeof nativeAddon !== "string" && !(nativeAddon instanceof URL) && (typeof nativeAddon !== "object" || 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 };
+  return { ...options, surface, backend, nativeAddon };
 }
 async function getBackendInfo(value = {}) {
   const { surface, backend, nativeAddon, wasm } = validateBackendInfoOptions(value);
@@ -2280,7 +2321,7 @@ async function getBackendInfo(value = {}) {
   const defaultWasm = surface === "agent" ? defaultCoreWasm : defaultTermWasm;
   const wasmSource = wasm ?? defaultWasm;
   try {
-    await loadModule(wasmInput(wasmSource));
+    await loadModule(await wasmInput(wasmSource));
     attempts.push({ backend: "wasm-jspi", available: true, reason: null });
     return { surface, backend: "wasm-jspi", attempts };
   } catch (error) {
@@ -2529,7 +2570,7 @@ async function createWithFallback(surface, nativeMethod, wasmFactory, defaultWas
     throw jspiFallbackError(surface, nativeError);
   }
   const wasmSource = runtimeOptions.wasm ?? defaultWasm;
-  return wasmFactory({ ...runtimeOptions, wasm: wasmInput(wasmSource) });
+  return wasmFactory({ ...runtimeOptions, wasm: await wasmInput(wasmSource) });
 }
 async function createFxAgent2(options = {}) {
   if (options != null && Object.hasOwn(Object(options), "env")) {

package/node.js

@@ -42,6 +42,16 @@ 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 jspiFallbackError(surface, nativeError) {
   const nativeDetail = nativeError ? ` Native loading failed: ${nativeError.message}.` : " No compatible native addon was found.";
   const error = new Error(
@@ -57,6 +67,7 @@ function jspiFallbackError(surface, nativeError) {
 async function loadNativeCandidate(candidate) {
   if (candidate == null) return null;
   if (candidate instanceof URL) {
+    if (candidate.protocol === "") candidate = bundledAssetUrl(candidate);
     if (candidate.protocol === "file:" && candidate.pathname.endsWith(".node")) {
       // Bundlers trace the asset URL; Node must load the native file at runtime.
       return Reflect.apply(nodeRequire, undefined, [fileURLToPath(candidate)]);
@@ -76,17 +87,30 @@ async function loadNativeCandidate(candidate) {
 }
 
 function defaultNativeCandidate() {
+  // Local path bindings let deployment tracers retain these assets in the generated CommonJS entry.
   if (process.platform === "linux" && process.arch === "x64") {
-    return new URL("./libfx.linux-x64.node", import.meta.url);
+    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") {
-    return new URL("./libfx.linux-arm64.node", import.meta.url);
+    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") {
-    return new URL("./libfx.darwin-x64.node", import.meta.url);
+    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") {
-    return new URL("./libfx.darwin-arm64.node", import.meta.url);
+    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;
 }
@@ -110,7 +134,10 @@ function missingArtifact(error) {
 }
 
 function nativeCandidateFilePath(candidate) {
-  if (candidate instanceof URL) return candidate.protocol === "file:" ? fileURLToPath(candidate) : null;
+  if (candidate instanceof URL) {
+    if (candidate.protocol === "") candidate = bundledAssetUrl(candidate);
+    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);
@@ -151,7 +178,7 @@ async function discoverNativeBackend() {
     return { backend: null, error: null, failure: "unsupported" };
   }
   try {
-    await access(fileURLToPath(candidate));
+    await access(candidate);
   } catch (error) {
     if (missingArtifact(error)) {
       return { backend: null, error: null, probeError: error, failure: "missing" };
@@ -191,7 +218,10 @@ function wasmInput(input) {
 }
 
 function wasmFilePath(input) {
-  if (input instanceof URL && input.protocol === "file:") return fileURLToPath(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;
 }
@@ -240,23 +270,21 @@ function validateBackendInfoOptions(value) {
   if (!value || typeof value !== "object" || Array.isArray(value)) {
     throw new TypeError("getBackendInfo() options must be an object");
   }
-  const options = { ...value };
+  const { nativeAddon, backend = "auto", surface = "agent", ...options } = value;
   for (const key of Object.keys(options)) {
-    if (!new Set(["surface", "backend", "nativeAddon", "wasm"]).has(key)) {
+    if (key !== "wasm") {
       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)) {
+  if (nativeAddon !== undefined && nativeAddon !== false &&
+    typeof nativeAddon !== "string" && !(nativeAddon instanceof URL) &&
+    (typeof nativeAddon !== "object" || 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 ||
@@ -265,7 +293,7 @@ function validateBackendInfoOptions(value) {
   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 };
+  return { ...options, surface, backend, nativeAddon };
 }
 
 export async function getBackendInfo(value = {}) {
@@ -299,7 +327,7 @@ export async function getBackendInfo(value = {}) {
   const defaultWasm = surface === "agent" ? defaultCoreWasm : defaultTermWasm;
   const wasmSource = wasm ?? defaultWasm;
   try {
-    await loadModule(wasmInput(wasmSource));
+    await loadModule(await wasmInput(wasmSource));
     attempts.push({ backend: "wasm-jspi", available: true, reason: null });
     return { surface, backend: "wasm-jspi", attempts };
   } catch (error) {
@@ -514,7 +542,7 @@ async function createWithFallback(surface, nativeMethod, wasmFactory, defaultWas
     throw jspiFallbackError(surface, nativeError);
   }
   const wasmSource = runtimeOptions.wasm ?? defaultWasm;
-  return wasmFactory({ ...runtimeOptions, wasm: wasmInput(wasmSource) });
+  return wasmFactory({ ...runtimeOptions, wasm: await wasmInput(wasmSource) });
 }
 
 export async function createFxAgent(options = {}) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "libfx",
-  "version": "0.0.8-dev.820.g1d9d3b63d6ea",
+  "version": "0.0.8",
   "description": "Embed fx agents and terminals in JavaScript hosts",
   "type": "module",
   "repository": {