libfx 0.0.7 → 0.0.8-dev.820.g1d9d3b63d6ea

package/node.js

@@ -1,32 +1,46 @@
 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,
   encodeXtermKeyEvent,
   fxSdkApiVersion,
+  listModels,
   supportsJspi,
   xtermAdapter,
 } from "./fx-sdk.js";
 
-export { encodeXtermKeyEvent, fxSdkApiVersion, supportsJspi, xtermAdapter };
+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.";
@@ -44,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;
@@ -53,83 +68,256 @@ 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.createFxAgent !== "function" && typeof backend.createCore !== "function" &&
-    typeof backend.createFxTerminal !== "function") {
-    throw new Error("native addon must export createFxAgent(), createCore(), or createFxTerminal()");
+  if (typeof backend.createCore !== "function" && typeof backend.createFxTerminal !== "function") {
+    throw new Error("native addon must export createCore() or createFxTerminal()");
   }
   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;
 }
 
-async function wasmBytes(input) {
-  if (input instanceof URL && input.protocol === "file:") return readFile(input);
-  if (typeof input === "string" && !URL.canParse(input)) return readFile(input);
-  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 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 && 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 validateGatewayChatUrl(value) {
-  if (value === undefined) return;
-  if (typeof value !== "string") throw new TypeError("FX_GATEWAY_CHAT_URL must be a string");
-  let url;
-  try { url = new URL(value); } catch { throw new TypeError("FX_GATEWAY_CHAT_URL must be a valid URL"); }
-  if (url.username || url.password || url.hash) {
-    throw new TypeError("FX_GATEWAY_CHAT_URL must not contain credentials or a fragment");
-  }
-  if (url.href === "https://ai-gateway.vercel.sh/v3/ai/language-model") return;
-  const loopback = url.hostname === "127.0.0.1" || url.hostname === "[::1]" || url.hostname === "localhost";
-  if (url.protocol !== "http:" || !loopback || !url.port) {
-    throw new TypeError("FX_GATEWAY_CHAT_URL must use the canonical Gateway or explicit loopback HTTP");
+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 = options.env?.AI_GATEWAY_API_KEY;
-  const model = options.env?.FX_MODEL;
-  const gatewayChatUrl = options.env?.FX_GATEWAY_CHAT_URL;
-  validateGatewayChatUrl(gatewayChatUrl);
+  const { apiKey, model, gatewayChatUrl } = options;
   const core = addon.createCore({
     apiKey,
     home: options.home ?? homedir(),
@@ -137,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; });
@@ -147,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();
@@ -197,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)) {
@@ -210,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) lineHandler(JSON.parse(line));
-        }
+      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 (addon.coreExited(core)) finish(addon.coreExitCode(core));
-    } catch {
-      finish(1);
+      if (!settled && addon.coreExited(core)) {
+        output.finish();
+        finish(addon.coreExitCode(core));
+      }
+    } 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; },
   };
 }
@@ -248,22 +483,20 @@ function createNativeAgent(addon, options) {
 
 async function createWithFallback(surface, nativeMethod, wasmFactory, defaultWasm, options) {
   const { nativeAddon, backend = "auto", ...runtimeOptions } = options ?? {};
-  validateGatewayChatUrl(runtimeOptions.env?.FX_GATEWAY_CHAT_URL);
   if (!new Set(["auto", "native", "wasm"]).has(backend)) {
     throw new TypeError('backend must be "auto", "native", or "wasm"');
   }
 
   let nativeError;
+  let nativeAttempted = false;
   if (backend !== "wasm") {
     const native = await resolveNativeBackend(nativeAddon);
     nativeError = native.error;
-    if (typeof native.backend?.[nativeMethod] === "function" ||
-      (surface === "agent" && typeof native.backend?.createCore === "function")) {
+    if (typeof native.backend?.[nativeMethod] === "function") {
+      nativeAttempted = true;
       try {
-        if (typeof native.backend?.[nativeMethod] === "function") {
-          return await native.backend[nativeMethod](runtimeOptions);
-        }
-        return await createNativeAgent(native.backend, runtimeOptions);
+        if (surface === "agent") return await createNativeAgent(native.backend, runtimeOptions);
+        return await native.backend[nativeMethod](runtimeOptions);
       } catch (error) {
         nativeError = error;
         if (backend === "native") throw error;
@@ -276,15 +509,25 @@ async function createWithFallback(surface, nativeMethod, wasmFactory, defaultWas
     }
   }
 
-  if (!supportsJspi()) throw jspiFallbackError(surface, nativeError);
-  return wasmFactory({
-    ...runtimeOptions,
-    wasm: await wasmBytes(runtimeOptions.wasm ?? defaultWasm),
-  });
+  if (!supportsJspi()) {
+    if (nativeAttempted) throw nativeError;
+    throw jspiFallbackError(surface, nativeError);
+  }
+  const wasmSource = runtimeOptions.wasm ?? defaultWasm;
+  return wasmFactory({ ...runtimeOptions, wasm: wasmInput(wasmSource) });
 }
 
-export function createFxAgent(options = {}) {
-  return createWithFallback("agent", "createFxAgent", createWasmAgent, defaultCoreWasm, options);
+export async function createFxAgent(options = {}) {
+  if (options != null && Object.hasOwn(Object(options), "env")) {
+    throw new TypeError("createFxAgent() does not accept env; pass apiKey and model directly");
+  }
+  return createWithFallback(
+    "agent",
+    "createCore",
+    createWasmAgent,
+    defaultCoreWasm,
+    options,
+  );
 }
 
 export function createFxTerminal(options = {}) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "libfx",
-  "version": "0.0.7",
+  "version": "0.0.8-dev.820.g1d9d3b63d6ea",
   "description": "Embed fx agents and terminals in JavaScript hosts",
   "type": "module",
   "repository": {
@@ -17,13 +17,22 @@
   },
   "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"
+    "./wasm": "./fx-sdk.js",
+    "./mcp": "./mcp.js",
+    "./skills": "./skills.js",
+    "./skills/node": "./skills-node.js"
   },
   "engines": {
     "node": ">=20"

package/skills-node.js

@@ -0,0 +1,29 @@
+import { readFile } from "node:fs/promises";
+import { basename } from "node:path";
+
+function parseFrontmatter(source) {
+  if (!source.startsWith("---\n")) return { metadata: {}, body: source };
+  const end = source.indexOf("\n---\n", 4);
+  if (end < 0) throw new Error("SKILL.md has unterminated frontmatter");
+  const metadata = {};
+  for (const line of source.slice(4, end).split("\n")) {
+    const separator = line.indexOf(":");
+    if (separator < 0) continue;
+    metadata[line.slice(0, separator).trim()] = line.slice(separator + 1).trim();
+  }
+  return { metadata, body: source.slice(end + 5).trim() };
+}
+
+export async function loadSkillFile(path, options = {}) {
+  const source = await (options.readFile ?? readFile)(path, "utf8");
+  const { metadata, body } = parseFrontmatter(source);
+  return {
+    name: metadata.name || basename(path).replace(/\.md$/i, ""),
+    description: metadata.description || "",
+    instructions: body,
+    resources: options.resources ?? [],
+    tools: options.tools ?? [],
+  };
+}
+
+export { createSkillsAdapter } from "./skills.js";

package/skills.js

@@ -0,0 +1,44 @@
+const maxSkills = 64;
+const maxInstructionsBytes = 64 * 1024;
+
+function escapeAttribute(value) {
+  return value.replaceAll("&", "&amp;").replaceAll('"', "&quot;").replaceAll("<", "&lt;");
+}
+
+export function createSkillsAdapter(records) {
+  if (!Array.isArray(records) || records.length > maxSkills) {
+    throw new TypeError("skills must be an array with at most 64 records");
+  }
+  const names = new Set();
+  const sections = [];
+  const tools = [];
+  for (const [index, record] of records.entries()) {
+    if (!record || typeof record.name !== "string" || typeof record.instructions !== "string") {
+      throw new TypeError(`skill ${index} requires name and instructions`);
+    }
+    if (names.has(record.name)) throw new TypeError(`duplicate skill name: ${record.name}`);
+    names.add(record.name);
+    const resources = (record.resources ?? []).map((resource) => {
+      if (typeof resource?.uri !== "string" || typeof resource?.text !== "string") {
+        throw new TypeError(`skill ${record.name} has an invalid resource`);
+      }
+      return `<resource uri="${escapeAttribute(resource.uri)}">\n${resource.text}\n</resource>`;
+    }).join("\n");
+    sections.push([
+      `<skill name="${escapeAttribute(record.name)}">`,
+      record.description ? `<description>${record.description}</description>` : "",
+      record.instructions,
+      resources,
+      "</skill>",
+    ].filter(Boolean).join("\n"));
+    if (record.tools !== undefined) {
+      if (!Array.isArray(record.tools)) throw new TypeError(`skill ${record.name} tools must be an array`);
+      tools.push(...record.tools);
+    }
+  }
+  const instructions = sections.join("\n\n");
+  if (new TextEncoder().encode(instructions).length > maxInstructionsBytes) {
+    throw new RangeError(`skill instructions exceed the ${maxInstructionsBytes} byte libfx limit`);
+  }
+  return { instructions, tools };
+}