libfx 0.0.13-dev.1432.g1df91f0b4ebf → 0.0.13-dev.1472.g2c7a4f83f06f

package/README.md

@@ -1,1220 +1,497 @@
 # libfx
 
-`libfx` is the fx agent kernel for JavaScript hosts. You create an agent once
-and open sessions on it. libfx saves each session as it runs, so a crash, a
-function timeout, or a redeploy continues the conversation instead of losing
-it. The same code runs on your machine and on Vercel.
+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.
-
-libfx ships TypeScript declarations for every entry point. Under
-`moduleResolution: "bundler"`, TypeScript reads the browser declarations for
-`libfx` unless `customConditions` includes `"node"`.
-
-## Agent
-
 ```js
 import { createFxAgent } from "libfx";
 
 const agent = createFxAgent({
-  model: "google/gemini-2.5-flash-lite",
+  model: "anthropic/claude-haiku-5.5",
   instructions: "Answer in one paragraph.",
 });
 
-const turn = agent.session().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); // { messageId, stopReason, usage }
 await agent.close();
 ```
 
-`createFxAgent()` returns at once and does no I/O until a session runs a turn.
-`apiKey` is optional. Without it, libfx uses `AI_GATEWAY_API_KEY`, then on
-Vercel the deployment's OIDC token. `model` defaults to fx's built-in model.
-Tools, MCP clients, and skills are agent options, described in
-[JavaScript tools and instructions](#javascript-tools-and-instructions) and the
-sections after it.
+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).
 
-Because nothing loads before a session runs, an option the backend rejects,
-such as an effort level the model does not support, fails that session's
-first turn rather than the `createFxAgent()` call. The turn's `result` has the
-stop reason `error` and the reason in `error`, and `onEvent` receives
-`session.error`.
+Importing libfx and calling `createFxAgent()` touch no network, files or processes. The engine loads when a session runs its first turn.
 
-An agent is the configuration its sessions run under. Every process that
-creates an agent with the same options can run the same sessions, so create
-one agent for your server and open a session per conversation.
-`agent.close()` waits for the turns this process is running, then lets their
-sessions go.
+The full documentation is at [fx.sh/docs/lib](https://fx.sh/docs/lib).
 
-### Sessions
+## How it fits together
 
-`agent.session(id)` opens the session `id`, and `agent.session()` starts a new
-one. Any other value, `null` included, throws. Opening a session reads
-nothing; its first prompt does. A new session's `id` is set once that prompt is
-accepted, so read it from `turn.accepted`:
+| Object | What it is | How long it lives |
+| --- | --- | --- |
+| Agent | Configuration: model, instructions, tools, provider and where sessions live | One per 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 |
 
-```js
-const turn = agent.session().prompt("Plan the migration.");
-const { sessionId } = await turn.accepted;
+An agent is configuration, and its conversations live in its sessions. Create it 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.
 
-// Later, in any process:
-const followUp = agent.session(sessionId).prompt("Start with the schema.");
-```
+Underneath the agent is `createFxEngine()`, a single conversation with no store, for when you don't want sessions. See [Without sessions](#without-sessions).
 
-To know the id before the first prompt, for example so a retried first
-request with the same `messageId` reaches the same session, get one from
-`await agent.newSessionId()` and open it with `agent.session(id)`.
-
-On `memory()`, a session id is 1 to 128 letters, digits, `.`, `_`, or `-`. A
-World durability, `local()`, `vercel()`, or `world()`, keeps each session as a
-World run, so the id is a run id: `wrun_` followed by 10 to 64 letters or
-digits. Take it from `agent.newSessionId()` or `turn.accepted`. Vercel's World
-only creates a run whose id was minted in the last 24 hours, so send a new
-id's first prompt within a day. `agent.prompt()` and `agent.checkpoint()` use
-a session the agent opens for itself, for code that holds one conversation.
-
-One process runs a session's turns at a time, one turn after another. A
-second process that receives a prompt for a busy session queues it behind the
-running turn. Pass `context` to hand JSON to the session's tools:
-`agent.session(id, { context: { userId } })` gives every tool call
-`context` beside its `executionId` and `sessionId`. Each turn runs with the context of the
-`session()` call whose prompt or steer started it, and a call without
-`context` gives its turns none.
-
-A conversation can also choose its own model and instructions.
-`agent.session(id, { model, instructions })` runs the turns it starts with
-that model, a model ID or a model object such as `{ id, effort, fast }`, in
-place of the agent's whole model choice, and with those instructions in place
-of the agent's. They follow the rule `context` follows: a turn keeps the
-settings of the `session()` call that started it, also when another process
-continues it, and a call without them runs with the agent's. Pass a
-conversation's settings on each call; a change applies from its next turn.
-When a session's next turn runs under another model than the one its last
-checkpoint was saved under, the session continues and `onEvent` receives a
-`checkpoint.mismatch` event.
-
-### Turns
-
-`session.prompt(input)` queues `input` as the session's next turn and returns
-a view of that turn. Prompt input is a string or an array of content blocks,
-as described in [prompt input](#prompt-input), except that image data must be a
-base64 string, because the prompt is stored as JSON before it runs. A turn
-view has:
-
-- `messageId`: the turn's id, which libfx chooses unless you pass one.
-- `accepted`: resolves to `{ messageId, sessionId }` once the prompt is stored,
-  or at once for a prompt whose `signal` had already aborted, which is never
-  stored.
-- `result`: resolves to `{ messageId, stopReason, usage }` when the turn ends.
-- Async iteration over the turn's events, as
-  [model and tool events](#prompt-input) describes.
-- `readable`: the same turn as an NDJSON `ReadableStream` that a route can
-  return as its response body. Each line is an event with a `cursor`.
-
-Dropping a turn view cancels nothing: the turn runs to its end whether or not
-anyone reads it. Call `session.cancel()` to stop it. A prompt's `signal`
-cancels that prompt's turn when it aborts, whether the turn is running or still
-waiting behind another, and never a later turn. A prompt whose `signal` had
-already aborted is not stored: its `result` resolves with the stop reason
-`cancelled`.
-
-Give a prompt a `messageId` when the same request can reach your server more
-than once, such as a client retry. A second `prompt()` with an id the session
-already accepted runs nothing: while that turn runs, the view follows it, and
-after it ends, `result` resolves to its outcome with `repeated: true`. When
-that turn failed and its end never reached the stream, `result` resolves with
-the failure from the session's log, without `repeated` if the failure could be
-this request's own run. When the process that ran the turn stopped before
-writing how it ended, `result` resolves with the stop reason `unknown` after
-30 seconds. An id follows the session id rule.
-
-`session.stream(cursor)` returns every event the session has produced from
-`cursor` on, as NDJSON, and stays open for the events after them. Any process
-can serve it, so a browser that loses its connection reconnects with the last
-`cursor` it saw and continues where it stopped. Beside the turn events, the
-stream marks each turn with `turn_start` and `turn_end`, a continued turn with
-`turn_resume`, and a turn that stopped for a function deadline with
-`turn_yield`. `turn_start` and `turn_resume` carry the `sessionId`, so a client
-that started a new session learns its id from the first line of
-`turn.readable`.
-
-Each line carries the `epoch` of the lease its writer held, and epochs only
-rise over a session's life. A worker that was replaced while it ran can still land lines late, because the World accepts
-them. A worker that takes a turn over writes its `turn_resume` line before it
-goes on, and every reader hides a line whose epoch is lower than one before
-it, so the replaced worker's later lines never show and every reader, on any
-server and after any refresh, shows the same lines. A replaced worker's line
-that lands in the moment between its successor's claim and that `turn_resume`
-line still shows; only a World that refuses stale stream writes closes that
-gap.
-
-`session.steer(text)` adds guidance to the running turn at its next model
-request, or to the next turn when none is running. `session.resume()`
-continues a turn a stopped process left open and returns its view, whose
-`result` has the stop reason `idle` when there was none. A prompt also
-continues an open turn before it runs, so most hosts never call `resume()`.
-
-### Durability
-
-The `durability` option chooses where sessions live. Without it, libfx picks
-one from the environment:
-
-| Environment | Durability | Sessions live in |
-| --- | --- | --- |
-| Vercel, where `VERCEL` is set | `vercel()` | Vercel's World, the store and queue behind Vercel Workflow |
-| Node.js elsewhere | `local()` | files in `FX_SESSIONS_DIR`, or `$TMPDIR/libfx/sessions` |
-| Browsers | `memory()` | this page's memory |
+## Sessions
 
 ```js
-import { createFxAgent, memory } from "libfx";
-import { local } from "libfx/durable-local";
+const turn = agent.session().prompt("Plan the migration.");
+const { sessionId } = await turn.accepted; // the prompt is stored
 
-createFxAgent({ durability: local({ dir: ".fx/sessions" }) });
-createFxAgent({ durability: memory() }); // nothing survives the process
+// Later, in any process that creates the same agent:
+agent.session(sessionId).prompt("Start with the schema.");
 ```
 
-`libfx/durable-local` and `libfx/durable-vercel` carry their World inside
-them, and libfx loads one only when a session first needs it, so your app
-installs no other package and an app with no sessions loads neither.
+- **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. Stop it with `session.cancel()`, or with the `signal` you passed to `prompt()`.
+- **Steering.** `session.steer(text)` adds guidance to the running turn at its next model request. When no turn is running, the text becomes the next turn.
+- **Retries are safe.** Give a prompt a `messageId`, and a repeated request with the same id runs nothing new. It follows the original turn, and its result has `repeated: true`.
 
-To keep sessions in a World your app creates, such as Workflow's Postgres
-World, pass it to `world()` from `libfx/durable-world`:
+Each conversation can bring its own settings, which apply to the turns that session object starts:
 
 ```js
-import { createFxAgent } from "libfx";
-import { world } from "libfx/durable-world";
-import { createWorld } from "@workflow/world-postgres";
+agent.session(sessionId, {
+  model: { id: "anthropic/claude-opus-5.5", effort: "high" },
+  instructions: "You review pull requests.",
+  context: { userId }, // handed to every tool call
+});
+```
 
-// libfx's own queue topics and jobs, apart from the app's workflows.
-const sessions = createWorld({ namespace: "libfx", jobPrefix: "libfx_" });
-await sessions.start();
+A turn's result says how it ended:
 
-const agent = createFxAgent({ durability: world(sessions, { queueDurable: true }) });
+```js
+const { stopReason, usage, error } = await turn.result;
 ```
 
-A World you pass in stays yours. libfx never starts or closes it, so start it
-before the agent's first prompt and close it after `agent.close()`. When the
-World delivers in your process, agents given the same World take its
-deliveries in turn, as servers sharing a queue do, and a delivery that arrives
-while no agent is listening fails, so the queue delivers it again. Pass a
-function that returns a World instead, and libfx creates, starts, and closes
-it with the agent. `local()` and `vercel()` are `world()` with the World each
-one bundles.
+`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.
 
-`world()` takes what libfx can't learn from the World itself:
+### Streaming to a browser
 
-| Option | Default | Meaning |
-| --- | --- | --- |
-| `queueDurable` | `false` | The queue keeps a message until a delivery acknowledges it, across crashes. When `false`, `prompt()` stores the prompt in the session before it queues it. |
-| `livenessKnown`, `alive(lease)`, `holderInfo()` | `false` | `alive(lease)` answers whether the holder of a lease still runs, from what `holderInfo()` put in it, so a crashed worker's session frees at once. Without it, a worker renews its lease while it runs, and the session of one that died frees `leaseMs` after its last renewal. |
-| `leaseMs` | 15000 | Without liveness, how long a lease lasts after its worker took or last renewed it. The worker renews it every third of that, and never past its deadline. |
-| `maxDurationMs`, `reserveMs` | no limit, 30000 | Each delivery stops `reserveMs` before `maxDurationMs`, or before the World's `getRuntimeDeadline()` when it has one. |
-| `pollMs` | 1000 | How often a waiting worker reads the session again. |
-| `gatewayKey()` | none | The AI Gateway credential when the agent has no `apiKey`. |
-| `name` | `"world"` | The durability's name in errors. |
-
-libfx uses the World's `events.create` and `events.list`, its streams, its
-queue, and `createQueueHandler`. It reads an event's position in its run from
-the event's id, which must be lowercase letters, an underscore, and that
-position as 26 digits, as in Workflow's Worlds; a session whose World returns
-another id fails. It sends every message on the topic
-`__libfx_wkf_workflow_session` and handles the prefix
-`__libfx_wkf_workflow_`, which is what a Workflow World's `namespace: "libfx"`
-gives, so a World serving the app's own workflows on the default namespace
-needs a second instance for libfx. A World with `registerHandler` delivers to
-the agent in its process. Any other World delivers over HTTP, so mount
-`agent.wakeHandler()` where it delivers, as [Next.js and
-Vercel](#nextjs-and-vercel) shows.
-
-libfx records each step of a turn as it happens. A prompt is stored before
-the caller hears it was accepted, and a tool call with effects is stored
-before it runs, so a crash never loses an accepted prompt and never repeats a
-tool call silently. When a session has no turn in progress, the process that
-takes it sends the next turn's first model request while it writes its claim
-on the session, and it writes, shows, and runs nothing for that turn until
-the claim lands. If another process's claim lands first, the late claim
-counts for nothing and its model request is cancelled. Other records are
-written while the model works, without holding up the turn. A session also
-saves a checkpoint at the end of every turn and wherever a turn yields, so the
-process that continues it reads the checkpoint and the few records after it,
-not the whole history.
-
-When the process running a turn stops, the next process to receive work for
-the session continues the turn from its last record:
-
-- On `local()`, a session held by a process that died is free at once.
-- On `vercel()`, where libfx cannot tell whether a function still runs, a
-  worker renews a 15 second lease while it runs. When its function dies, its
-  session frees 15 seconds after the last renewal, and the next delivery for
-  it continues the turn. When
-  the deadline is near, libfx stops before the next model request and saves
-  the turn, and the next invocation continues it. A model request or tool
-  call still running shortly before the deadline is cut off: `onEvent`
-  receives `session.deadline`, and the next invocation continues the turn,
-  running a cut-off idempotent call again and telling the model about any
-  other. The event's `cutoffs` counts the times in a row the deadline cut
-  off the same step. After 3, the next invocation does not run that step
-  again: a call is answered as possibly run, so the model decides what to do
-  next, and a model request cancels the turn. So a process never runs on
-  after the deadline its hold ends at. A
-  process that freezes, or whose renewals stall for a lease, and wakes after
-  another took its session over stops at its next write, a renewal included,
-  and `onEvent` receives `session.fenced`. Until then it
-  can finish a model request or a call to an idempotent tool; it never starts
-  a tool with effects, because that waits for its record to be stored. A
-  process that started a new turn on an idle session and was taken over
-  while still claiming the session runs nothing for that turn and reads the
-  session's log again instead, so the prompt it brought is not lost.
-- When a write fails for any other reason, or the engine running a turn stops,
-  `onEvent` receives `session.error`, and the same queue message runs the
-  session again with a new engine. A turn whose engine stops 3 times is
-  cancelled, and the prompts behind it run; one that never got started ends
-  with an error instead. When the engine stops twice more, even to cancel the
-  turn, the session can run no more turns: the turn and every prompt sent to
-  the session end with an error. A turn whose engine stops after storing its
-  end resolves with the stop reason `unknown`.
-- When an engine cannot open, the turn waiting on it ends with an error, and
-  each later engine that cannot open ends the next waiting prompt the same
-  way. A started turn that ended this way stays open in the session, and
-  `session.resume()` answers `idle` for it. The next prompt's engine first
-  continues it, or cancels it when it was cancelled or its engine kept
-  stopping, and then runs that prompt.
-- On `memory()`, sessions end with the process.
-
-The model is told when its turn was interrupted, so it can check what
-happened before going on. A turn that stopped at a model request for a
-deadline continues without that notice; one whose call was cut off gets it.
-
-A durability holds conversation history only. Every process supplies the
-model, credentials, instructions, tools, MCP clients, and skills when it
-creates the agent. Every checkpoint records the libfx version, tool set, and
-model that saved it. When a saved session, or a checkpoint passed as
-`checkpoint`, was saved under different ones than the agent now has, it still
-loads, and `onEvent` receives a `checkpoint.mismatch` event naming what
-changed.
-
-`session.checkpoint()` returns the session's history as opaque bytes, read
-without changing the session. Pass them as `checkpoint` to start a new agent's
-own session from them, for example to move a conversation between
-durabilities.
-
-### Tools with effects
-
-When a process stops while a tool call runs, libfx cannot know whether the
-call finished. Mark a tool `idempotent: true` when running it twice is safe,
-such as a lookup:
+`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
-const tools = [
-  { name: "get_order", description: "Looks up an order", idempotent: true, inputSchema, async execute(input, { executionId }) { /* ... */ } },
-  { name: "refund_order", description: "Refunds an order", inputSchema, async execute(input, { executionId }) { /* ... */ } },
-];
+// 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)));
+}
 ```
 
-An idempotent call that was running runs again when the turn continues. Any
-other call never runs again on its own: the turn continues at once, and the
-model receives that call's result as an error saying it may have partly run,
-so it can check the call's effects before calling it again or ask the user.
+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.
 
-`executionId` is the same for a call each time it runs, including after a
-crash. Pass it to the service the tool calls, as an idempotency key, so a call
-that runs again changes nothing twice. Calls to idempotent tools also start
-without waiting for their record to be stored.
+## Durability
 
-## Model options
+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.
 
-Model configuration groups the model ID and model-specific options:
+Where sessions live depends on where your code runs. libfx picks for you:
 
-```js
-const agent = createFxAgent({
-  model: { id: "anthropic/claude-opus-5.5-fast", effort: "low", fast: true },
-});
-```
+| 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 |
 
-Agent configuration uses named options; `env` is reserved for
-`createFxTerminal()`. 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.
-
-## A single engine
-
-`createFxEngine()` is the kernel under `createFxAgent()`: one conversation,
-held in the memory of the process that runs it, with no queue and no session
-store. Use it to run turns inside one request and keep nothing, or to keep a
-conversation in storage of your own through [persistence](#persistence). It
-takes the same model, tool, MCP, and skill options, `apiKey` is required, and
-it resolves once its backend has loaded. In this section, `agent` is an engine:
+To choose yourself, pass `durability`:
 
 ```js
-import { createFxEngine } from "libfx";
+import { createFxAgent, memory } from "libfx";
+import { local } from "libfx/durable-local";
 
-const agent = await createFxEngine({ apiKey: process.env.AI_GATEWAY_API_KEY, model });
+createFxAgent({ durability: local({ dir: ".fx/sessions" }) });
+createFxAgent({ durability: memory() }); // nothing outlives the process
 ```
 
-### Code written for libfx 0.0.12
-
-In libfx 0.0.12, `createFxAgent()` created this engine. It now creates the
-durable agent, so rename those calls to `createFxEngine()`. Code that still
-calls `createFxAgent()` keeps running, with these differences:
-
-- `await createFxAgent(...)` resolves to the durable agent, because awaiting a
-  value that is not a promise returns the value.
-- Breaking out of a turn's events no longer cancels the turn, which runs to
-  its end. Cancel it with the prompt's `signal` or `session.cancel()`.
-- Turns have no `cancel()` or `steer()`, and the agent has no `followUp()` or
-  `resume()`. A session has `steer()`, `cancel()`, and `resume()`.
-- `persistence` and `sessionId` throw, because the durability holds the
-  session.
-
-On the native backend, host tools now run alongside each other unless they
-are marked `writes: true`, in `createFxEngine()` as well. WebAssembly runs
-them one at a time.
+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.
 
-### Prompt input
+A session stores the conversation and nothing else. Every process passes its own model, credentials, tools, MCP clients and skills when it creates the agent. 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.
 
-`prompt(input, { signal? })` accepts a string or text, image, and resource
-blocks. It returns an async iterable of normalized events:
+### On Vercel
 
-- `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:
+Add a route for libfx's queue deliveries:
 
 ```js
-const turn = agent.prompt("Update the index.");
-for await (const _ of turn) {}
-const result = await turn.result;
+// app/api/libfx/route.js
+import { agent } from "@/lib/agent";
+
+export const POST = agent.wakeHandler();
 ```
 
-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
-`createFxEngine()`. 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:
+Then subscribe it to libfx's topic in `vercel.json`:
 
-```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" }
-]);
+```json
+{
+  "functions": {
+    "app/api/libfx/route.js": {
+      "experimentalTriggers": [{ "type": "queue/v2beta", "topic": "__libfx_wkf_workflow_session" }]
+    }
+  }
+}
 ```
 
-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:
+That's all. `prompt()` sends each turn to Vercel Queues, and this route runs it:
 
-```js
-agent.prompt([
-  { type: "image", mimeType: "image/png", sourceRef: "uploads:screenshot-1" },
-]);
-```
+- When a turn gets within 30 seconds of the function's time limit, libfx stops it, and the next invocation continues it.
+- The function running a turn renews a 15-second lease on its session. If the function dies, the session frees when the lease runs out, and the turn continues in a new invocation.
+- A function that only stalled and wakes up after that is refused at its next write, so two processes never write one session.
 
-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`:
+`vercel({ reserveMs, leaseMs })` from `libfx/durable-vercel` changes both timings.
 
-```js
-import sharp from "sharp";
-
-const agent = await createFxEngine({
-  apiKey,
-  model,
-  async resizeImage({ bytes }) {
-    const png = await sharp(bytes).resize({ width: 1568, withoutEnlargement: true }).png().toBuffer();
-    return { bytes: png, mimeType: "image/png" };
-  },
-});
-```
+### Tools that change things
 
-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:
+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 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"],
+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),
   },
-  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 }],
-    };
+  {
+    name: "refund_order",
+    description: "Refund an order.",
+    inputSchema: byId,
+    execute: ({ id }, { executionId }) => payments.refund(id, { idempotencyKey: executionId }),
   },
-};
-// Supply prepareImage in createFxEngine({ tools: [prepareImage], ... }).
+];
 ```
 
-`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`.
+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.
 
-```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.");
-  }
-}
-```
+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.
 
-`steer()` resolves to `{ id }`, and the returned promise carries the same `id`
-at once. Until the model sees a steer, `turn.withdraw(id)` takes it back and
-resolves to `withdrawn`; after that it resolves to `already_placed`. With
-[persistence](#persistence), a steer resolves only once its acceptance is stored, a model request
-carries it only after that, and a withdrawal resolves once it is stored, so a
-crash never loses a steer the call reported as accepted: `agent.resume()`
-delivers one the model had not seen yet. The web core accepts a steer when it
-takes it at the next boundary, so there `steer()` resolves then, and a steer
-still queued when the turn ends rejects.
-
-`agent.followUp(input)` queues text to run as its own turn once the current
-turn ends, or at once when none is running, instead of failing with
-`a prompt is already in progress`. It returns a promise for that turn; the
-promise carries the follow-up's `id` and `accepted`, which resolves `{ id }`
-once it is stored. With persistence, a follow-up survives a crash. After a
-restore, the follow-ups the session held have no caller, so each waits for
-`agent.resume()`: every call continues the open turn first, then starts the
-next held follow-up, and returns `null` once none is left. Follow-ups this
-agent queues run on their own and do not wait behind held ones. Call `resume()`
-until it returns `null` whenever a session opens, before this agent queues
-follow-ups of its own: one queued during a resumed turn starts when that turn
-ends, and `resume()` throws while it runs. A follow-up whose turn ends before
-libfx records its first `turn_progress` is withdrawn, and one that ends after
-it is recorded like any other turn, so a follow-up never runs twice. `close()`
-rejects follow-ups that have not started; the session's records still hold them.
-
-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:
+### Your own store
+
+`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
-const restored = await createFxEngine({ apiKey, model, checkpoint });
-```
+import { createWorld } from "@workflow/world-postgres";
+import { createFxAgent } from "libfx";
+import { world } from "libfx/durable-world";
 
-An already-aborted prompt signal returns `cancelled` without a model request
-or a history change. The next prompt can run normally.
+const sessions = createWorld({
+  connectionString: process.env.DATABASE_URL,
+  namespace: "libfx",
+  jobPrefix: "libfx_",
+});
+await sessions.start();
 
-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.
+export const agent = createFxAgent({
+  durability: world(sessions, { name: "postgres", queueDurable: true }),
+});
+```
 
-### Persistence
+A World that delivers queue messages over HTTP needs `agent.wakeHandler()` 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.
 
-Pass a store as `persistence`, and libfx records the session as it runs, so a
-new agent can continue it after the process running it stops. libfx writes
-opaque records and checkpoints to the store and reads them back. The store
-never parses them, and libfx never sees how they are stored.
+## Tools
 
 ```js
-import { createFxEngine, createMemoryPersistence } from "libfx";
-
-const persistence = createMemoryPersistence();
-const agent = await createFxEngine({ apiKey, model, persistence, sessionId: "support-42" });
+const agent = createFxAgent({
+  tools: [{
+    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 });
+    },
+  }],
+});
 ```
 
-A store is an object with these methods:
-
-```ts
-interface Persistence {
-  load(): Promise<{
-    checkpoint?: { data: Uint8Array; through: string };
-    journal?: Iterable<JournalRecord> | AsyncIterable<JournalRecord>;
-  }>;
-  append(input: { expected: string | null; idempotencyKey: string; data: Uint8Array }): Promise<{ cursor: string }>;
-  saveCheckpoint?(input: { through: string; data: Uint8Array }): Promise<void>;
-}
+`execute` receives the model's input and a context:
 
-interface JournalRecord {
-  cursor: string;
-  data: Uint8Array;
-}
-```
+| 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` | The JSON passed as `context` to `agent.session()` |
 
-`append()` stores one record and resolves to its cursor, a string the store
-chooses that places the record after the ones before it. The session's records
-are its journal. libfx sends records one at a time, in order, and `expected`
-is the cursor of the last record the agent knows of, or `null` for a new
-session. Reject the append with an `FxFencedError` when `expected` is not the
-cursor of the last stored record, so that a second agent writing the same
-session stops the first instead of interleaving with it. `idempotencyKey` is
-unique to each write, so a store that retries a write can return the stored
-record's cursor instead of storing it twice.
-
-`createFxEngine()` calls `load()` once. Resolve to the latest checkpoint, if any,
-and the records stored after it, oldest first, each with its cursor. Resolve to
-`{}` for a session with nothing stored. libfx skips any record the checkpoint
-already covers.
-
-libfx waits for the store only where a crash could otherwise lose work or
-repeat it: the first record of each turn, which holds the prompt, is stored
-before the model sees it, and a response's tool calls are stored before any of
-them starts. Other appends are not waited for, so a turn's `result` can settle
-before its last records land, and `agent.close()` waits for every append. If
-`append` rejects, libfx stops the current turn at once: it starts no further
-model request or tool call and writes nothing more. The turn fails with an
-error whose `code` is `FX_JOURNAL_APPEND_FAILED` and whose `cause` is your
-error, and the agent refuses later prompts. When no turn was left to report
-the failure, `close()` rejects with it. A model request the turn started while
-the failed append was in flight can still complete.
-
-When the store has `saveCheckpoint()`, libfx saves a checkpoint after a turn
-ends or yields once the records stored since the last checkpoint reach
-`checkpointAfterBytes` (default 1 MiB). A checkpoint where a turn yielded
-holds the open turn, and the next load continues it. `through` is the cursor of the last
-record the checkpoint covers, so `load()` can return that checkpoint and only
-the records after it, and the cost of opening a session stays bounded as its
-history grows. libfx takes a checkpoint only while no turn is running. A saved
-checkpoint emits a `checkpoint.save` event. A failed save emits
-`checkpoint.error` and changes nothing: the records still restore the session,
-and the next turn's end tries again. Deleting the records a checkpoint covers
-is up to the store.
-
-The records a load reads, after libfx drops the older progress of an open
-turn, must fit in 4 MiB of JSON, a checkpoint in 4 MiB, and the history in
-1,024 turns. Otherwise `createFxEngine()` rejects with an error whose `code` is
-`FX_JOURNAL_TOO_LARGE`. libfx refuses records that repeat, skip, or do not
-parse, and `createFxEngine()` rejects with the reason and the `code`
-`FX_JOURNAL_INVALID`. For records written by a newer libfx, it rejects with an
-`FxJournalVersionError`, whose `code` is `FX_JOURNAL_VERSION`. Each libfx
-release resumes the sessions and checkpoints that the release before it saved,
-so upgrade the processes that read a session before the ones that write it.
-
-AI Gateway keys session affinity and prompt caching to the session's id. libfx
-picks a new id for each agent unless you pass `sessionId`, so give a restored
-session the id it had before. An id is 1 to 255 letters, digits, `.`, `_`, or
-`-`. `agent.sessionId` is the id the agent uses.
-
-If the last process stopped during a turn, `agent.resume()` continues that
-turn with no new input and returns it, like `prompt()`. The model is told
-"Resuming from unexpected session interruption.". A tool call that was
-running does not run again: it comes back answered with an error saying it may
-have partly run, and the model decides whether to check its effects, call it
-again, or ask the user. A turn that fails or is cancelled ends in the journal
-as it does in the agent, so only a stopped process leaves one to resume.
-`resume()` returns `null` when the session holds no open turn and no held
-follow-up, so a host can call it until it does every time it opens a session:
+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.
 
-```js
-const agent = await createFxEngine({ apiKey, model, persistence, sessionId, tools });
-for (let turn = agent.resume(); turn; turn = agent.resume()) {
-  for await (const event of turn) console.log(event);
-  await turn.result;
-}
-```
+On the native backend, the calls from one model response run at the same time, up to 16 at once. Mark a tool `writes: true` to keep its calls from overlapping any other. On WebAssembly, calls run one after another.
 
-When your host knows a call never ran, such as one it handed to another
-process before the call did anything, pass `resume({ onAmbiguous })`. libfx
-calls `onAmbiguous({ executionId, name, input })` once for each call the turn
-left running, and each call it returns `"rerun"` for runs again under the same
-`executionId` before the turn continues. Every other call keeps the answer that it may
-have partly run.
-
-Calling `prompt()` instead ends the open turn as interrupted and starts a new
-one.
-
-Give a prompt a `turnId` when the same request can reach libfx more than once,
-such as from a queue that delivers it again after a crash. When the open turn
-has that id, `prompt(input, { turnId })` continues it as `resume()` does, and
-takes `onAmbiguous` the same way. When
-the session's last turn ended with that id, it returns a turn that has already
-ended, with the stop reason `end_turn`, without calling the model. Any other id
-starts a new turn. A turn id is 1 to 128 letters, digits, `.`, `_`, or `-`.
-Without one, libfx names the turn. `turn.id` is the turn's id.
-
-To move a running session to another process, call
-`turn.cancel({ reason: "handoff" })`. The turn stops at once, like any
-cancellation, but libfx stores nothing more, so the journal keeps the turn
-open and the agent that opens the session next continues it with `resume()`.
-The handed-off agent then refuses `prompt()`, `resume()`, and `followUp()`;
-close it. A handoff needs persistence.
-
-Pass `persistence` instead of a `checkpoint` option; the two cannot be
-combined. Like a checkpoint, persistence holds conversation history only:
-resupply models, credentials, instructions, tools, MCP clients, and skill
-records when you create the agent. A resumed turn continues under the tools the
-new agent has. `createMemoryPersistence()` keeps the records and the latest
-checkpoint in memory as `persistence.records` and `persistence.checkpoint`,
-which suits tests and hosts that copy them to their own storage. It fences an
-append whose `expected` cursor is not its last record's, and returns the stored
-cursor for a repeated `idempotencyKey`. `FxFencedError` is exported by `libfx`;
-its `code` is `FX_FENCED`, which a store of your own can use for the same case.
-`FxJournalVersionError` is exported by `libfx` too.
+Validate the input and authorize the action inside `execute`. libfx orders the calls but grants nothing itself.
 
-## Models
+`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.
 
-Model discovery is explicit and does not create an Agent or load native or Wasm
-artifacts:
+### MCP and skills
 
 ```js
-import { listModels } from "libfx";
+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 models = await listModels({
-  apiKey: process.env.AI_GATEWAY_API_KEY,
+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();
 ```
 
-`listModels()` performs one bounded Gateway request and returns sorted, unique
-language-model IDs. It accepts the same optional `fetch` override as the Agent
-API.
-
-An agent reads the AI Gateway model catalog to learn what its model supports,
-such as image input, reasoning effort, and output limits, and those details
-shape every request. It fetches the catalog through your `fetch`. If that
-request fails, for example behind a proxy that only forwards chat requests,
-the agent cannot confirm the model's capabilities and refuses image prompts.
-Pass `modelCatalog` to supply the catalog instead: the entries from
-`https://ai-gateway.vercel.sh/coding-agent/v1/models`, either the response's
-`{ data }` or the array, or only the entries for the models you use. The agent
-then makes no catalog request, so every process that receives the same
-entries builds the same requests:
+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.
+
+## Models
 
 ```js
-const agent = createFxAgent({ apiKey, model, modelCatalog });
+createFxAgent({ model: { id: "anthropic/claude-opus-5.5", effort: "high", fast: true } });
 ```
 
-## JavaScript tools and instructions
+`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
-const agent = createFxAgent({
-  apiKey,
-  model,
-  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 });
-    },
-  }],
-});
-```
+`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.
+
+## Providers
+
+### AI Gateway
 
-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`:
+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:
 
 ```js
 const agent = createFxAgent({
-  apiKey,
-  tools: [{ name: "web_search", providerExecuted: true }],
+  provider: "codex",
+  model: "gpt-6.1-sol",
+  credentials: ({ provider, sessionId }) => tokens.load(provider, sessionId),
+  onCredentials: (credentials, { provider, sessionId }) => tokens.save(provider, sessionId, credentials),
 });
 ```
 
-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.
-
-`tools` may also be an object keyed by tool name, such as
-`tools: { lookup, save }`, where each value is a descriptor without `name`.
-A descriptor that does include `name` must match its key.
-
-When one model response calls several tools, the native backend runs them at
-the same time and returns their results to the model in the order it called
-them. Mark a tool `writes: true` when its calls must not overlap others: it
-starts after every earlier call in the response finishes, and later calls
-wait for it. WebAssembly runs calls one at a time. Every call still goes
-through its own permission check before any of them starts.
-
-`execute` receives `{ signal, executionId, sessionId }`, plus `context` when
-the turn has one. `executionId` is the model's id for the call and stays the same when
-the call runs again after a crash, so a tool with an external effect can pass
-it on as an idempotency key. [Tools with effects](#tools-with-effects)
-describes which calls run again.
-When a tool rejects with an empty message, the model receives a non-empty error
-so the provider does not refuse the conversation.
-
-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 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
-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.
-  ],
-};
-```
+import { startSignIn, finishSignIn } from "libfx/chatgpt";
 
-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.
+// One request: send the user to signIn.url and keep signIn on the server.
+const signIn = await startSignIn();
 
-```js
-import { createMcpAdapter } from "libfx/mcp";
+// A later request: the user pastes back the address OpenAI opened.
+const credentials = await finishSignIn(signIn, pastedAddress);
+```
 
-const mcp = await createMcpAdapter(client, {
-  prefix: "github_",
-  resources: ["repo://instructions"],
-  prompts: ["review"],
-});
+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.
 
-const agent = createFxAgent({
-  apiKey,
-  model,
-  tools: mcp.tools,
-  instructions: mcp.instructions,
-});
+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.
 
-// ...
-await agent.close();
-await mcp.close();
-```
+### Grok plans
 
-## Skills
+`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.
 
-Use `libfx/skills` for already-loaded records or `libfx/skills/node` to load a
-`SKILL.md` explicitly in Node or Bun.
+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 = 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
-createFxAgent({ apiKey, backend: "auto" });   // native, then Wasm fallback
-createFxAgent({ apiKey, backend: "native" }); // require N-API
-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.
+
+### Custom providers
 
-Use `getBackendInfo()` to inspect backend availability without creating an
-Agent or terminal:
+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.
-
-Create one agent for the server and open a session per request. The route
-returns the turn's stream and never runs the agent itself:
+### Where credentials go
 
-```js
-// lib/agent.js
-import { createFxAgent } from "libfx";
+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
 
-export const agent = createFxAgent({ model: "anthropic/claude-haiku-4.5", tools });
+```js
+agent.session().prompt([
+  { type: "text", text: "What's wrong with this chart?" },
+  { type: "image", mimeType: "image/png", data: base64Png },
+]);
 ```
 
+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.
+
+## 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.
+
+## 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
-// app/api/chat/route.js
-import { agent } from "@/lib/agent";
+import { createFxEngine } from "libfx";
 
-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);
-}
+const engine = await createFxEngine({ apiKey: process.env.AI_GATEWAY_API_KEY, model: "anthropic/claude-haiku-5.5" });
 
-// Reconnects from any server.
-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 });
-  // The same check as POST.
-  const stream = agent.session(sessionId).stream(Number(params.get("cursor") ?? 0));
-  return new Response(stream);
+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 });
 ```
 
-On your machine, the server runs each turn in its own process and keeps the
-session with `local()`. On Vercel, `prompt()` sends the prompt to Vercel Queues, and a separate
-invocation runs the turn while the `POST` response streams it. If the route's
-response ends first, the turn keeps running, and the client reconnects with
-the last `cursor` it read.
+An engine differs from a session:
 
-Until Vercel's World can deliver queue messages to the function itself, mount
-the agent's delivery route and subscribe it to libfx's queue topic in
-`vercel.json`:
+- 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()`.
 
-```js
-// app/api/libfx/route.js
-import { agent } from "@/lib/agent";
+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:
 
-export const POST = agent.wakeHandler();
-```
+```ts
+interface Persistence {
+  load(): Promise<{
+    checkpoint?: { data: Uint8Array; through: string };
+    journal?: Iterable<JournalRecord> | AsyncIterable<JournalRecord>;
+  }>;
+  append(input: { expected: string | null; idempotencyKey: string; data: Uint8Array }): Promise<{ cursor: string }>;
+  saveCheckpoint?(input: { through: string; data: Uint8Array }): Promise<void>;
+}
 
-```json
-{
-  "functions": {
-    "app/api/libfx/route.js": {
-      "experimentalTriggers": [{ "type": "queue/v2beta", "topic": "__libfx_wkf_workflow_session" }]
-    }
-  }
+interface JournalRecord {
+  cursor: string;
+  data: Uint8Array;
 }
 ```
 
-The delivery route's maximum duration bounds each invocation. libfx stops a
-turn 30 seconds before the deadline, at its next model request, and cuts off a
-call still running 2 seconds before it; either way the same queue message runs
-the rest of the turn in a new invocation. Pass
-`durability: vercel({ reserveMs })` from `libfx/durable-vercel` to change that
-margin. A function that dies mid-turn holds its session for at most
-`leaseMs` after its last renewal, 15 seconds unless you pass
-`vercel({ leaseMs })`. libfx authenticates to the AI Gateway with the deployment's OIDC token
-unless you pass `apiKey` or set `AI_GATEWAY_API_KEY`.
+Reject an `append()` whose `expected` isn't the last stored cursor with `FxFencedError`, so two processes can't write the same conversation. `createMemoryPersistence()` is a reference store for tests. When a resumed turn left a tool call running, `resume({ onAmbiguous })` lets you return `"rerun"` to run it again under the same `executionId`.
+
+## 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. |
 
-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.
+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.
 
-## Interactive terminal
+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.
 
-`createFxTerminal()` remains a separate terminal harness API. In browsers,
-connect it to xterm.js with `xtermAdapter()`:
+## 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;
 ```
 
-Pass `args: ["--fast"]` to request Fast mode. The terminal loads model
-capabilities when its first Fast or Ultra turn starts, without adding catalog
-requests to startup. After the catalog loads, `/fast` toggles Fast for later
-turns. Models without Fast support use their normal routing.
-
-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`.
-
-A terminal with a `workspace` adapter loads AGENTS.md project instructions from
-it the way the CLI reads them from disk: `<home>/.fx/AGENTS.md`,
-`<root>/AGENTS.md`, and, when `root` is below `home`, the `AGENTS.md` files in
-the directories between them. Provide them through an optional `readFile`
-method:
+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).
 
-```js
-const workspace = {
-  info: { version: 1, root: "/workspace", cwd: "/workspace", home: "/home/visitor", gitAvailable: false, ephemeral: true },
-  permission: "allow-sandboxed",
-  exec({ command, cwd, signal, timeoutMs, outputLimitBytes }) { /* run one command */ },
-  async readFile({ path, signal }) {
-    // Return a string, UTF-8 bytes (a Uint8Array or ArrayBuffer), or null when the file does not exist.
-  },
-};
-```
+## Entry points
+
+| Import | What's in it |
+| --- | --- |
+| `libfx` | `createFxAgent`, `createFxEngine`, `createFxTerminal`, `memory`, `listModels`, `createMemoryPersistence`, `FxFencedError`, `FxJournalVersionError`, `supportsJspi`, `xtermAdapter`, `encodeXtermKeyEvent`, and on Node.js `getBackendInfo` |
+| `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 |
 
-fx calls `readFile` only for absolute `AGENTS.md` paths inside `root` or
-`home`. Each read has a 10-second deadline, the interrupt key aborts it through
-`signal`, and the CLI's project instruction size limits apply. Without
-`readFile`, fx tells the model that the workspace's project instructions were
-omitted and records the omission in the full transcript.
+Every entry point ships TypeScript types, and the package has no runtime dependencies.
 
-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.
+## 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.
+- **One agent per process:** create it 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:** set `idempotent: 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.
+- **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 keeps running against the agent, 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.
 
 ## 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)