libfx 0.0.13 → 0.0.14-dev.1561.g1a070af32cdf

package/README.md

@@ -1,611 +1,579 @@
 # libfx
 
-`libfx` is the small fx agent kernel for JavaScript hosts. One agent is one
-in-memory conversation with `prompt`, `checkpoint`, and `close` operations,
-plus mid-turn steering on each running turn.
+libfx is the agent from [fx](https://github.com/vercel-labs/fx), the open source coding agent from Vercel Labs, as a JavaScript library. You give it a model, instructions and your own tools, and it runs the conversation: the model loop, streaming, tool calls, retries, steering and images. It's the same Zig engine that runs fx in a terminal, built as a Node.js addon and as WebAssembly.
+
+The hard part of running an agent on a server is that the server goes away. A function reaches its time limit in the middle of a reply, a deploy replaces the process, or it crashes during a tool call. libfx stores every prompt before it accepts it and every step of a turn as the turn runs, so the next process that picks up the session continues the turn where it stopped. On Vercel, that takes one route and one line of `vercel.json`.
 
 ```sh
 npm install libfx
 ```
 
-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.
-
-## Agent
-
 ```js
 import { createFxAgent } from "libfx";
 
-const agent = await createFxAgent({
-  apiKey: process.env.AI_GATEWAY_API_KEY,
-  model: "google/gemini-2.5-flash-lite",
-  onEvent(event) {
-    if (event.type === "transport.response") console.log(event.elapsedMs);
-  },
+const agent = createFxAgent({
+  model: "anthropic/claude-haiku-5.5",
+  instructions: "Answer in one paragraph.",
 });
 
-const turn = agent.prompt("Explain this project.");
+const turn = agent.session().prompt("What is an agent loop?");
 
 for await (const event of turn) {
   if (event.type === "text_delta") process.stdout.write(event.delta);
 }
 
-console.log(await turn.result); // { stopReason, usage }
-const checkpoint = await agent.checkpoint();
 await agent.close();
 ```
 
-`apiKey` is required. `model` is optional and defaults to fx's built-in model.
-Agent configuration uses named options; `env` is reserved for
-`createFxTerminal()`. The canonical model configuration groups the model ID
-and model-specific options:
+Set `AI_GATEWAY_API_KEY` and run it with Node.js 20 or newer. Model calls go through [AI Gateway](https://vercel.com/docs/ai-gateway), so any model it lists works, and on Vercel libfx uses the deployment's OIDC token instead of a key. libfx can also run on a user's own ChatGPT or Grok plan, or on another server through the OpenAI Chat Completions API. See [Providers](#providers).
+
+Importing libfx and calling `createFxAgent()` touch no network, files or processes. The engine loads when a session runs its first turn.
+
+The full documentation is at [fx.sh/docs/lib](https://fx.sh/docs/lib).
+
+## How it fits together
+
+| Object | What it is | How long it lives |
+| --- | --- | --- |
+| Agent | Configuration: model, instructions, tools, provider and where sessions live | As long as the server process |
+| Session | One conversation | As long as its store keeps it |
+| Turn | One prompt and everything the agent does to answer it | Until it ends with a stop reason |
+
+An agent is configuration, and its conversations live in its sessions. Create each agent once per process with the same options on every server, and open a session for each conversation. Any process with that agent can run, continue or stream any of its sessions. An app can have [several agents](#several-agents), each with its own name.
+
+Underneath the agent is `createFxEngine()`, a single conversation with no store, for when you don't want sessions. See [Without sessions](#without-sessions).
+
+## Sessions
 
 ```js
-const agent = await createFxAgent({
-  apiKey,
-  model: { id: "anthropic/claude-opus-5.5-fast", effort: "low", fast: true },
-});
+const turn = agent.session().prompt("Plan the migration.");
+const { sessionId } = await turn.accepted; // the prompt is stored
+
+// Later, in any process that creates the same agent:
+agent.session(sessionId).prompt("Start with the schema.");
 ```
 
-A string `model` remains supported as shorthand. Top-level `effort` and
-`fast` are deprecated but remain supported with a string model or no model;
-they cannot be mixed with a model object. New code should use the model object.
-
-`model.effort` sets the reasoning effort for models that advertise effort
-levels. It uses the same vocabulary as the fx CLI's `--effort` flag:
-`"default"` leaves the choice to the model; named levels such as `"low"`,
-`"medium"`, `"high"`, or `"xhigh"` request a specific level. A named level is
-validated at creation; an unsupported level rejects with an Error carrying
-`code: "LIBFX_MODEL_UNSUPPORTED_EFFORT"`, `model`, and
-`capability: "effort"`. Its message names the supported set when available.
-Omitting effort or using `"default"` leaves the model default in place.
-
-`model.fast` enables the fast lane for models that advertise one, matching the
-fx CLI's `--fast` flag. A model without a fast path rejects at creation with
-`code: "LIBFX_MODEL_UNSUPPORTED_FAST"`, `model`, and `capability: "fast"`.
-Omitting fast or setting it to `false` leaves the model default in place.
-
-`model.ultrafast` requests Ultra mode. It is off by default and maps to
-`openai.serviceTier: "ultrafast"` through the Vercel AI Gateway for models
-whose metadata advertises Ultra eligibility. It uses the higher-cost service tier.
-Set it to `true` only after the host has selected an eligible model; an
-unsupported request rejects with `code: "LIBFX_MODEL_UNSUPPORTED_ULTRAFAST"`,
-`model`, and `capability: "ultrafast"`. Set it to `false` to explicitly disable
-an inherited request. Ultra and Fast are mutually exclusive, so `ultrafast:
-true` disables Fast for the agent. Gateway metadata currently marks Astra
-eligible; libfx does not select Ultra automatically.
-
-The new codes replace `LIBFX_UNSUPPORTED_EFFORT` and `LIBFX_UNSUPPORTED_FAST`
-for both nested and legacy top-level settings. Callers that check the old codes
-must update their error handling.
-
-The host selects the model. Agent creation does not fetch the Gateway model
-catalog unless effort requests a named level, fast is enabled, or ultrafast is enabled. 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
-request metadata, failures, and throttled `transport.activity` liveness while a
-response body is streaming. Activity events include the attempt, current chunk
-bytes, and cumulative response bytes. They call the host directly at most once
-per 250 ms rather than entering the normalized turn queue, so an unread turn
-cannot accumulate heartbeat events. Credentials and raw headers are never
-included.
-
-libfx makes at most one automatic retry after a retryable transport failure and
-only before model output or tool effects escape. Cancellation prevents a retry.
-
-`prompt(input, { signal? })` accepts a string or text, image, and resource
-blocks. It returns an async iterable of normalized events:
-
-- `text_delta`
-- `reasoning_delta` when supplied by the provider
-- `tool_start` with `id`, `name`, and the tool's `input` object. Inputs over
-  64 KiB of JSON arrive as an `inputPreview` string prefix plus
-  `inputTruncated: true` instead; the tool still receives complete arguments.
-- `tool_end`
-- `user_message` with `text` when accepted mid-turn steering enters the turn
-
-Consume the turn while it runs, then await `turn.result`. Streamed text and
-tool results are 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:
+- **One turn at a time.** A prompt sent while a turn runs waits behind it, even when it reaches a different server.
+- **Turns finish on their own.** A turn runs to the end whether or not anyone reads its events, and a turn nobody reads holds no connection open: its view starts reading only once you use its events, `readable` or `result`. Stop it with `session.cancel()`, or with the `signal` you passed to `prompt()`.
+- **Steering.** `session.steer(input)` steers the running turn the way the fx CLI does. While the model streams a reply, the steer cuts it short and the turn continues with it. While a tool runs, the steer waits for the tool. A steer sent while a turn waits to start joins that turn, and when no turn runs or waits, the steer becomes the next turn. A steer with images can't join a turn, so the running turn ends at its next safe point and the steer runs next.
+- **Retries are safe.** Give a prompt or a steer a `messageId`, and a repeated request with the same id runs nothing new. A repeated prompt follows the original turn, and its result has `repeated: true`. One id names one input, so a steer that reuses a prompt's id is rejected with `FX_MESSAGE_ID_IN_USE`. A steer's `user_message` event carries its id as `id` where it joined a turn.
+- **Inputs have a size limit.** A prompt or steer whose input, with the session's `context` and settings, comes to more than 8 MiB of JSON is rejected with `FX_INPUT_TOO_LARGE` before anything is stored. The model can't take a larger one.
+
+Each conversation can bring its own settings, which apply to the turns that session object starts:
 
 ```js
-const turn = agent.prompt("Update the index.");
-for await (const _ of turn) {}
-const result = await turn.result;
+agent.session(sessionId, {
+  model: { id: "anthropic/claude-opus-5.5", effort: "high" },
+  instructions: "You review pull requests.",
+  context: { userId }, // handed to every tool call
+});
 ```
 
-A turn has one event consumer. Breaking out of its iterator cancels the turn;
-`turn.cancel()` and `agent.close()` also release blocked output. Embedded agents
-have no implicit model-step cap, so hosts should cancel turns that exceed their
-own budgets. The CLI's `max_agent_steps` setting does not apply to
-`createFxAgent()`. 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.
-
-Image blocks accept a `Blob` or `File` with a non-empty `type`, raw bytes
-(`Uint8Array`, `Buffer`, `ArrayBuffer`, or another typed array) with an
-explicit `mimeType`, or canonical base64 (no line wrapping) with an explicit
-`mimeType`. The payload must be PNG, JPEG, GIF, or WebP. For a Blob, the MIME
-type is inferred from `Blob.type`; an empty type or a conflicting explicit
-`mimeType` rejects the input:
+A turn's result says how it ended:
 
 ```js
-const turn = agent.prompt([
-  { type: "text", text: "What does this screenshot show?" },
-  { type: "image", data: file, sourceRef: "uploads:screenshot-1" }, // File or Blob, with file.type
-  // Or: { type: "image", data: pngBytes, mimeType: "image/png" }
-  // Or: { type: "image", data: base64Png, mimeType: "image/png" }
-]);
+const { stopReason, usage, error } = await turn.result;
 ```
 
-An optional `sourceRef` identifies a host-owned original. It must be a non-empty
-UTF-8 string of at most 512 bytes, without ASCII control characters (0–31 or
-DEL). With a reference, you may omit `data` entirely:
+`stopReason` is `end_turn`, `max_output_tokens`, `max_model_turns`, `refused` or `cancelled`. It's `error` when the turn failed, with the reason in `error`, and `unknown` when the process running it stopped before recording how it ended.
+
+### Streaming to a browser
+
+`turn.readable` is the turn as newline-delimited JSON, ready to return from a route. `session.stream(cursor)` returns every line after `cursor` and stays open for new ones, so a client that loses its connection reconnects to any server and carries on.
 
 ```js
-agent.prompt([
-  { type: "image", mimeType: "image/png", sourceRef: "uploads:screenshot-1" },
-]);
+// app/api/chat/route.js
+import { agent } from "@/lib/agent";
+
+export async function POST(request) {
+  const sessionId = new URL(request.url).searchParams.get("sessionId") ?? undefined;
+  // Check that the caller may use this session.
+  const turn = agent.session(sessionId).prompt(await request.text());
+  return new Response(turn.readable);
+}
+
+export async function GET(request) {
+  const params = new URL(request.url).searchParams;
+  const sessionId = params.get("sessionId");
+  if (!sessionId) return new Response("sessionId is required", { status: 400 });
+  // Same check as POST.
+  return new Response(agent.session(sessionId).stream(Number(params.get("cursor") ?? 0)));
+}
 ```
 
-Image bytes reach the agent core beside the ACP prompt message rather than
-inside it. Base64 input is decoded before transfer; prompt image bytes are
-encoded as base64 only for the model request. A prompt may contain up to
-8 images, including reference-only blocks. Each image may contain up to
-3.75 MiB (3,932,160 bytes) of raw data, with at most 6 MiB of raw image data
-per prompt. Once encoded for the model request, those limits are 5 MiB per
-image and 8 MiB per prompt. The prompt's text, encoded images, and metadata
-must fit within the same 8 MiB frame budget.
-
-Without `resizeImage`, the SDK checks Blob size before reading it and the actual
-byte count after reading it. If referenced image data would exceed a per-image,
-aggregate image, or combined frame limit, the SDK sends its MIME type and
-reference without image data. Referenced Blobs known to exceed those limits
-remain unread and host-owned. A reference does not increase the limits;
-unreferenced oversized input rejects with typed `RangeError`s.
-
-Base64 that is not canonical throws a `TypeError` from `prompt()`. Raw bytes
-are copied before `prompt()` returns, so the caller can reuse its buffer. Blob
-reads are asynchronous: `prompt()` returns a turn, and read failures reject
-`turn.result`. Cancelling or closing during a Blob read settles the turn without
-sending its prompt. Without `resizeImage`, size errors for unreferenced base64
-and raw-byte input throw synchronously from `prompt()`.
-
-To downscale or convert prompt images before they are sent, pass the optional
-`resizeImage` hook when creating the agent. It receives `{ bytes, mimeType }`,
-where `bytes` is a `Uint8Array`, and returns `{ bytes, mimeType }` directly or
-as a promise. Returned `bytes` may be any typed array or `ArrayBuffer`.
-For a Node.js host that already uses `sharp`:
+Each line is one JSON object with a `type`: the model's events, such as `text_delta` and `tool_start`, and the turn's own, `turn_start` (which carries the `sessionId`), `turn_end`, `turn_resume` and `turn_yield`. Lines from `session.stream()` carry a `cursor`. Store the last one you read and pass it back to resume after it. The `FxStreamLine` type lists every field.
+
+## Durability
+
+libfx stores a prompt before `turn.accepted` resolves, and stores each step of a turn while the turn runs. If the process running a turn dies, the next process that gets work for the session continues the turn from its last stored step. The model is told the turn was interrupted, so it can check what happened before going on.
+
+Where sessions live depends on where your code runs. libfx picks for you:
+
+| Where | Durability | Sessions live in |
+| --- | --- | --- |
+| Vercel | `vercel()` | Vercel's [Workflow World](https://workflow-sdk.dev/worlds), the store and queue behind Vercel Workflow |
+| Node.js | `local()` | Files in `FX_SESSIONS_DIR`, or in `libfx/sessions` under the system's temporary directory |
+| Browsers | `memory()` | The page's memory |
+
+To choose yourself, pass `durability`:
 
 ```js
-import sharp from "sharp";
-
-const agent = await createFxAgent({
-  apiKey,
-  model,
-  async resizeImage({ bytes }) {
-    const png = await sharp(bytes).resize({ width: 1568, withoutEnlargement: true }).png().toBuffer();
-    return { bytes: png, mimeType: "image/png" };
-  },
-});
+import { createFxAgent, memory } from "libfx";
+import { local } from "libfx/durable-local";
+
+createFxAgent({ durability: local({ dir: ".fx/sessions" }) });
+createFxAgent({ durability: memory() }); // nothing outlives the process
 ```
 
-In a browser, return the `ArrayBuffer` from `Blob.arrayBuffer()`, including a
-Blob produced by `OffscreenCanvas.convertToBlob()`. The returned bytes are
-copied, so the hook may reuse its buffer. With `resizeImage`, image size limits
-apply to its output rather than its input; image count and frame metadata
-limits still apply. Image prompts with data are prepared asynchronously like
-a Blob prompt, and a failure inside the hook rejects `turn.result`. This
-opt-in preprocessing reads supplied Blob data even when its original size
-exceeds the limits. Reference-only blocks have no bytes and do not call the
-hook or fetch the original. The hook is host-provided, not a built-in image
-converter or a libfx runtime dependency.
-
-The kernel sniffs the final bytes and compares them with the claimed MIME type
-for every input form that carries data; a mismatch fails the turn with
-`Invalid image prompt block`. Eligible images reach the model unchanged unless
-your hook changes them. Images are routed only to models that advertise image
-input; for any other model the turn fails with
-`Image prompts are unavailable for the selected model` and no image bytes
-leave the process. Images outside the request's pixel or encoded-size limits,
-and reference-only originals, are withheld with model-visible recovery feedback
-that includes their `sourceRef` when supplied.
-
-A source reference is metadata, not an access grant or an automatic fetch.
-Your host owns the original's lifetime, reference resolution, and authorization.
-Expose preparation or retrieval through your existing tools' `execute()`
-callbacks if the agent needs a smaller copy. libfx has no built-in image resizer,
-shell, global converter, or source store, and a reference grants no native
-filesystem authority. If a tool is absent or fails, the original remains
-withheld rather than being sent anyway.
-
-For example, a tool can delegate to your app's authorized image store:
+On `local()`, `vercel()` and `world()`, a session id is a Workflow run id, `wrun_` followed by letters and digits. Take it from `turn.accepted` or `await agent.newSessionId()` instead of making one up. On `memory()`, any 1 to 128 letters, digits, `.`, `_` or `-` work.
+
+A session stores the conversation, and with each prompt and steer the caller's `context` and the session object's settings. Every process passes its own model, credentials, tools, MCP clients and skills when it creates the agent.
+
+libfx doesn't know who is calling. Anyone with a session's id can prompt, steer, cancel, stream or checkpoint it, so your app must check that the caller may use a session before it opens it. A queue message only names an input libfx already stored: a delivery that names one the session's log doesn't hold runs nothing, and the agent's `onEvent` gets a `session.refused` event. If a session's saved checkpoint came from a different libfx version, tool set or model, the session still loads, and `onEvent` gets a `checkpoint.mismatch` event naming what changed.
+
+### Several agents
+
+An app can have more than one durable agent, each with its own model, instructions and tools. Give each one a name:
 
 ```js
-const prepareImage = {
-  name: "prepare_image",
-  description: "Return a new smaller copy of a host-owned image. Use the request limit for maxSide.",
-  inputSchema: {
-    type: "object",
-    properties: { sourceRef: { type: "string" }, maxSide: { type: "integer" } },
-    required: ["sourceRef", "maxSide"],
-  },
-  async execute({ sourceRef, maxSide }, { signal }) {
-    const copy = await imageStore.prepareCopy(sourceRef, { maxSide, signal });
-    return {
-      type: "libfx.tool-result",
-      text: "Prepared a new copy; original unchanged.",
-      images: [{ type: "image", data: copy.base64, mimeType: copy.mimeType, sourceRef }],
-    };
-  },
-};
-// Supply prepareImage in createFxAgent({ tools: [prepareImage], ... }).
+export const support = createFxAgent({ name: "support", instructions: "Answer billing questions." });
+export const coding = createFxAgent({ name: "coding", model: "anthropic/claude-opus-5.5", tools: codingTools });
 ```
 
-`imageStore` is application code, not a libfx API. It must authorize references,
-validate the requested dimensions, and stop conversion when `signal` aborts.
-The returned copy is checked again by the kernel before model submission.
-Typed host-tool images still use base64 `data`; `resizeImage` prepares prompt
-images only.
-
-Version 2 checkpoints retain prompt images as raw image blobs and preserve
-source refs within the existing 4 MiB checkpoint bound on both backends. A
-checkpoint does not store a source file or host-owned original for a
-reference-only block. On restoration, resupply your tools and restore the
-sources those refs identify.
-
-Only one top-level prompt may run at a time. While it runs,
-`await turn.steer(text)` appends guidance at the next safe model boundary
-without discarding the in-flight response or completed tool work. Steering also
-accepts an array of text blocks; image and resource steering blocks are rejected.
-Each message is limited to 64 KiB, with at most 64 queued messages and 1 MiB of
-queued steering text. Accepted steering appears as a `user_message` event before
-the model's continued output. For a Blob prompt or one prepared by
-`resizeImage`, steering during that preparation waits for the prompt to be
-sent; cancelling before then rejects the pending steering. Calling `steer()` after the turn settles rejects with
-`no prompt is running`.
+A session belongs to the agent that created it, and its turns run only on an agent with that name. A prompt sent through another agent, such as `coding.session(supportSessionId).prompt()`, still runs on `support`, and the sending agent's `onEvent` gets a `session.forwarded` event. An agent created without a name is named `default`.
+
+- Agents with the same name are copies of one agent, such as one on each server, and take turns running its sessions. In one process, every agent with a name on a store must have the same configuration: creating one with different options throws `FX_AGENT_NAME_IN_USE`. Agents created without a name or a durability share the name `default` and the default store, so an app that serves several customers gives each customer's agent its own name. Create an agent once, at module scope, or close it when you're done with it.
+- Keep names stable. A session keeps the name it was created with, so renaming an agent leaves its sessions with no agent to run them.
+- A process that gets a turn for a name it has no agent for refuses it with an `FX_NO_AGENT` error naming the agent, and the queue delivers it again.
+- Agents share sessions through their durability. Give agents that share sessions the same durability, or none: agents created without one share the default.
+- One route takes the deliveries for every World in the process and hands each to the agent of its name on the store it names. A World's store is its `store` option, or its name. An app that serves several customers gives each customer a store of its own, with `world()`'s `store`, and never shares one store between customers who must not reach each other's sessions.
+
+### On Vercel
+
+Add a route for libfx's queue deliveries:
 
 ```js
-const turn = agent.prompt("Build the feature.");
-for await (const event of turn) {
-  if (event.type === "tool_end" && event.name === "read_file") {
-    await turn.steer("Keep the public API backward compatible.");
+// app/api/libfx/route.js
+import { wakeHandler } from "libfx";
+import "@/lib/agents"; // creates the app's agents, so this function has them
+
+export const POST = wakeHandler();
+```
+
+The route delivers each turn to the agent it belongs to, so one route serves every agent the module it imports creates. With one agent, `agent.wakeHandler()` does the same.
+
+Then subscribe it to libfx's topic in `vercel.json`:
+
+```json
+{
+  "functions": {
+    "app/api/libfx/route.js": {
+      "experimentalTriggers": [{ "type": "queue/v2beta", "topic": "__libfx_wkf_workflow_session", "retryAfterSeconds": 5 }]
+    }
   }
 }
 ```
 
-Cancelling a steered turn drops any guidance that has not reached a safe
-boundary and releases its queue. Applied guidance is part of the same history
-turn, so an idle `checkpoint()` includes the full steered conversation.
-`checkpoint()` returns opaque, bounded, versioned bytes. Concurrent calls run
-one at a time, and a call still waiting for an earlier one fails the same way a
-direct call would if a prompt starts or the agent closes first. A newer libfx
-restores checkpoints from older versions, but an older libfx cannot restore one
-written by a newer version. Restore them only when creating a fresh agent:
+The trigger makes the route private: it has no public URL, and only Vercel Queues can call it. Keep `wakeHandler()` on that route only. An app whose own World queues to a route the internet can reach must check that each request comes from its queue before it calls `wakeHandler()`. libfx runs only inputs its sessions already stored, but a forged request can still wake a session.
+
+That's all. When no other invocation holds the session, `prompt()` runs the turn in the request that called it, so the first model request goes out without a queue hop, and the function stays alive for the turn after the route responds. Vercel Queues keeps the prompt until after that request's time limit, and if the request dies mid-turn, that delivery continues the turn. Other turns go through Vercel Queues to this route:
+
+- When a turn gets within 30 seconds of the function's time limit, libfx stops it, and the next invocation continues it. `vercel({ reserveMs })` from `libfx/durable-vercel` changes that margin.
+- A function holds its session for as long as Vercel Queues keeps the turn's message for it, so nothing is written while a turn runs to show the function is alive. If the function's process exits mid-turn, Vercel runs the same delivery again about a second later, and that invocation continues the turn.
+- A function that stops without its process exiting holds the message until the queue's hold on it runs out, up to five minutes. A prompt sent to the session meanwhile continues the turn at that function's time limit, if that comes sooner. `vercel({ leaseMs: 15_000 })` bounds that case: the function renews a 15-second lease on its session every 5 seconds, and the session frees about 15 seconds after the last renewal. With it, every prompt goes through the queue instead of running in the request.
+- A function that only stalled and wakes up after that is refused at its next write, so two processes never write one session.
+
+### Tools that change things
+
+When a process dies during a tool call, libfx can't know whether the call finished. So each tool says whether it's safe to run twice:
 
 ```js
-const restored = await createFxAgent({ apiKey, model, checkpoint });
+const byId = { type: "object", properties: { id: { type: "string" } }, required: ["id"] };
+
+const tools = [
+  {
+    name: "get_order",
+    description: "Look up an order.",
+    inputSchema: byId,
+    idempotent: true, // a lookup is harmless to repeat
+    execute: ({ id }) => orders.get(id),
+  },
+  {
+    name: "refund_order",
+    description: "Refund an order.",
+    inputSchema: byId,
+    idempotent: true, // keyed on executionId, so running it again refunds once
+    writes: true,
+    execute: ({ id }, { executionId }) => payments.refund(id, { idempotencyKey: executionId }),
+  },
+];
 ```
 
-An already-aborted prompt signal returns `cancelled` without a model request
-or a history change. The next prompt can run normally.
+When the turn continues, a call to an `idempotent: true` tool runs again. A call to any other tool never runs twice on its own: the model gets an error saying the call may have partly run, and decides whether to check, try again or ask the user. The turn's events end the call with that error too, as a `tool_end` with `isError: true`. libfx refuses a tool that doesn't set `idempotent`, so each one makes that choice. A call that finished before the process died keeps its result, whichever kind of tool it is: libfx stores each result as the call finishes.
 
-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. Reasoning effort, Fast mode, and Ultra mode are
-agent-creation options and are not stored in a checkpoint: recreate the agent
-with new `model.effort`, `model.fast`, or `model.ultrafast` values to change
-them, the same path as switching models.
+Each call's `executionId` stays the same when it runs again. Pass it to the service your tool calls as an idempotency key, and a service that honors idempotency keys won't refund twice. That makes the tool safe to mark `idempotent: true` with `writes: true`.
 
-## Models
+A tool marked `idempotent: true` without `writes: true` starts as soon as the model asks for it, while libfx stores the call. If the process dies before the call is stored, the model asks again and the call gets a new `executionId`, which is harmless for a lookup. Every other tool starts only once its call is stored, so its `executionId` never changes.
+
+### Your own store
 
-Model discovery is explicit and does not create an Agent or load native or Wasm
-artifacts:
+`world()` from `libfx/durable-world` keeps sessions in a [Workflow World](https://workflow-sdk.dev/worlds) you create, such as Workflow's Postgres World:
 
 ```js
-import { listModels } from "libfx";
+import { createWorld } from "@workflow/world-postgres";
+import { createFxAgent } from "libfx";
+import { world } from "libfx/durable-world";
 
-const models = await listModels({
-  apiKey: process.env.AI_GATEWAY_API_KEY,
+const sessions = createWorld({
+  connectionString: process.env.DATABASE_URL,
+  namespace: "libfx",
+  jobPrefix: "libfx_",
+});
+await sessions.start();
+
+export const agent = createFxAgent({
+  durability: world(sessions, { name: "postgres", queueDurable: true }),
 });
 ```
 
-`listModels()` performs one bounded Gateway request and returns sorted, unique
-language-model IDs. It accepts the same optional `fetch` override as the Agent
-API.
+A World that delivers queue messages over HTTP needs `agent.wakeHandler()`, or `wakeHandler()` for several agents, at the address it posts to. Workflow's Postgres World 5.0.2 posts every message to `/.well-known/workflow/v1/flow` on your app. `world()` takes options for what libfx can't learn from the World itself, such as how long a lease lasts and whether the queue keeps a message across crashes. The `WorldOptions` type documents each one.
+
+On a World with Workflow's in-band writer fence, libfx writes each claim and record so that the World itself refuses a write from a worker another has replaced, and nothing of it is stored. libfx finds the fence in the World's capabilities, so there's nothing to configure. On a World without it, libfx detects the replaced worker after its write instead, and the session's log ignores what that worker wrote.
 
-## JavaScript tools and instructions
+## Tools
 
 ```js
-const agent = await createFxAgent({
-  apiKey,
-  model,
-  instructions: "Keep answers concise.",
+const agent = createFxAgent({
   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 });
+    name: "get_order",
+    description: "Look up an order by id.",
+    inputSchema: { type: "object", properties: { id: { type: "string" } }, required: ["id"] },
+    idempotent: true,
+    async execute({ id }, { signal }) {
+      return orders.get(id, { signal });
     },
   }],
 });
 ```
 
-Gateway web search can run at the provider instead of in the JavaScript host.
-Mark its canonical tool name with `providerExecuted: true` and omit `execute`:
+`execute` receives the model's input and a context:
+
+| Field | What it is |
+| --- | --- |
+| `signal` | Aborts when the turn is cancelled |
+| `executionId` | The call's id, the same if the call runs again after a crash |
+| `sessionId` | The session the call belongs to |
+| `context` | A copy of the JSON passed as `context` to `agent.session()`, taken when you call it |
+
+Return a string to send it as is, or any other value to send it as JSON. A thrown error reaches the model as a failed tool result. To return images, return `{ type: "libfx.tool-result", text, images }`, with base64 image data.
+
+Validate the input and authorize the action inside `execute`. libfx orders the calls but grants nothing itself.
+
+On the native backend, calls to idempotent tools from one model response run at the same time, up to 16 at once. A tool that isn't idempotent runs alone, and so does one marked `writes: true`. Mark a tool `writes: false` to let it overlap with others anyway. On WebAssembly, calls run one after another.
+
+`tools` can also be an object keyed by tool name. Add `{ name: "web_search", providerExecuted: true }` for AI Gateway's web search, which runs at the provider instead of in your code.
+
+### MCP and skills
 
 ```js
-const agent = await createFxAgent({
-  apiKey,
-  tools: [{ name: "web_search", providerExecuted: true }],
+import { createMcpAdapter } from "libfx/mcp";
+import { createSkillsAdapter } from "libfx/skills";
+import { loadSkillFile } from "libfx/skills/node";
+
+const mcp = await createMcpAdapter(client, { prefix: "github_" }); // your MCP SDK client
+const skills = createSkillsAdapter([await loadSkillFile("./skills/review/SKILL.md")]);
+
+const agent = createFxAgent({
+  tools: [...mcp.tools, ...skills.tools],
+  instructions: [mcp.instructions, skills.instructions].join("\n\n"),
 });
+
+// When you're done:
+await agent.close();
+await mcp.close();
 ```
 
-The kernel supplies the canonical schema and Gateway advertisement. Currently
-`web_search` is the supported provider-executed descriptor; unknown or local
-names reject agent creation. Provider-executed tools do not
-call host code or require a separate provider key; their `tool_start` and
-`tool_end` events, results, and checkpoint history use the same turn contract.
-Their built-in permission policy is enforced when the request is projected, as
-there is no local call-time effect to approve.
-
-For ordinary tools, the JavaScript host is the authority for 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.
-
-A host tool may use any name, including the kernel's builtin names such as
-`write_file` and `edit_file`: the kernel routes by the registered executor, so
-a host-defined `write_file` calls the host's `execute()` rather than the
-builtin file mutation.
-
-Ordinary objects returned by tools are JSON text. To return rich image content,
-use the typed result:
+libfx doesn't own the MCP connection. You create the client, handle its auth and close it after the agent. `loadSkillFile()` reads one `SKILL.md` and nothing it references.
+
+Every MCP tool comes with `idempotent: false`, since a server's hints can't be trusted. Set it to `true` on a tool you know is safe to run twice. A skill's tools set `idempotent` themselves.
+
+## Models
 
 ```js
-return {
-  type: "libfx.tool-result",
-  text: "Original is available through the host image tools.",
-  images: [
-    { type: "image", mimeType: "image/png", sourceRef: "uploads:screenshot-1" },
-    // A prepared copy may also include data: base64Png.
-  ],
-};
+createFxAgent({ model: { id: "anthropic/claude-opus-5.5", effort: "high", fast: true } });
 ```
 
-Tool images require `mimeType` and accept base64 `data`, or a `sourceRef` with no
-`data`. They do not accept raw bytes or Blobs and do not run `resizeImage`.
-References use the same validation, ownership, recovery feedback, and checkpoint
-rules as prompt images. A result may contain up to 8 images, each with up to
-5 MiB of base64-encoded data. Its text, encoded images, and metadata must fit
-within the 8 MiB result/frame bound. Referenced data is omitted if those bounds
-would overflow; an unreferenced oversized result remains a tool error.
-
-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
-message.
-
-## MCP
-
-`libfx/mcp` accepts a host-owned MCP client. Transport, authentication,
-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.
+`effort` and `fast` mean the same as the fx CLI's `--effort` and `--fast` flags. `ultrafast: true` asks for the faster, more expensive service tier on models that offer it. A setting the model doesn't support fails with an error whose `code` names it, such as `LIBFX_MODEL_UNSUPPORTED_EFFORT`.
 
-```js
-import { createMcpAdapter } from "libfx/mcp";
+`listModels({ apiKey })` returns the ids of AI Gateway's language models. Behind a proxy that forwards only chat requests, pass the catalog yourself as `modelCatalog`, and the agent won't fetch it.
 
-const mcp = await createMcpAdapter(client, {
-  prefix: "github_",
-  resources: ["repo://instructions"],
-  prompts: ["review"],
-});
+## Providers
+
+### AI Gateway
+
+AI Gateway is the default. libfx uses the first credential it finds: the `apiKey` option, then `AI_GATEWAY_API_KEY`, then on Vercel the deployment's OIDC token.
+
+### ChatGPT plans
+
+An agent can run on a user's ChatGPT plan through Codex. Set `provider: "codex"` and give libfx the user's credentials:
 
-const agent = await createFxAgent({
-  apiKey,
-  model,
-  tools: mcp.tools,
-  instructions: mcp.instructions,
+```js
+const agent = createFxAgent({
+  provider: "codex",
+  model: "gpt-6.1-sol",
+  credentials: ({ provider, sessionId }) => tokens.load(provider, sessionId),
+  onCredentials: (credentials, { provider, sessionId }) => tokens.save(provider, sessionId, credentials),
 });
+```
 
-// ...
-await agent.close();
-await mcp.close();
+libfx calls `credentials()` in whichever process runs the turn. It refreshes the credentials shortly before they expire and once after a rejected request, then passes the new ones to `onCredentials` for you to save. Codex doesn't accept requests from web pages, so these turns run on your server.
+
+To sign a user in, use `libfx/chatgpt`:
+
+```js
+import { startSignIn, finishSignIn } from "libfx/chatgpt";
+
+// One request: send the user to signIn.url and keep signIn on the server.
+const signIn = await startSignIn();
+
+// A later request: the user pastes back the address OpenAI opened.
+const credentials = await finishSignIn(signIn, pastedAddress);
 ```
 
-## Skills
+After the user signs in, OpenAI opens a page at `localhost:1455` that doesn't load. That's expected: ask the user to copy the page's whole address and paste it back. If their account or ChatGPT workspace allows device code sign-in, `startDeviceSignIn()` returns a short code to enter on OpenAI's site instead, and `pollDeviceSignIn()` or `completeDeviceSignIn()` waits for it. Each step returns plain data, so a later request or function can finish it.
+
+The sign-in uses the same OpenAI client as the Codex CLI, and the user's ChatGPT plan and OpenAI's terms apply to the turns.
+
+### Grok plans
 
-Use `libfx/skills` for already-loaded records or `libfx/skills/node` to load a
-`SKILL.md` explicitly in Node or Bun.
+`provider: "grok"` runs on a user's Grok plan, with the same `credentials` and `onCredentials` callbacks, called with `provider: "grok"`. libfx also checks that refreshed credentials still belong to the same xAI account. These turns run on your server too.
+
+To sign a user in, use `libfx/grok`. Device code is the simplest:
 
 ```js
-import { loadSkillFile } from "libfx/skills/node";
-import { createSkillsAdapter } from "libfx/skills";
+import { startDeviceSignIn, completeDeviceSignIn } from "libfx/grok";
 
-const record = await loadSkillFile("./skills/review/SKILL.md");
-const skills = createSkillsAdapter([record]);
-const agent = await createFxAgent({ apiKey, model, ...skills });
+// Show device.userCode and a link to device.verificationUrl.
+const device = await startDeviceSignIn();
+
+// Waits until the user enters the code. pollDeviceSignIn() checks once, for a later request.
+const credentials = await completeDeviceSignIn(device);
 ```
 
-## Backends
+`startSignIn()` and `finishSignIn()` work as for ChatGPT, except that xAI opens a page at `127.0.0.1`. The sign-in uses the same xAI client as the fx CLI, and the user's Grok plan and xAI's terms apply to the turns.
+
+### Several servers, one account
+
+The sessions in one process share each refresh. Across servers, two can notice the same expiring credentials at once, and the provider accepts only the first refresh. Pass `refreshLock` so they take turns:
 
 ```js
-await createFxAgent({ apiKey, backend: "auto" });   // native, then Wasm fallback
-await createFxAgent({ apiKey, backend: "native" }); // require N-API
-await createFxAgent({ apiKey, backend: "wasm" });   // require Wasm + JSPI
+refreshLock: ({ provider, sessionId }, refresh) => locks.withLock(`${provider}:${accountOf(sessionId)}`, refresh),
 ```
 
-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.
+libfx calls it with a function to run while you hold a lock on that user's account, for example in Redis. Inside it, libfx calls `credentials()` again and uses what another server already saved.
 
-Use `getBackendInfo()` to inspect backend availability without creating an
-Agent or terminal:
+### Custom providers
+
+An agent can run on a server that speaks the OpenAI Chat Completions API, such as a local model server or a router:
 
 ```js
-import { getBackendInfo } from "libfx";
-
-const info = await getBackendInfo({ surface: "agent", backend: "auto" });
-// {
-//   surface: "agent",
-//   backend: "native" | "wasm-jspi" | "unavailable",
-//   attempts: [{ backend, available, reason }]
-// }
+const router = {
+  name: "router",
+  baseUrl: "https://openrouter.ai/api/v1",
+  models: { "qwen/qwen3-coder": { contextWindow: 128000, supportsToolUse: true } },
+};
+
+const agent = createFxAgent({
+  provider: router,
+  model: "qwen/qwen3-coder",
+  credentials: async ({ provider, sessionId }) => ({ apiKey: await keys.load(provider, sessionId) }),
+});
 ```
 
-`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.
+Requests go to `{baseUrl}/chat/completions`, which must use HTTPS, or HTTP on `localhost`. Leave out `credentials` for a server that needs no key. `models` tells libfx what it can't ask the server: each model's context window and output limit, and whether it takes tools and images. A key isn't refreshed, so a rejected one ends the turn with the server's error. In a browser, the server must accept cross-origin requests, and the page can read the key.
 
-Expected environmental failures resolve as structured attempts. Invalid
-options reject with `TypeError`. The stable reason codes are:
+Saved sessions follow the agent's provider: point an agent at another base URL and its sessions continue there, history included.
 
-| 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, 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.
-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. 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.
+### Where credentials go
+
+libfx adds ChatGPT, Grok and custom-provider credentials to each request in JavaScript, just before it's sent, and sends them only to that provider. They never reach the engine. No credential is written to a saved session or passed to `onEvent`, and if a server quotes a key or token back in an error, libfx masks it before the error reaches the turn.
+
+## Images
 
 ```js
-import { createFxAgent } from "libfx";
+agent.session().prompt([
+  { type: "text", text: "What's wrong with this chart?" },
+  { type: "image", mimeType: "image/png", data: base64Png },
+]);
+```
 
-export const runtime = "nodejs";
+A session stores each prompt as JSON before it runs, so a session prompt takes image data as a base64 string. `createFxEngine()` also takes bytes, a `Blob` or a `File`. Each prompt takes up to 8 PNG, JPEG, GIF or WebP images, at most 3.75 MiB each and 6 MiB together. Pass `resizeImage` to downscale or convert prompt images before they're sent.
 
-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();
-  }
+## Diagnostics
+
+`onEvent` receives diagnostics apart from the model's output: request timing and retries, and session events such as `session.deadline` when a turn stops for a function's time limit. The `FxAgentEvent` type lists them all.
+
+## Instrumentation hooks
+
+Pass `hooks` to `createFxAgent()` or `createFxEngine()` to observe semantic execution on both native and Wasm backends. Your host owns span topology, naming, redaction, and export. libfx doesn't load a tracing library.
+
+```ts
+import { createFxAgent, type FxHookEvent } from "libfx";
+
+const observed: FxHookEvent[] = [];
+const agent = createFxAgent({
+  hooks: {
+    captureContent: true,
+    onEvent(event) { observed.push(event); },
+    onError(error) { console.error("Instrumentation callback failed", error); },
+  },
+});
+```
+
+`FxHookEvent` includes turn and step boundaries, model requests and completions, provider admission and first output, tool execution and accepted results, permission evaluation, and journal restore/commit/error receipts. Events carry the session ID, logical turn ID, and a fresh execution ID for each prompt or resume. Model-call and step ordinals are scoped to that execution; tool call IDs come from the model and survive recovery. Join a tool to its issuing model through `model.end.data.toolCalls`, without matching tool names or parsing UI events.
+
+`tool.end` reports execution; `tool.result` means the result entered the conversation, not that storage accepted it. `journal.commit` follows a successful append and includes its validated cursor and sequence range. Journal receipts are session-scoped, with null turn and execution IDs. A yielded or paused turn stays resumable; `turn.end.data.handoff` identifies an explicit host handoff. Replaying saved results doesn't emit fresh tool execution events; an authorized rerun emits `tool.start` with `rerun: true` and the original call ID.
+
+`wait.start` and `wait.end` describe actual input requests separately from permission evaluation. Their `kind` is `approval`, `question`, `mcp_form`, or `mcp_url`; request IDs pair outcomes, including denial, cancellation, and failure. Native delegation events carry the child session and durable work ID. Child events retain that work ID, their own session/turn/execution identity, and the root and parent session IDs, so the host can join them even if delivery interleaves.
+
+MCP events include the configured server, original remote tool name, and owning fx call ID. `mcp.request.data.requestIdKind` distinguishes a native JSON-RPC ID, an MCP-v2 engine handle, and an explicitly propagated host correlation token. Hooks don't change remote MCP requests by default: the host adapter emits `mcp.start` and `mcp.end` without adding metadata or emitting a request ID. Opt in with `createMcpAdapter(client, { propagateCorrelation: true })` to send an opaque UUID as `_meta["libfx/correlationId"]` and record it in `mcp.request`. It contains no internal execution/call IDs and doesn't request progress notifications. Give the adapter a `serverName` for a stable local identity; otherwise it uses the client's reported server name when available. Native resource/prompt operations also report their server and action.
+
+`mcp.end.status` uses `success`, `failure`, `cancelled`, `input_required`, `unavailable`, or `unknown`. Native tool/protocol failures map to `failure`; `unavailable` means no operation result was available, and `unknown` means observation couldn't classify a returned host result.
+
+Host tools receive `context.observation` when hooks are enabled. Wrap host-owned approvals or questions with `observation.wait(request, effect)`; the effect still owns the decision, response, cancellation, and error. For a host-created child engine, pass `hooks: context.observation.childHooks()` to retain the parent tool relationship. These helpers are optional, and neither requires a tracing library. Native review, vision, title, and compaction calls use the model event family with an explicit purpose; tool-owned model calls include `parentCallId`.
+
+Always call the host effect when `context.observation` is absent too. Disabling hooks must not skip an approval or question; the observer doesn't make permission decisions.
+
+JavaScript host-tool callbacks apply to the engine's own root session, not native descendant sessions. Descendant hook metadata doesn't authorize a cross-session host-tool request. A host-created child engine has its own root session and can install `childHooks()` for lineage.
+
+Content capture defaults to off. Enabling it includes bounded messages, instructions, tool arguments/results, input prompts/answers, and schemas, which can contain sensitive application content. Each event has a shared 64 KiB text budget. For model requests, the newest messages are kept first from the last 128 messages, followed by instructions, tool descriptions, and schemas. Collections keep at most 128 entries, and tool `inputSchemaJson` fields keep at most 8 KiB each. `contentTruncated` marks omissions. JSON text fields can be prefixes after truncation; `inputSchemaJson` is complete JSON or null. Credentials, request headers, raw image bytes, and opaque provider replay state aren't fields in this protocol. Apply your own redaction before export.
+
+Callbacks run in delivery order, but libfx doesn't await their promises. Callback throws and rejections go to `hooks.onError` and don't fail or retry agent work. A slow synchronous callback still delays delivery, so enqueue events and let the host own buffering and flushing. Hooks are best-effort observations, not a durable trace outbox or exactly-once delivery contract. Existing `onEvent` diagnostics and turn UI streams remain separate.
+
+Auxiliary title-model calls can outlive `turn.end` and report model events with the same turn/execution IDs afterward. Their model-call IDs and `purpose: "title"` distinguish them from the finished agent loop.
+
+## Without sessions
+
+`createFxEngine()` is the engine under the agent: one conversation in the memory of one process, with no queue and no session store. Use it for a single request, a subagent inside a tool call, or a conversation you store yourself.
+
+```js
+import { createFxEngine } from "libfx";
+
+const engine = await createFxEngine({ apiKey: process.env.AI_GATEWAY_API_KEY, model: "anthropic/claude-haiku-5.5" });
+
+const turn = engine.prompt("Summarize this file.");
+for await (const event of turn) {
+  if (event.type === "text_delta") process.stdout.write(event.delta);
 }
+
+const checkpoint = await engine.checkpoint(); // opaque bytes, up to 4 MiB
+await engine.close();
+
+const restored = await createFxEngine({ apiKey: process.env.AI_GATEWAY_API_KEY, model: "anthropic/claude-haiku-5.5", checkpoint });
 ```
 
-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.
+An engine differs from a session:
+
+- On AI Gateway, it needs an `apiKey`.
+- One prompt runs at a time, and breaking out of a turn's events cancels the turn.
+- The turn itself has `cancel()` and `steer()`. Like a session's steer, it cuts a streaming reply short and waits for a running tool, and it takes text only.
+
+To have the engine record the conversation as it runs, pass a `persistence` store instead of a checkpoint. A new engine on the same store can then `resume()` a turn the last process left open. A store needs two methods and can add a third, and the bytes are opaque, so it never has to understand them:
+
+```ts
+interface Persistence {
+  load(): Promise<{
+    checkpoint?: { data: Uint8Array; through: string };
+    journal?: Iterable<JournalRecord> | AsyncIterable<JournalRecord>;
+    head?: string | null;
+  }>;
+  append(input: { expected: string | null; idempotencyKey: string; data: Uint8Array; barrier: boolean; marks?: object[] }): Promise<{ cursor: string }>;
+  saveCheckpoint?(input: { through: string; data: Uint8Array }): Promise<void>;
+  marks?: boolean;
+}
+
+interface JournalRecord {
+  cursor: string;
+  data: Uint8Array;
+}
+```
 
-## Interactive terminal
+Reject an `append()` whose `expected` isn't the last stored cursor with `FxFencedError`, so two processes can't write the same conversation. If your store keeps entries of its own after the last record, return the cursor the next `append()` should name as `head`. When a resumed turn left a tool call running, `resume({ onAmbiguous })` lets you return `"rerun"` to run it again under the same `executionId`.
 
-`createFxTerminal()` remains a separate terminal harness API. In browsers,
-connect it to xterm.js with `xtermAdapter()`:
+The engine sends one `append()` at a time, and everything that happens while one is in flight goes in the next record. `barrier` is `true` when the engine waits for the record before it goes on, such as before a tool call with effects. A store may acknowledge a record with `barrier: false` before it is durable, as long as it keeps records in order and acknowledges a barrier only once it and every record before it are durable. Set `marks: true` to receive each record's `marks`, which say where turns start (`{ start: turnId }`), yield and end, and which inputs a turn took (`{ accepted: id }`), so a store can track turns without reading records.
+
+`prompt()` and `resume()` take `yieldAt`, a time in milliseconds since the epoch: the turn stops before its next model request after that time, with the stop reason `yielded`, and the next `resume()` continues it without telling the model it was interrupted.
+
+A journal or `checkpoint` from a newer libfx fails with `FxJournalVersionError`. `createMemoryPersistence()` is a reference store for tests.
+
+## Runtimes
+
+| Runtime | Backend |
+| --- | --- |
+| Node.js 20+ on macOS or Linux, x64 or arm64 | Native addon. Linux needs glibc 2.34 or newer. |
+| Node.js elsewhere | WebAssembly with JSPI. Some Node versions need `--experimental-wasm-jspi`. |
+| Browsers | WebAssembly with JSPI, from `libfx/browser` |
+| Bun | The same as Node.js. For WebAssembly, use Bun 1.4.2 or newer. |
+
+The default `backend: "auto"` tries the native addon first. Pass `"native"` or `"wasm"` to require one, and call `getBackendInfo()` to see what would load without creating anything.
+
+Next.js works in Node.js route handlers, with webpack or Turbopack, and doesn't need `serverExternalPackages`. CommonJS apps can `require("libfx")`. With TypeScript's `moduleResolution: "bundler"`, add `"node"` to `customConditions` to get the Node.js types.
+
+## The fx terminal in a browser
 
 ```js
 import { createFxTerminal, xtermAdapter } from "libfx/browser";
 
-const runtime = await createFxTerminal({
-  terminal: xtermAdapter(term),
-  env: { AI_GATEWAY_API_KEY: "<short-lived credential>" },
+const terminal = await createFxTerminal({
+  terminal: xtermAdapter(term), // an xterm.js Terminal
+  env: { AI_GATEWAY_API_KEY: shortLivedKey },
 });
 
-await runtime.interactive;
+await terminal.interactive;
 ```
 
-The xterm adapter preserves browser-style composer editing for Shift+Enter,
-Command+A, Command+C, Command+X, Command+Z, and Command+Shift+Z. Shift+Enter
-inserts a newline without submitting. A click inside the visible composer moves
-its caret; pointer drags remain xterm terminal-output selections.
-When xterm already has an output selection, Command+C copies that selection
-instead of the composer selection.
-
-The terminal runtime exposes `interactive`, `exited`, `write`, `resize`, and
-`abort`. Terminal session, config, OAuth, prompt-history, clipboard, URL, and
-workspace stores remain terminal-only host integrations. Clipboard copy writes
-through the host `clipboard.writeText(text)` adapter and defaults to
-`navigator.clipboard`.
-
-During `/compact` and automatic compaction, the terminal shows a live
-`Compacting` activity row with elapsed time. Input and cancellation remain
-responsive while the summary request is pending. Compaction progress and
-outcomes do not add transcript entries, including cancellation after resume.
-Stored snapshots retain cancellation-origin metadata; keep them opaque and
-resume with the same or a newer SDK build. Older snapshots remain readable.
+This is the fx CLI's interface compiled to WebAssembly. Your page supplies storage for its sessions, settings and sign-in, and can give it a workspace that runs commands. See [Terminal](https://fx.sh/docs/lib/terminal).
+
+## Entry points
+
+| Import | What's in it |
+| --- | --- |
+| `libfx` | `createFxAgent`, `createFxEngine`, `createFxTerminal`, `memory`, `listModels`, `createMemoryPersistence`, `FxFencedError`, `FxJournalVersionError`, `supportsJspi`, `xtermAdapter`, `encodeXtermKeyEvent`, and on Node.js `getBackendInfo` and `wakeHandler` |
+| `libfx/node`, `libfx/browser` | The same, for Node.js or browsers explicitly |
+| `libfx/wasm` | The WebAssembly SDK without packaged asset paths, so you pass `wasm` yourself |
+| `libfx/durable-local`, `libfx/durable-vercel`, `libfx/durable-world` | `local()`, `vercel()` and `world()` |
+| `libfx/chatgpt`, `libfx/grok` | Sign-in for ChatGPT and Grok plans, and `refreshCredentials` |
+| `libfx/mcp` | `createMcpAdapter` |
+| `libfx/skills`, `libfx/skills/node` | `createSkillsAdapter`, and `loadSkillFile` for Node.js and Bun |
+
+Every entry point ships TypeScript types, and the package has no runtime dependencies.
+
+## For coding agents
+
+- **Docs as Markdown:** [fx.sh/llms.txt](https://fx.sh/llms.txt) indexes every page, and each page has a `.md` version, such as `https://fx.sh/docs/lib/durability.md`. The declarations in `types/` are the exact API.
+- **Agents at module scope:** create each agent once at module scope, not per request, and open `agent.session(id)` for each conversation.
+- **Session ids:** take them from `turn.accepted` or `agent.newSessionId()`. On every durability except `memory()`, an id that isn't a Workflow run id throws.
+- **Side effects:** every tool sets `idempotent`. Set it to `true` only on tools that are safe to run twice, and pass `executionId` to services that take an idempotency key.
+- **Deployments:** on Vercel, the `wakeHandler()` route and its `vercel.json` trigger are both required, or prompts are stored and never run. The route must import the module that creates the agents.
+- **Several agents:** give each durable agent its own `name`, and never rename one that has sessions.
+- **Credentials:** keep keys and ChatGPT or Grok credentials on the server, and the object `startSignIn()` returns too.
+- **Checking a setup:** `getBackendInfo()` reports which backend would load without creating anything or making requests.
+- **Changing libfx:** the source is in the [fx repository](https://github.com/vercel-labs/fx) under `sdk/`. Its `AGENTS.md` files name the tests each change needs.
+
+## Upgrading from 0.0.13
+
+In libfx 0.0.13 and earlier, `createFxAgent()` created the engine. It now creates the durable agent, so rename those calls to `createFxEngine()`. Old code runs against the agent once its tools set `idempotent`, with a few differences: breaking out of a turn's events no longer cancels it, turns have no `cancel()` or `steer()` (the session does), and `persistence` and `sessionId` throw because the durability holds the session.
+
+`libfxApiVersion` is now 3. Every tool given to `createFxAgent()` must set `idempotent`, and a tool's `writes` now defaults to the opposite of `idempotent`, in the engine too, so a tool that isn't marked idempotent runs alone. A journal written by this libfx can't be loaded by an older one, which fails with `FxJournalVersionError`.
 
 ## Security
 
-Treat `nativeAddon` and `gatewayChatUrl` 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.
+Your tools, MCP clients and skill loaders have whatever access your code gives them. libfx orders their calls but grants nothing itself, and the native backend doesn't turn on fx's built-in shell or file tools. Don't put long-lived keys in browser code, and treat the `nativeAddon` and `gatewayChatUrl` options as trusted configuration.
+
+## Contributing
+
+libfx is developed in the [fx repository](https://github.com/vercel-labs/fx), under `sdk/`. Bug reports and pull requests are welcome. See [CONTRIBUTING.md](https://github.com/vercel-labs/fx/blob/main/CONTRIBUTING.md) to get started.
+
+## License
+
+[Apache-2.0](https://github.com/vercel-labs/fx/blob/main/LICENSE)