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

package/README.md

@@ -41,8 +41,9 @@ await agent.close();
 Agent configuration uses named options; `env` is reserved for
 `createFxTerminal()`.
 
-The host selects the model. Agent creation and prompting do not fetch the
-Gateway model catalog.
+The host selects the model. Agent creation does not fetch the Gateway model
+catalog. Prompting can resolve model capabilities and context capacity through
+the supplied `fetch`; fx caches that metadata for the agent.
 
 `onEvent` receives runtime diagnostics separately from model output. Transport
 events report request start, response status and elapsed time, safe Gateway
@@ -59,6 +60,28 @@ returns an async iterable of normalized events:
 - `tool_start`
 - `tool_end`
 
+Consume the turn while it runs, then await `turn.result`. Output is lossless and
+backpressured: a slow reader pauses production instead of growing an unlimited
+event queue. Awaiting only `turn.result` can wait for an unread stream to drain.
+If you only need the result, explicitly discard events:
+
+```js
+const turn = agent.prompt("Update the index.");
+for await (const _ of turn) {}
+const result = await turn.result;
+```
+
+A turn has one event consumer. Breaking out of its iterator cancels the turn;
+`turn.cancel()` and `agent.close()` also release blocked output. Transport or
+message-decoding failures reject the result instead of returning success with
+missing text.
+
+Native transport buffers at most 8 MiB of output bytes. Unread SDK events apply
+backpressure at 1 MiB of encoded messages or 256 events. One message can exceed
+that threshold when the queue is empty; an individual encoded ACP message is
+limited to 64 MiB on both backends. These are transport bounds, not a total
+answer-size limit or a bound on retained conversation history.
+
 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:
@@ -67,6 +90,9 @@ agent:
 const restored = await createFxAgent({ apiKey, model, checkpoint });
 ```
 
+An already-aborted prompt signal returns `cancelled` without a model request
+or a history change. The next prompt can run normally.
+
 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.
@@ -112,6 +138,9 @@ const agent = await createFxAgent({
 
 The JavaScript host is the authority for tool effects. The same descriptors,
 schemas, cancellation, results, and events are used by N-API and WebAssembly.
+Cancelling a prompt aborts its tools' signals and stops waiting for their
+callbacks. Late results and rejections are ignored. Tools remain responsible
+for stopping their own work when their signal is aborted.
 Instructions are limited to 64 KiB of UTF-8 text, including text assembled by
 the MCP and skills adapters. They are the complete host-owned system context:
 libfx adds no hidden base prompt, and omitting `instructions` sends no system
@@ -120,7 +149,19 @@ message.
 ## MCP
 
 `libfx/mcp` accepts a host-owned MCP client. Transport, authentication,
-elicitation, and cleanup remain outside the kernel.
+elicitation, and cleanup remain outside the kernel. The client uses the MCP
+TypeScript SDK v1 signature: `callTool(params, resultSchema?, options?)`, with
+cancellation passed in `options`. Tool text and structured data
+reach the model together. PNG, JPEG, GIF, and WebP tool images reach models that
+advertise image input support; other models receive an explicit omission notice.
+Images are retained in checkpoints within the existing checkpoint size limit.
+Each image may contain up to 5 MiB of base64 data, with at most eight images and
+an 8 MiB result frame. Ordinary host tool objects remain JSON text. Resource and
+prompt options supply text instructions; non-text context has an omission notice.
+Tool catalogs are paginated up to the existing 64-tool bound. Tool names are
+normalized for model APIs, with collisions kept distinct and original names used
+for calls to the MCP client. Each tool description and JSON schema may contain up
+to 64 KiB, within the control message's 8 MiB limit.
 
 ```js
 import { createMcpAdapter } from "libfx/mcp";
@@ -165,13 +206,97 @@ await createFxAgent({ apiKey, backend: "native" }); // require N-API
 await createFxAgent({ apiKey, backend: "wasm" });   // require Wasm + JSPI
 ```
 
-Within one JavaScript realm, libfx compiles each stable Wasm source once and
+CommonJS applications can load the same Node API with `require("libfx")`. The
+package chooses its generated CommonJS entry automatically and keeps asset
+paths relative to the installed package.
+
+Use `getBackendInfo()` to inspect backend availability without creating an
+Agent or terminal:
+
+```js
+import { getBackendInfo } from "libfx";
+
+const info = await getBackendInfo({ surface: "agent", backend: "auto" });
+// {
+//   surface: "agent",
+//   backend: "native" | "wasm-jspi" | "unavailable",
+//   attempts: [{ backend, available, reason }]
+// }
+```
+
+`surface` is `agent` by default and may also be `terminal`. `backend` has the
+same `auto`, `native`, and `wasm` selection as the factories. `nativeAddon` and
+`wasm` select explicit assets with the same meanings as their factory options.
+The probe loads and validates the native module or compiles the selected Wasm
+asset, then stops. It does not create a core, open a runtime socket, read
+credentials, start a model request, or write session state. A remote Wasm
+source can perform its normal asset fetch.
+
+Expected environmental failures resolve as structured attempts. Invalid
+options reject with `TypeError`. The stable reason codes are:
+
+| Code | Meaning |
+| --- | --- |
+| `LIBFX_UNSUPPORTED_PLATFORM` | No packaged native addon supports the current platform and architecture. |
+| `LIBFX_NATIVE_ARTIFACT_MISSING` | The selected native addon file is absent. |
+| `LIBFX_NATIVE_LOAD_FAILED` | Node could not load the selected native addon. |
+| `LIBFX_NATIVE_API_MISMATCH` | The addon API version is incompatible. |
+| `LIBFX_NATIVE_SURFACE_MISSING` | The addon does not implement the selected Agent or terminal surface. |
+| `LIBFX_NATIVE_DISABLED` | `nativeAddon: false` disabled native loading. |
+| `LIBFX_JSPI_UNAVAILABLE` | The current JavaScript runtime does not provide JSPI. |
+| `LIBFX_WASM_LOAD_FAILED` | The selected Wasm asset could not be loaded or compiled. |
+
+The optional `causeCode` field retains a Node error code such as `ENOENT` or
+`ERR_DLOPEN_FAILED` when one exists. Probe success establishes backend loading
+only; it does not validate credentials, a future Agent initialization, or a
+model request.
+
+Within one loaded SDK module, 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.
+processes maintain their own module caches, as do the ESM and CommonJS entries.
 
 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.
 Some Node versions require `--experimental-wasm-jspi`.
+Bun 1.4.2 is the tested recommendation for Bun's WebAssembly backend.
+Bun 1.3.14 can crash when a hot WebAssembly loop resumes through JSPI during
+JIT tier-up.
+
+### Next.js and Vercel
+
+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.
+
+```js
+import { createFxAgent } from "libfx";
+
+export const runtime = "nodejs";
+
+export async function POST(request) {
+  const { prompt } = await request.json();
+  const agent = await createFxAgent({ apiKey: process.env.AI_GATEWAY_API_KEY });
+  try {
+    let text = "";
+    const turn = agent.prompt(prompt, { signal: request.signal });
+    for await (const event of turn) {
+      if (event.type === "text_delta") text += event.delta;
+    }
+    await turn.result;
+    return Response.json({ text });
+  } finally {
+    await agent.close();
+  }
+}
+```
+
+Use the application's normal authentication and request limits around the
+route. JavaScript tools and MCP clients remain host-owned and must be supplied
+when creating an agent, including after checkpoint restoration. The native
+backend does not enable the CLI's built-in shell or filesystem tools.
 
 ## Interactive terminal
 

package/core-output.js

@@ -0,0 +1,58 @@
+export const maxCoreMessageBytes = 64 * 1024 * 1024;
+
+// One ordered writer per core; a pending handler holds admission of the next message.
+export class CoreOutput {
+  constructor(handler) {
+    this.handler = handler;
+    this.decoder = new TextDecoder("utf-8", { fatal: true });
+    this.buffer = new Uint8Array(0);
+    this.bytes = 0;
+    this.closed = false;
+  }
+
+  write(chunk) {
+    let offset = 0;
+    const consume = () => {
+      while (offset < chunk.length) {
+        if (this.closed) throw new Error("core output is closed");
+        const newline = chunk.indexOf(10, offset);
+        const end = newline < 0 ? chunk.length : newline;
+        const fragment = chunk.subarray(offset, end);
+        const length = this.bytes + fragment.length;
+        if (length + (newline < 0 ? 0 : 1) > maxCoreMessageBytes) throw new RangeError("core output message exceeds 64 MiB");
+        let data = fragment;
+        if (this.bytes || newline < 0) {
+          if (length > this.buffer.length) {
+            const next = new Uint8Array(Math.min(maxCoreMessageBytes, Math.max(length, this.buffer.length * 2, 4096)));
+            next.set(this.buffer.subarray(0, this.bytes));
+            this.buffer = next;
+          }
+          this.buffer.set(fragment, this.bytes);
+          data = this.buffer.subarray(0, length);
+        }
+        this.bytes = length;
+        offset = newline < 0 ? end : end + 1;
+        if (newline < 0) return;
+        const line = this.decoder.decode(data);
+        const size = length + 1;
+        this.bytes = 0;
+        if (this.buffer.length > 1024 * 1024) this.buffer = new Uint8Array(0);
+        if (line) {
+          const pending = this.handler(JSON.parse(line), size);
+          if (pending) return Promise.resolve(pending).then(consume);
+        }
+      }
+    };
+    return consume();
+  }
+
+  finish() {
+    if (this.bytes) throw new Error("core output ended within a message");
+  }
+
+  close() {
+    this.closed = true;
+    this.buffer = new Uint8Array(0);
+    this.bytes = 0;
+  }
+}