libfx 0.0.6 → 0.0.7-dev.607.ga90fc3585568

package/README.md

@@ -1,357 +1,162 @@
 # libfx
 
-`libfx` embeds fx agents and interactive terminals in JavaScript
-applications. It supports Node.js hosts and browser environments with
-JavaScript Promise Integration (JSPI).
-
-## Installation
+`libfx` is the small fx agent kernel for JavaScript hosts. One agent is one
+in-memory conversation with three operations: `prompt`, `checkpoint`, and
+`close`.
 
 ```sh
 npm install libfx
 ```
 
-Requirements:
-
-- Node.js 20 or later
-- Chrome or Edge 137 or later for browser WebAssembly
-- JSPI when using the WebAssembly backend
-- A Vercel AI Gateway credential or a host-provided authenticated `fetch`
-
-The package includes:
-
-- Native Node addons for Linux and macOS on x64 and arm64
-- `fx-core.wasm` for headless agents
-- `fx-term.wasm` for interactive terminals
-- A dependency-free JavaScript host layer
-
-## Exports
-
-| Import | Environment | Description |
-| --- | --- | --- |
-| `libfx` | Node.js or browser | Environment-aware default |
-| `libfx/node` | Node.js | Native-first Node entry point |
-| `libfx/browser` | Browser | WebAssembly browser entry point |
-| `libfx/wasm` | Browser or Node.js | Direct WebAssembly host layer |
+Node.js uses the native addon when available and falls back to WebAssembly.
+Browsers use WebAssembly with JSPI. The default package has no runtime
+dependencies and performs no MCP connection, skill scan, process spawn, or
+filesystem read when imported.
 
-Public exports:
-
-- `createFxAgent()` creates a headless ACP agent.
-- `createFxTerminal()` runs the interactive fx terminal.
-- `supportsJspi()` detects WebAssembly JSPI support.
-- `xtermAdapter()` connects fx to an xterm.js terminal.
-- `encodeXtermKeyEvent()` translates browser keyboard events into terminal input.
-
-## Headless agent
-
-The default Node entry point prefers the native addon and falls back to
-WebAssembly when necessary.
+## Agent
 
 ```js
 import { createFxAgent } from "libfx";
 
 const agent = await createFxAgent({
-  env: {
-    AI_GATEWAY_API_KEY: process.env.AI_GATEWAY_API_KEY,
-  },
-  onEvent(event) {
-    console.log(event.type);
-  },
-  async onPermission(request) {
-    // Return one of request.options[*].optionId to approve it.
-    // Returning null or undefined cancels the request.
-    return null;
-  },
+  env: { AI_GATEWAY_API_KEY: process.env.AI_GATEWAY_API_KEY },
 });
 
-const session = await agent.createSession();
-const turn = session.prompt("Explain the files in this project.");
+const turn = agent.prompt("Explain this project.");
 
-for await (const update of turn) {
-  console.log(update);
+for await (const event of turn) {
+  if (event.type === "text_delta") process.stdout.write(event.delta);
 }
 
-console.log("Stopped:", await turn.stopReason);
-
-await session.close();
+console.log(await turn.result); // { stopReason, usage }
+const checkpoint = await agent.checkpoint();
 await agent.close();
 ```
 
-A prompt may be a string or an array of text and resource blocks:
+`prompt(input, { signal? })` accepts a string or text/resource blocks. It
+returns an async iterable of normalized events:
 
-```js
-const turn = session.prompt([
-  { type: "text", text: "Summarize this file." },
-  {
-    type: "resource",
-    resource: {
-      uri: "file:///workspace/README.md",
-      text: readmeContents,
-    },
-  },
-]);
-```
-
-Image prompt blocks are not currently supported.
-
-### Agent lifecycle
-
-The object returned by `createFxAgent()` provides:
+- `text_delta`
+- `reasoning_delta` when supplied by the provider
+- `tool_start`
+- `tool_end`
 
-| Member | Description |
-| --- | --- |
-| `createSession()` | Creates a new active session |
-| `openSession(id)` | Loads a stored session |
-| `listSessions()` | Lists stored sessions |
-| `close()` | Closes the active session and shuts down cleanly |
-| `abort()` | Immediately aborts the runtime |
-| `exited` | Promise that resolves with the process exit code |
-
-A session provides:
-
-| Member | Description |
-| --- | --- |
-| `prompt(input, options?)` | Starts an async iterable turn |
-| `setModel(model)` | Changes the active model |
-| `setMode(mode)` | Changes the active mode |
-| `setConfig(config)` | Applies multiple configuration values |
-| `close()` | Closes the active session |
-| `remove()` | Removes the stored session |
-| `history` | Previously loaded session updates |
-| `configOptions` | Current configurable values |
-
-Each session allows one active prompt at a time. Cancel a turn directly or
-with an `AbortSignal`:
+Only one prompt may run at a time. `checkpoint()` is idle-only and returns
+opaque, bounded, versioned bytes. Restore them only when creating a fresh
+agent:
 
 ```js
-const controller = new AbortController();
-const turn = session.prompt("Wait for more instructions.", {
-  signal: controller.signal,
-});
-
-controller.abort();
-console.log(await turn.stopReason); // "cancelled"
+const restored = await createFxAgent({ checkpoint, env });
 ```
 
-## Browser agent
+The checkpoint contains conversation history and usage only. The host owns
+durable storage and must resupply models, credentials, instructions, tools,
+MCP clients, and skill records.
 
-Browser hosts always use WebAssembly.
+## JavaScript tools and instructions
 
 ```js
-import {
-  createFxAgent,
-  supportsJspi,
-} from "libfx/browser";
-
-if (!supportsJspi()) {
-  throw new Error("This browser does not support WebAssembly JSPI.");
-}
-
 const agent = await createFxAgent({
-  env: {
-    AI_GATEWAY_API_KEY: "<short-lived credential>",
-  },
+  instructions: "Keep answers concise.",
+  tools: [{
+    name: "lookup",
+    description: "Look up a value.",
+    inputSchema: {
+      type: "object",
+      properties: { key: { type: "string" } },
+      required: ["key"],
+    },
+    async execute(input, { signal }) {
+      return database.get(input.key, { signal });
+    },
+  }],
+  env,
 });
-
-const session = await agent.createSession();
-const turn = session.prompt("Describe this workspace.");
-
-for await (const update of turn) {
-  console.log(update);
-}
 ```
 
-The browser entry point resolves `fx-core.wasm` and `fx-term.wasm` relative to
-the installed package. Pass `wasm` explicitly to provide a URL, `Response`,
-`ArrayBuffer`, typed array, or precompiled `WebAssembly.Module`.
-
-Do not embed a long-lived API key in public browser code. Use a short-lived
-credential or an authenticated server-side proxy.
-
-## Interactive terminal
+The JavaScript host is the authority for tool effects. The same descriptors,
+schemas, cancellation, results, and events are used by N-API and WebAssembly.
+Instructions are limited to 64 KiB of UTF-8 text, including text assembled by
+the MCP and skills adapters.
 
-Install xterm.js in the host application:
+## MCP
 
-```sh
-npm install @xterm/xterm @xterm/addon-fit
-```
-
-Create the terminal and connect it to fx:
+`libfx/mcp` accepts a host-owned MCP client. Transport, authentication,
+elicitation, and cleanup remain outside the kernel.
 
 ```js
-import { Terminal } from "@xterm/xterm";
-import { FitAddon } from "@xterm/addon-fit";
-import "@xterm/xterm/css/xterm.css";
-import {
-  createFxTerminal,
-  supportsJspi,
-  xtermAdapter,
-} from "libfx/browser";
-
-if (!supportsJspi()) {
-  throw new Error("This browser does not support WebAssembly JSPI.");
-}
+import { createMcpAdapter } from "libfx/mcp";
 
-const terminal = new Terminal({
-  cursorBlink: true,
-  scrollback: 10_000,
+const mcp = await createMcpAdapter(client, {
+  prefix: "github_",
+  resources: ["repo://instructions"],
+  prompts: ["review"],
 });
 
-const fit = new FitAddon();
-terminal.loadAddon(fit);
-terminal.open(document.querySelector("#terminal"));
-fit.fit();
-
-const runtime = await createFxTerminal({
-  terminal: xtermAdapter(terminal),
-  env: {
-    AI_GATEWAY_API_KEY: "<short-lived credential>",
-  },
-});
-
-await runtime.interactive;
-
-window.addEventListener("resize", () => {
-  fit.fit();
-  runtime.resize();
-});
-```
-
-The terminal runtime provides:
-
-| Member | Description |
-| --- | --- |
-| `interactive` | Resolves after the terminal is ready for input |
-| `exited` | Resolves with the terminal exit code |
-| `write(data)` | Writes input directly to fx |
-| `resize()` | Notifies fx of terminal geometry changes |
-| `abort()` | Stops the terminal and releases subscriptions |
-
-Try the hosted terminal at [fx.sh/try](https://fx.sh/try).
-
-## Backend selection
-
-Node hosts may select a backend explicitly:
-
-```js
 const agent = await createFxAgent({
-  backend: "native",
+  tools: mcp.tools,
+  instructions: mcp.instructions,
+  env,
 });
-```
-
-| Backend | Behavior |
-| --- | --- |
-| `auto` | Prefer a compatible native addon and fall back to WebAssembly |
-| `native` | Require the native backend and fail if it cannot load |
-| `wasm` | Require WebAssembly and JSPI |
-
-The native loader checks `libfx.node` followed by the platform-specific addon:
 
-```text
-libfx.<platform>-<arch>.node
+// ...
+await agent.close();
+await mcp.close();
 ```
 
-Supported packaged targets:
-
-- `linux-x64`
-- `linux-arm64`
-- `darwin-x64`
-- `darwin-arm64`
+## Skills
 
-If no compatible native backend is available and JSPI cannot run, startup
-rejects with:
+Use `libfx/skills` for already-loaded records or `libfx/skills/node` to load a
+`SKILL.md` explicitly in Node or Bun.
 
 ```js
-error.code === "LIBFX_JSPI_REQUIRED"
-```
-
-On Node versions where JSPI remains behind a flag, start the process with:
+import { loadSkillFile } from "libfx/skills/node";
+import { createSkillsAdapter } from "libfx/skills";
 
-```sh
-node --experimental-wasm-jspi app.mjs
+const record = await loadSkillFile("./skills/review/SKILL.md");
+const skills = createSkillsAdapter([record]);
+const agent = await createFxAgent({ ...skills, env });
 ```
 
-## Host integrations
-
-Hosts may provide adapters for runtime state and external effects:
-
-| Option | Purpose |
-| --- | --- |
-| `fetch` | Routes Gateway requests through the host |
-| `env` | Supplies runtime configuration without changing process globals |
-| `onEvent` | Receives runtime, ACP, terminal, and lifecycle events |
-| `onPermission` | Resolves agent permission requests |
-| `configStore` | Persists accepted configuration values |
-| `sessionStore` | Persists agent or terminal sessions |
-| `oauthSessionStore` | Persists browser device-login sessions |
-| `promptHistoryStore` | Stores terminal prompt history |
-| `openUrl` | Opens authentication and verification URLs |
-| `workspace` | Provides the constrained browser workspace adapter |
-
-## Security boundaries
-
-`nativeAddon` and `env.FX_GATEWAY_CHAT_URL` are trusted host configuration. Do
-not populate them from request, tenant, or other untrusted input.
-
-The native backend sends production credentials only to the canonical Vercel
-AI Gateway endpoint. Custom Gateway endpoints are limited to explicit loopback
-HTTP URLs for local development.
-
-The WebAssembly runtime intentionally does not provide:
-
-- Native processes
-- OS sandboxing
-- Native MCP servers
-- Subagents or skills
-- Automatic upgrades
-- Clipboard integration
-- Arbitrary WASI filesystem access
-- Web search
-
-The optional browser workspace exposes foreground terminal execution through
-the typed contract:
+## Backends
 
 ```js
-{ action: "exec", command }
+await createFxAgent({ backend: "auto" });   // native, then Wasm fallback
+await createFxAgent({ backend: "native" }); // require N-API
+await createFxAgent({ backend: "wasm" });   // require Wasm + JSPI
 ```
 
-The host remains responsible for admitting commands, enforcing limits, and
-returning bounded output.
-
-## Local development
-
-From the fx repository root, build the native addon and both WebAssembly
-surfaces:
-
-```sh
-zig build -Dnapi-surface=core -Doptimize=ReleaseSafe
-zig build -Dwasm-surface=core -Doptimize=ReleaseSmall
-zig build -Dwasm-surface=term -Doptimize=ReleaseSmall
-```
+Within one JavaScript realm, libfx compiles each stable Wasm source once and
+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.
 
-Run the SDK test suites:
+Node.js 20+ is supported. Browser WebAssembly requires a JSPI-capable browser.
+Some Node versions require `--experimental-wasm-jspi`.
 
-```sh
-npm ci --prefix sdk/node
-npm run --prefix sdk test:node-napi
-npm run --prefix sdk test:node-wasm
-```
+## Interactive terminal
 
-Serve the repository:
+`createFxTerminal()` remains a separate terminal harness API. In browsers,
+connect it to xterm.js with `xtermAdapter()`:
 
-```sh
-python3 -m http.server 8080
-```
+```js
+import { createFxTerminal, xtermAdapter } from "libfx/browser";
 
-After starting the server, open these local URLs:
+const runtime = await createFxTerminal({
+  terminal: xtermAdapter(term),
+  env: { AI_GATEWAY_API_KEY: "<short-lived credential>" },
+});
 
-```text
-Core debugger:        http://localhost:8080/sdk/index.html
-Interactive terminal: http://localhost:8080/sdk/term-demo.html
+await runtime.interactive;
 ```
 
-These are local development pages and are not publicly hosted links.
+The terminal runtime exposes `interactive`, `exited`, `write`, `resize`, and
+`abort`. Terminal session, config, OAuth, prompt-history, URL, and workspace
+stores remain terminal-only host integrations.
 
-Maintainer references:
+## Security
 
-- [SDK contributor guide](https://github.com/vercel-labs/fx/blob/main/sdk/AGENTS.md)
-- [Native Node-API design and security model](https://github.com/vercel-labs/fx/blob/main/sdk/NAPI.md)
+Treat `nativeAddon` and `env.FX_GATEWAY_CHAT_URL` as trusted host
+configuration. Do not embed long-lived credentials in public browser code.
+Host tool functions, MCP clients, and skill loaders retain their own authority;
+libfx validates and sequences them but does not grant operating-system access.

package/fx-sdk.js

@@ -4,6 +4,7 @@ const strictDecoder = new TextDecoder("utf-8", { fatal: true });
 const workspaceInfoLimit = 4 * 1024;
 const workspaceCommandLimit = 64 * 1024;
 const workspaceOutputLimit = 64 * 1024;
+const maxInstructionsBytes = 64 * 1024;
 const streamReadsPerTaskYield = 32;
 
 function validWorkspacePath(path) {
@@ -50,7 +51,7 @@ function utf8Prefix(value, limit) {
   return value.subarray(0, end);
 }
 
-export const fxSdkApiVersion = 1;
+export const fxSdkApiVersion = 2;
 
 export function supportsJspi() {
   return typeof WebAssembly.Suspending === "function" &&
@@ -92,35 +93,6 @@ export function xtermAdapter(term) {
   };
 }
 
-function createMemorySessionStore() {
-  const records = new Map();
-  let nextRevision = 1;
-  return {
-    async load(id) {
-      const record = records.get(id);
-      return record ? { bytes: record.bytes.slice(), revision: record.revision } : null;
-    },
-    async commit(id, bytes, expectedRevision) {
-      const current = records.get(id);
-      if ((current?.revision) !== expectedRevision) throw revisionConflict();
-      const revision = String(nextRevision++);
-      records.set(id, { bytes: bytes.slice(), revision, updatedAtMs: Date.now() });
-      return { revision };
-    },
-    async list() {
-      return [...records.entries()].map(([id, record]) => ({ id, updatedAtMs: record.updatedAtMs }))
-        .sort((a, b) => b.updatedAtMs - a.updatedAtMs);
-    },
-    async remove(id) { records.delete(id); },
-  };
-}
-
-function revisionConflict() {
-  const error = new Error("session revision conflict");
-  error.code = "FX_SESSION_REVISION_CONFLICT";
-  return error;
-}
-
 class ByteQueue {
   chunks = [];
   waiters = [];
@@ -176,7 +148,10 @@ class ByteQueue {
   }
 }
 
-async function loadModule(input) {
+const modulePromisesBySource = new Map();
+const modulePromisesByObject = new WeakMap();
+
+async function compileModule(input) {
   if (input instanceof WebAssembly.Module) return input;
   if (typeof input === "string") input = fetch(input);
   if (input instanceof Promise) input = await input;
@@ -195,6 +170,21 @@ async function loadModule(input) {
   throw new TypeError("wasm must be a URL, Response, ArrayBuffer, typed array, or WebAssembly.Module");
 }
 
+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;
+}
+
 function raceWithTimeout(promise, timeoutMs, timeoutValue) {
   let timer;
   return new Promise((resolve, reject) => {
@@ -455,6 +445,22 @@ function createRuntime(options) {
     }).catch(() => -1);
   }
 
+  function hostToolCall(namePtr, nameLen, argumentsPtr, argumentsLen, outputPtr, outputCap, statusPtr) {
+    if (typeof options.hostToolExecutor !== "function") return -1;
+    if (options.traceWasi) console.error("fx host tool call start");
+    let input;
+    try { input = JSON.parse(text(argumentsPtr, argumentsLen)); } catch { return -1; }
+    return Promise.resolve(options.hostToolExecutor(text(namePtr, nameLen), input)).then((result) => {
+      if (options.traceWasi) console.error("fx host tool call settled", result.cancelled, result.isError);
+      if (result.cancelled) return -2;
+      const output = encoder.encode(result.content);
+      if (output.length > outputCap) return -3;
+      bytes(outputPtr, output.length).set(output);
+      bytes(statusPtr, 1)[0] = result.isError ? 1 : 0;
+      return output.length;
+    }).catch(() => -1);
+  }
+
   function openUrl(urlPtr, urlLen) {
     if (typeof options.openUrl !== "function") return 0;
     return Promise.resolve().then(() => options.openUrl(text(urlPtr, urlLen))).then((accepted) =>
@@ -774,6 +780,7 @@ function createRuntime(options) {
     fx_http_stream_next: new WebAssembly.Suspending(streamNext),
     fx_http_stream_close(handle) { const state = streams.get(handle); state?.controller.abort(); streams.delete(handle); },
     fx_http_request: new WebAssembly.Suspending(httpRequest),
+    fx_host_tool_call: new WebAssembly.Suspending(hostToolCall),
     fx_open_url: new WebAssembly.Suspending(openUrl),
     fx_oauth_session_load: new WebAssembly.Suspending(oauthSessionLoad),
     fx_oauth_session_commit: new WebAssembly.Suspending(oauthSessionCommit),
@@ -930,20 +937,117 @@ function normalizePromptInput(input) {
   });
 }
 
-export async function createFxAgent(options) {
-  options = { ...options, sessionStore: options.sessionStore || createMemorySessionStore() };
+function normalizeHostTools(value) {
+  if (value === undefined) return { descriptors: [], executors: new Map() };
+  if (!Array.isArray(value)) throw new TypeError("tools must be an array");
+  if (value.length > 64) throw new RangeError("tools cannot contain more than 64 entries");
+  const descriptors = [];
+  const executors = new Map();
+  for (const [index, tool] of value.entries()) {
+    if (!tool || typeof tool !== "object") throw new TypeError(`tool ${index} must be an object`);
+    const { name, description, inputSchema, execute } = tool;
+    if (typeof name !== "string" || !/^[A-Za-z0-9_-]{1,64}$/.test(name)) {
+      throw new TypeError(`tool ${index} has an invalid name`);
+    }
+    if (executors.has(name)) throw new TypeError(`duplicate tool name: ${name}`);
+    if (typeof description !== "string") throw new TypeError(`tool ${name} requires a description`);
+    if (typeof execute !== "function") throw new TypeError(`tool ${name} requires execute()`);
+    if (!inputSchema || typeof inputSchema !== "object" || Array.isArray(inputSchema)) {
+      throw new TypeError(`tool ${name} requires an object inputSchema`);
+    }
+    let schema;
+    try { schema = JSON.parse(JSON.stringify(inputSchema)); } catch {
+      throw new TypeError(`tool ${name} inputSchema must be JSON-serializable`);
+    }
+    descriptors.push({ name, description, inputSchema: schema });
+    executors.set(name, execute);
+  }
+  return { descriptors, executors };
+}
+
+function normalizeInstructions(value) {
+  let instructions;
+  if (value === undefined) instructions = "";
+  else if (typeof value === "string") instructions = value;
+  if (Array.isArray(value) && value.every((entry) => typeof entry === "string")) {
+    instructions = value.filter(Boolean).join("\n\n");
+  }
+  if (instructions === undefined) {
+    throw new TypeError("instructions must be a string or an array of strings");
+  }
+  if (encoder.encode(instructions).length > maxInstructionsBytes) {
+    throw new RangeError(`instructions exceed the ${maxInstructionsBytes} byte libfx limit`);
+  }
+  return instructions;
+}
+
+function hostToolContent(value) {
+  if (typeof value === "string") return value;
+  if (value === undefined) return "null";
+  const encoded = JSON.stringify(value);
+  return encoded === undefined ? "null" : encoded;
+}
+
+function checkpointBytes(value) {
+  if (value === undefined) return null;
+  if (value instanceof Uint8Array) return value.slice();
+  if (value instanceof ArrayBuffer) return new Uint8Array(value.slice(0));
+  if (ArrayBuffer.isView(value)) {
+    return new Uint8Array(value.buffer.slice(value.byteOffset, value.byteOffset + value.byteLength));
+  }
+  throw new TypeError("checkpoint must be an ArrayBuffer or typed array");
+}
+
+function bytesToBase64(value) {
+  let binary = "";
+  for (let offset = 0; offset < value.length; offset += 0x8000) {
+    binary += String.fromCharCode(...value.subarray(offset, offset + 0x8000));
+  }
+  return btoa(binary);
+}
+
+function base64ToBytes(value) {
+  const binary = atob(value);
+  const bytes = new Uint8Array(binary.length);
+  for (let index = 0; index < binary.length; index++) bytes[index] = binary.charCodeAt(index);
+  return bytes;
+}
+
+export async function createFxAgent(options = {}) {
+  options = { ...options };
+  const hostTools = normalizeHostTools(options.tools);
+  const instructions = normalizeInstructions(options.instructions);
+  const initialCheckpoint = checkpointBytes(options.checkpoint);
   const pending = new Map();
-  const turns = new Map();
   let nextId = 1;
-  let activeSession = null;
-  let loadingSessionId = null;
-  let loadingUpdates = [];
+  let sessionId = null;
+  let activeTurn = null;
   let closing = false;
   const emit = (type, detail = {}) => {
     try { options.onEvent?.({ type, timestamp: performance.now(), ...detail }); } catch {}
   };
+  const executeHostTool = async (name, input, requestedSessionId) => {
+    const execute = hostTools.executors.get(name);
+    const turn = requestedSessionId === undefined || requestedSessionId === sessionId
+      ? activeTurn
+      : null;
+    const controller = new AbortController();
+    turn?.toolControllers.add(controller);
+    let content;
+    let isError = false;
+    try {
+      if (!execute) throw new Error(`unknown host tool: ${String(name)}`);
+      content = hostToolContent(await execute(input, { signal: controller.signal }));
+    } catch (error) {
+      isError = true;
+      content = error instanceof Error ? error.message : String(error);
+    } finally {
+      turn?.toolControllers.delete(controller);
+    }
+    return { content, isError, cancelled: controller.signal.aborted };
+  };
   emit("runtime.start");
-  const runtimeOptions = { ...options, args: ["acp"] };
+  const runtimeOptions = { ...options, args: ["acp"], hostToolExecutor: executeHostTool };
   const runtime = options.runtimeFactory
     ? await options.runtimeFactory(runtimeOptions)
     : await instantiate(runtimeOptions);
@@ -967,9 +1071,7 @@ export async function createFxAgent(options) {
   runtime.setLineHandler(async (message) => {
     emit("acp.receive", { message });
     if (message.method === "session/update") {
-      const turn = turns.get(message.params.sessionId);
-      if (turn) turn.push(message.params.update);
-      else if (loadingSessionId === message.params.sessionId) loadingUpdates.push(message.params.update);
+      if (message.params.sessionId === sessionId) activeTurn?.push(message.params.update);
       return;
     }
     if (message.method === "session/request_permission") {
@@ -980,150 +1082,169 @@ export async function createFxAgent(options) {
       send({ jsonrpc: "2.0", id: message.id, result: optionId ? { outcome: { outcome: "selected", optionId } } : { outcome: { outcome: "cancelled" } } });
       return;
     }
+    if (message.method === "libfx/tool_call") {
+      const { content, isError, cancelled } = await executeHostTool(
+        message.params?.name,
+        message.params?.input,
+        message.params?.sessionId,
+      );
+      if (cancelled || closing) return;
+      send({ jsonrpc: "2.0", id: message.id, result: { content, isError } });
+      return;
+    }
     const waiter = pending.get(message.id); if (!waiter) return; pending.delete(message.id);
     if (message.error) waiter.reject(new Error(message.error.message)); else waiter.resolve(message.result);
   });
-  await request("initialize", { protocolVersion: 1, clientCapabilities: {} });
+  try {
+    await request("initialize", {
+      protocolVersion: 1,
+      clientCapabilities: {
+        ...(hostTools.descriptors.length || instructions
+          ? { libfx: { tools: hostTools.descriptors, instructions } }
+          : {}),
+      },
+    });
+
+    const sessionResult = await request("libfx/new");
+    sessionId = sessionResult.sessionId;
+    if (initialCheckpoint) {
+      await request("libfx/restore", {
+        sessionId,
+        checkpoint: bytesToBase64(initialCheckpoint),
+      });
+    }
+  } catch (error) {
+    closing = true;
+    try { runtime.abortHostEffects(); } catch {}
+    try { runtime.closeStdin(); } catch {}
+    try { await runtime.exited; } catch {}
+    throw error;
+  }
 
   const agent = {
-    exited: runtime.exited,
-    abort() { closing = true; runtime.abort(); },
+    prompt(input, promptOptions = {}) {
+      if (closing) throw new Error("fx agent is closed");
+      if (activeTurn) throw new Error("a prompt is already in progress for this session");
+      return normalizeTurn(startTurn(input, promptOptions));
+    },
+    async checkpoint() {
+      if (closing) throw new Error("fx agent is closed");
+      if (activeTurn) throw new Error("cannot checkpoint while a prompt is active");
+      const response = await request("libfx/checkpoint", { sessionId });
+      if (typeof response?.checkpoint !== "string") throw new Error("fx returned an invalid checkpoint");
+      return base64ToBytes(response.checkpoint);
+    },
     async close() {
-      if (closing) return runtime.exited;
-      if (activeSession) await activeSession.close();
+      if (closing) { await runtime.exited; return; }
+      const turn = activeTurn;
+      turn?.cancel();
+      if (turn) await turn.result.catch(() => {});
       closing = true;
       runtime.closeStdin();
-      return runtime.exited;
-    },
-    async createSession() {
-      if (activeSession) await activeSession.close();
-      const result = await request("session/new");
-      activeSession = await makeSession(result);
-      return activeSession;
-    },
-    async listSessions() {
-      return (await request("session/list")).sessions || [];
-    },
-    async openSession(id) {
-      if (activeSession) await activeSession.close();
-      loadingSessionId = id;
-      loadingUpdates = [];
-      try {
-        const result = await request("session/load", { sessionId: id });
-        activeSession = await makeSession({ sessionId: id, history: loadingUpdates, ...result });
-        return activeSession;
-      } finally {
-        loadingSessionId = null;
-        loadingUpdates = [];
-      }
+      await runtime.exited;
     },
   };
   return agent;
 
-  async function makeSession(result) {
-    let configOptions = result.configOptions || [];
-    let closed = false;
-    let activeTurn = null;
-    const assertOpen = () => {
-      if (closed) throw new Error("fx session is closed");
-      if (activeSession !== session) throw new Error("fx session is no longer active");
-    };
-    const updateConfig = (response) => {
-      configOptions = response.configOptions || configOptions;
-      return configOptions;
+  function normalizeTurn(rawTurn) {
+    const toolNames = new Map();
+    const started = new Set();
+    const eventFor = (update) => {
+      if (update.sessionUpdate === "agent_message_chunk") {
+        const delta = update.content?.text;
+        if (!delta || delta.startsWith("[context]")) return null;
+        return { type: "text_delta", delta };
+      }
+      if (update.sessionUpdate === "agent_thought_chunk") {
+        const delta = update.content?.text;
+        return delta ? { type: "reasoning_delta", delta } : null;
+      }
+      if (update.sessionUpdate === "tool_call") {
+        toolNames.set(update.toolCallId, update.name || update.toolName || update.title || "tool");
+        if (started.has(update.toolCallId)) return null;
+        started.add(update.toolCallId);
+        return {
+          type: "tool_start",
+          id: update.toolCallId,
+          name: toolNames.get(update.toolCallId),
+        };
+      }
+      if (update.sessionUpdate === "tool_call_update" &&
+        (update.status === "completed" || update.status === "failed")) {
+        const content = update.content?.find((entry) => entry.content?.type === "text")?.content?.text;
+        return {
+          type: "tool_end",
+          id: update.toolCallId,
+          name: toolNames.get(update.toolCallId) || "tool",
+          ...(content === undefined ? {} : { content }),
+          isError: update.status === "failed",
+        };
+      }
+      return null;
     };
-    const session = {
-      id: result.sessionId,
-      modes: result.modes,
-      history: result.history || [],
-      get configOptions() { return configOptions; },
-      async setConfigOption(configId, value, source = "sdk") {
-        assertOpen();
-        const previousValue = configOptions.find((option) => option.id === configId)?.currentValue;
-        const updated = updateConfig(await request("session/set_config_option", { sessionId: result.sessionId, configId, value }));
-        const accepted = updated.find((option) => option.id === configId)?.currentValue;
-        if (configId === "mode" && accepted) this.modes.currentModeId = accepted;
-        if (accepted === value) {
-          if (options.configStore?.set) {
-            try { await options.configStore.set(configId, value); } catch (error) { emit("config.persist_error", { configId, error }); }
-          }
-          emit("config.changed", { configId, previousValue, value: accepted, source });
+    return {
+      cancel() { rawTurn.cancel(); },
+      async *[Symbol.asyncIterator]() {
+        for await (const update of rawTurn) {
+          const event = eventFor(update);
+          if (event) yield event;
         }
-        return updated;
-      },
-      setModel(value) { return this.setConfigOption("model", value); },
-      setMode(value) { return this.setConfigOption("mode", value); },
-      async setConfig(config) {
-        for (const [key, value] of Object.entries(config)) await this.setConfigOption(key, value);
-        return configOptions;
-      },
-      async close() {
-        if (closed) return;
-        activeTurn?.cancel();
-        if (activeTurn) await activeTurn.result.catch(() => {});
-        closed = true;
-        activeTurn = null;
-        if (activeSession === session) activeSession = null;
-      },
-      async remove() {
-        if (activeTurn) throw new Error("cannot remove a session while a prompt is active");
-        await request("session/remove", { sessionId: result.sessionId });
-        closed = true;
-        if (activeSession === session) activeSession = null;
       },
-      prompt(input, promptOptions = {}) {
-        assertOpen();
-        if (activeTurn) throw new Error("a prompt is already in progress for this session");
-        const prompt = normalizePromptInput(input);
-        const signal = promptOptions.signal;
-        if (signal !== undefined && (typeof signal?.addEventListener !== "function" || typeof signal?.removeEventListener !== "function")) throw new TypeError("prompt signal must be an AbortSignal");
-        const queue = [];
-        const waiters = [];
-        let finished = false;
-        let cancelled = false;
-        const turn = {
-          push(update) { const waiter = waiters.shift(); if (waiter) waiter({ value: update, done: false }); else queue.push(update); },
-          cancel() {
-            if (finished || cancelled) return;
-            cancelled = true;
-            send({ jsonrpc: "2.0", method: "session/cancel", params: { sessionId: result.sessionId } });
-            runtime.abortHostEffects();
-          },
-          [Symbol.asyncIterator]() { return { next() { if (queue.length) return Promise.resolve({ value: queue.shift(), done: false }); if (finished) return Promise.resolve({ done: true }); return new Promise((resolve) => waiters.push(resolve)); } }; },
-        };
-        turns.set(result.sessionId, turn);
-        activeTurn = turn;
-        const abort = () => turn.cancel();
-        signal?.addEventListener("abort", abort, { once: true });
-        turn.result = request("session/prompt", { sessionId: result.sessionId, prompt })
-          .then((response) => ({ stopReason: response.stopReason }))
-          .catch((error) => {
-            if (error.message === "Cancelled") return { stopReason: "cancelled" };
-            throw error;
-          })
-          .finally(() => {
-            finished = true;
-            signal?.removeEventListener("abort", abort);
-            turns.delete(result.sessionId);
-            if (activeTurn === turn) activeTurn = null;
-            waiters.splice(0).forEach((resolve) => resolve({ done: true }));
-          });
-        turn.stopReason = turn.result.then((turnResult) => turnResult.stopReason);
-        void turn.stopReason.catch(() => {});
-        if (signal?.aborted) turn.cancel();
-        return turn;
+      result: rawTurn.result.then((result) => ({
+        stopReason: result.stopReason,
+        usage: normalizeTurnUsage(result.usage),
+      })),
+    };
+  }
+
+  function normalizeTurnUsage(usage) {
+    const result = {};
+    if (Number.isSafeInteger(usage?.inputTokens)) result.inputTokens = usage.inputTokens;
+    if (Number.isSafeInteger(usage?.outputTokens)) result.outputTokens = usage.outputTokens;
+    if (Number.isSafeInteger(usage?.cacheReadTokens)) result.cacheReadTokens = usage.cacheReadTokens;
+    if (Number.isSafeInteger(usage?.cacheWriteTokens)) result.cacheWriteTokens = usage.cacheWriteTokens;
+    if (Number.isSafeInteger(usage?.reasoningTokens)) result.reasoningTokens = usage.reasoningTokens;
+    return result;
+  }
+
+  function startTurn(input, promptOptions) {
+    const prompt = normalizePromptInput(input);
+    const signal = promptOptions.signal;
+    if (signal !== undefined && (typeof signal?.addEventListener !== "function" || typeof signal?.removeEventListener !== "function")) throw new TypeError("prompt signal must be an AbortSignal");
+    const queue = [];
+    const waiters = [];
+    const toolControllers = new Set();
+    let finished = false;
+    let cancelled = false;
+    const turn = {
+      push(update) { const waiter = waiters.shift(); if (waiter) waiter({ value: update, done: false }); else queue.push(update); },
+      toolControllers,
+      cancel() {
+        if (finished || cancelled) return;
+        cancelled = true;
+        send({ jsonrpc: "2.0", method: "session/cancel", params: { sessionId } });
+        for (const controller of toolControllers) controller.abort();
+        runtime.abortHostEffects();
       },
+      [Symbol.asyncIterator]() { return { next() { if (queue.length) return Promise.resolve({ value: queue.shift(), done: false }); if (finished) return Promise.resolve({ done: true }); return new Promise((resolve) => waiters.push(resolve)); } }; },
     };
-    if (options.configStore?.get) {
-      activeSession = session;
-      for (const config of [...configOptions]) {
-        let value;
-        try { value = await options.configStore.get(config.id); } catch (error) { emit("config.restore_error", { configId: config.id, error }); continue; }
-        if (typeof value !== "string" || value === config.currentValue) continue;
-        try { await session.setConfigOption(config.id, value, "restore"); } catch (error) { emit("config.restore_error", { configId: config.id, error }); }
-      }
-    }
-    session.modes.currentModeId = configOptions.find((option) => option.id === "mode")?.currentValue || session.modes.currentModeId;
-    return session;
+    activeTurn = turn;
+    const abort = () => turn.cancel();
+    signal?.addEventListener("abort", abort, { once: true });
+    turn.result = request("session/prompt", { sessionId, prompt })
+      .then((response) => ({ stopReason: response.stopReason, usage: response.usage }))
+      .catch((error) => {
+        if (error.message === "Cancelled") return { stopReason: "cancelled" };
+        throw error;
+      })
+      .finally(() => {
+        finished = true;
+        signal?.removeEventListener("abort", abort);
+        if (activeTurn === turn) activeTurn = null;
+        toolControllers.clear();
+        waiters.splice(0).forEach((resolve) => resolve({ done: true }));
+      });
+    if (signal?.aborted) turn.cancel();
+    return turn;
   }
 }

package/mcp.js

@@ -0,0 +1,89 @@
+const maxTools = 64;
+const maxInstructionsBytes = 64 * 1024;
+
+function contentText(content) {
+  if (typeof content === "string") return content;
+  if (!Array.isArray(content)) return "";
+  return content.map((item) => {
+    if (item?.type === "text" && typeof item.text === "string") return item.text;
+    if (item?.type === "resource" && typeof item.resource?.text === "string") return item.resource.text;
+    if (typeof item?.text === "string") return item.text;
+    return "";
+  }).filter(Boolean).join("\n");
+}
+
+function resultText(result) {
+  const text = contentText(result?.content);
+  if (text) return text;
+  if (result?.structuredContent !== undefined) return JSON.stringify(result.structuredContent);
+  return "";
+}
+
+function appendInstruction(parts, label, text) {
+  if (!text) return;
+  parts.push(`<${label}>\n${text}\n</${label}>`);
+}
+
+export async function createMcpAdapter(client, options = {}) {
+  if (!client || typeof client.listTools !== "function" || typeof client.callTool !== "function") {
+    throw new TypeError("MCP client must provide listTools() and callTool()");
+  }
+  const prefix = options.prefix ?? "";
+  if (typeof prefix !== "string" || !/^[A-Za-z0-9_-]*$/.test(prefix)) {
+    throw new TypeError("MCP prefix must contain only letters, digits, underscore, or hyphen");
+  }
+  const listed = await client.listTools();
+  const catalog = Array.isArray(listed) ? listed : listed?.tools;
+  if (!Array.isArray(catalog) || catalog.length > maxTools) {
+    throw new TypeError("MCP listTools() returned an invalid tool catalog");
+  }
+  const tools = catalog.map((tool, index) => {
+    if (!tool || typeof tool.name !== "string" || typeof tool.description !== "string") {
+      throw new TypeError(`MCP tool ${index} is invalid`);
+    }
+    const name = `${prefix}${tool.name}`;
+    return {
+      name,
+      description: tool.description,
+      inputSchema: tool.inputSchema ?? { type: "object", properties: {} },
+      async execute(input, { signal }) {
+        const result = await client.callTool({ name: tool.name, arguments: input }, { signal });
+        const text = resultText(result);
+        if (result?.isError) throw new Error(text || `MCP tool ${tool.name} failed`);
+        return text;
+      },
+    };
+  });
+
+  const instructions = [];
+  for (const uri of options.resources ?? []) {
+    if (typeof client.readResource !== "function") throw new TypeError("MCP client does not provide readResource()");
+    const result = await client.readResource({ uri });
+    appendInstruction(instructions, "mcp_resource", contentText(result?.contents ?? result?.content));
+  }
+  for (const prompt of options.prompts ?? []) {
+    if (typeof client.getPrompt !== "function") throw new TypeError("MCP client does not provide getPrompt()");
+    const request = typeof prompt === "string" ? { name: prompt } : prompt;
+    const result = await client.getPrompt(request);
+    appendInstruction(
+      instructions,
+      "mcp_prompt",
+      (result?.messages ?? []).map((message) => contentText(message.content)).filter(Boolean).join("\n"),
+    );
+  }
+  const instructionText = instructions.join("\n\n");
+  if (new TextEncoder().encode(instructionText).length > maxInstructionsBytes) {
+    throw new RangeError(`MCP instructions exceed the ${maxInstructionsBytes} byte libfx limit`);
+  }
+
+  let closed = false;
+  return {
+    tools,
+    instructions: instructionText,
+    async close() {
+      if (closed) return;
+      closed = true;
+      await client.close?.();
+    },
+  };
+}

package/node.js

@@ -27,6 +27,7 @@ const defaultNativeCandidates = [
   `./libfx.${process.platform}-${process.arch}.node`,
 ];
 let nativeBackendPromise;
+const wasmFilePromises = new Map();
 
 function jspiFallbackError(surface, nativeError) {
   const nativeDetail = nativeError ? ` Native loading failed: ${nativeError.message}.` : " No compatible native addon was found.";
@@ -104,10 +105,19 @@ async function resolveNativeBackend(nativeAddon) {
   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 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;
+  const cached = wasmFilePromises.get(path);
+  if (cached) return cached;
+  const pending = readFile(path);
+  wasmFilePromises.set(path, pending);
+  pending.catch(() => {
+    if (wasmFilePromises.get(path) === pending) wasmFilePromises.delete(path);
+  });
+  return pending;
 }
 
 function validateGatewayChatUrl(value) {
@@ -218,7 +228,7 @@ function createNativeCoreRuntime(addon, options) {
           if (newline < 0) break;
           const line = lineBuffer.slice(0, newline);
           lineBuffer = lineBuffer.slice(newline + 1);
-          if (line) lineHandler(JSON.parse(line));
+          if (line) void Promise.resolve(lineHandler(JSON.parse(line))).catch(() => finish(1));
         }
       }
       if (addon.coreExited(core)) finish(addon.coreExitCode(core));
@@ -254,11 +264,13 @@ async function createWithFallback(surface, nativeMethod, wasmFactory, defaultWas
   }
 
   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")) {
+      nativeAttempted = true;
       try {
         if (typeof native.backend?.[nativeMethod] === "function") {
           return await native.backend[nativeMethod](runtimeOptions);
@@ -276,7 +288,10 @@ async function createWithFallback(surface, nativeMethod, wasmFactory, defaultWas
     }
   }
 
-  if (!supportsJspi()) throw jspiFallbackError(surface, nativeError);
+  if (!supportsJspi()) {
+    if (nativeAttempted) throw nativeError;
+    throw jspiFallbackError(surface, nativeError);
+  }
   return wasmFactory({
     ...runtimeOptions,
     wasm: await wasmBytes(runtimeOptions.wasm ?? defaultWasm),

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "libfx",
-  "version": "0.0.6",
+  "version": "0.0.7-dev.607.ga90fc3585568",
   "description": "Embed fx agents and terminals in JavaScript hosts",
   "type": "module",
   "repository": {
@@ -23,7 +23,10 @@
     },
     "./node": "./node.js",
     "./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 };
+}