README.md
# 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 ```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 | 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. ```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; }, }); const session = await agent.createSession(); const turn = session.prompt("Explain the files in this project."); for await (const update of turn) { console.log(update); } console.log("Stopped:", await turn.stopReason); await session.close(); await agent.cl…