# Axle — full documentation > A small, focused TypeScript library for building multi-turn LLM agents. Generated from https://axle.fifthrevision.com. Pages appear in the site's own reading order. --- # Introduction Source: https://axle.fifthrevision.com/ _What Axle is, why it exists, and how these docs are organized._ Axle is a TypeScript library for building multi-turn LLM agents. You get an `Agent` that owns a conversation, a tool loop that runs to completion, structured output backed by Zod, and one event stream you can render — all working the same way across Anthropic, OpenAI, Gemini, and any OpenAI-compatible endpoint. It's a library, not a framework. There's no graph to declare, no runtime to host, no DSL to learn. You make an object and call `send()`. ```typescript import { Agent, anthropic } from "@fifthrevision/axle"; const agent = new Agent({ provider: anthropic(process.env.ANTHROPIC_API_KEY!), model: "claude-sonnet-4-5", }); const result = await agent.send("What is the capital of France?").final; if (result.ok) console.log(result.response); ``` That's a complete program. Everything else in these docs builds on it. ## Is this for you? Probably, if you want: - **TypeScript, end to end.** Zod-typed tools, typed structured output, typed events. No `any` at the seams, no Python port. - **Any provider, one agent.** Anthropic, OpenAI, Gemini, Bedrock, OpenRouter, Ollama. Change two constructor fields — your tools, `Instruct`s and event handling don't move. - **A library, not a framework.** No graph to declare, no runtime to host, no conventions to learn. You make an object and call `send()`. `Agent`, `Instruct`, `stream()` and `generate()` is most of the library. - **State that's ready to render.** `Transcript` folds the event stream into turns and parts shaped the way UIs actually are — streaming text, tool calls with their arguments and results, thinking, citations, files. Hand it to your components. - **To cross a network cleanly.** Events are JSON and sessions are serializable, so you can stream a run to the browser and fold it there. The `/ui` import keeps three provider SDKs out of your bundle, and `RemoteAgent` drives a server-side agent from the client, picking up where a dropped connection left off. - **The hard parts already solved.** A programmable queue you can interrupt and steer, concurrent tool batches, compaction, thinking continuity across turns, token usage and cost per request — the things you find out about three weeks into a hand-rolled loop. Probably not, if you want: - A graph to declare, or a platform to deploy onto. - Durable, checkpointed workflows. Axle runs *inside* the engine you already trust, rather than replacing it. - Memory, RAG and evals in one box. ## What we're going for A small, ergonomic surface for building agents. Each piece has one job, and they're designed to compose rather than to be configured. Axle started life as a DSPy-inspired workflow tool. As models got better at reasoning and tool use, rigid workflow graphs stopped earning their keep — but the goals behind them (structured output, verification, multi-step reasoning) didn't go away. So the project shifted toward making those capabilities composable primitives instead of fixed pipelines. Axle powers [Sunnyday](https://www.sunnyday.run), a hosted AI agent platform, and forms the core of [Axle CLI](https://www.npmjs.com/package/@fifthrevision/axle-cli) and experiments like [Axle Code](https://github.com/johncch/axle-code). ## Finding your way around **Getting Started** takes you from an empty directory to a working agent. **Agent** is the main path — start with [Anatomy of a send](/concepts/anatomy-of-a-send), which sets up three words (messages, steps, turns) that the rest of the docs lean on constantly. It's a five-minute read and it makes everything after it easier. **Primitives** is the layer underneath: `generate()` and `stream()`, for when you want the tool loop without a conversation. **Building blocks** are the pieces both layers use — providers, the model catalog, `Instruct`, tools, results, observability. Dip in as you need them. **API Reference** is the exhaustive listing: what a thing accepts, what it returns. It doesn't teach, it just tells you. **Cookbook** is task-shaped recipes. Streaming to a UI, attaching files, cancelling a run, delegating to subagents. ## What's not here yet A few honest gaps, so you don't go looking: - No multi-modal *output*. Models can read images and PDFs, but Axle won't surface generated images or audio. - Compaction is marked experimental and may change in any release. - Axle CLI is being reworked, so it isn't documented on this site yet. ## Where to next - [Installation](/getting-started/installation) and [Quick Start](/getting-started/quick-start) - [Anatomy of a send](/concepts/anatomy-of-a-send) — the mental model - [Agent](/concepts/agent) — the interface you'll use most - [AGENTS.md](https://axle.fifthrevision.com/AGENTS.md) — the one-page contract for coding agents, alongside [llms.txt](https://axle.fifthrevision.com/llms.txt) and [llms-full.txt](https://axle.fifthrevision.com/llms-full.txt) --- # Installation Source: https://axle.fifthrevision.com/getting-started/installation _Install Axle and point it at a provider._ ```bash npm install @fifthrevision/axle ``` ```bash pnpm add @fifthrevision/axle ``` ```bash yarn add @fifthrevision/axle ``` Zod is a peer dependency (`^4.2.0`), so schemas work as long as your project lists it — which it already does if you define tools: ```typescript import * as z from "zod"; ``` ```bash npm install @fifthrevision/axle zod ``` ## What you'll need - **Node.js 22 or newer.** Axle uses `Promise.withResolvers` and `AbortSignal.any`, which landed in 22. CI builds and tests on Node 24. - **An ESM project.** The package ships `"type": "module"` with no CommonJS build, so `require("@fifthrevision/axle")` won't work. - **An API key** for Anthropic, OpenAI, or Gemini — or a local OpenAI-compatible endpoint like Ollama or vLLM, which needs no key at all. ## The two entry points Most of the time you'll only use the first one. | Import | What's in it | | --- | --- | | `@fifthrevision/axle` | Everything: `Agent`, `Instruct`, providers, `stream()`, `generate()`, tools, MCP, errors. | | `@fifthrevision/axle/ui` | The render and client surface: the `Turn`, `TurnEvent`, `Citation` and `Stats` types, plus the runtime pieces a UI needs — `Transcript`, `computeCost`, the `isCall` / `isActionOf` / `isTimeoutReason` narrowing helpers, `renderTerminalMarkdown`, `Instruct`, and the `RemoteAgent` client with `httpTransport`. Import this in UI code so you don't pull three provider SDKs into your browser bundle: it depends on `chalk`, `marked` and `zod`, and nothing else. | ## API keys Axle never reads environment variables behind your back — you hand the key to the provider factory yourself. Load it however you like: ```typescript import { anthropic, openai, gemini, chatCompletions } from "@fifthrevision/axle"; const provider = anthropic(process.env.ANTHROPIC_API_KEY!); ``` Running against a local model? No key needed: ```typescript const local = chatCompletions({ baseUrl: "http://localhost:11434/v1" }); ``` [Providers & models](/concepts/providers) covers the full list, plus retry and timeout options. ## Next - [Quick Start](/getting-started/quick-start) — a working agent in a few lines. - [Anatomy of a send](/concepts/anatomy-of-a-send) — the model behind the API. --- # Quick Start Source: https://axle.fifthrevision.com/getting-started/quick-start _A working agent, a tool loop, and structured output in a few minutes._ We'll build up in five small steps. Each one is a complete, runnable program. ## 1. Send a message ```typescript import { Agent, anthropic } from "@fifthrevision/axle"; const agent = new Agent({ provider: anthropic(process.env.ANTHROPIC_API_KEY!), model: "claude-sonnet-4-5", system: "You are a concise assistant.", }); const result = await agent.send("What is the capital of France?").final; if (!result.ok) throw new Error(result.error.message); console.log(result.response); // "Paris." console.log(result.usage); // { in: 24, out: 4 } ``` Two things to notice. `send()` hands you a *handle* right away, and `handle.final` is the promise you await. That split exists so you can cancel a run — more on that later. And results come back as a two-state union, so you check `ok` before reading `response`. TypeScript enforces it, which means you can't forget. See [Results & errors](/concepts/results-and-errors). ## 2. Keep the conversation going The agent owns its conversation, so every `send()` builds on the ones before it. You don't manage a message array. ```typescript await agent.send("Hi, my name is Ana.").final; const r = await agent.send("What's my name?").final; // → "Your name is Ana." ``` Sends queue up in order, so you can fire several without awaiting each one. ## 3. Add a tool A tool is a plain object — name, description, Zod schema, and an `execute` function. Axle runs the whole call-execute-respond loop for you. ```typescript import { Agent, anthropic, type ExecutableTool } from "@fifthrevision/axle"; import * as z from "zod"; const getWeather: ExecutableTool = { name: "get_weather", description: "Get the current weather for a city", schema: z.object({ city: z.string() }), async execute({ city }) { return JSON.stringify({ city, temp: 72, condition: "sunny" }); }, }; const agent = new Agent({ provider: anthropic(process.env.ANTHROPIC_API_KEY!), model: "claude-sonnet-4-5", tools: [getWeather], }); const result = await agent.send("What's the weather in Lisbon?").final; ``` Behind that single `await`, the model asked for the tool, Axle ran it, and the model got the answer and replied. That took two round trips to the provider — they're called [steps](/concepts/anatomy-of-a-send), and you don't have to think about them. You just get the final answer. ## 4. Get structured output Wrap your prompt in an `Instruct` with a Zod schema, and `result.response` comes back parsed and typed. ```typescript import { Instruct } from "@fifthrevision/axle"; import * as z from "zod"; const instruct = new Instruct({ prompt: "Tell me about Mars.", schema: z.object({ name: z.string(), distanceFromSunKm: z.number(), moons: z.array(z.string()), }), }); const result = await agent.send(instruct).final; if (!result.ok) throw new Error(result.error.message); result.response.moons; // string[] — your editor knows ``` No JSON parsing, no casting. Axle compiles the schema into instructions for the model, then parses what comes back. ## 5. Stream it `agent.on()` registers a callback that fires for every send from then on. You wire it once. ```typescript agent.on((event) => { if (event.type === "text:delta") process.stdout.write(event.delta); }); await agent.send("Write a haiku about compilers.").final; ``` Those are [turn events](/concepts/turn-events) — the render-layer stream. Writing deltas straight to stdout is fine for a terminal. For an actual UI, don't handle events yourself: hand them to a [`Transcript`](/concepts/transcripts) and render what it gives you. ```typescript import { Transcript } from "@fifthrevision/axle"; const transcript = new Transcript(); agent.on((event) => transcript.apply(event)); await agent.send("Write a haiku about compilers.").final; transcript.turns; // ready to render ``` ## That's the whole library, roughly An agent, a tool, a schema, and an event stream. Everything else is detail on top of these four ideas. Good places to go next: - [Anatomy of a send](/concepts/anatomy-of-a-send) — what actually happened above - [Agent](/concepts/agent) — queueing, interruption, cancellation - [Tools](/concepts/tools) — provider tools, MCP servers, subagents - [Cookbook](/cookbook/tool-using-agent) — complete recipes you can lift --- # Agent Source: https://axle.fifthrevision.com/concepts/agent _The interface you'll use most — scheduling, interruption, and what it owns._ `Agent` holds a provider, a model, a system prompt, a tool registry, a skill registry, and the active conversation. `send()` is the verb. ```typescript import { Agent, anthropic } from "@fifthrevision/axle"; const agent = new Agent({ provider: anthropic(apiKey), model: "claude-sonnet-4-5", system: "You are a helpful assistant.", tools: [getWeather], }); ``` One thing it deliberately doesn't hold: a transcript. It emits events and keeps only the active messages. [Transcripts](/concepts/transcripts) explains why, and what you do about it. ## send() ```typescript const handle = agent.send("Write me a poem."); const result = await handle.final; if (!result.ok) throw new Error(result.error.message); console.log(result.response); ``` `send()` takes a plain string or an [`Instruct`](/concepts/instruct), and hands back a handle immediately. What you get in `response` follows what you put in: - a string → the assistant's text - an `Instruct` with a schema → the parsed, typed object - an `Instruct` without one → text Two small conveniences you don't have to think about, but might appreciate knowing. Strings get wrapped in an `Instruct` with `vars: "optional"`, so if a user types `{{braces}}` at you, nothing explodes. And an `Instruct` you pass in gets cloned, so you can reuse and even mutate the same object afterwards without affecting a send in flight. ## after — continuations run after the turn settles A send can carry `after`, a program that runs once the turn settles, holds the queue until it returns, and runs further turns inline: ```typescript declare const judge: (result: unknown) => Promise<{ ok: boolean; feedback: string }>; const handle = agent.send("Summarize the report.", { after: async (result, ctx) => { for (let attempt = 0; attempt < 3; attempt++) { const verdict = await judge(result); if (verdict.ok) break; result = await ctx.send(verdict.feedback); } }, }); agent.send("Next question."); // waits until the continuation returns ``` The continuation runs after the send's turn settles with a result, `ok` or not; a turn whose handle rejects (cancelled, a fatal tool error, a setup failure) skips it. `ctx.send()` runs an inline turn — the same arguments as `send()` without `after`, an ordinary turn in every way except it starts at once with no `pending:queued`. Inline sends run one at a time in call order and return a promise, not a handle. `ctx` also carries `signal`, `id` (the send's user turn id), and read-only `messages` and `pending`. The handle resolves when the continuation returns, with the inline turns listed under `result.after`. A plain send's result has no `after`. A manual `compact()` carries no continuation, and an inline turn carries none. Full types are in the [Agent reference](/reference/agent#after-continuations). ## Sends line up in a queue Call `send()` while a turn is running and it waits its turn. Sends never run concurrently or interleave. ```typescript const a = agent.send("First question."); const b = agent.send("Second question."); // waits for a ``` Each handle settles with its own result, and `b` sees the history `a` committed. The queue is doing more work than it looks like: `compact()` goes through it too, so compaction never races a turn. (Saving doesn't queue: `snapshot()` waits for the agent to go idle instead, and `session` reads the state as it stands — see [Sessions & persistence](/concepts/sessions).) Every accepted operation also announces itself: `send()` emits `pending:queued` with a preview turn carrying the id the committed turn will have, so a UI rendering `[...transcript.turns, ...transcript.pending]` keyed by id shows queued work. A handle cancelled while still queued emits `pending:dropped` and commits nothing. See [Turn events](/concepts/turn-events). **One way to deadlock** `agent.compact()` queues behind in-flight work, and `agent.snapshot()` waits for idle — so if you await either from inside a tool's `execute`, an `onToolCall` handler, a compaction callback, an `onStep` callback, or an `onSettled` callback, you'll hang. The send is holding the queue (or the idle) that your nested call is waiting on. Call them from outside a send instead — or read `agent.session` when you need the state from inside one. ## Interrupting: four different things `agent.stop()`, `agent.cancel()`, `agent.clear()` and `handle.cancel()` sound similar and do quite different jobs. Here's the short version: | You want to | Use | | --- | --- | | Let the current work finish, then stop | `agent.stop()` | | Stop the active operation right now | `agent.cancel()` | | Throw away what's queued up behind it | `agent.clear()` | | Stop one specific send right now, mid-request | `handle.cancel()` | These are the four calls. A turn can also stop without you asking: a `turnTimeoutMs` cancels it from the inside, with a timeout as the abort reason (see [Listening in](#listening-in)). ### stop() — wind down gracefully ```typescript agent.stop(); // false if nothing was running ``` This asks the active turn to finish at its **next tool-batch boundary**. Every call in the in-flight batch runs to completion and commits — they're [already running at once](/concepts/tools#one-batch-all-at-once). Then the handle settles without another provider request. Nothing gets wasted, and the history stays coherent. `stop()` won't interrupt a request or a tool that's already in flight, and it leaves queued sends alone. One consequence to expect: since a stopped turn ends on its tool-call exchange, a plain send resolves with whatever text that step produced — often nothing. An `Instruct` send may come back `ok: false` with a parse error. That's not a bug; there genuinely isn't a final answer yet. ### agent.cancel() — stop the active operation now ```typescript agent.cancel("user-navigated-away"); // false if nothing was running ``` Immediate, like `handle.cancel()`, but aimed at whatever is active rather than a specific handle: the active operation aborts, a turn that already opened settles `cancelled` with its partial work committed, and queued operations are unaffected — the next one starts. `stop()` remains the gentle form. Graceful shutdown is `clear()`, then `stop()` or `cancel()`, then `snapshot()` (or the last `onSettled`). ### clear() — empty the queue ```typescript const dropped = agent.clear(); // how many you cancelled ``` Cancels everything queued, leaves the active turn alone. Each cleared handle rejects with `AxleAgentAbortError`, having committed nothing. A waiting `snapshot()` is not queued work, so `clear()` doesn't touch it. ### handle.cancel() — stop one send now ```typescript const handle = agent.send("Long task..."); handle.cancel("user-navigated-away"); ``` Immediate, and local to that handle. `handle.final` rejects with `AxleAgentAbortError`. Whether anything commits comes down to timing, and the line is whether the turn opened: - Cancel **before** it (while queued) and the handle just disappears — `pending:queued` is followed by `pending:dropped`, no user message, nothing committed. (Failing or cancelling while listing MCP tools no longer drops the send: the user turn opens first, so the user message stays and the agent turn ends `error` or `cancelled`. A retry is a new send, so remove the first user message first if you don't want both kept.) - Cancel **after** it and the user message stays, with the agent turn marked `cancelled`. A cancelled turn is always recorded as `cancelled`, even when the provider rethrows something that doesn't look like an abort. That includes cancelling during `beforeTurn` compaction — compaction is ordinary work inside an already-open turn, so cancelling it doesn't unwind anything. One timing subtlety: the user turn is stamped when `send()` is called, so the queued preview and the committed turn share their id, parts, and timing. For a send that waited in the queue, the turn's timing is the moment of the call, not the moment it committed. Either way, the rejected error hangs on to `reason`, `usage`, `turn`, and whatever partial output existed. You paid for that; you may as well show it. When the cancel landed while the model was still writing its response, the partial keeps only what was written — no tool calls, no empty text or thinking parts — and is `undefined` when nothing was written. ### Steering: stop, clear, send The pattern you'll reach for most combines three of them — `stop()` so the active turn commits what it has, `clear()` so queued work the user has just superseded is dropped, then `send()` to land the new instruction on a clean history. The order matters, and the full recipe with the chat-box wiring is [Interrupting & cancelling](/cookbook/cancellation#the-steer-playbook). ## Listening in ```typescript const unsubscribe = agent.on((event) => { if (event.type === "text:delta") process.stdout.write(event.delta); }); ``` `on()` gives you back an unsubscribe function. Callbacks fire for every send from then on, so you wire them once rather than per turn. [Turn events](/concepts/turn-events) covers what you'll receive. Beside the turn events, `on()` delivers the operation's lifecycle — the frame around the turns: `operation:start` when a send or compaction takes the queue, `after:start` / `after:end` around its continuation, `operation:end` with the outcome, and `agent:idle` when nothing is left behind it. The callback type is `AgentEventCallback`. If all you want is "is it working," skip the events and read `agent.status` — `{ phase: "idle" }`, or `{ phase: "busy", id }` with the running operation's id. It already reads the new value by the time the event that moved it reaches you. Two hooks run at the edges of an operation. `onStart()` fires once an operation holds the queue, before its turn opens, with `{ kind, id, signal }` — and it can refuse the work by throwing, which drops the pending turn and rejects the handle without running anything: ```typescript agent.onStart(({ kind, id }) => { if (shuttingDown) throw new Error("shutting down"); }); ``` `onSettled()` fires once per operation that ran — one send, one call, however it ended: after its turn and its continuation, before its handle settles — handing you the session and exactly what the handle is about to settle with. That's the hook for saving after each operation without awaiting the queue empty the way `snapshot()` does. The agent awaits your callback, so returning a promise holds the handle and the next queued operation; a callback that throws can't affect the operation. `onIdle()` fires each time the agent goes from busy to idle, after the last operation's `onSettled` callbacks — the place to close whatever your host opened when work began. Neither fires for an operation cancelled while still queued: it never ran. See the [Agent reference](/reference/agent#onsettled). One more hook, at a finer grain: `onStep()` fires at the end of each step inside a turn — one model call and the tools it asked for — however the step ended. The agent waits for your callback before sending the next request, so it's where you save usage and state while the turn is still running instead of once at `turn:end`. Read `agent.session` there, not `snapshot()`. Full shape in the [Agent reference](/reference/agent#onstep). ## Reading the conversation ```typescript agent.messages; // AxleMessage[] — a copy agent.context(); // estimated token usage, broken down agent.sessionId; // stable id, generated if you didn't supply one agent.system; // readonly getter — configured prompt, then the skills catalog when skills exist ``` `messages` is a copy, so mutating it does nothing. If you want to change the conversation, that's [compaction](/concepts/compaction). It grows as each step ends while a turn runs — an assistant message that asked for tools appears together with its tool results — so code that reads it mid-turn (a tool, an event listener, `onStep`) sees the finished steps. `system` is derived — set the prompt at construction; skills append their own section (see [Skills](/concepts/skills)). A send takes options beyond the message. `id` names the send's user turn — the id its `pending:queued` preview, its committed turn, and `onSettled` all carry (generated when omitted, so pass one when an outside system needs to correlate). And two timeouts bound the work: `turnTimeoutMs` cancels a turn that runs too long — every step, tool call, and deferred wait included — while `streamStallMs` fails a step whose provider stream goes silent. Both are unset by default, and both can be set on the agent or per send. ## Tools and MCP Supply tools at construction or add them later. MCP servers resolve lazily — their tool lists get fetched on the first send that needs them, once per client. ```typescript const agent = new Agent({ provider, model, tools: [a], providerTools: [b] }); agent.addMcp(mcpClient); agent.hasTools(); // true agent.registry; // the ToolRegistry, if you want to poke at it agent.skills; // the SkillRegistry — add/remove/set at any time, lands on the next request ``` `tools` takes executable and deferred tools side by side. An executable tool runs through its own `execute`; a deferred tool's calls go to the handler registered with `agent.onToolCall()`, one per agent, or wait for `agent.toolCall(id)` when no branch answers. See [Tools](/concepts/tools) and [Skills](/concepts/skills). ## Picking up where you left off ```typescript const session = agent.session; // ...later, in a new process const restored = new Agent(config, session); ``` `snapshot()` (which waits for the agent to go idle) is deprecated — read `session` instead. See [Sessions & persistence](/concepts/sessions). ## Next - [Instruct](/concepts/instruct) — when a string isn't enough - [Results & errors](/concepts/results-and-errors) — what `send()` gives you back - [Remote agents](/concepts/remote-agents) — driving an agent served elsewhere - [Agent reference](/reference/agent) — every option and method --- # Anatomy of a send Source: https://axle.fifthrevision.com/concepts/anatomy-of-a-send _Messages, steps, and turns — the three words the rest of the docs lean on._ Axle looks at a conversation through three different lenses, and it has a different word for the unit at each one. Almost every confusing moment with this library comes from mixing them up, so let's sort them out first. It won't take long. | Lens | Unit | Made of | Where you find it | | --- | --- | --- | --- | | Wire | **Message** | content parts | `agent.messages` | | Execution | **Step** | one request + its fallout | inside `send()` | | Render | **Turn** | parts (+ annotations) | your `Transcript` | One `send()` is **one or more steps**, and it produces **one user turn and one agent turn**, carried over the wire as **messages**. If you only remember one thing: *step* is about what the code does, *turn* is about what the reader sees. ## Let's walk through one ```typescript const result = await agent.send("What's the weather in Lisbon?").final; ``` With a `get_weather` tool registered, here's what that one line actually does. 1. **Your message commits.** Axle renders the `Instruct` into an `AxleUserMessage`, appends it to `agent.messages`, and emits `turn:user`. Before this moment, cancelling commits nothing at all. 2. **The agent turn opens.** `turn:start` fires with a fresh `turnId`. Everything the model does for the rest of this send piles into that one turn. 3. **Step 1 runs.** One streaming request to the provider. The model comes back asking for `get_weather`. That assistant message joins `agent.messages`. 4. **The tools run.** Everything the model asked for executes — in parallel, if it asked for several. The results become one tool message, also appended. 5. **Step 2 runs.** A second request, now carrying the tool results. This time the model answers with text and no tool calls, so the loop ends. 6. **The turn closes.** `turn:end` fires. `result.response` is the text from step 2, `result.usage` covers both steps, and `result.turn` is the whole accumulated agent turn. Two steps. Four messages. Two turns. One `send()` — and from your side, one `await`. ## Message — the wire lens An `AxleMessage` is a role-tagged record (`user`, `assistant`, or `tool`) whose `content` is a list of parts. Messages are what providers actually consume, and what [compaction](/concepts/compaction) rewrites. ```typescript agent.messages; // AxleMessage[] — a copy of the active conversation ``` One thing worth knowing early: this is the *active* conversation, not a complete log. Compaction can replace the whole array, and when it does, the old messages are genuinely gone. If you need to show a user what happened earlier, that's the transcript's job, not this array's. "Message" never means render state, and never means the text a user typed into your chat box. More detail: [Messages & parts](/reference/messages). ## Step — the execution lens A **step** is one pass of the loop inside a `send()`: one provider request, the assistant message it produced, and the tools that message asked for, if any. A send ends at the first step where the model doesn't ask for tools. It can also end early if a budget stops it (`maxSteps`, `maxContextTokens`), if a timeout fires (`turnTimeoutMs` cancels the turn, `streamStallMs` fails a silent step), or if you call `agent.stop()`. Steps don't show up in conversation state — each one's output gets flattened into messages and into the agent turn's parts. You'll see them in two places: - [Stream events](/concepts/stream-events) `step:start` / `step:complete` - Spans named `step-N` in [tracing](/concepts/observability) The name matches how the rest of the ecosystem uses it — the Vercel AI SDK's `maxSteps`, OpenAI's run steps. **This was renamed in 0.29.0** Steps used to be called "turns", and the option used to be `maxIterations`. It's `maxSteps` now, and the stop reason is `"max-steps"`. See [Upgrading](/upgrading) if you're coming from an older version. ## Turn — the render lens A **turn** is one conversation entry as a reader sees it — a user turn or an agent turn. A send's own exchange is one user turn and one agent turn; a continuation adds further pairs, threaded under the first. The agent turn collects parts (text, thinking, tool actions, files, citations) from every step of that send. ```typescript result.turn.parts; // TurnPart[], in display order result.turn.status; // "complete" | "cancelled" | "error" ``` Compaction can open turns too: a manual `agent.compact()` opens and closes its own agent turn around the compaction part. "Turn" never means a single assistant message, and never means one provider request. That's a step. More detail: [Turns & Transcripts](/concepts/transcripts). ## Two more words **Send** — the Agent verb. One scheduled exchange, run as a FIFO queue item. It's the unit that means "the agent took its turn." **Session** — the continuable identity of a conversation. `AgentSession` is its serialized form: `{ sessionId, messages }`, and nothing more. The transcript isn't part of it — you persist that alongside. See [Sessions & persistence](/concepts/sessions). ## Who owns what This is the part that surprises people most, so it's worth stating plainly: - **Axle owns** the active conversation (`agent.messages`) and the event stream. - **You own** the transcript. The agent doesn't keep one. It emits `TurnEvent`s and forgets them. If you don't fold those events into a `Transcript` and store it, the reader-facing history is gone. `agent.session` gives you the continuation — session id and messages — and deliberately leaves turns out. It's not an oversight; it's the boundary. The [Transcripts](/concepts/transcripts) page explains why it's drawn there, and it's three lines of code to hold up your end. ## Next - [Providers & models](/concepts/providers) — where requests actually go - [Agent](/concepts/agent) — scheduling, interruption, cancellation - [Glossary](/glossary) — all of this, in short form, for when you forget --- # Turns & Transcripts Source: https://axle.fifthrevision.com/concepts/transcripts _The render-layer unit, and the container that accumulates it. Axle emits them; you keep them._ A **turn** is one conversation entry as a reader sees it — a user turn or an agent turn. It's the render-layer unit from [Anatomy of a send](/concepts/anatomy-of-a-send#turn-the-render-lens), and it's what your UI actually draws. ```typescript interface Turn { id: string; owner: "user" | "agent"; parts: TurnPart[]; // display order status: "pending" | "streaming" | "complete" | "cancelled" | "error"; annotations?: Annotation[]; metadata?: Record; threadId?: string; // on inline turns — the send's id, rooting the thread cursor?: string; // where this turn closed on a served event stream timing?: { start: string; end?: string }; usage?: Stats; failure?: TurnFailure; // when the send resolved ok: false error?: { message: string; code?: string }; // when the send threw instead cancelReason?: { type: "timeout"; limitMs: number }; // when turnTimeoutMs cancelled it reason?: "stop" | "length"; // how the final answer ended, when there was one } ``` A **transcript** is the container that accumulates them. And here's the part that catches people: **the agent doesn't keep one.** It emits `TurnEvent`s and holds only the active [messages](/concepts/anatomy-of-a-send). If you don't fold those events into a `Transcript` and store it, the reader-facing history is gone. That sounds like a chore. It's three lines: ```typescript import { Transcript } from "@fifthrevision/axle"; const transcript = new Transcript(); agent.on((event) => transcript.apply(event)); await agent.send("Hello").final; transcript.turns; // readonly Turn[] — ready to render ``` That's the entire integration. The rest of this page is about why the boundary sits there, and what you get once it does. ## Why the split The model-facing conversation and the reader-facing history are genuinely different things, and they drift apart: - **Compaction** replaces `agent.messages` wholesale. For the model, the old messages stop existing. Your user should still see what happened. - **Tool internals** — argument deltas, progress chunks, intermediate steps — are render detail that has no business in the wire format. - **Annotations** — sandbox status, eval results, deploy state — are UI state that must never reach a provider. Keeping the transcript outside the agent means compaction can be aggressive without destroying your user's view, and your UI state can't leak into a prompt. It's a small amount of work on your side in exchange for those two guarantees. ## What's in a turn ### It's shaped like your UI, on purpose This is the thing worth noticing about turns: they aren't a lightly-renamed provider stream. They're designed backwards from what a chat interface actually needs to draw. A turn maps to a message bubble. Parts map to components. Part ids are stable for the life of the turn, so they're correct React keys. Statuses map to spinners and error states. Even the awkward moments have a field — `pendingArgs` holds the half-streamed JSON of a tool call's arguments, so there's something to render before they parse. The practical upshot is that rendering an agent is a `switch` over `turn.parts`, and not much else: ```typescript turn.parts.map((part) => { switch (part.type) { case "text": return ; case "thinking": return ; case "action": return ; // … } }); ``` No reducer of your own, no buffering, no correlating ids across events — `Transcript` did that on the way in. If you've built a chat UI on a raw provider stream before, that's most of the work gone. Parts are a discriminated union on `type`, so a `switch` covers them exhaustively: | Part | What it carries | | --- | --- | | `text` | Accumulated text, plus any anchored `citations` | | `thinking` | A `summary` and/or `raw` thinking field, provider `continuity` | | `file` | A `FileInfo` attached to a user turn | | `citation` | An unanchored source list the provider emitted on its own | | `action` | A tool call, subagent run, or provider tool — see below | | `compaction` | A compaction event, rendered as a divider or summary (`trigger`, `status`, `summary`) | A failed turn carries `failure` (`kind`, `message`, plus `type`/`status`/`text`/`category` where the kind has them) instead of an `error` object, and a turn cut off at the output limit carries `reason: "length"` (`"stop"` when the final answer finished). The old `turn.error` field is gone. A turn whose send *threw* — a fatal tool error, a throwing `onStep`, a failed MCP tool listing — carries `error` (`message`, plus `code` when Axle threw it) instead of `failure`: a turn has one or the other, never both. A turn cancelled by `turnTimeoutMs` carries `cancelReason`; a caller-cancelled turn carries neither. Action parts discriminate further on `kind`: - `kind: "tool"` — `detail.name`, `detail.parameters`, `detail.pendingArgs`, `detail.result` - `kind: "agent"` — a subagent, with `detail.children: Turn[]` for the nested run - `kind: "provider-tool"` — `detail.input`, `detail.result` - `kind: "deferred"` — `detail.callId`, `detail.input`, `detail.pendingArgs`, `detail.result`; never `running`, waiting on your answer instead (see [Tools](/concepts/tools#deferred-tools)) Which means rendering a subagent is recursive: the same component that renders `transcript.turns` renders `part.detail.children`. That falls out nicely. How these parts get built — the event families, and the openings-vs-deltas rule `Transcript` is applying — is [Turn events](/concepts/turn-events). ## Pending: the turns that haven't opened yet A queued `send()` or manual `compact()` is accepted before it runs, and the agent says so up front: `pending:queued` carries a preview turn with `status: "pending"` and the id the real turn will carry — the user turn the send will commit, or an agent turn with one `pending` compaction part. `Transcript` holds these in `pending`, never in `turns`, and each leaves when its turn opens (or when `pending:dropped` arrives because the operation was cancelled while queued or failed during setup). Render both, keyed by id: ```typescript agent.on((event) => transcript.apply(event)); for (const turn of [...transcript.turns, ...transcript.pending]) { console.log(turn.id, turn.status); } ``` The preview and the committed turn share the id, so the queued row becomes the real row with no flicker — one component, keyed by id. A `pending` turn only ever appears in `pending`, so a renderer that reads `turns` alone never sees one. And `pending` is live state: saving `turns` doesn't save it, a transcript restored from saved turns has none, and the constructor takes it only as an optional second list for mirroring a live transcript: ```typescript const mirror = new Transcript(saved.turns, transcript.pending); ``` ## Annotations: the extension point Parts are Axle's vocabulary — text, thinking, tool calls. **Annotations are yours.** They're how you attach things Axle has no concept of to a turn or a part, and have them render in the right place, without any of it becoming model state. ```typescript interface Annotation { id: string; kind: TKind; // your discriminator label: string; // what a generic renderer shows placement?: "before" | "after"; status?: "running" | "complete" | "cancelled" | "error"; data?: TData; // your payload timing?: { start: string; end?: string }; } ``` Think of it as a plugin slot in the transcript. Eval scores, a sandbox booting, a deploy status, a cost warning, a moderation flag, "3 files changed" — none of these are things a model said, and none belong in a prompt. But all of them want to appear next to the turn they relate to, in order, with a lifecycle. Three properties make this work as an extension mechanism: **They're typed as a union you define.** `Transcript` flows your type through `turn.annotations` and `part.annotations`, so a `switch (annotation.kind)` in your renderer is exhaustive and checked. **They have a lifecycle.** `annotation:start` → `annotation:update` → `annotation:end`, with `status` moving `running` → `complete` / `error`. So async work — an eval that takes six seconds — can show a spinner and then a result, using the same machinery a tool call uses. **`label` is required for a reason.** It means a generic renderer can display *any* annotation kind, including ones added after that renderer was written. You get a working fallback for free, and specialize only the kinds worth specializing. **They never reach a provider.** Annotations live on the transcript, which the agent doesn't own or send. You can attach anything, including things you'd never want a model to read. The worked example — an eval pipeline that scores each turn and renders inline — is in [Annotations & evals](/cookbook/annotations). ## Saving and restoring `Transcript` is a plain in-memory fold. Save `turns`, restore by handing them back: ```typescript await db.save(sessionId, { session: agent.session, // { sessionId, messages } turns: transcript.turns, }); // later const saved = await db.load(sessionId); const agent = new Agent(config, saved.session); const transcript = new Transcript(saved.turns); agent.on((event) => transcript.apply(event)); ``` Two things to persist, not one. `AgentSession` leaves turns out on purpose. See [Sessions & persistence](/concepts/sessions). The constructor shallow-copies the array you give it, and `turns` is readonly — so later changes to your array won't reach inside the transcript. Structural changes only happen through `apply()`. ## Mixing in your own events If your application has its own event stream, `apply()` passes through anything it doesn't recognize: ```typescript import { Transcript } from "@fifthrevision/axle"; import type { Annotation, TurnEvent } from "@fifthrevision/axle"; type SandboxAnnotation = Annotation<{ image: string }, "sandbox">; type HostEvent = { type: "run:terminal"; status: string }; const transcript = new Transcript(); // Type your event source as the union the transcript accepts. declare const incoming: Array | HostEvent>; for (const event of incoming) { const result = transcript.apply(event); if (!result.handled) { // result.event is typed as HostEvent here myReducer(result.event); } } ``` Note the annotation type flows into `TurnEvent` too. Once you parameterize `Transcript` with your own annotation union, a bare `TurnEvent` from `agent.on()` won't be assignable — type the transport as `TurnEvent | YourHostEvent` at the boundary. Both `Transcript` and `apply()` are generic over your annotation union and your host event type, so one dispatcher stays fully typed end to end — including the `handled: false` branch. ## Keeping provider SDKs out of your bundle Your UI code probably shouldn't transitively import the Anthropic, OpenAI, and Google SDKs. The `/ui` subpath is the renderer's surface — the render-layer types plus the runtime pieces a UI actually runs (`Transcript`, `computeCost`, the `isCall` / `isActionOf` narrowing helpers, `Instruct`, the `RemoteAgent` client), and nothing that reaches a provider SDK: ```typescript import type { Turn, TurnEvent, TurnPart } from "@fifthrevision/axle/ui"; import { Transcript } from "@fifthrevision/axle/ui"; ``` ## What about `result.turn`? Each send resolves with a `turn` — the agent turn for that send, already accumulated. It's a convenience for callers who don't maintain a transcript. The agent's internal accumulator resets after every send, so it isn't a history and shouldn't be treated as one. ## Next - [Sessions & persistence](/concepts/sessions) - [Transcript & turn events reference](/reference/transcript) - [Streaming to a UI](/cookbook/streaming-ui) --- # Turn events Source: https://axle.fifthrevision.com/concepts/turn-events _The event stream an Agent emits — render-shaped, and best consumed by a Transcript._ `agent.on()` emits `AgentEvent` — the stream that builds the [turns](/concepts/transcripts) you just met, plus the operation lifecycle around them. The turn events are organized into turns and parts with stable ids, shaped for drawing a conversation rather than for driving a loop. A turn is an Agent concept, so this is the *only* place turn events come from. Down at [`generate()` and `stream()`](/concepts/generate-and-stream) there's no conversation, so there are no turns — those emit [`StreamEvent`](/concepts/stream-events) instead. You've already seen what to *do* with these: hand them to a [`Transcript`](/concepts/transcripts) and render its turns. That stays the advice. This page is about what's actually flowing through that pipe — useful for understanding what you're rendering, and for the times you want to tap the stream directly. ## When to handle events yourself Three situations, and they have something in common: you aren't rendering a conversation. - **Terminal output or logging.** You want `text:delta` written to stdout, not a turn structure. - **Forwarding over a wire.** Serialize the event, ship it, and call `apply()` on the *other* side. Don't reduce twice. - **Reacting to a specific moment** — telemetry on `action:complete`, a notification on `turn:end`. Subscribe alongside a transcript rather than instead of one; `agent.on()` takes as many callbacks as you like. If you find yourself accumulating text into a variable, tracking which part is open, or keying a map by `partId` — stop. That's `Transcript`'s job, and it already handles the edge cases you haven't hit yet. ## The event families Every event after `turn:user` carries a `turnId`, and part-level events carry a `partId` — the same stable ids you render against. - **Operation lifecycle** — `operation:start`, `after:start`, `after:end`, `operation:end`, `agent:idle` - **Pending lifecycle** — `pending:queued`, `pending:dropped` - **Turn lifecycle** — `turn:user`, `turn:start`, `turn:end` (carries `failure?`, `error?`, `cancelReason?`, and `reason?`) - **Part streaming** — `part:start`, `text:delta`, `text:citation`, `thinking:raw-delta`, `thinking:summary-delta`, `thinking:update`, `part:end` - **Actions** — `action:args-delta`, `action:running`, `action:waiting`, `action:input`, `action:progress`, `action:complete`, `action:cancelled`, `action:error` - **Nesting** — `action:child-event`, wrapping a subagent's own turn events - **Compaction** — `compaction:update`, `compaction:complete`, `compaction:cancelled`, `compaction:error` - **Annotations** — `annotation:start`, `annotation:update`, `annotation:end` ### The operation around the turns A send is an **operation** — a queued unit of work that produces turns. The lifecycle events frame it: `operation:start { id, kind }` when it takes the queue, `after:start` / `after:end` around its continuation if it carries one, `operation:end { id, outcome }` when the handle settles, and `agent:idle` when nothing is left queued behind it. The outcome is `complete`, `cancelled`, or `error` with a message. You rarely render these — they're for status bars, queue badges, and "agent is working" indicators — but one companion is worth knowing: `agent.status` reads `{ phase: "idle" }` or `{ phase: "busy", id }`, and already shows the new value by the time the event that moved it reaches your callback. The callback type is `AgentEventCallback`, taking the whole `AgentEvent`; every `AgentEvent` is still a `TurnEvent`, so `agent.on(transcript.apply)` keeps working unchanged. ### The first event of a send is pending:queued `send()` builds the user message and its turn up front, so the queued preview and the committed turn share their id, parts, and timing. That means `pending:queued` arrives inside the `send()` call, before `turn:user` — and a send that never starts still emits `pending:queued` followed by `pending:dropped` (cancelled while queued, refused by `onStart`, or a setup failure). A send that fails while listing MCP tools is not dropped — the user turn opens first, so the failure ends the turn `error` instead. The turn's timing is the moment of the call, not the moment the turn committed; for a send that waited in the queue the two differ by the wait. A renderer that has no use for previews can ignore both events — `Transcript` folds them, and they never reach `turns`. ### Openings carry everything, deltas carry almost nothing The one structural rule worth internalizing: `part:start` hands you the complete part object, while every delta after it carries only `partId` and the change. So somebody has to hold that part and patch it as deltas arrive. That somebody should be `Transcript` — this asymmetry is precisely the work it exists to do, and it's why hand-rolling a reducer gets fiddly faster than you'd expect. Full listing in the [Transcript & turn events reference](/reference/transcript). ### A tool call, in phases A tool call shows up as an `action` part moving through states: 1. `part:start` with `status: "pending"` — the model has begun requesting it 2. `action:args-delta` — argument JSON streaming in, not yet parseable 3. `action:running` with parsed `parameters` — execution has begun 4. `action:progress` — whatever the tool passed to `ctx.emit` 5. `action:complete`, `action:cancelled`, or `action:error` Those phases describe one call. A step's calls [run at once](/concepts/tools#one-batch-all-at-once), so in a batch every call reaches phase 1 before any reaches phase 5, and phases 2 to 5 interleave across calls in finish order. Key on the part's `id`, never on "the running tool". A cancelled call ends `action:cancelled` with `status: "cancelled"` and no `result` — a call that never got to run (turn cancelled while the model was still streaming it, or before its batch started) settles the same way before `turn:end`. Match `status === "cancelled"` instead of the old `error.type === "aborted"` shape. A deferred call skips the running phase entirely — nothing executes. The part opens `pending`, moves to `waiting` when the validated call reaches your handler (`action:waiting`, carrying the tool call `id` as `callId` plus `name` and `input`), and closes with the answer. Its `kind` is `"deferred"`, with `status` running `pending` → `waiting` → `complete` | `cancelled` | `error`. See [Tools](/concepts/tools#deferred-tools). `Transcript` folds all five into one `action` part whose `status` and `detail` you can render directly. The `pendingArgs` field it maintains during phase 2 exists so you have *something* to show while the arguments are still an incomplete JSON string — a small thing that makes streaming UIs feel much better. ### Annotation events `annotation:start` / `:update` / `:end` carry a `target` — `{ type: "turn", turnId }` or `{ type: "part", turnId, partId }` — and `Transcript` files them against it. What annotations are *for* is covered under [Annotations](/concepts/transcripts#annotations-the-extension-point); the recipe is [Annotations & evals](/cookbook/annotations). ## Next - [Turns & Transcripts](/concepts/transcripts) — folding these into render state - [Streaming to a UI](/cookbook/streaming-ui) — a complete recipe - [Stream events](/concepts/stream-events) — the primitive layer's equivalent --- # Continuations Source: https://axle.fifthrevision.com/concepts/continuations _Running follow-up turns after a send settles, without leaving the queue._ A continuation is a program a send carries under `after`. It runs once that send's turn settles, holds the queue until it returns, and runs further turns inline through `ctx.send()`. ```typescript declare const judge: (result: unknown) => Promise<{ ok: boolean; feedback: string }>; const handle = agent.send("Summarize the report.", { after: async (result, ctx) => { for (let attempt = 0; attempt < 3; attempt++) { const verdict = await judge(result); if (verdict.ok) break; result = await ctx.send(verdict.feedback); } }, }); agent.send("Next question."); // waits until the continuation returns ``` Reach for one when the next step depends on judging the last answer — verify-then-retry loops, critic loops, "keep going until the checker passes". If the follow-up doesn't depend on the result, a second `send()` is simpler. ## How it runs The continuation runs after the send's turn settles with a result, `ok` or not. A turn whose handle rejects (cancelled, a fatal tool error, a setup failure) skips it. While it runs, the queue is held: sends queued behind this one wait until the continuation returns. `ctx.send()` runs an **inline turn** — the same arguments as `send()` without `after`, an ordinary turn in every way except it starts at once with no `pending:queued`, runs one at a time in call order, and returns a promise (not a handle). `ctx` also carries `signal`, `id` (the send's user turn id), and read-only `messages` and `pending`. ```typescript after: async (result, ctx) => { if (!result.ok) return; // decide what a failure means here const second = await ctx.send("Now compress that to one sentence."); console.log(second.response); }, ``` The handle resolves when the continuation returns, with the inline turns listed in order under `result.after` — each an `InlineTurn` (`userTurn` plus that turn's `ok`, `response`, `turn`, `usage`). The top-level fields stay the message you sent and its reply; a caller that wants the corrected answer reads the last entry. A plain send's result has no `after`. Three boundaries to know: - A manual `compact()` carries no continuation, and an inline turn carries none — no nesting. - A continuation that throws rejects the handle, and the queue continues. - `cancel()` during a continuation aborts `ctx.signal` and any inline turn in flight and rejects the handle; before it starts, it never starts. `stop()` keeps its tool-batch meaning for an inline turn in flight. `clear()` never touches a continuation. ## Observing it Inline turns are ordinary turns: they emit the usual `turn:*` and part events, commit to `agent.messages`, and fold into your `Transcript` the same way. Two differences for hosts that track the queue: - No `pending:queued` announces an inline turn — it starts at once. A host that keys queued rows by id ignores inline turns by construction. - No hook fires for an inline turn on its own. `onSettled` fires once for the whole operation, after the continuation returns — not per inline turn — and the inline turns arrive listed under `result.after`. Each inline turn's user turn carries `threadId`: the send's id, rooting the thread. A renderer can draw them as replies; the transcript stays a flat list. ## Next - [Agent](/concepts/agent#after-continuations-run-after-the-turn-settles) — sends, the queue, and interruption - [Agent reference](/reference/agent#after-continuations) — `Continuation`, `ContinuationContext`, `InlineTurn` - [Sessions & persistence](/concepts/sessions) — saving after each turn with `onSettled` --- # Sessions & persistence Source: https://axle.fifthrevision.com/concepts/sessions _Saving a conversation, bringing it back, and what's deliberately left out._ A **session** is the continuable identity of a conversation. Its serialized form is deliberately small: ```typescript interface AgentSession { sessionId: string; messages: AxleMessage[]; } ``` That's the pure continuation — a session id and the active model-facing conversation. Nothing else. ## Snapshot and restore Save it when you're done: ```typescript const session = agent.session; await db.save(session.sessionId, session); ``` Then pick it up later, in another process: ```typescript const session = await db.load(sessionId); const agent = new Agent(config, session); ``` `agent.session` returns that same `{ sessionId, messages }` synchronously, as it stands — safe inside `onStep`, `onStart`, `onSettled`, continuations, and tools, where `snapshot()` would deadlock. To save a state at rest, read it in an `onSettled` or `onIdle` callback, or after awaiting the send's `final`. `snapshot()` is deprecated but still works: it is async, and it resolves when the agent goes idle — at once when nothing is running, otherwise when the last queued operation has settled. That's what guarantees you're capturing a conversation at rest: a snapshot never contains a streaming or half-executed turn, and it includes everything queued before the agent went idle. It is not queued work itself — it doesn't make the agent busy, fires no `onIdle`, and `clear()` doesn't cancel it. **Don't await snapshot() from inside a send or an onSettled callback** It needs the agent to go idle, so calling it from a tool's `execute`, an `onToolCall` handler, a compaction callback, an `onStep` callback, or an `onSettled` callback will deadlock. Call it from outside a send — or read `agent.session` instead. **save after each operation without awaiting the queue empty, use `onSettled`** instead — it hands you the same session plus exactly what the handle settled with, before the handle settles: ```typescript agent.onSettled(async (session, operation) => { await db.save(session.sessionId, { session, turns: transcript.turns }); }); ``` If you supply both `config.sessionId` and `session.sessionId`, the restored one wins. Unknown keys from older Axle versions get ignored, so an old stored session still loads fine. ## What a session leaves out, and why Not included: providers, tools, MCP clients, file resolvers, tracers — anything executable. And not the transcript. Runtime objects are excluded because they're process-local and frequently carry secrets. You rebuild them from your own configuration: ```typescript const config = { provider: anthropic(process.env.ANTHROPIC_API_KEY!), model: "claude-sonnet-4-5", tools: [getWeather], }; const agent = new Agent(config, session); ``` The transcript is excluded because it's [yours](/concepts/transcripts). So persist both: ```typescript await db.save(id, { session: agent.session, turns: transcript.turns, }); ``` And restore both: ```typescript const saved = await db.load(id); const agent = new Agent(config, saved.session); const transcript = new Transcript(saved.turns); agent.on((event) => transcript.apply(event)); ``` Persist `turns` only — `transcript.pending` is live state (queued sends and compactions the agent accepted but hasn't started) and is never saved. After a restore there is no pending, and nothing recorded a save for. Worth saying plainly: if you save only the session, you get an agent that remembers the conversation perfectly and a UI with nothing to show. It's an easy mistake to make once. ## Storing agent recipes If your application lets users *configure* agents rather than hardcoding them, keep the recipe in your own shape — a path, a name, the parsed recipe file — and rebuild `AgentConfig` from it directly. Core carries no serializable agent recipe (`AgentDefinition`, `createAgentConfig()`, and friends were removed in 0.35.0): the definition mirrored `AgentConfig` field for field, and every host resolved providers, tools, MCPs, and skills from its own configuration anyway. ```typescript // your shape, your store const saved = await db.loadAgent(id); // { recipe, session } declare const providers: Record; declare const tools: Record; const agent = new Agent( { provider: providers[saved.recipe.provider], model: saved.recipe.model, system: saved.recipe.system, tools: saved.recipe.tools?.map((name) => tools[name]), }, saved.session, ); ``` Harness concerns like file resolvers, tracing, transport, and stores stay outside the recipe on purpose. Keep those in your own configuration. ## Long conversations A session grows without bound until you do something about it. That something is [compaction](/concepts/compaction) — and since it rewrites `agent.messages`, any snapshot you take afterwards is correspondingly smaller. ## Next - [Compaction](/concepts/compaction) - [Turns & Transcripts](/concepts/transcripts) - [Agent reference](/reference/agent) --- # Remote agents Source: https://axle.fifthrevision.com/concepts/remote-agents _Driving an agent served elsewhere — an event store on its side, a RemoteAgent on yours._ **Experimental** Remote agents are under active design and may change in any release. The wire shapes (`AgentCommand`, `CommandOutcome`) are Zod schemas, so expect fields to move. **the agent can't live where its consumer does. The model key belongs** on a server, the UI belongs in a browser, and the two meet over HTTP. Or one process serves the agent and another drives it, and the calls in between need a human's answer. `RemoteAgent` is how you drive an agent served elsewhere. It has the `Agent` surface you already know — `on`, `onToolCall`, `toolCall(id)`, `send`, `cancel`, `stop`, `clear`, `status` — and holds no transcript, exactly like `Agent`. Events come in, commands go out, and everything else reads the same from the consumer side. ## The pieces Two things on the served side, one on yours, a transport between them, and a switch in the middle: - **The served `Agent`** — an ordinary agent, with the provider key, the tools with their `execute` functions, and whatever else only exists server-side. - **`InMemoryEventStore`** — sits beside the agent, stamps every event with a cursor, and replays after it on reconnect. - **A transport** — `httpTransport` over one URL (`GET` for the event stream, `POST` for commands), or `loopbackTransport` for the same contract with no wire: the store's events straight out, each command straight to a handler. - **The host's command switch** — yours to write: it turns each `AgentCommand` into an `Agent` call. Creating, finding, and ending agents is the host's job too, since an `Agent` is built from secrets and connections that never cross a wire. Here's the whole thing over `loopbackTransport` — a served agent and its consumer in one process. HTTP changes the transport, not the shape. ```typescript import { Agent, InMemoryEventStore, Instruct, RemoteAgent, isCall, loopbackTransport, type DeferredTool, } from "@fifthrevision/axle"; const askUser = { type: "deferred", name: "ask_user", description: "Ask the person a question and wait for their answer", schema: z.object({ question: z.string() }), } satisfies DeferredTool; const served = new Agent({ provider, model, tools: [askUser] }); const store = new InMemoryEventStore(served); const remoteAgent = new RemoteAgent( loopbackTransport(store, async (command) => { switch (command.type) { case "send": { const handle = served.send(Instruct.fromJSON(command.instruct), { id: command.id }); handle.final.catch(() => {}); return { accepted: true as const }; } case "answer": { const call = served.toolCall(command.callId); if (!call) { return { accepted: false as const, reason: { type: "not-waiting" as const, message: `No waiting call ${command.callId}` }, }; } await call.answer(command.content); return { accepted: true as const }; } case "fail": { const call = served.toolCall(command.callId); if (!call) { return { accepted: false as const, reason: { type: "not-waiting" as const, message: `No waiting call ${command.callId}` }, }; } await call.fail(command.message); return { accepted: true as const }; } case "cancel": case "stop": { const took = command.type === "cancel" ? served.cancel() : served.stop(); return took ? { accepted: true as const } : { accepted: false as const, reason: { type: "idle" as const, message: "No active turn" }, }; } case "clear": served.clear(); return { accepted: true as const }; } }), ); const transcript = new Transcript(); remoteAgent.on((event) => transcript.apply(event)); remoteAgent.onToolCall((call) => { if (!isCall(askUser, call)) return; return prompt(call.input.question); }); const result = await remoteAgent .send("Ask me my favourite colour, then tell me one fact about it.") .final; remoteAgent.close(); ``` The served side keeps working exactly as it would locally — deferred calls and all. The consumer answers `ask_user` from its own `onToolCall`, folds events into its own transcript, and reads the result off `final`. The switch in the middle is the only new code, and over HTTP it looks the same, with `parseAgentCommand` checking the body and `toEventStreamResponse` writing the stream — [Remote agents over HTTP](/cookbook/remote-over-http) is that version, with both routes and the reconnect. ## What crosses the wire Commands go in; everything else comes out as events. A command's response only says whether the agent took it — `{ accepted: true }`, or `not-waiting` for an answer to a call nobody is waiting on, `idle` for a cancel or stop with no active turn. Results, the waiting call, the settled turn: those arrive as events, so every consumer of the store sees them, not just the one that asked. A `send` crosses as the `Instruct` itself — serialized data carrying the prompt with everything already in it, its files, and the schema. The served side renders it, so the remote `send` still takes an `Instruct`, and `final` still gives you the parsed object. Per-send request options don't cross either; the served agent's configuration applies. A 0.36 client and a 0.37 host do not interoperate — the old shape (a rendered `prompt`) is rejected — so deploy both sides together. Two things don't survive the trip. A remote result carries no `after` list — the inline sends' schemas live on the served side, so only their turns cross. And an `error` outcome crosses as its message, not as the error the served side threw. ## Status and connection are separate ```typescript import { RemoteAgent } from "@fifthrevision/axle"; declare const remoteAgent: RemoteAgent; remoteAgent.connection; // connecting → open → ended | error remoteAgent.status; // the served agent's own idle/busy — idle until the stream opens remoteAgent.onConnection((connection) => console.log(connection.phase)); ``` `connection` is the link: `connecting` until the stream opens, `open` while it runs, then `ended` or `error`. `status` is the served agent: what the stream opened with, then moved by `operation:start` and `agent:idle` — and already reading the new value whenever `on` or `onConnection` fires, so snapshotting it from both misses no change. A remote `onToolCall` handler receives the call and no `ToolContext`: no `emit` for progress, no `signal` — cancellation is visible from the events. ## Resuming after a drop Every event carries a cursor, and every turn folded from one keeps it as `turn.cursor`. Pass the last one back when you reconnect and the store fills the gap: ```typescript const resume = new RemoteAgent( httpTransport(url, { after: transcript.turns.at(-1)?.cursor }), ); ``` A dropped stream reopens with the last delivered cursor, so a reconnect sees exactly what it missed. A `404` or `410` ends the agent instead — there is no agent at that URL anymore, and every open `final` rejects. `close()` ends it deliberately. ## Next - [Remote agents reference](/reference/remote) — every method, transport, and wire type - [Turns & Transcripts](/concepts/transcripts) — folding the stream you receive - [Sessions & persistence](/concepts/sessions) — saving the session alongside the turns --- # Compaction Source: https://axle.fifthrevision.com/concepts/compaction _Trading a long conversation for a shorter one, without losing what the reader sees._ **Experimental** Compaction is still under active design and may change in any release. It was restructured in 0.30.0 and its sizing contract changed in 0.31.0. Everything here is accurate for 0.32.0, but do check the changelog when you upgrade. **a conversation gets too long for the model's context window.** Compaction is the answer: it swaps the active conversation for a condensed rewrite. The old messages stop existing for the model, while your [transcript](/concepts/transcripts) keeps a `compaction` part marking where it happened — so your user still sees a coherent history. ## Three layers, three jobs Compaction is split so each piece answers exactly one question: | Layer | Question | | --- | --- | | `triggers` | When should we *consider* compacting automatically? | | `shouldCompactOnTrigger` | This trigger fired — should we actually do it? | | `compact` | Produce the new conversation. | ```typescript agent.setCompaction({ triggers: { beforeTurn: true }, shouldCompactOnTrigger: (state, ctx) => ctx.usage.total > 100_000, compact: async (state, ctx) => { const summary = await summarize(state.messages); return { messages: [{ role: "user", content: summary }], summary: "Summarized the earlier conversation.", }; }, }); ``` Calling `setCompaction` again replaces the whole configuration. ## The built-in compactor You probably don't want to write your own on day one. `PromptCompactor` handles both the policy and the work — it uses a model to summarize, keeps recent user messages verbatim, and reports progress while it runs. ```typescript import { PromptCompactor } from "@fifthrevision/axle"; const compactor = new PromptCompactor({ provider, model: "claude-haiku-4-5", prompt: "Summarize this conversation, preserving decisions and open questions.", thresholdTokens: 100_000, summaryWords: 1_000, appendixTokens: 10_000, }); agent.setCompaction({ compact: compactor.compact, shouldCompactOnTrigger: compactor.shouldCompactOnTrigger, triggers: { beforeTurn: true }, }); ``` Use a cheap, fast model here — summarization doesn't need your best one. The compactor treats the transcript it's summarizing as untrusted data and says so in its own system prompt, which matters if that conversation contains anything a user or a tool put there. `reasoning` is left unset by default for the summary call, so the summarizing model follows its own default. Pass an explicit setting such as `reasoning: { effort: "medium" }` (and `providerOptions` for the knobs) if you want a thinking-capable model to do the summarizing — most of the time you don't, which is why it's opt-in. See [Reasoning models](/cookbook/reasoning#turning-it-off) for the trade-off. The two size controls are denominated in their honest units. `summaryWords` steers the summary length in words — a word count is the only size a model can actually aim for — and is enforced by escalation: the prompt asks for it, the result is measured, one relative-shrink rewrite runs if it lands over ~1.3× the request, and word-boundary truncation is the last resort. `appendixTokens` budgets the verbatim recent-user-message appendix in tokens (up to the last ten user messages, evicted oldest-first); it defaults to a tenth of `thresholdTokens`, and `0` keeps no appendix. The summarizer request carries no output cap, so thinking models summarize reliably at any reasoning setting. ## Triggers | Trigger | Fires | | --- | --- | | `beforeTurn` | After the user message commits, before the provider request | | `afterTurn` | After the response is parsed, at the end of the send | | manual | Whenever you call `agent.compact()` | `beforeTurn` is usually what you want — it keeps the *next* request inside budget. `afterTurn` compacts eagerly so the cost lands after your user already has their answer, which can feel snappier. `agent.compact()` skips `shouldCompactOnTrigger` entirely. If you asked for it explicitly, Axle does it. ```typescript const applied = await agent.compact(); // false if no config is registered ``` **Don't await compact() from inside a send** Like `snapshot()`, it queues behind in-flight work and will deadlock if you call it from a tool's `execute` or from a compaction callback. ## Writing your own compactor ```typescript const compact: CompactionCallback = async (state, ctx) => { ctx.usage; // ContextUsage before compaction ctx.trigger; // "manual" | "beforeTurn" | "afterTurn" ctx.signal; // abort signal ctx.id; // this compaction's id — the emitted part shares it ctx.emit({ progress: 0.5, summary: "Summarizing…" }); return { messages: newMessages, summary: "Compacted 40 messages." }; }; ``` Four things that are easy to get wrong the first time: - **Return the complete new conversation**, not a delta. What you return *becomes* `agent.messages`. - **There's no decline path.** Declining automatic work is `shouldCompactOnTrigger`'s job. Failures throw. - **`summary` is a presentation choice**, independent of the messages you return. It can be the summary text, or `"Reduced context by 50%"`, or nothing at all. Omit it and the last emitted transient summary stands; with none at all, the part renders as a bare divider. - **`shouldCompactOnTrigger` has to be synchronous and cheap.** It runs at every configured boundary. ### Your messages have to stand alone Axle validates what you return before applying it, because providers reject malformed conversations: - Every tool call must be answered by the tool message immediately after it, with nothing interleaved. - Every tool result must answer a preceding call. - No unanswered tool calls at the end. Violations throw `AxleError` with code `COMPACTION_INVALID_MESSAGES`, and nothing gets applied. In practice this means one rule: when you truncate, cut at a clean turn boundary, never in the middle of a tool exchange. ### Recognizing your own output Stamp the messages you emit, so a later run can tell which part of the conversation is already-compacted output: ```typescript import { getCompactionStamp, type CompactionCallback } from "@fifthrevision/axle"; const compact: CompactionCallback = async (state, context) => { // Skip anything a previous run of this compactor already produced. const fresh = state.messages.filter((message) => !getCompactionStamp(message)); return { messages: [ { role: "user", content: await summarize(fresh), metadata: { axleCompaction: { id: context.id, role: "summary" } }, }, ], }; }; ``` `PromptCompactor` uses this to avoid summarizing its own summaries — which otherwise degrades badly over a long session. ## What your user sees Compaction is ordinary, fallible turn work, streamed like a tool call. It lands in whatever turn context is natural: - `beforeTurn` → at the head of that send's agent turn - `afterTurn` → at the tail - `manual` → in its own engine-opened turn The part carries `trigger` (`manual`, `beforeTurn`, `afterTurn`) and moves from `running` to `complete`, `cancelled`, or `error`. A compaction that `shouldCompactOnTrigger` declined never appears at all. A settled `complete` part means the message swap applied, atomically. An `error` part records a failed attempt — and importantly, that's **non-fatal for automatic triggers**: the send carries on with the conversation uncompacted. A failed manual `compact()` rejects, since you asked for it directly. A compaction stopped by a cancel ends `cancelled` (`compaction:cancelled`) with `status: "cancelled"` and no `error` — only a failed compactor emits `compaction:error`. ## Cancelling mid-compaction Cancelling during `beforeTurn` compaction does **not** unwind the transcript. The user message is already committed, compaction is work inside that open turn, and the turn simply gets marked cancelled. See [Agent](/concepts/agent#interrupting-four-different-things). ## Next - [Sessions & persistence](/concepts/sessions) - [Turns & Transcripts](/concepts/transcripts) - [Configuration reference](/reference/configuration) --- # Skills Source: https://axle.fifthrevision.com/concepts/skills _On-demand instructions the model loads itself — the catalog, view-skill, and live updates._ A skill is packaged instructions for a specific task — how to fill a PDF, how to run the deploy checklist — that the model loads only when the task matches. Instead of pasting every playbook into the system prompt, you disclose a one-line catalog and let the model pull the full text on demand. ```typescript import { Agent, type Skill } from "@fifthrevision/axle"; const pdfFill: Skill = { name: "pdf-fill", description: "Fill a PDF form from JSON using the pdf-fill script.", instructions: "Run ./scripts/fill.sh with --help first. Never guess field names…", }; const agent = new Agent({ provider, model, tools: [myTool], skills: [pdfFill] }); ``` That's the whole setup. The agent's system prompt now carries a catalog section after your prompt — one `- pdf-fill: Fill a PDF…` line — plus a `view-skill` tool. When a task matches a description, the model calls `view-skill` with the name and gets the full instructions back as a tool result, like any other. ## A skill is not a tool This is the distinction worth getting right. A tool is capability — code that runs. A skill is instructions — text the model reads. The skill above doesn't fill PDFs; it tells the model *how* to fill them with the `exec` tool you already registered. Skills reach files only through the tools the host registered, which is also why they're safe to share: no skill can do anything your tool set doesn't already allow. In core a `Skill` is plain data: ```typescript interface Skill { name: string; description: string; instructions: string; // the SKILL.md body, frontmatter stripped root?: string; // opaque base your tools understand — a directory, an s3:// prefix, anything files?: string[]; // relative to root, listed not read frontmatter?: SkillFrontmatter; // license, compatibility, metadata, allowed-tools } ``` `root` is printed to the model verbatim so relative paths in `instructions` resolve; core never reads a skill's files. `files` is a listing, not content. ## The two tiers core guarantees Progressive disclosure in two steps. Tier one: the catalog in the system prompt, rendered from `agent.skills` as it is right now. Tier two: the `view-skill` tool, whose `name` argument is an enum of the loaded skills, which returns the instructions wrapped in `` with the directory and file listing when the skill has them. Tier three — reading references, running scripts — works exactly as far as your tools can read what `root` names. With no skills there is no surface at all: `system` is your prompt alone and no tool is registered, at construction and after the last skill is removed. And since the catalog lives in the system prompt, it survives compaction while activated content compacts like any other tool result. Two escaping details, both deliberate. Descriptions and compatibility notes are author text the model reads for meaning, so angle brackets and line breaks are neutralised where they're printed. The body, `root`, and file names print raw — the body is Markdown whose code samples escaping would mangle, and the model hands paths back to your tools exactly. ## Loading from disk Skills on disk follow the Agent Skills format: a directory with a `SKILL.md` whose frontmatter has `name` and `description` and whose body is the instructions. `loadSkill` reads one; `parseSkillMarkdown` parses text you already hold (handy for zip bundles or object storage): ```typescript import { loadSkill, parseSkillMarkdown } from "@fifthrevision/axle"; const fromDisk = await loadSkill("./skills/pdf-fill"); ``` Parsing is strict on the required fields — no frontmatter, an empty `name` or `description`, or bad YAML throws `SKILL_INVALID` naming the field — and lenient on the name otherwise, except for `<`, `>`, `"`, and line breaks, which are rejected in the parser and again on registration. Don't name a host tool `view-skill`: it collides at construction or at the `add` that would publish, whichever comes first. ## Live updates `agent.skills` is a `SkillRegistry` you change at any time — `add`, `remove`, `set` (which replaces the whole list atomically), `has`, `get`, `list`, `size`. Every change rebuilds the `view-skill` tool from the current list, and the agent hands its prompt and tool lists to the loop at turn open and again at every tool-batch boundary. So a change lands on the next provider request, whether you made it between turns or from inside a tool during one: ```typescript agent.skills.add(await loadSkill("./skills/deploy")); agent.skills.remove("pdf-fill"); agent.skills.set([pdfFill]); ``` If your application lets users *configure* agents, definitions name skills by reference — `skills: [{ name: "pdf-fill" }]` — and your resolver turns them into `Skill[]`, exactly like tools. See [Sessions & persistence](/concepts/sessions). ## Next - [Skills reference](/reference/skills) — every signature - [The tool registry](/concepts/tool-registry) — the sibling live collection - [Agent](/concepts/agent) — what owns the registry --- # Analyzing a conversation Source: https://axle.fifthrevision.com/concepts/analyze _Reading stored turns with analyze() — segments, predicates, and simplifying helpers._ **Experimental** `@fifthrevision/axle/analyze` is experimental and may change in a minor release. **a run is over, the turns you saved know everything about what happened —** what failed, what the model recovered from, how the conversation ended. But turns are shaped for rendering, not for counting. `analyze()` re-reads them into **segments**: plain data that says what happened and where, with no content attached. ```typescript import { analyze, byAgent, failed, named, streaks } from "@fifthrevision/axle/analyze"; const a = analyze(transcript.turns); a.tools.filter(failed); // tool calls that errored a.tools.some(named("read-file")); // did it ever call read-file? a.errors.filter((e) => e.recovered); // errors the model got past by itself a.turns.filter((t) => t.rescue).length; // user turns that followed a failed turn streaks(a.turns.filter(byAgent), failed); // runs of failed turns ``` `analyze()` takes `Transcript.turns` — from a live transcript or from storage — and returns six lists of segments in the order things happened. For one send, `analyze([result.turn])` reads the agent turn the send resolved with, no `Transcript` attached. ## What a segment is One piece of the conversation: a turn, a tool call, a subagent call, a compaction, or a piece of text the agent wrote. It says what happened and where, and carries no content. | List | Holds | | --- | --- | | `turns` | the user and agent turns | | `tools` | tool calls: ordinary, deferred, and provider tools | | `subagents` | subagent calls, each with the same six lists for its own run | | `compactions` | compaction attempts | | `texts` | the pieces of text the agent wrote, as a length | | `errors` | every segment that failed, of any kind | A turn segment carries the same lists for that turn, with `parts` (its segments in order) in place of `turns`. The same segment is one object wherever you reach it: `a.tools[0]`, its turn's `parts` entry, and — if it failed — its `a.errors` entry are identical. Every segment has `turnId`, `turnIndex`, and `depth`, and a part segment has `partId`. The fields worth knowing: - **`status`** — the turn's or part's own status. `failed`, `completed`, and `cancelled` read it. - **`error`** — `{ type, message, code? }` on a segment that failed. On a turn, `type` is the failure kind (`api`, `incomplete`, `refusal`, `parse`) or `thrown`; on a tool call it is the tool error type. - **`recovered`** — on a failed segment, whether the turn it happened in went on to complete. - **`rescue`** — on a user turn, whether the turn before it was a failed agent turn. - **`cancelled`** — on a cancelled turn, `"timeout"` or `"user"`. - **`tokens`, `ms`** — a turn's usage and duration. A tool call has `ms`, and a text segment has `chars`. - **`name`, `parameters`** — on tool and subagent calls. A deferred tool call also has `callId`. - **`threadId`** — on a user turn a continuation sent inline. ## Asking questions The JavaScript array methods are the query language. The predicates are named filters to pass to them: `failed`, `completed`, `cancelled`, `byUser`, `byAgent`, and `named(name)`. Five functions cover what a filter can't: | Function | Returns | | --- | --- | | `streaks(list, predicate)` | runs of two or more consecutive matches | | `repeats(list)` | groups of the same call or the same error made more than once | | `sum(list, pick)` | a total, such as `sum(a.turns.filter(failed), (t) => t.ms)` | | `flatten(analysis)` | the same lists with every subagent's segments folded in, told apart by `depth` | | `partOf(turns, segment)` | the original turn or part, for when you need the content | Subagents are kept apart: `a.tools` is what this agent called, and `a.subagents[0].tools` is what that subagent called. `flatten(a)` merges them — a turn's `tokens` already include its subagents' usage, so `flatten` leaves `turns` as the top-level turns. ```typescript import { failed, flatten, partOf } from "@fifthrevision/axle/analyze"; const all = flatten(a); const rows = all.tools.filter(failed).map((call) => ({ tool: call.name, type: call.error?.type, message: call.error?.message, recovered: call.recovered, })); const part = partOf(transcript.turns, a.tools[0]); // the full part, with its result ``` ## Reading instead of counting `simplify()` is the one function that keeps content. It reduces turns to what was said and done, for a person or a model to read: ids, timing, usage, annotations, and metadata are removed, and strings longer than `maxChars` (800 by default) are cut short and end with `…`. ```typescript import { simplify } from "@fifthrevision/axle/analyze"; const prompt = JSON.stringify(simplify(transcript.turns, { maxChars: 800 })); ``` Each simplified turn is `{ owner, status, error?, parts }`. A part is a `text`, a `thinking`, a `file` (name only), a `tool` (`name`, `parameters`, and `result` or `error`), a `subagent` (the same, plus its own `turns`), or a `compaction`. ## What analyze can't see `analyze()` sees what the turns record. A queued send cancelled before it started and an error thrown before any turn opened leave no turn, so neither appears. ## Next - [Turns & Transcripts](/concepts/transcripts) — what you're analyzing - [Transcript & turn events reference](/reference/transcript) — the shapes underneath - [Annotations & evals](/cookbook/annotations) — scoring turns instead of counting them --- # generate() & stream() Source: https://axle.fifthrevision.com/concepts/generate-and-stream _The tool loop, without the conversation management._ These two functions are the primitive. `Agent` is built on `stream()` and adds conversation management on top — so when you don't want a conversation, drop to this layer directly. Batch jobs, stateless request handlers, evaluation harnesses, or your own conversation container. Because there's no conversation here, there are no turns. These functions deal in **messages** and **steps**, and `stream()` emits [`StreamEvent`](/concepts/stream-events) rather than the `TurnEvent`s you'd get from `Agent`. | | `generate()` | `stream()` | | --- | --- | --- | | Returns | `Promise` (exactly `stream().final`) | A handle with `.on()` and `.final` | | Events | None | `StreamEvent` | | Cancellable | Via `signal` | Via `signal` or `handle.cancel()` | Both run the complete tool loop. Neither keeps any history — you pass `messages` in and get `messages` back. ## generate() ```typescript import { generate } from "@fifthrevision/axle"; const result = await generate({ provider, model, messages: [{ role: "user", content: "What's the weather in Lisbon?" }], tools: [getWeather], }); if (!result.ok) throw new Error(result.error.message); result.response; // the final AxleAssistantMessage result.messages; // everything produced this run ``` Watch out for one difference from `Agent`: `response` is the whole assistant **message**, not a string. Reach into `content` for the parts you want. It's deliberate — at this level you usually want more than the text. ## stream() ```typescript import { stream } from "@fifthrevision/axle"; const handle = stream({ provider, model, messages, tools: [getWeather] }); handle.on((event) => { if (event.type === "text:delta") process.stdout.write(event.delta); }); const result = await handle.final; ``` You don't have to hurry to register callbacks — processing starts on the next microtask, so anything registered synchronously after the call sees every event. `handle.cancel(reason)` aborts, and `handle.final` then rejects with `AxleAbortError` carrying `reason`, `usage`, `messages`, and `partial` (`partial` is `undefined` when the cancel landed before anything was written). ## Passing an Instruct Both take an `Instruct` in place of a final user message, which is how you get structured output without an agent: ```typescript const result = await generate({ provider, model, messages: previousMessages, // prior context — optional instruct: new Instruct({ prompt: "Answer {{question}}.", schema: z.object({ answer: z.string() }), }).withInput("question", "Should we proceed?"), }); if (result.ok) result.response.answer; // typed ``` When you give both `messages` and `instruct`, `messages` is treated as prior context and the rendered `Instruct` is appended as the new user message. With `instruct`, `response` becomes the parsed value rather than a message. ## Tools Supply tools inline: ```typescript stream({ provider, model, messages, tools: [a], providerTools: [b] }); ``` `tools` takes executable and deferred tools side by side (`AnyTool`). The loop builds every request from the values it was given. (`registry` was removed in 0.34.0 — the loop never reads one, so a tool added to a `ToolRegistry` after the call no longer appears mid-loop. To change tools or the prompt mid-loop, return them from `onToolBatchComplete`, below. See [Upgrading](/upgrading).) When the model requests several tool calls in one message, they all start at once — the step's tool phase takes as long as its longest call, and results answer in request order. `tool:exec-start` fires for every call up front and completions interleave in finish order, so key on `id`. A fatal tool error or a cancelled run aborts the batch's other calls through `ctx.signal`. There's also `onToolCall`, which answers the deferred tools in `tools` — definitions with no `execute` that the caller resolves: ```typescript stream({ provider, model, messages, tools: [a, askUser], onToolCall: (call) => { if (!isCall(askUser, call)) return; // this branch answers nothing: the call waits return prompt(call.input.question); }, }); ``` The handler receives one call (`{ id, name, input }`, input already validated) plus the tool context, and returns what an `execute` would — or throws to hand the model an error. It never sees executable tools; those always run through their own `execute`. A call the handler doesn't answer waits instead of failing: answer it from outside through the handle while it waits, or bound the wait with the tool's `timeout`: ```typescript const handle = stream({ provider, model, messages, tools: [askUser] }); handle.on((event) => { if (event.type === "tool:waiting") showPrompt(event.id, event.input); }); handle.toolCall(id)?.answer("teal"); ``` `generate()` has no handle, so nothing outside its handler can answer. It keeps failing fast: a call the handler doesn't answer, or any call when there's no handler, is an `execution` error result at once. See [Tools](/concepts/tools#deferred-tools). ## Bounding the loop ```typescript const result = await generate({ provider, model, messages, tools, maxSteps: 8 }); const result2 = await generate({ provider, model, messages, tools, maxContextTokens: 100_000 }); ``` `maxSteps` caps model requests. `maxContextTokens` caps the context budget, checked after each step's tools are answered against that step's reported usage. Crossing either one is a **stop, not an error** — you get `ok: true` with `stopped: "max-steps" | "token-limit"` and everything accumulated so far. The conversation is well-formed and continuable, and it's your call whether to compact and carry on. Non-positive limits throw at call time. `streamStallMs` is the other bound: the longest gap in milliseconds between two chunks from the provider on one step's stream, the wait for the first included. When it passes, the request aborts and the run ends `ok: false` with an `api` / `StreamStall` failure. It is not retried, and it is unset by default — reach for it when a hung socket is worse than a failed run. See [Results & errors](/concepts/results-and-errors#stops-arent-errors). ## Steering the loop yourself ```typescript handle.onToolBatchComplete((message) => (done ? "finish" : "continue")); ``` This runs after each tool batch settles. `"finish"` ends the run without another provider request — every tool in that batch has already completed and committed, so nothing is lost. It's the primitive behind `agent.stop()`. It can also steer the loop: return `{ system?, tools?, providerTools? }` (typed as `ToolBatchDecision`) and the loop continues with those inputs replacing the current ones, exactly as the initial call set them. That's how the `Agent` keeps skill and registry changes live mid-turn — the same mechanism is available to you when you drive `stream()` directly. ## One step at a time `stream()` with `maxSteps: 1` performs exactly one provider request and reads `final` — the bottom of the stack for when you're building your own orchestration and want Axle purely for provider normalization. (The standalone `generateStep()` was removed in 0.32.0 when `generate()` was unified onto the streaming transport.) ## When to use Agent instead Use `Agent` when you want history management, a FIFO queue, turn events, session snapshots, compaction, or lazy MCP resolution. That's a fair amount of machinery to rebuild, and `Agent` is essentially `stream()` plus exactly those things. ## Next - [Stream events](/concepts/stream-events) — what `stream()` emits, in full - [generate() & stream() reference](/reference/generate-stream) --- # Stream events Source: https://axle.fifthrevision.com/concepts/stream-events _The event stream the primitives emit — execution-shaped, and yours to handle._ `stream()` emits `StreamEvent`. It's the execution-layer stream: steps, raw provider output, and tool lifecycle, in the order they happen. There's no conversation down here, so there are no turns and nothing for a [`Transcript`](/concepts/transcripts) to fold. These events are execution-shaped rather than UI-shaped, and handling them yourself is the expected thing to do — the opposite of the advice for [turn events](/concepts/turn-events). ```typescript import { stream } from "@fifthrevision/axle"; const handle = stream({ provider, model, messages: [{ role: "user", content: "Hello" }], tools: [myTool], }); handle.on((event) => { switch (event.type) { case "step:start": console.log("request", event.id, event.model); break; case "text:delta": process.stdout.write(event.delta); break; case "tool:exec-complete": console.log("tool done", event.name); break; } }); const result = await handle.final; ``` You don't have to race to register callbacks — processing starts on the next microtask, so anything you register synchronously after `stream()` returns will see every event. ## What's different from turn events If you've come from `agent.on()`, four things change: - **Deltas carry `accumulated` as well as `delta`**, so you never have to concatenate yourself. Turn events assume a `Transcript` is holding the part. Every text and thinking event also carries `index` — the part's position in the step's assistant message — so a late citation still finds its part. - **Tool events correlate by `id`**, not by part id. - **Text and thinking stream sequentially**, and a delta belongs to the most recently opened part of its kind. - **`step:start` / `step:complete` are visible.** Turn events deliberately hide the loop boundaries by flattening every step into one turn; here they're the primary structure. ## The event families - **Step and batch boundaries** — `step:start`, `step:complete`, `tool-results:start`, `tool-results:complete` - **Text** — `text:start`, `text:delta`, `text:citation`, `text:end`, plus `citation` for an unanchored source list - **Thinking** — `thinking:start`, `thinking:raw-delta`, `thinking:summary-delta`, `thinking:update`, `thinking:end` - **Tools** — `tool:request`, `tool:args-delta`, `tool:exec-start`, `tool:waiting`, `tool:exec-delta`, `tool:exec-complete`, `tool:exec-error` - **Provider tools** — `provider-tool:start`, `provider-tool:input`, `provider-tool:complete`, `provider-tool:error` - **Error** — `error` Every field is listed in the [generate() & stream() reference](/reference/generate-stream#streamevent). ## Steering the loop `onToolBatchComplete` runs after each tool batch settles and decides whether to keep going: ```typescript handle.onToolBatchComplete((message) => { return shouldStop ? "finish" : "continue"; }); ``` `"finish"` ends the run without another provider request — every tool in that batch has already completed and committed, so nothing is lost. This is the primitive [`agent.stop()`](/concepts/agent#stop-wind-down-gracefully) is built on, if you want that behaviour in your own loop. ## Waiting on a deferred call A call to a deferred tool never executes — there is no `tool:exec-start` for it. Instead, `tool:request` carries `kind: "deferred"`, and once the arguments validate, `tool:waiting` fires with the call's `id`, `name`, and `input`. That event is your cue to prompt whoever answers: the `id` is what `handle.toolCall(id)` takes. The call closes with `tool:exec-complete` (answered) or `tool:exec-error` (failed, timed out, or aborted) like any other call. See [Tools](/concepts/tools#deferred-tools). ## What about generate()? `generate()` is `stream()` resolved as a promise — the same request, the same tool loop, and the same result, without streaming. No events at all. It's the right choice for batch work where nobody's watching. ## If you want render state anyway `TurnEventBuilder` performs the same `StreamEvent` → `TurnEvent` translation `Agent` does internally, so you *can* build a transcript from a raw `stream()`. But if that's what you want, you probably want `Agent` — it's `stream()` plus exactly that translation, history management, and a send queue. Reach for the builder only when you need the loop control the primitives give you *and* a rendered conversation. ## Next - [generate() & stream()](/concepts/generate-and-stream) — the functions themselves - [Turn events](/concepts/turn-events) — the Agent-layer equivalent - [generate() & stream() reference](/reference/generate-stream) — every event field --- # Typed decisions Source: https://axle.fifthrevision.com/concepts/decisions _One request, one typed answer per question — decide() and the typesafe() provider._ Some calls aren't conversation. You have a support ticket and want to know "is this a bug, and who owns it?" — not a sentence, but two typed values. That's a decision: one input, a set of typed questions about it, one answer per question, no messages, no turns, no tool loop. **Experimental** Decisions are marked `@experimental`: the question, answer, and provider shapes may change in a minor release. ```typescript import { decide, typesafe, noul, choice } from "@fifthrevision/axle"; const decisionProvider = typesafe(process.env.TYPESAFE_API_KEY!); const result = await decide({ provider: decisionProvider, model: "jev-latest", input: "Refund request #4821: customer was charged twice after a failed checkout.", questions: { isBug: noul("Is this a bug in our checkout?"), owner: choice("Which team owns this?", { payments: "Money movement and charging", frontend: "UI and checkout flow", }), }, }); if (result.answers.isBug.type === "noul" && result.answers.isBug.noul > 0.8) { const owner = result.answers.owner; console.log(`likely a bug — queue for ${owner.type === "choice" ? owner.choice : "triage"}`); } ``` Questions are built with three helpers. `noul` is yes/no — its answer `noul` is the probability of yes, 0 to 1, where near 0.5 means unsure rather than "partly". `choice` picks one option you define — its answer carries the chosen option, a probability per option, and a confidence. `score` places the input on an ordered scale you define, lowest level first — its answer `score` is a probability-weighted, zero-based position that can fall between levels. `criteria` is your description of the possible answers in each case. ## Answers come back under your keys Questions are a map keyed by names you choose, and answers arrive under the same keys — typed from the questions when you write them literally, so a `choice` over `payments` and `frontend` yields a `choice` answer whose `choice` is `"payments" | "frontend"`. Every answer is its own type or a refusal: narrow on `type` before reading a value. ```typescript const answer = result.answers.owner; if (answer.type === "refusal") { // the provider declined this question; the rest of the decision stands } else { console.log(answer.choice, answer.confidence); } ``` A refusal belongs to one question and is unrelated to the chat-side `Refusal`, which describes a declined request or blocked output. ## decide() throws; it does not return ok There is no partial state to hand back, so there is no `ok` flag. A rejected request, a transport failure, a timeout, or an abort rejects the promise — and a result that contradicts its questions (a missing or mistyped answer) throws `DECISION_ANSWER_MISMATCH`. `result.usage` carries the provider's input and output token counts. Pass `signal` to abort, `span` to trace (it opens a child span named `decide`). `typesafe()` reaches TypeSafe's System One API and nothing else: it answers `decide()` questions and cannot generate text, so the type system rejects it as the `provider` of `stream()`, `generate()`, or an `Agent`. Point `baseUrl` at a compatible host (an OpenRouter key with `https://openrouter.ai/api`) to route through it. ## Next - [Decisions reference](/reference/decisions) — every signature - [Providers & models](/concepts/providers) — the chat-side counterpart - [generate() & stream()](/concepts/generate-and-stream) — the other primitive --- # Providers & models Source: https://axle.fifthrevision.com/concepts/providers _Protocols, providers and presets; naming models; controlling requests portably._ A provider answers two questions, and since 0.35.0 it answers them in two separate fields: **which wire format** to speak, and **which service** to speak it to. ```typescript import { anthropic } from "@fifthrevision/axle"; const a = anthropic(process.env.ANTHROPIC_API_KEY!); a.protocol; // "messages" — the wire format it speaks a.id; // "anthropic" — the service it reaches, as models.dev names it ``` You hand one to an `Agent` (or to `stream()` / `generate()`) and then mostly forget about it. The split is still worth understanding once, because it is what makes "same model, different route" a one-line change. ## The four protocols Four wire formats cover the field. Each has a constructor of the same name that returns a provider speaking it at any base URL. | Protocol | The API it speaks | Who serves it | | --- | --- | --- | | `messages` | Anthropic Messages | Anthropic; Claude on Bedrock | | `responses` | OpenAI Responses | OpenAI; what Mantle serves on Bedrock | | `generateContent` | Google Gemini | Gemini | | `chatCompletions` | OpenAI Chat Completions | everyone else: OpenRouter, Together, Ollama, vLLM, LM Studio, most gateways | A protocol is not a vendor — that's the point of keeping the two apart. `messages` serves Anthropic, Claude on Bedrock, and any proxy in front of either; `chatCompletions` serves a dozen services that implement one API. One string could never say both things, which is why `AIProvider.name` became `protocol` + `id` in 0.35.0. ## Presets The named factories are presets: a protocol constructor with one service's base URL, `id` and quirks filled in. There is nothing else in them. ```typescript import { anthropic, messages, openrouter, chatCompletions, openrouterDialect } from "@fifthrevision/axle"; anthropic(apiKey); // is messages({ baseUrl: "https://api.anthropic.com", apiKey, id: "anthropic", resolveModel: … }) openrouter(apiKey); // is chatCompletions({ baseUrl: "https://openrouter.ai/api/v1", apiKey, id: "openrouter", dialect: openrouterDialect }) ``` | Preset | Protocol | `id` | | --- | --- | --- | | `anthropic(apiKey)` | `messages` | `anthropic` | | `openai(apiKey)` | `responses` | `openai` | | `gemini(apiKey)` | `generateContent` | `google` | | `openrouter(apiKey)` | `chatCompletions` | `openrouter` | | `togetherai(apiKey)` | `chatCompletions` | `togetherai` | | `bedrock(apiKey, { protocol, region })` | the one you name | `amazon-bedrock` | `bedrock()`'s protocol follows the model: `messages` for Claude, `responses` or `chatCompletions` for what Mantle serves. Call a constructor yourself when no preset fits — a gateway, a logging proxy, a local runtime, a test double: ```typescript import { chatCompletions, messages } from "@fifthrevision/axle"; const local = chatCompletions({ baseUrl: "http://localhost:11434/v1" }); const viaProxy = messages({ baseUrl: "https://proxy.example.com", apiKey }); ``` Presets take no `baseUrl` of their own; redirecting one is what the constructor is for. (`openrouter()` is the exception, for OpenRouter's regional hosts, and `typesafe()` — a [decision provider](/concepts/decisions), not an `AIProvider` — keeps its own.) A preset also passes its base URL explicitly, so the vendor SDKs' environment variables no longer redirect it. ## What each field is for **`protocol`** builds the request and parses the stream. It is the only field that decides what goes over the wire. **`id`** is the models.dev provider id, stamped on every usage row — which is how a run gets priced, since a price belongs to a service and model together, not to a model alone. Each constructor infers it from the base URL's hostname when it recognizes one (`api.anthropic.com`, `api.openai.com`, `generativelanguage.googleapis.com`, `openrouter.ai`, `api.together.ai`, `api.together.xyz`, subdomains included) and leaves it `undefined` otherwise, so a provider at `localhost` produces rows that can't be priced. Point a known service's protocol at your own hostname and you should pass `id` yourself. See [Model catalog & cost](/concepts/model-catalog). **`dialect`** exists on `chatCompletions` alone, and carries one service's deltas from the shared API: the fields that express a reasoning setting, what keeps a session pinned to the same upstream, which provider tools the service hosts itself, how it reports a citation. Axle ships `openrouterDialect` and `togetheraiDialect`, and infers the dialect from the same hostnames as the `id`. Behind a proxy the hostname says nothing, so pass both: ```typescript const viaGateway = chatCompletions({ baseUrl: "https://gateway.example.com/v1", apiKey, id: "openrouter", dialect: openrouterDialect, }); ``` A `chatCompletions()` provider works without a dialect; it just won't read OpenRouter's `reasoning_details` or a citation's quoted text, so thinking continuity is lost. Prefer the `openrouter(apiKey)` and `togetherai(apiKey)` presets when you talk to those services directly. Two providers can share an `id` — Bedrock in two regions — and one protocol serves many ids. Both are fine: the fields are independent on purpose. ## Switching providers Provider and model are two constructor fields. That's the whole switch — your tools, `Instruct`s, schemas, and event handling don't change at all. And if you name models the [portable way](#one-model-string-any-inference-provider), often only the provider changes. ```typescript const agent = new Agent({ provider: anthropic(apiKey), model: "claude-sonnet-4-5" }); // same tools, same Instructs, same events const cheaper = new Agent({ provider: gemini(apiKey), model: "gemini-2.5-flash" }); ``` A fair warning about what *isn't* portable: `providerOptions` (it's raw passthrough), provider tool configuration payloads, and whatever a particular model chooses to do with `reasoning`. Those are the escape hatches, and using them ties that agent to that vendor. Which is fine — just know when you're doing it. Enabling reasoning (`{ effort }` or `{ enabled: true }`) now also requests disclosure wherever a request field exists, so Claude and OpenAI stream thinking where they previously streamed none — pass `{ effort, display: "hidden" }` to keep the old wire behaviour. See [Reasoning models](/cookbook/reasoning#disclosure-vs-form). ## Naming models You can pass whatever string the vendor expects: ```typescript model: "claude-sonnet-4-5"; model: "gpt-5.1"; ``` But there's a better option. First-party providers also accept **publisher-namespaced** ids and strip the prefix themselves: ```typescript model: "anthropic/claude-sonnet-4-5"; // anthropic() sends "claude-sonnet-4-5" ``` Both forms work identically against `anthropic()`. The reason to prefer the namespaced one is that it's a *portable identity* rather than one vendor's wire format. ### One model string, any inference provider Third-party inference providers like OpenRouter address models by publisher — `anthropic/claude-sonnet-4-5` is already exactly what their API wants. So the namespaced form is the string that works everywhere: ```typescript const model = "anthropic/claude-sonnet-4-5"; // direct — strips the prefix new Agent({ provider: anthropic(key), model }); // through OpenRouter — passes it straight through new Agent({ provider: openrouter(key), model }); ``` Same string, no branching. Switching between a first-party provider and an inference provider becomes a one-line provider change — which is what you want when you're moving between direct API access and a gateway for cost, routing, or availability reasons. Pass the slug the gateway lists. `chatCompletions()` no longer rewrites model IDs — the alias table for OpenRouter slugs that differed from the publisher's canonical form was removed in 0.33.0, so `zai/glm-5.3` stays `zai/glm-5.3` and you should pass `z-ai/glm-5.3` yourself. ### The safety net Hand a model from the wrong publisher to a first-party provider and it throws immediately rather than forwarding it and failing at the API — `anthropic()` rejects `"openai/gpt-5.1"` before it costs you a round trip. Accepted prefixes are what you'd guess, with one convenience: `gemini()` takes both `google/` and `gemini/`. Stripping is the preset's doing, not the protocol's: a constructor you call yourself sends the model id exactly as given. Pass `resolveModel` if you want the same behaviour behind your own base URL. Full signatures are in the [Providers reference](/reference/providers#protocol-constructors). ### No model registry There is no model registry. Axle ships no list of models, no context windows, no output ceilings — model IDs are plain strings your application owns. A model hosted by several vendors has a different ID on each, so a shared constant could never be portable with `chatCompletions()` anyway. ```typescript const model = "openai/gpt-5.5"; ``` (The `@fifthrevision/axle/models` entry point and its `Models`, `ModelInfo`, and `ModelMetadata` exports were removed in 0.33.0 — see [Upgrading](/upgrading).) When you do need a ceiling, a capability flag or a price, there is an opt-in data layer for it: `ModelCatalog` indexes the models.dev catalog, and `computeCost(usage, catalog)` prices a `Stats` with it. Neither is a registry — you load and store the data, and the runtime never consults it. See [Model catalog & cost](/concepts/model-catalog). ## Request options These get normalized by Axle and mapped onto each provider's request shape. Set them as defaults on the `Agent`, or per send when one call needs something different. ```typescript const agent = new Agent({ provider, model, maxOutputTokens: 4096, reasoning: { effort: "medium" }, }); // Just this one send — merged over the agent's defaults await agent.send("...", { maxOutputTokens: 1024 }).final; ``` | Option | What it does | | --- | --- | | `reasoning` | Portable thinking/reasoning control: `"default"` or `{ enabled?, effort?: "minimal" \| "low" \| "medium" \| "high" \| "xhigh" \| "max", display?: "visible" \| "hidden" }` — `display` (default `"visible"`) asks the provider to disclose its thinking | | `maxOutputTokens` | Caps output tokens for the request | | `toolChoice` | `"auto"`, `"none"`, `"required"`, or `{ type: "tool", name }` | | `parallelToolCalls` | Asks the provider to avoid parallel tool calls | | `cache` | Asks the provider to cache the prompt prefix where asking is required (Anthropic, OpenRouter). Defaults to on; `false` omits the field | | `providerOptions` | Raw passthrough, applied *after* Axle's mappings | | `signal` | Aborts the request | Sampling controls (`temperature`, `topP`) and stop sequences were removed in 0.33.0 — they were never portable, and the newest models reject them. Send them through `providerOptions` using the provider's own field names: ```typescript await agent.send("...", { providerOptions: { temperature: 0.2 } }).final; ``` | Removed option | Anthropic | OpenAI | Gemini | Chat Completions | | --- | --- | --- | --- | --- | | `temperature` | `temperature` | `temperature` | `temperature` | `temperature` | | `topP` | `top_p` | `top_p` | `topP` | `top_p` | | `stop` | `stop_sequences` | not supported | `stopSequences` | `stop` | `providerOptions` merges key by key with the agent's defaults and lands last, so it can deliberately override Axle's own mapping. It's the escape hatch for anything Axle hasn't normalized yet. ### Prompt caching Axle asks the provider to cache the prompt prefix wherever asking is required. Requests to the Anthropic provider — and chat-completions requests to the OpenRouter vendor — carry a top-level `cache_control: { type: "ephemeral" }` unless you pass `cache: false`. The provider puts one cache breakpoint on the last cacheable block and moves it forward as the conversation grows, so in a tool loop each step reads everything so far at cache-read rates and writes only what the previous step added. OpenAI, Gemini, and Together cache automatically and get no field; `cache` is ignored there, at either value. On by default is the loop's doing. Without it, every step of every tool loop re-bills the whole conversation at full price. The trade lands on one-shot prompts: a prompt that is never repeated pays the ~25% cache-write premium for a read that never comes, and a prompt under the model's minimum cacheable length (512 to 4,096 tokens on Anthropic, by model) is silently not cached either way. That one-shot case is the case for opting out: ```typescript await generate({ provider, model, messages, cache: false }); new Agent({ provider, model, cache: false }); ``` Two things worth knowing. First, `cache: false` means "do not ask", not "do not cache" — the automatic providers are unaffected. Second, an explicit `providerOptions.cache_control` still wins over the default, so a host that placed its own marker — or wants Anthropic's one-hour TTL instead of the five-minute default — is unchanged. `result.usage` reports what happened: `cachedIn` is tokens read from cache and `cacheWriteIn` tokens written, both already counted inside `in` (see [Token usage](/concepts/observability#token-usage)). And one OpenRouter wrinkle: a hit needs the next request to reach the same upstream host, which OpenRouter pins by `session_id`. `Agent` always sends its `sessionId`, and a bare `generate()` or `stream()` call gets a fresh id for its own tool loop — so hits across separate calls need a `sessionId` you pass to both. Full signatures are in the [Providers reference](/reference/providers#axlemodelrequestoptions). ## Retries and timeouts These belong to the client, so you set them when you build the provider rather than per request. ```typescript const provider = anthropic(apiKey, { maxRetries: 0, timeoutMs: 30_000 }); ``` `maxRetries` defaults to `2` on the built-in providers. `timeoutMs` defaults to whatever the vendor SDK does — except `chatCompletions()`, which gives up each attempt after ten minutes (the default the OpenAI and Anthropic SDKs already apply). The timer covers the wait for the response to start, not the stream that follows, and it restarts on every retry. A `chatCompletions()` timeout fails as `TimeoutError` (`"Request timed out after ms"`); aborting through your own signal still reports `AbortError`. Every provider factory, `typesafe()` included, also takes a `fetch` that replaces the global for that provider's requests — handy for logging or tests: ```typescript declare const loggingFetch: typeof fetch; const provider = chatCompletions({ baseUrl: "http://localhost:11434/v1", fetch: loggingFetch }); ``` ## How full is the context? ```typescript const usage = agent.context(); // { total, system, tools, mcpTools, providerTools, messages } ``` One caveat worth internalizing: these are **estimates**, computed locally from your messages and tool payloads. They're not what the provider will bill you. They're good enough to drive a compaction threshold or a progress meter, and not good enough for accounting. For real numbers, read `result.usage` after a send. What `agent.context()` can't tell you is how full "full" is — it reports no limit, because the runtime keeps no table of windows. [Model catalog & cost](/concepts/model-catalog#budgeting-the-window) is where the limit comes from. ## Next - [Agent](/concepts/agent) — the thing that uses a provider - [Model catalog & cost](/concepts/model-catalog) — windows, prices, and where `provider.id` lands - [Tools](/concepts/tools) — including the provider-managed kind - [Providers reference](/reference/providers) — every factory signature --- # Model catalog & cost Source: https://axle.fifthrevision.com/concepts/model-catalog _Looking up a model's window, budgeting the context, and pricing a run against the models.dev catalog._ Axle ships no table of models. Model ids are plain strings your application owns, and the runtime never needs to know what a model can do — see [no model registry](/concepts/providers#no-model-registry) for why that stays true. *You* sometimes need the facts anyway: how big is this model's window, what did that run cost, does this one take attachments. The catalog is the opt-in data layer for exactly those questions. It indexes [models.dev](https://models.dev), you decide where the data lives, and nothing in Axle fetches it behind your back. **Experimental** `ModelCatalog`, `ModelCatalogStore`, the catalog functions and `computeCost` are marked `@experimental`: they are new in 0.35.0 and may change in a minor release. ## Four calls, each one yours `ModelCatalogStore` holds the current catalog and moves it through its stages. Every stage is a call you make — the store never touches storage, and nothing refreshes on a timer. ```typescript import { ModelCatalogStore, catalogFile } from "@fifthrevision/axle"; const file = catalogFile("./.cache/axle-models.json"); const catalogs = new ModelCatalogStore({ providers: ["anthropic", "openai"] }); catalogs.load(await file.read()); // the saved copy, if any — no network const snapshot = await catalogs.refreshIfStale(); // JSON to save, or undefined if (snapshot) await file.write(snapshot); const catalog = catalogs.current; // ModelCatalog | undefined ``` - **`load(json)`** takes saved JSON text and ignores anything unusable — missing, corrupt, or written by an older Axle. It neither throws nor tells you; `current` just stays as it was, which on a cold start means `undefined` — a case every reader already handles. - **`refresh()`** fetches models.dev with the current data's ETags and makes the result current. It resolves the JSON snapshot to save, or `undefined` when the fetch failed: it never rejects for the network. Calls that arrive while a refresh is in flight join it, so ten requests noticing a stale catalog make one fetch. - **`refreshIfStale()`** is `refresh()` only when there is no data or it is older than `maxAge` (one day by default), and otherwise resolves `undefined`. - **`snapshot()`** is the current data as JSON, whenever you want to write it. `catalogFile(path)` is a file-backed `CatalogStorage` — `{ read, write }`, the write atomic, a missing file reading as "none". It is a convenience, not a requirement: the store speaks JSON text at both ends, so a database row or an object store works the same way. ### Nothing has to block `current` is `undefined` until a load or refresh gives it data, and every reader has an answer for that case — an unknown window, an unpriced row. So a server that must not wait reads the file, lets a refresh run, and gets on with the request: ```typescript catalogs.load(await file.read()); void catalogs.refreshIfStale().then(async (next) => { if (next) await file.write(next); }); // catalogs.current is usable now; a refresh that lands replaces it ``` On a serverless host, invert it: a scheduled job calls `refresh()` and writes the snapshot, and request handlers only ever `load()`. ## Asking the catalog something `ModelCatalog` is synchronous and immutable. It never fetches — a new catalog is how you get new data. ```typescript catalog.lookup("claude-sonnet-5", { provider: "anthropic" }); // { id: "anthropic/claude-sonnet-5", match: "provider", model: {…}, cost: {…} } catalog.contextWindow("claude-sonnet-5", { provider: "anthropic" }); // { window, id: "anthropic/claude-sonnet-5", match: "provider" } ``` `model` is a `CatalogModel`: `name`, `limit.context` / `limit.output`, `reasoning`, `toolCall`, `structuredOutput`, `attachment`, `modalities` and the `knowledge` cutoff — enough to answer "can this model take a PDF?" before you send one. `cost` is per million tokens, as that provider charges it. Both return `undefined` when nothing matches, and what to assume then is your call. That's the one decision the catalog refuses to make for you. ### What thinking a model offers ```typescript declare const thinkingOn: boolean; const found = catalog.reasoningControl(model, { provider: "anthropic" }); // { control: "levels", efforts: ["low", "medium", "high"], suggested: { effort: "medium" }, id } // | { control: "toggle", efforts: [], suggested: { enabled: true }, id } // | { control: "none", efforts: [], id } // | undefined ``` `reasoningControl()` reads the catalog's record of a provider's reasoning controls: the efforts a model offers and the `reasoning` setting to send. `control` is `"levels"` (efforts listed, `suggested` nearest medium), `"toggle"` (an on/off switch, `suggested` is `{ enabled: true }`), or `"none"` — which is different from `undefined` (the catalog has no record of the model's reasoning controls at all). It is advisory: requests are never checked against it. The usual use is picking a setting for a model chosen at run time: ```typescript new Agent({ provider, model, reasoning: thinkingOn ? (found?.suggested ?? { effort: "medium" }) : { enabled: false }, }); ``` See [Reasoning models](/cookbook/reasoning#picking-a-setting-for-a-model-you-choose-at-run-time). ### Two layers, and why a price needs a provider The data has a canonical layer, keyed `publisher/model` and independent of who serves the weights, and a provider layer, keyed by each provider's own ids with that provider's limits and prices. `lookup` tries them in order: the provider's own ids first when you pass a `provider`, then the canonical key, then a best-effort match on the model's name — the shape local runtimes hand you, with trailing build tags such as `-mlx` or `:q8_0` dropped, punctuation and case ignored, and the publisher ignored; an exact normalized match first, a unique prefix after. The result says which route it took: `match` is `"provider"`, `"exact"` or `"prefix"`, and `id` is what it landed on, so a guess is always visible as a guess. Prices live in the provider layer because that is where they are real — the same weights cost different amounts at Anthropic, at OpenRouter and on Bedrock. A lookup without a `provider` still answers the window; it cannot answer the price, and `cost` is simply absent. The `provider` you pass is a models.dev provider id, which is exactly what [`AIProvider.id`](/concepts/providers) already is: `anthropic`, `openai`, `google` for Gemini, `openrouter`, `togetherai`, `amazon-bedrock` for `bedrock()`. The same string is stamped on every usage row, so one id carries from the provider you constructed through to the price. ## Budgeting the window `agent.context()` estimates what the conversation currently occupies. The catalog supplies the other half — what it is allowed to occupy: ```typescript const limit = catalog?.contextWindow(model, { provider: provider.id })?.window; const used = agent.context().total; const share = limit ? used / limit : undefined; // 0…1, for a meter ``` Working one layer down, with no `Agent` to ask, estimate it yourself and hand `estimateContextUsage` the same limit — then `limit` and `free` come back filled in: ```typescript import { estimateContextUsage } from "@fifthrevision/axle"; const limit = catalog?.contextWindow(model, { provider: provider.id })?.window; const usage = estimateContextUsage({ system: agent.system, messages, tools, limit }); // { total, system, tools, mcpTools, providerTools, messages, limit, free } ``` `agent.context()` passes no limit of its own, so its result never carries `limit` or `free`. The limit is data; the used side is an estimate, computed locally from your messages and tool payloads — good enough for a compaction threshold or a progress meter, not good enough for accounting. For real numbers, read `result.usage` after a send. [Compaction](/concepts/compaction) covers wiring a threshold to them. ## What a run cost ```typescript import { computeCost } from "@fifthrevision/axle"; const result = await agent.send("Summarize the incident report").final; if (result.ok) { const cost = computeCost(result.usage, catalog); // { usd, priced, unpriced, pricedWith? } } ``` `computeCost` prices each row of `Stats.breakdown` separately — one row per request, each carrying its own `provider`, `model` and `requestedModel`. Per row is what makes the number right for a run that crossed models: a cheap one summarizing for compaction, a subagent on another provider entirely. Within a row, the price tier is chosen by that request's own input size, and cached, cache-write and reasoning tokens are priced at their own rates wherever the provider lists one. It is synchronous and never throws. A row it cannot price lands in `unpriced` with a reason, and the four reasons are worth knowing because each has a different fix: | `reason` | What happened | What to do about it | | --- | --- | --- | | `no-catalog` | you passed no catalog | load one | | `no-provider` | the row has no provider id — a `chatCompletions()` pointed at a host Axle doesn't recognize | pass `id` when you construct the provider | | `unlisted` | models.dev doesn't list that model under that provider | check the id you sent, or amend the data yourself | | `no-price` | the provider lists the model but no price | nothing — it was free, or it's a local runtime and the price is yours to know | `usd` sums `priced` only, so a partial answer is visibly partial: read `unpriced.length` before you show a total as *the* total. `pricedWith` is the `fetchedAt` of the catalog that priced the rows — the receipt for a number that will be wrong next month. `computeCost` is also exported from `@fifthrevision/axle/ui`, so a renderer can price a `Stats` without pulling the provider SDKs into its bundle. The catalog itself is only on the root entry point, so the usual split is to build it server-side and send the `Cost` down. ## Writing your own data `CatalogData` is plain JSON, version-stamped, and yours to amend: a negotiated rate, a self-hosted model models.dev never heard of, a fixture that needs no network. ```typescript import { fetchModelsDev, ModelCatalog } from "@fifthrevision/axle"; const data = await fetchModelsDev({ providers: ["anthropic"] }); data.providers.anthropic["claude-sonnet-5"].cost = { input: 2.4, output: 12 }; const catalog = new ModelCatalog(data); ``` `new ModelCatalog(data)` takes its data as given, so read saved text with `parseCatalogData` rather than `JSON.parse` — it validates the version and shape and returns `undefined` when there is no usable copy, which means fetch. `CatalogData` is version-stamped (version 5, which added per-provider `reasoningOptions`), and a file saved by an older Axle is treated as no usable copy — the next `refreshIfStale()` refetches. `fetchModelsDev()` is the fetch on its own if you would rather not keep a store: it resolves `CatalogData` or rejects with `CatalogFetchError`, never a partial result, so the data you already had stays the best you have. The `providers` filter is worth setting. The provider layer carries every provider models.dev knows and is most of what you would save; naming the two or three you actually use trims it. The filter is recorded as `coverage`, and a `previous` fetched under a different filter is not reused for that layer. ## Next - [Providers & models](/concepts/providers) — where `provider.id` comes from - [Observability](/concepts/observability) — the `Stats` you are pricing - [Compaction](/concepts/compaction) — spending the window you just measured - [Providers reference](/reference/providers#model-catalog-and-cost) — every signature, option and type --- # Instruct Source: https://axle.fifthrevision.com/concepts/instruct _A richer user message — templates, schemas, host context, and attachments._ `Instruct` is one user message with more in it than a string. You'll reach for it when you want any of four things: **structured output**, **template variables**, **host-supplied context**, or **file attachments**. For plain text, a string passed to `send()` is still the right answer. ```typescript import { Instruct } from "@fifthrevision/axle"; import * as z from "zod"; const instruct = new Instruct({ prompt: "Summarize the following {{topic}}.", schema: z.object({ summary: z.string(), keyPoints: z.array(z.string()), }), }).withInputs({ topic: "document" }); const result = await agent.send(instruct).final; if (result.ok) result.response.keyPoints; // string[] ``` The same object works with [`generate()` and `stream()`](/concepts/generate-and-stream) if you want a one-shot call without agent-managed history. ## Structured output Hand it a schema — a Zod schema (or any Standard Schema), or a plain JSON Schema object. Axle shows the model the JSON Schema, prepended to your prompt as output-format instructions, and parses the reply back into a typed value. ```typescript const instruct = new Instruct({ prompt: "Tell me about Mars.", schema: z.object({ name: z.string(), distanceFromSunKm: z.number(), moons: z.array(z.string()).describe("Named moons, largest first"), }), }); ``` ```typescript const instruct = new Instruct({ prompt: "Tell me about Mars.", schema: { type: "object", properties: { name: { type: "string" }, distanceFromSunKm: { type: "number" }, moons: { type: "array", items: { type: "string" }, description: "Named moons, largest first" }, }, required: ["name", "distanceFromSunKm", "moons"], }, }); ``` A Zod schema works unchanged and `response` keeps its type. `.describe()` on a field flows into the instructions shown to the model, so it's the cheapest way to clear up an ambiguous field name. And because the model sees the schema itself rather than an example object, value constraints like `.min()` and `.regex()` now reach it — as do schemas that used to throw: `.nullable()`, unions, tuples, records, `z.email()` and other formats, and non-object roots. A schema a library can't convert to JSON Schema (such as one with `z.date()`) throws that library's error. With `.transform()` the model is shown the input side, and a key with `.default()` is not required. ```typescript declare const reply: import("@fifthrevision/axle").AxleAssistantMessage | undefined; const value = await instruct.parse(reply); // Promise — validation may be async const same = await parseResponse(text, schema); ``` Parsing is async — `Instruct.parse()` and the exported `parseResponse()` return a promise, since a schema's validator may answer asynchronously. Note the `await`: code written before 0.37 that reads the value synchronously now holds a promise instead of the parsed object. If the model returns something unparseable, you get `ok: false` with `error.kind === "parse"` rather than a throw. See [Results & errors](/concepts/results-and-errors). ## Template variables `{{name}}` placeholders get filled in from inputs. ```typescript const template = new Instruct({ prompt: "Translate {{text}} into {{language}}." }); const es = template.withInputs({ text: "hello", language: "Spanish" }); const fr = template.withInput("language", "French").withInput("text", "hello"); ``` Notice that `withInputs()` and `withInput()` return **new** instances and leave the original alone. That's what makes an `Instruct` usable as a reusable template — build it once, fill it in many times. If you'd rather mutate in place, `setInputs()` and `addInput()` do that. By default `vars` is `"required"`, so a missing variable throws `AxleInstructVariableError` at send time and tells you exactly which ones are missing. Switch to `"optional"` if you want unmatched placeholders left as literal text: ```typescript new Instruct({ prompt: "Cost is {{price}}", vars: "optional" }); ``` Strings you pass to `agent.send()` are already wrapped with `vars: "optional"`, so user-typed braces will never blow up a turn. Inputs are strings, numbers, booleans, or `null` — the values that render the same on both sides of a remote send. Render anything else yourself before passing it in, and pass `null` instead of `undefined`: ```typescript template.withInput("when", new Date().toISOString()); template.withInput("tags", ["a", "b"].join(", ")); template.withInput("count", null); ``` ## Host context vs. your prompt `addContext()` appends supporting material your application supplies — a file manifest, environment details, retrieved records, application state — without touching the prompt you authored. ```typescript const instruct = new Instruct({ prompt: "Review the sandbox and propose the next change.", }); instruct .addContext("src/index.ts\nsrc/server.ts\npackage.json", { title: "Sandbox files" }) .addContext("Node.js 24\nPackage manager: pnpm", { title: "Environment" }); ``` Context sections stay in order, survive `clone()` and `withInputs()`, and deliberately skip variable substitution — which is the point, since retrieved content full of `{` characters should stay exactly as it is. **Worth being clear about** Context sections render into the same final user message as fenced `## Context N` sections. So `addContext` is a **composition boundary, not a privilege boundary** — it doesn't give that content different authority in the model's eyes. If you're passing in content you didn't author, treat it as untrusted data and say so in your system prompt. ## Files and attachments ```typescript import { loadFileContent } from "@fifthrevision/axle"; instruct.addFile(await loadFileContent("./chart.png")); // image → native file part instruct.addFile(await loadFileContent("./report.pdf")); // document → native file part instruct.addFile("Inline reference text", { name: "notes.txt" }); // → ## Reference section ``` Text becomes a fenced `## Reference N` section in the message body. Images and documents stay as file parts and get converted to each provider's native format at request time. Files can also be URLs, or host-owned deferred references that only resolve when a request actually needs them — see [Files, images & PDFs](/cookbook/files-and-images). ## What actually gets sent The stored message is the prompt — output instructions are no longer part of it. The message carries the schema as `output: { schema }`, and each request's copy of the message gets the schema prepended as output-format instructions (the directive plus the JSON Schema itself, not a field list or an example). A conversation saved by an earlier Axle keeps the old instructions in its message text and has no `output`, so it replays as it was. The final message comes together in this order: 1. Your prompt, with variables filled in 2. `## Reference N` sections, one per text file 3. `## Context N` sections, one per `addContext` call And you can just look at it: ```typescript console.log(instruct.render()); ``` `render()` returns the prompt alone — no output instructions. (Code that sent `render()` to a model itself and relied on the instructions now passes the `Instruct` to `stream()` or `generate()` instead.) Honestly, that's still the most useful debugging call in the library. When a model does something baffling, print the message first. ## Reusing an Instruct `send()` clones whatever you give it, so passing the same object twice is safe and the two sends can't interfere with each other. Clone explicitly when you want to fork a template: ```typescript const base = new Instruct({ prompt: "Answer {{q}}.", schema }); const variant = base.clone(); ``` An `Instruct` also round-trips as plain data — what crosses the wire on a remote send, and what you can persist yourself: ```typescript const data = instruct.toJSON(); const revived = Instruct.fromJSON(data); ``` A revived `Instruct` holds a JSON Schema, so its answer is parsed as JSON without validation. See [Remote agents](/concepts/remote-agents). ## Next - [Tools](/concepts/tools) - [Results & errors](/concepts/results-and-errors) - [Instruct reference](/reference/instruct) --- # Tools Source: https://axle.fifthrevision.com/concepts/tools _Five ways to give an agent capabilities — local tools, deferred tools, provider tools, MCP, and subagents._ Axle has one tool registry and four ways to fill it. | Kind | Runs where | What you supply | | --- | --- | --- | | **Executable tool** | Your process | Name, description, Zod schema, `execute` | | **Deferred tool** | Whoever holds the loop | Name, description, Zod schema — no `execute` | | **Provider tool** | The provider's infrastructure | A name and optional config | | **MCP tool** | An MCP server | A client config — Axle discovers the tools | | **Subagent** | Your process, as a nested `Agent` | A child agent factory | They all land in the same `ToolRegistry`, and the model sees one flat list. Which means names have to be unique across all five — duplicates throw as soon as you register them, rather than confusing the model later. ## Executable tools A tool is a plain object. No base class, no decorator. ```typescript import type { ExecutableTool } from "@fifthrevision/axle"; import * as z from "zod"; const getWeather: ExecutableTool = { name: "get_weather", description: "Get the current weather for a city", schema: z.object({ city: z.string().describe("City name, e.g. Lisbon") }), async execute({ city }, ctx) { const res = await fetch(`https://api.example.com/weather?q=${city}`, { signal: ctx.signal, }); return JSON.stringify(await res.json()); }, }; const agent = new Agent({ provider, model, tools: [getWeather] }); ``` **Get typed input in `execute`** Declare the schema separately and pass its type: `const tool: ExecutableTool = { schema, … }`. With a bare `ExecutableTool` annotation it still compiles, but your `input` properties come through as `unknown`. **'s the thing worth internalizing: **the description and the schema are the** prompt for this tool.** That's where the model decides whether to call it and what to pass. Time spent on a clear description and a `.describe()` on each non-obvious field pays back more than almost anything else you can do. Axle ships no concrete local tools — no filesystem, no shell. That's on purpose: what your application should expose is your call, not the library's. ## Validated before `execute` Every call's arguments are parsed with the tool's schema before `execute` runs, so `execute` receives the parsed value — with schema defaults and transforms already applied. A `z.number().default(10)` field arrives as `10` when the model omits it; you don't re-apply defaults inside `execute`. When the arguments don't match, `execute` is not called at all. The model gets an error tool result it can correct in the same turn instead: ```json { "error": { "type": "validation", "message": "Invalid arguments for get_weather: city: Invalid input: expected string, received undefined" } } ``` The message names each issue with its path (`steps.0.label` for a bad nested field, `items.1.description` inside a parallelized call), joined with `;` when there are several. Because this is an ordinary tool result — not a thrown error — the loop continues and the model usually retries with fixed arguments in the same turn. Deferred tools validate the same way before the call reaches your handler; executable tools always run through their own `execute` and never consult `onToolCall` (see [Deferred tools](#deferred-tools) below). ## One batch, all at once When the model requests several calls in one message, they all start before the loop waits on any of them: the step's tool phase takes as long as its longest call, not the sum of them. There's no concurrency cap — the model bounds the batch by how many calls it makes, and a tool that has to throttle itself (a subagent, a rate-limited client) does that inside its own `execute`. What the model sees doesn't change. Results answer **in request order**, one per call, whatever order the calls actually finished in. Three consequences are worth knowing before you write a tool: - **State shared between calls is yours to guard.** Two calls to the same tool can sit inside `execute` at the same time, and `onToolCall` is called once per deferred call with no ordering between calls — executable calls run beside it. - **An ordinary failure touches no sibling.** Arguments that fail the schema, a tool that isn't found, a plain `throw` — each becomes that call's error result, the other calls run to completion, and the model sees every result. - **A fatal failure ends the batch, but every call is still answered.** `AxleToolFatalError` aborts the other calls through their `ctx.signal`, the loop waits for every one to settle, and then it commits the tool results message before rethrowing: a call that returned keeps its real result, the fatal call gets an `isError` result with `{"error":{"type":"fatal","message":…}}`, and each call cut short by the abort gets an `isError` result with `{"error":{"type":"cancelled","message":…}}`. Results answer in request order, so the history stays valid and a follow-up send is accepted. A cancelled run settles the same way — the only difference is every unfinished call reads `cancelled`. Events follow the same shape: every call's `action` part opens before any of them completes, and the phases interleave from there, so a renderer keys on the part's `id` rather than on "the running tool". See [A tool call, in phases](/concepts/turn-events#a-tool-call-in-phases). A [deferred call](#deferred-tools) is a call in the batch like any other: the batch waits for its answer exactly as it waits for a running tool, so everything above holds for it too. One consequence is easy to miss — a deferred call that nobody has answered yet keeps waiting while its siblings finish, and the run's abort settles it like any other call. `parallelize` is a different thing — one call, many items, under a cap you set. See [Running a tool over many inputs](#running-a-tool-over-many-inputs). ## The tool context `execute` gets a `ToolContext` as its second argument: ```typescript async execute(input, ctx) { ctx.signal; // AbortSignal — please forward it to your I/O ctx.emit("Fetching…"); // stream progress to the UI ctx.reportUsage(usage); // roll a nested model call's tokens into the parent ctx.span; // tracing span for this call } ``` `ctx.emit` is what makes a slow tool feel alive — whatever you pass shows up as `action:progress` events while `execute` is still running. Without it, a ten-second tool just looks frozen to your user. `ctx.signal` is the **batch's** signal, not the run's. It aborts when the run is cancelled, with the run's reason, and also when a sibling call in the same batch fails fatally, with that sibling's error as the reason. So forwarding it to your I/O buys you two things: cancellation, and not holding a batch open after another call has already doomed it. (`ctx.registry` was removed in 0.34.0. A tool that changes the agent it runs under uses that agent in closure scope — `agent.registry.add(...)`, `agent.skills.add(...)` — and the change lands on the next provider request, even mid-turn. See [The tool registry](/concepts/tool-registry).) ## Returning more than text `execute` can return a string, or an array of parts including files: ```typescript async execute() { const image = await loadFileContent("./chart.png", "base64"); return [ { type: "text", text: "Chart attached." }, { type: "file", file: image }, ]; } ``` [Files, images & PDFs](/cookbook/files-and-images) covers URL and deferred-reference sources. ## When a tool fails There are two ways a call becomes an error tool result, and they're worth telling apart. A **validation** error means the arguments never matched the schema — `execute` never ran, and the message names each issue so the model can fix the call. An **execution** error means `execute` ran and threw — an ordinary throw inside `execute` becomes a tool error result that goes back to the model, which usually retries or works around it. The run keeps going in both cases. That's almost always what you want. If you need to kill the run instead, throw `AxleToolFatalError` — that propagates out of `send()` rather than resolving as a result, and it takes the rest of the batch with it (above). Save it for cases where carrying on would be incoherent, like the sandbox your tool operates on no longer existing. See [Results & errors](/concepts/results-and-errors). ## Deferred tools Some calls can't be answered by code — they need a person. A deferred tool is a tool definition with no `execute`: the model calls it like any other tool, and whoever holds the loop answers each call. ```typescript import type { DeferredTool } from "@fifthrevision/axle"; const askUser = { type: "deferred", name: "ask_user", description: "Ask the person a question and wait for their answer", schema: z.object({ question: z.string() }), } satisfies DeferredTool; ``` Register it like anything else — `tools` takes executable and deferred side by side — and answer its calls with `onToolCall`: ```typescript const agent = new Agent({ provider, model, tools: [getWeather, askUser] }); agent.onToolCall((call) => { if (!isCall(askUser, call)) return; return prompt(call.input.question); }); ``` The handler receives one call — `{ id, name, input }`, with `input` already validated against the schema — and the same `ToolContext` an `execute` gets. The contract is `execute`'s: return the result, throw to hand the model an error result with the message as the reason, and return nothing when this branch doesn't answer. A call nobody answers doesn't fail. It waits — for `toolCall(id)`, for the tool's `timeout`, or for cancellation: ```typescript agent.on((event) => { if (event.type === "action:waiting") showPrompt(event.callId, event.input); }); // when the person answers, from anywhere that holds the agent: agent.toolCall(id)?.answer("teal"); ``` A few things worth knowing about the wait: - **Outside the handler, use `toolCall(id)`.** It returns `{ answer, fail }` while that call is waiting and `undefined` once it has settled. `fail` hands the model an `execution` error, the same as throwing inside the handler. The first settle wins; later ones do nothing. - **`generate()` has no handle, so it fails fast.** A call the handler doesn't answer — or any call when there's no handler — becomes an `execution` error result at once, instead of waiting. On `stream()` and `Agent`, the same call waits. - **`timeout` bounds the wait.** A deferred tool may set one in milliseconds; when it elapses, the call settles as a `timeout` error result the model reads. Unset, a call waits until it is answered or the run is cancelled. - **Cancelling aborts the wait.** The handler's `signal` aborts when anything else settles the call, so stop prompting and drop whatever the handler later resolves to — it's discarded. On the event stream, a deferred call never runs — there is no `action:running`. The part opens `pending`, moves to `waiting` when the validated call reaches your handler (`tool:waiting` on the stream layer, `action:waiting` on turns), and closes with the answer. `isCall(tool, call)` narrows a handler call to one tool with its input typed; `isActionOf(tool, part)` does the same for a rendered part, so a UI can find the handler's promise from the part. Both live on the main entry point and on `@fifthrevision/axle/ui`. Reach for a deferred tool for approvals, human-in-the-loop answers, and anything else the caller decides at runtime. If the answer is computable where the agent runs, write an `execute` instead. ## Provider tools Provider-managed tools run on the provider's infrastructure — hosted web search, code execution. You name them; you don't implement them. ```typescript import type { ProviderTool } from "@fifthrevision/axle"; const webSearch: ProviderTool = { type: "provider", name: "web_search" }; const agent = new Agent({ provider, model, providerTools: [webSearch] }); ``` Axle translates the portable names `web_search` and `code_execution` into each vendor's own name: | Portable name | Anthropic | OpenAI | Gemini | | --- | --- | --- | --- | | `web_search` | `web_search_20260318` | `web_search` | `googleSearch` | | `code_execution` | `code_execution_20260521` | `code_interpreter` | `codeExecution` | Any other name passes through untouched, so vendor-specific tools work by naming them directly. The optional `config` object is raw passthrough — field names and placement differ per vendor, so anything you put there is not portable. (It also never reaches a tool served by an attached executable — more on that in [Web search](/cookbook/web-search).) Results come back as `provider-tool` action parts and, for search, as [citations](/reference/messages). See [Provider tools](/cookbook/provider-tools). The provider owns every provider tool: core hands `providerTools` to the provider unchanged, and each provider decides how to serve a name — as a tool the vendor hosts, as an executable tool the provider brings (`AIProvider.tools`, which is how `chatCompletions()` serves an attached `webSearch`), or not at all. A provider asked for a tool it cannot serve fails the request (`ok: false`, `error.kind` `"api"`, naming the tool) — never silently dropped, except OpenRouter's warn-and-skip for names it doesn't map, which predates the change. ### If a provider has no native search Ask for `web_search` on a provider that doesn't host one and the request fails — unless you attached a search to that `chatCompletions()` provider, in which case it runs as an ordinary tool call. ```typescript import { chatCompletions, braveWebSearch } from "@fifthrevision/axle"; const provider = chatCompletions({ baseUrl: "http://localhost:11434/v1", webSearch: braveWebSearch({ apiKey: braveKey }), }); ``` Now the same agent code works against Ollama as against Anthropic — with one visible difference: an attached search renders as `tool` parts, not `provider-tool` parts, because that is what happened. See [Web search](/cookbook/web-search). ## MCP servers An `MCP` client connects to a server and brings its tools along. ```typescript import { MCP } from "@fifthrevision/axle"; const fs = new MCP({ transport: "stdio", name: "fs", command: "npx", args: ["-y", "@modelcontextprotocol/server-filesystem", "/tmp"], }); await fs.connect(); const agent = new Agent({ provider, model, mcps: [fs] }); ``` Both `stdio` and streamable `http` transports work. Tool discovery is **lazy** — the agent calls `listTools()` on the first send that needs it, once per client, and caches the result. But you do have to `connect()` yourself first; the agent won't do it for you, and an unconnected client throws on that first send. It's the single most common stumble here. The client's `name` becomes a prefix on every tool it contributes, which is how two servers can both offer a `read_file` without colliding. Call `refreshTools()` if a server's tool list changes while running, and `close()` when you're done. MCP tools are validated like any other tool: the call's arguments are parsed with the converted schema before they reach the server, and unknown top-level keys are stripped — matching a default `z.object()` — rather than rejected. The schema advertised to the provider carries `additionalProperties: false`, as vendors like OpenAI require. ## Subagents `createAgentTool` turns a whole `Agent` into a tool, so a parent model can hand off bounded work and get back only the final answer. ```typescript import { createAgentTool } from "@fifthrevision/axle"; const research = createAgentTool({ name: "research", description: "Research a topic in depth and report findings", schema: z.object({ topic: z.string() }), createAgent: () => new Agent({ provider, model, tools: [webSearchTool] }), prompt: (input) => `Research ${input.topic}. Report the three key findings.`, }); ``` The child's turn events get forwarded through `ctx.emit`, so your UI can render the nested run live as a `SubagentAction` with its own `children` turns. Its token usage flows through `ctx.reportUsage` and rolls into the parent's totals. Do create a **fresh** child agent per call. A shared one accumulates history across unrelated invocations, which gets strange quickly. ## Running a tool over many inputs `parallelize` wraps any tool in a parallelized tool: one tool whose single call runs the inner tool over many inputs concurrently. ```typescript import { parallelize } from "@fifthrevision/axle"; const researchBatch = parallelize(research, { maxConcurrency: 4, maxItems: 20 }); ``` The call's arguments are validated like any other tool call's, so one invalid item rejects the whole call before any item runs — with the item's path (for example `items.2.question`) in the validation message. Once running, results keep their input order. Ordinary per-item execution failures get reported per item instead of failing the call, while fatal and abort errors still terminate the run — same contract as the unwrapped tool. The parallelized tool inherits the wrapped tool's `kind`, so parallelized subagents still stream their child turns under its action. ## Where they all end up All four kinds land in the same [`ToolRegistry`](/concepts/tool-registry) — one flat namespace the model sees as a single list. ```typescript agent.registry.size; // everything, across all four sources ``` Worth reading that page rather than treating the registry as plumbing. It exists so the tool set can **change while the agent runs** — a tool that loads more tools, capabilities unlocked as a conversation narrows, permissions decided per-user. Not a constructor argument you set once. ## Next - [The tool registry](/concepts/tool-registry) — where they live, and changing them at runtime - [generate() & stream()](/concepts/generate-and-stream) — the tool loop without an Agent - [Tools reference](/reference/tools) - [Tool-using agent](/cookbook/tool-using-agent) --- # The tool registry Source: https://axle.fifthrevision.com/concepts/tool-registry _The agent's tool set is meant to change while it runs. The registry is what makes that possible._ Most tool APIs treat a tool set as a constructor argument: you decide what the agent can do, and that's what it can do forever. The registry exists because that's the wrong shape for real agents. **The tool set is meant to change while the agent runs.** A tool can load more tools. A conversation can unlock capabilities as it reveals what it's about. A user's permissions can decide what exists at all. The registry is what makes those first-class operations instead of a rebuild. That was the design goal from the start — the registry was introduced specifically to support `load_tools` patterns, where a tool call mutates the agent's own tool set mid-run. ## Loading tools with a tool The pattern the registry was built for: a tool whose job is to make other tools exist. ```typescript import { Agent, type ExecutableTool } from "@fifthrevision/axle"; import * as z from "zod"; declare const toolsets: Record; const loadToolsSchema = z.object({ toolset: z.enum(["database", "deploy", "analytics"]), }); const agent = new Agent({ provider, model, tools: [] }); const loadTools: ExecutableTool = { name: "load_tools", description: "Load a toolset when you need it. Available: 'database', 'deploy', 'analytics'.", schema: loadToolsSchema, async execute({ toolset }) { const loaded = toolsets[toolset]; agent.registry.add(loaded); return `Loaded: ${loaded.map((t) => t.name).join(", ")}. You can call these now.`; }, }; agent.registry.add(loadTools); ``` The agent starts with one tool and grows into whatever the task needs. The model decides when to expand its own capabilities — cheaper than declaring forty tools up front, and more accurate, since tool-selection quality degrades measurably as the list grows. Note the `ExecutableTool` annotation — passing the schema type is what gives you a typed `input` in `execute`. A bare `ExecutableTool` compiles fine but leaves the input properties `unknown`. Two details make it work: - **The agent is in closure scope.** `ToolContext` no longer carries a `registry` (removed in 0.34.0) — the tool reaches the agent it runs under directly, and `agent.registry.add()` lands on the next provider request, even mid-turn. - **Say so in the return value.** The model has no other signal that its capabilities changed. `"Loaded: query_db, list_tables. You can call these now."` is doing real work. ## The other three shapes Same mechanism, driven by your code rather than the model's. **Progressive disclosure.** Widen the tool set as the conversation narrows: ```typescript declare const listProjects: ExecutableTool; declare const deployProject: ExecutableTool; declare const rollbackProject: ExecutableTool; const agent = new Agent({ provider, model, tools: [listProjects] }); // once we know which project they mean agent.registry.add([deployProject, rollbackProject]); ``` **Permissions.** The registry is the boundary the model cannot see past: ```typescript declare const user: { canDeploy: boolean }; declare const deployTool: ExecutableTool; if (user.canDeploy) agent.registry.add(deployTool); ``` An unregistered tool isn't in the request at all, so it can't be called or hallucinated into being. That's a much stronger guarantee than instructing a model not to use something. **Phases.** Planning and editing want different toolsets on the same conversation. Swap at the boundary instead of building a second agent: ```typescript declare const planningTools: ExecutableTool[]; declare const editingTools: ExecutableTool[]; for (const tool of planningTools) agent.registry.remove(tool.name); agent.registry.add(editingTools); ``` **When changes take effect** `agent.registry` is live and the agent hands its prompt and tool lists to the tool loop at turn open and again at every tool-batch boundary, so host-side mutations land on the **next provider request** — between turns, or mid-turn when a tool mutates the agent in closure scope. Either way, the [steer playbook](/cookbook/cancellation#the-steer-playbook) gives you a clean boundary to change things at. **word of restraint: keep tools that mutate the registry few and obvious. A tool** set that changes unpredictably is genuinely hard to debug, and a model that wasn't told its capabilities changed will carry on as if they hadn't. ## What's actually in it Four collections, one namespace. | Collection | Filled by | Answered by | | --- | --- | --- | | **Local** | `tools:`, `registry.add()` | Your `execute` function | | **Deferred** | `tools:`, `registry.add()` | Your `onToolCall` handler, or `toolCall(id)` | | **MCP** | Resolved from `mcps:` on first send | The MCP server | | **Provider** | `providerTools:`, `registry.addProvider()` | The provider's infrastructure | They're stored separately because Axle handles them differently — local tools are functions it calls, deferred tools are calls it hands back to you, MCP tools are proxied over a transport, provider tools are names passed to the vendor. But **names are unique across all four**, because the model sees one flat list. A duplicate throws `TOOL_REGISTRY_DUPLICATE` at registration rather than silently shadowing. ```typescript agent.registry.has("get_weather"); // across all four agent.registry.size; // total across all four agent.registry.local(); // just yours agent.registry.deferred(); // just the deferred ones, for your handler agent.registry.mcp(); // just MCP's agent.registry.provider(); // just provider tools agent.registry.executable(); // local + MCP — everything Axle actually runs ``` The `executable()` / `provider()` split is the one that matters: executables have an `execute` function, deferred tools have a handler instead, and provider tools are just names and config. `get()` returns executable tools only — reach deferred ones through `getDeferred(name)`. ## Where your registry comes from `Agent` builds its own. There's no `registry` option on `AgentConfig` — you pass `tools` and `providerTools`, and the agent constructs one from them. You reach it afterwards: ```typescript const agent = new Agent({ provider, model, tools: [getWeather] }); agent.registry; // the one it built — mutate this ``` `generate()` and `stream()` take `tools` and `providerTools` directly — there is no `registry` option anymore (removed in 0.34.0). To share one set of capabilities across many independent calls, share the tool arrays: ```typescript const tools = [getWeather, searchTool]; const providerTools: ProviderTool[] = [{ type: "provider", name: "web_search" }]; await generate({ provider, model, messages, tools, providerTools }); await generate({ provider, model, messages: [...messages], tools, providerTools }); ``` **Sharing capabilities between agents** Since each `Agent` owns its registry, share the tool *arrays* rather than the registry — every agent built from the same arrays ends up with an equivalent tool set, and each can then diverge independently as its conversation goes its own way. ## MCP arrives late MCP tools land in the registry on the first send after the client is registered, not when you call `addMcp()`: ```typescript agent.addMcp(fs); agent.registry.size; // unchanged — nothing resolved yet await agent.send("List the files.").final; // now they're in ``` Each client resolves once and caches. That's why `hasTools()` is a method rather than `size > 0` — it also accounts for MCP clients that haven't resolved yet. ## It shows up in context accounting `agent.context()` reports the three kinds separately, because you trim them differently: ```typescript const usage = agent.context(); usage.tools; // local tool schemas usage.mcpTools; // MCP tool schemas usage.providerTools; // provider tool declarations ``` This is where you discover that thirty MCP tools are eating more of your window than the conversation is. Trimming the registry is often a bigger win than [compaction](/concepts/compaction) — and it's the measurement that tells you whether a `load_tools` pattern is worth building. ## Building one by hand ```typescript import { ToolRegistry } from "@fifthrevision/axle"; import type { ExecutableTool } from "@fifthrevision/axle"; declare const anotherTool: ExecutableTool; declare const mcpClient: MCP; const registry = new ToolRegistry({ tools: [getWeather], providerTools: [{ type: "provider", name: "web_search" }], }); registry.add(anotherTool); registry.add(askUser); // deferred tools go through the same add — the kind is on the tool registry.addProvider({ type: "provider", name: "code_execution" }); registry.addMcp(await mcpClient.listTools({ prefix: "fs" })); registry.getDeferred("ask_user"); // deferred only — get() returns executables registry.remove("get_weather"); // removes from whichever collection holds it ``` The collection is chosen by which `add` method you call, not by inspecting the tool. `addMcp` exists so MCP-sourced tools stay countable separately even though they execute like any other. ## Next - [Tools](/concepts/tools) — what goes in the registry - [Tools reference](/reference/tools#toolregistry) — every method - [MCP servers](/cookbook/mcp-servers) — where MCP tools come from --- # Results & errors Source: https://axle.fifthrevision.com/concepts/results-and-errors _What resolves, what throws, and where Axle draws the line._ Axle splits failures into two piles. **Things you should expect resolve. Things that mean something is broken throw.** Once that clicks, the rest of this page is detail. The reasoning: a rate limit or a malformed JSON response isn't exceptional — it's an ordinary Tuesday for an LLM application, and it deserves a branch in your code rather than a `try`/`catch`. Whereas "you cancelled this" or "two tools have the same name" really are exceptional. ## The result shape `generate(...)`, `stream(...).final`, and `agent.send(...).final` all resolve to the same two-state union: ```typescript const result = await agent.send("...").final; if (!result.ok) { result.error.kind; // "api" | "incomplete" | "refusal" | "parse" result.error.message; // always there return; } result.response; // always there when ok result.usage; // token totals result.turn; // the renderable agent turn ``` TypeScript narrows on `ok`, so `response` is simply unreachable in the failure branch. You can't forget to check. The shapes differ in one respect. `AgentResult` carries `turn`; `GenerateResult` and `StreamResult` carry `messages`, `final`, and `stopped` instead. `Agent` doesn't expose the loop budgets (`maxSteps`, `maxContextTokens`), so there's no `stopped` on its results — see [Stops aren't errors](#stops-arent-errors). ### The four kinds of failure | `kind` | What happened | | --- | --- | | `api` | The request didn't complete: rejected, failed mid-way, connection broke. `type` names it (`"authentication"` when your key was rejected); `status` carries the HTTP status when there was one; `usage` is usually absent | | `incomplete` | The request completed but stopped for a reason that isn't a usable end. `type` is the stop reason verbatim (or `FinishReasonError`, `IncompleteStream`, `RESPONSES_API_INCOMPLETE`); `usage` is present — the call was charged | | `refusal` | The provider declined the request or blocked its output — a safety refusal, a content filter, a blocked prompt. `text` and `category` carry what the provider said, when it said anything | | `parse` | The response didn't match your `Instruct` schema | `api` is what `model` was before 0.35.0, split on what the API did. A `switch` on `kind` with an exhaustiveness check stops compiling until it handles both new arms. A refusal is not a model error and not an empty success. Before 0.33.0 an Anthropic refusal arrived as `ok: true` with `finishReason: "error"`, an OpenAI or Chat Completions refusal as `ok: true` with empty content, and a Gemini block as a `model` failure — now all of them resolve `ok: false` with `kind: "refusal"`. Branch on it explicitly: retrying won't help, and falling through to your generic model-error path will mislead. The refused step is not stored — `messages` holds only the steps that completed before it — and after a refused `agent.send()` the agent's history ends with the user message. A refusal the model writes as ordinary text is still a normal `ok: true` answer; only provider-marked refusals take this branch. Failures are flat: an `api` failure carries `type`, `message`, `status?`, `usage?`, `raw?` directly on `error` (no nested `error` object since 0.33.0). To detect a bad key, check `!result.ok && result.error.kind === "api" && result.error.type === "authentication"` instead of digging through `raw.status` or message strings. Two more `type` values worth knowing: `"TimeoutError"` means a `chatCompletions()` request timed out (match on it rather than `AbortError`, which now means only your own signal fired), and a provider tool no provider serves — `web_search` with nothing attached, say — fails the request as an `api` failure naming the tool. A bad model id or tool choice no longer resolves at all — it throws `AxleError` (`INVALID_OPTIONS`) before any request. See [Errors](/reference/errors) for the full union. ### What `response` holds | Call | `response` | | --- | --- | | `agent.send("text")` | The assistant's text | | `agent.send(instruct)` with a schema | The parsed, typed object | | `generate(...)` / `stream(...)`, plain | The final `AxleAssistantMessage` | | `generate(...)` / `stream(...)` with `instruct` | The parsed value | There's an asymmetry there worth flagging: `Agent` unwraps to text, while the low-level functions hand you the whole message. That's deliberate — down at that level you usually want the content parts, not just the text. ## Stops aren't errors `maxSteps` and `maxContextTokens` put a bound on the tool loop. They're options on `generate()` and `stream()` — `Agent` doesn't take them, so this whole section is about the low-level functions. Crossing either one is a **stop**, not a failure: ```typescript const result = await generate({ provider, model, messages, tools, maxSteps: 5 }); if (result.ok && result.stopped === "max-steps") { // conversation is well-formed and continuable — your call what happens next } ``` You get `ok: true` with everything accumulated so far, and a conversation that's valid to continue from. `final.finishReason` keeps the provider's own reason, usually `function_call`, because the model wanted to keep going. **A combination that looks alarming but isn't** A limit stop usually lands on a tool-call step with no parseable text. So an `Instruct` call to `generate()` or `stream()` can come back `ok: false` with `kind: "parse"` **and** a `stopped` marker. That means "continuable, limit tripped" — not "the model produced garbage." Check `stopped` before you conclude the model misbehaved. **-positive limits are a caller bug, so those throw at call time.** ## What throws | Thrown | When | | --- | --- | | `AxleAgentAbortError` | An `Agent` handle was cancelled, or its queue was cleared | | `AxleAbortError` | A `stream()` handle was cancelled | | `AxleToolFatalError` | A tool threw `AxleToolFatalError` — the run can't continue | | `AxleInstructVariableError` | A required `{{variable}}` had no input | | `AxleError` | Configuration and setup mistakes — duplicate tool name, bad model id, unsupported feature, unreadable file, unconnected MCP, invalid limits (`code` says which) | A result's `ok: false` now carries one thing only: the provider's answer to a request that went out. Everything else throws a coded `AxleError` before any request is sent — a loop limit below 1, a bad model id, an unsupported reasoning setting, a tool choice naming an absent tool, a non-PDF file on a provider with no wire shape for it, an unreadable host file, an MCP tool called before `connect()`. A host that checked `result.ok` and then fixed its configuration from the message now does that in a `catch`: ```typescript import { isAxleError } from "@fifthrevision/axle"; declare const fixSetup: (message: string) => void; try { const result = await generate({ provider, model, messages, toolChoice: { type: "tool", name: "nope" } }); } catch (error) { if (isAxleError(error) && error.code === "INVALID_OPTIONS") fixSetup(error.message); } ``` `isAxleError` narrows to the payload union (it tests for an `AxleErrorCode`, so it holds across duplicate package copies — prefer it over `instanceof AxleError`). Every one of these is either "you cancelled it" or "something's wired wrong." Neither belongs in a result union you'd branch on. They all carry a `code`, optional `details`, and a `toJSON()` that serializes the whole cause chain — so logging one is a one-liner. ## Cancellation Standard JavaScript abort semantics, so your existing habits work: ```typescript const handle = agent.send("Long task..."); setTimeout(() => handle.cancel("timeout"), 5000); try { const result = await handle.final; } catch (error) { if (error instanceof Error && error.name === "AbortError") { // AxleAbortError sets name = "AbortError", so this catches both } else { throw error; } } ``` `AxleAbortError.name` is `"AbortError"`, so the conventional check works. Use `instanceof` when you want the extra fields: ```typescript error.reason; // whatever you passed to cancel() error.usage; // tokens spent before the abort error.messages; // messages completed before the abort error.partial; // the partially-streamed assistant message error.turn; // AxleAgentAbortError only — the cancelled turn ``` That partial state is kept on purpose. A cancelled long generation still cost you money and still produced text — you'll usually want to show it. For what commits when you cancel, and how `cancel()` differs from `stop()` and `clear()`, see [Agent](/concepts/agent#interrupting-four-different-things). ## Tool errors: validation vs. execution vs. fatal A tool call can fail before `execute` ever runs. Each call's arguments are parsed with the tool's schema first; when they don't match, `execute` is not called and the model gets an error tool result with type `validation` naming each issue (`Invalid arguments for getWeather: city: Invalid input: expected string, received undefined`). The loop continues, so the model usually corrects the call in the same turn. `execute` receives the parsed value, so schema defaults and transforms already apply when it runs. A parallelized tool's call is rejected as a whole when any item is invalid, with the item's path (for example `items.2.question`) in the message. Inside `execute`, an ordinary throw is handled gracefully: ```typescript async execute(input, ctx) { throw new Error("Service unavailable"); // → tool error result, model sees it, loop continues } ``` To end the run instead: ```typescript import { AxleToolFatalError } from "@fifthrevision/axle"; async execute(input, ctx) { throw new AxleToolFatalError("Sandbox destroyed", { toolName: "run_command" }); // → propagates out of send(), loop terminates } ``` Default to ordinary throws. Models are pretty good at recovering from a tool that says "that didn't work." Reserve fatal for when continuing would be incoherent — the environment your tool operates on is gone. The two also differ in what they do to the rest of the batch, since a step's calls [run at once](/concepts/tools#one-batch-all-at-once). An ordinary throw is one call's result and touches no sibling. A fatal error aborts the siblings through their `ctx.signal` and waits for each to settle, then commits the tool results message — with one result per call in request order — before rethrowing. The fatal call's result is `isError` with `{"error":{"type":"fatal","message":…}}`; each call the abort cut short reads `isError` with `{"error":{"type":"cancelled","message":…}}`; a call that finished before the abort keeps its real result. A cancelled turn settles the same way, with every unfinished call reading `cancelled`. Either way the rejection carries the usage every call reported before it was cut short, and the history is left valid — `agent.messages` ends in the `tool` message, so a follow-up send is accepted instead of failing on unanswered calls. One nicety: a subagent's fatal errors get re-wrapped before they reach the parent, so the parent never accidentally adopts the child conversation's messages. Usage is preserved for accounting. ## Next - [Agent](/concepts/agent) - [Errors reference](/reference/errors) - [Interrupting & cancelling](/cookbook/cancellation) --- # Observability Source: https://axle.fifthrevision.com/concepts/observability _Structured logs, span traces, and where the token numbers come from._ Axle builds a span tree for every operation. You can consume it as flat structured logs, as a real trace, or both. One vocabulary note first: a **trace** here means the span tree from the tracer. It never means the conversation transcript. Two different things, unfortunately similar words. See [Glossary](/glossary). ## The common case: structured logs Hand Axle a `log` function and it creates and owns a tracer behind the scenes. For most applications this is all you need: ```typescript const agent = new Agent({ provider, model, observability: { level: "info", log: ({ level, message, fields }) => { console.log(JSON.stringify({ level, message, ...fields })); }, }, }); ``` Every entry carries `traceId`, `spanId`, and usually `parentSpanId` — enough to reconstruct the trace skeleton from the log stream alone, without running a tracing backend at all. `level` defaults to `"info"`. Reach for `"debug"` in development: tool calls and the top-level run log at info, while the full span tree (steps, stream internals) sits at debug depth. So info reads like a narrative and debug reads like a stack trace. ## Bringing your own tracer ```typescript import { Tracer, LogWriter, SimpleWriter } from "@fifthrevision/axle"; const tracer = new Tracer({ minLevel: "debug" }); tracer.addWriter(new LogWriter((entry) => logger.log(entry))); tracer.addWriter(myOtelWriter); const agent = new Agent({ provider, model, observability: { trace: tracer } }); ``` `trace` accepts two shapes: - A **`Tracer`** — each send becomes its own root span. - A **`Span`** — sends nest underneath it, which is how you attach an agent run to a larger request trace. Axle attaches its spans but never ends or flushes something you handed it — that stays your responsibility. When you supply only `log`, Axle owns the tracer and flushes it at the end of each operation. The `level` option governs only the tracer Axle creates from `log`. If you bring your own, set `minLevel` on it instead. ## What the span tree looks like A send produces roughly this: ``` agent.send (workflow) ├─ stream (internal) │ ├─ step-1 (llm) │ ├─ tool:get_weather (tool) │ └─ step-2 (llm) ``` `agent.compact()` produces its own `agent.compact` workflow root, with a `trigger` attribute and an `outcome` of `complete`, `skipped`, or `error`. Span types are conventions rather than an enum — `workflow`, `llm`, `tool`, `action`, `internal`. ## Writing a trace writer ```typescript import type { TraceWriter, SpanData } from "@fifthrevision/axle"; const writer: TraceWriter = { onSpanStart(span) {}, onSpanEnd(span) { exporter.record(span); // traceId, spanId, parentSpanId, timings, attributes, result }, async flush() { await exporter.flush(); }, }; ``` `onSpanUpdate` and `onEvent` are optional. LLM and tool spans carry a typed `result` — `{ kind: "llm", model, request, response, usage, finishReason }` or `{ kind: "tool", name, input, output }` — so your exporter can render them natively instead of digging through attributes. `SimpleWriter` is the built-in human-readable console writer, handy in development. ## Tools get their own spans Each tool call has a span, handed to `execute` as `ctx.span`: ```typescript async execute(input, ctx) { ctx.span?.setAttribute("cacheHit", true); ctx.span?.debug("fetching", { url }); } ``` ## Token usage There are two different numbers here and they get confused constantly, so: | | Where it comes from | What it's for | | --- | --- | --- | | `result.usage` | The provider reports it | Billing, real accounting | | `agent.context()` | Estimated locally | Compaction thresholds, UI meters | ```typescript result.usage; // { in, out, cachedIn?, cacheWriteIn?, reasoningOut?, breakdown: UsageEntry[] } ``` `cachedIn` and `cacheWriteIn` are already counted inside `in`, and `reasoningOut` is already inside `out`. Don't add them again — that's the classic double-counting bug. Since 0.34.1 these two are populated on Anthropic and OpenRouter as well, because Axle asks for caching there by default (see [Prompt caching](/concepts/providers#prompt-caching)). `breakdown` holds one row per provider request, in request order — not one row per model. A step that fans out (Anthropic `pause_turn` follow-ups, a tool loop with several steps) yields one row per request, each with that request's own `in` and `out`, so each row can be priced at the tier its prompt size selects. A request that failed or was refused after the provider reported usage is included too. When several subagents run in one tool batch, each subagent's rows stay together and the groups follow the order the calls were requested, not the order they finished. The top-level `in`/`out` are still the totals. A turn's `turn:end` usage is the sum of what its steps reported to `onStep`, so it matches the send's `result.usage` exactly. ```typescript for (const entry of result.usage.breakdown) { console.log(entry.provider, entry.model, entry.agent, entry.in, entry.out); } ``` Each row also carries `requestedModel` (what you asked for — differs from `model` when the provider reports another id), `agent` (the `Agent.name` that made the request, when it has one — subagent rows sit between the parent's own rows), and `at` (ISO 8601, when the provider finished). `provider` is the provider's `id` (`"anthropic"`, `"openai"`, `"google"`, `"openrouter"` — note Gemini rows changed from `"Gemini"` to `"google"` in 0.35.0) and is absent for a provider with no `id`. Entries *explain* the aggregate; they don't add to it. A reader that assumed one row per model — a cost table keyed by `provider + model`, say — now groups the rows first. To price a `Stats`, use `computeCost`: ```typescript import { computeCost } from "@fifthrevision/axle"; const cost = computeCost(usage, catalog); // { usd, priced, unpriced, pricedWith? } ``` It prices each row at its own provider, model and tier, and reports the rows it couldn't price rather than guessing. [Model catalog & cost](/concepts/model-catalog#what-a-run-cost) covers where `catalog` comes from and what an unpriced row means. If you write a tool that calls a model, report its usage so it rolls up. `breakdown` is required — a hand-built `Stats` needs rows, so build it with `attributeStats`: ```typescript import { attributeStats } from "@fifthrevision/axle"; async execute(input, ctx) { const r = await generate({ provider, model, messages }); if (r.usage) ctx.reportUsage?.(r.usage); return "..."; } // a tool that calls a model API directly: ctx.reportUsage( attributeStats( { in: 900, out: 120 }, { provider: "openai", model: "gpt-5", requestedModel: "gpt-5" }, ), ); ``` `createAgentTool` already does the `reportUsage` part for you. ## Next - [Observability reference](/reference/observability) - [Model catalog & cost](/concepts/model-catalog) — turning a `Stats` into dollars - [Results & errors](/concepts/results-and-errors) --- # Agent Source: https://axle.fifthrevision.com/reference/agent _Constructor options, methods, and result types for Agent._ ```typescript import { Agent } from "@fifthrevision/axle"; new Agent(config: AgentConfig, session?: AgentSession) ``` Conceptual guide: [Agent](/concepts/agent). ## AgentConfig Extends `AxleModelRequestOptions` minus `signal`. | Option | Type | Default | Description | | --- | --- | --- | --- | | `provider` | `AIProvider` | — | **Required.** Provider adapter. | | `model` | `string` | — | **Required.** Model identifier. | | `sessionId` | `string` | `crypto.randomUUID()` | Stable conversation id. | | `system` | `string` | — | System/developer instruction. | | `name` | `string` | — | Agent name; appears on spans as `agentName`. | | `tools` | `AnyTool[]` | — | Executable tools the agent runs, and deferred tools answered through `agent.onToolCall()`. | | `providerTools` | `ProviderTool[]` | — | Provider-managed tools. | | `skills` | `Skill[]` | — | Skills disclosed in the system prompt and loaded on demand through the `view-skill` tool. See [Skills](/concepts/skills). | | `mcps` | `MCP[]` | — | MCP clients, resolved lazily on first send. | | `observability` | `ObservabilityOptions` | — | Logging and tracing. | | `fileResolver` | `FileResolver` | — | Resolves deferred file references. | | `reasoning` | `ReasoningSetting` | — | Portable reasoning/thinking control: `"default"` or `{ enabled?, effort?, display? }`. | | `maxOutputTokens` | `number` | — | Output token cap. | | `toolChoice` | `ToolChoice` | — | `"auto"`, `"none"`, `"required"`, `{ type: "tool", name }`. | | `parallelToolCalls` | `boolean` | — | Ask the provider to avoid parallel tool calls. | | `cache` | `boolean` | — | Ask the provider to cache the prompt prefix where asking is required (Anthropic, OpenRouter). Defaults to on. | | `providerOptions` | `Record` | — | Raw passthrough, applied after normalized mappings. | | `turnTimeoutMs` | `number` | — | Longest a turn may run, from opening to `turn:end` — every model step, tool call, and deferred wait included. When it elapses the turn is cancelled with `{ type: "timeout", limitMs }` as the abort reason (see `isTimeoutReason`); on the send's own turn the handle rejects and `operation:end` carries it as `{ type: "cancelled", reason }`. A send's own value overrides it. | | `streamStallMs` | `number` | — | Longest gap between two chunks from the provider — as `stream()`'s `streamStallMs`. When it passes, the step fails `ok: false` with `{ kind: "api", type: "StreamStall" }`; not retried. A send's own value overrides it. | When both `config.sessionId` and `session.sessionId` are supplied, the restored session id wins. ### ObservabilityOptions | Field | Type | Description | | --- | --- | --- | | `level` | `EventLevel` | Minimum level. Default `"info"`. Governs only the tracer Axle creates from `log`. | | `log` | `LogFn` | Structured sink. Axle creates and owns a tracer when `trace` is absent. | | `trace` | `Tracer \| Span` | Bring your own. A `Tracer` gives each send its own root; a `Span` nests sends under it. Axle never ends or flushes what you pass. | ## Properties | Property | Type | Notes | | --- | --- | --- | | `provider` | `AIProvider` | readonly | | `model` | `string` | readonly | | `name` | `string \| undefined` | readonly | | `registry` | `ToolRegistry` | readonly | | `skills` | `SkillRegistry` | readonly — the skills disclosed in the system prompt; mutating it rebuilds the `view-skill` tool and lands on the next provider request | | `requestOptions` | `Omit` | readonly | | `fileResolver` | `FileResolver \| undefined` | readonly | | `turnTimeoutMs` | `number \| undefined` | readonly | | `streamStallMs` | `number \| undefined` | readonly | | `status` | `AgentStatus` | `{ phase: "idle" }`, or `{ phase: "busy", id }` with the running operation's id. Busy covers `onStart` callbacks, the continuation, and `onSettled` — changes only at `operation:start` and `agent:idle`, and already reads the new value when the event that moved it is delivered. | | `sessionId` | `string` | mutable | | `session` | `AgentSession` | Getter returning `{ sessionId, messages }` as it stands — synchronous, and safe inside `onStep`, `onStart`, `onSettled`, continuations, and tools, where `snapshot()` would deadlock. | | `system` | `string \| undefined` | readonly getter — the configured system prompt, then the skills catalog when skills are present | | `messages` | `AxleMessage[]` | Getter returning a **copy** of the active conversation. Grows as each step ends while a turn runs, so a reader inside the turn sees finished steps. | ## send() ```typescript send(message: string | Instruct, options?: SendMessageOptions): AgentHandle send(instruct: Instruct, options?: SendMessageOptions): AgentHandle> ``` Schedules a FIFO conversation turn and returns a handle synchronously. The user message and its turn are built up front, so `send()` emits `pending:queued` with a `pending` preview turn carrying the id the committed turn will have — render `[...transcript.turns, ...transcript.pending]` keyed by id to show queued work. A handle cancelled while still queued emits `pending:dropped` and commits nothing. Strings are wrapped in an `Instruct` with `vars: "optional"`. A supplied `Instruct` is cloned, then validated — `AxleInstructVariableError` throws synchronously from `send()` if a required variable is missing. ### SendMessageOptions Extends `AxleModelRequestOptions`. Per-send values are merged over the agent defaults; `providerOptions` merges key-by-key. | Option | Type | Description | | --- | --- | --- | | `after` | `Continuation?` | Continuation to run after this send's turn settles. Holds the queue; inline turns run via `ctx.send()`. See [after — continuations](#after-continuations). | | `fileResolver` | `FileResolver` | Overrides the agent's resolver for this send. | | `metadata` | `MessageMetadata` | Host-owned metadata attached to the user message and copied to the user turn. Providers ignore it. | | `signal` | `AbortSignal` | Cancels this send. | | `id` | `string` | Id for the send's user turn — the one `pending:queued`, `turn:user`, and `onSettled` carry. Generated when omitted. | | `turnTimeoutMs` | `number` | This send's turn timeout, overriding the agent's `turnTimeoutMs`. | | `streamStallMs` | `number` | This send's stall limit, overriding the agent's `streamStallMs`. | | ...request options | | `reasoning`, `maxOutputTokens`, `toolChoice`, `parallelToolCalls`, `cache`, `providerOptions`. (`temperature`, `topP`, and `stop` were removed in 0.33.0 — use `providerOptions`.) | ### AgentHandle ```typescript interface AgentHandle { cancel(reason?: unknown): void; readonly final: Promise | AgentErrorResult>; } ``` `AgentHandle` and `StreamHandle` both satisfy the exported `Handle` (`{ cancel, final }`), so code that only cancels and awaits can take either. ### AgentResult ```typescript interface AgentResult { ok: true; response: T; error?: undefined; turn: Turn; usage: Stats; after?: InlineTurn[]; } interface AgentErrorResult { ok: false; response?: undefined; error: AxleProviderFailure; turn: Turn | undefined; usage: Stats; after?: InlineTurn[]; } type InlineTurn = { userTurn: Turn } & ( Omit, "after"> | Omit ); ``` `AxleProviderFailure` is `{ kind: "api" }`, `{ kind: "incomplete" }`, `{ kind: "refusal" }`, or `{ kind: "parse" }` — see [Errors](/reference/errors). `after` is present only when the send carried a continuation: the inline turns it ran, in order. ## after — continuations ```typescript type Continuation = ( result: AgentResult | AgentErrorResult, ctx: ContinuationContext, ) => void | Promise; interface ContinuationContext { send(message: string | Instruct, options?: InlineSendOptions): Promise | AgentErrorResult>; send(instruct: Instruct, options?: InlineSendOptions): Promise> | AgentErrorResult>; readonly signal: AbortSignal; readonly id: string; readonly messages: readonly AxleMessage[]; readonly pending: readonly Turn[]; } type InlineSendOptions = Omit; ``` The continuation runs after the send's turn settles with a result (`ok` or not); a rejected handle skips it. It holds the queue until it returns and `ctx.send()` runs inline turns — ordinary turns except they start at once with no `pending:queued`, carry the send's id as `threadId` on their user turn and `Turn`, and fire no hook of their own. A continuation that throws rejects the handle and the queue continues. `cancel()` during a continuation aborts `ctx.signal` and any inline turn in flight; `stop()` keeps its tool-batch meaning for an inline turn; `clear()` never touches a continuation. ## stop() ```typescript stop(): boolean ``` Asks the active turn to finish at its next complete tool-batch boundary. The in-flight batch executes and commits, then the handle settles without another provider request. Returns `false` when no turn is executing. Queued sends are unaffected. ## cancel() ```typescript cancel(reason?: unknown): boolean ``` Cancels the active operation immediately — as if that handle's own `cancel()` had been called. A turn that already opened settles `cancelled` with its partial work committed. Queued operations are unaffected and the next one starts. Returns `false` when nothing is running. While `onSettled` callbacks run, the operation is already done, so `cancel()` (and `stop()`) return `false`. ## clear() ```typescript clear(): number ``` Cancels every queued operation without touching the active turn. Each cleared handle rejects with `AxleAgentAbortError`, committing nothing. Returns the number cleared. ## on() ```typescript on(callback: (event: AgentEvent) => void): () => void ``` Registers an event callback for all subsequent sends. Returns an unsubscribe function. `AgentEvent` is the turn events plus the operation lifecycle (`operation:start`, `after:start` / `after:end`, `operation:end`, `agent:idle`). `TurnEventCallback` is removed — annotate with `AgentEventCallback`. ## onStart() ```typescript onStart(callback: StartCallback): () => void ``` Called each time an operation takes the queue, before its turn opens — never inside `send()` itself. `status` is already `busy` with the operation's id, and `operation:start` has been emitted. ```typescript type StartCallback = (operation: StartedOperation) => void | Promise; interface StartedOperation { kind: "send" | "compaction"; id: string; // the one its pending:queued turn carried signal: AbortSignal; // aborts when the operation is cancelled } ``` The operation does not start its work until every callback has settled, and all callbacks run together. One that throws skips the work and the continuation: the pending turn is dropped with the error, `onSettled` still runs with it as the result, and the handle rejects with it. A `cancel()` while callbacks run aborts `operation.signal`, and the work is skipped once they return. An operation cancelled while still queued never starts and does not fire. Do not await `send()`, `compact()`, or `snapshot()` on this agent from inside a callback: the callback holds the queue they wait for, so the nested call deadlocks. ## onStep() ```typescript onStep(callback: StepCallback): () => void ``` Called each time a step ends inside a turn, so a host can save usage and state while the turn runs. A step is one model call and the tool batch it asked for, if any, and it fires however the step ended: answered, failed, refused, or cancelled. A compaction whose callback ran is a step too. Inline turns sent by a continuation fire it. ```typescript type StepCallback = (step: AgentStep) => void | Promise; interface AgentStep { turnId: string; index: number; // counts the turn's steps from 0, compactions included signal: AbortSignal; // aborts when the turn is cancelled or times out usage: Stats; // what the Agent saw spent in the step (empty for a compaction) } ``` `step.index` counts the turn's steps from 0 and `step.usage` holds the rows the step added: the rows of a turn's steps, in order, are the `usage` its `turn:end` reports. The step's messages are already in `messages` — a conversation the provider accepts — and every event belonging to the step has reached `on` listeners. A subagent's rows arrive on the step whose tools ran it. The agent waits for the callback before it sends the next request: a callback may return a promise, and all callbacks run together. One that throws stops the turn there — nothing further runs, the turn ends `error`, `onSettled` runs with the thrown error, and the handle rejects with it. A `cancel()` while callbacks run takes effect when they return. No timeout is applied. Catch your own errors if saving should be best effort. Do not await `send()`, `compact()`, or `snapshot()` on this agent from inside a callback — the callback holds the queue they wait for, so the nested call deadlocks. Read `session` for the state to save. ```typescript declare const saveSession: (session: AgentSession) => Promise; declare const usageLedger: unknown; agent.onStep(async (step) => { await db.insert(usageLedger).values( step.usage.breakdown.map((row, i) => ({ turnId: step.turnId, step: step.index, row: i, ...row, })), ); await saveSession(agent.session); }); ``` `stream()` has the same hook as `handle.onStep(callback)`, receiving `{ usage, messages }` for the step. Custom `StreamHandle` implementations must add it. ## onToolCall() ```typescript onToolCall(handler: ToolCallCallback): () => void ``` Answers the agent's deferred tool calls. One handler per agent, the dispatcher over every deferred tool: registering another replaces it, and the returned function removes it if it is still the one in place. The handler in place when a turn opens is the one that turn uses. The contract is `execute`'s — return the result, throw to give the model an error, and return nothing for a call no branch answers. See [Deferred tools](/concepts/tools#deferred-tools). ## toolCall() ```typescript toolCall(id: string): WaitingToolCall | undefined ``` The deferred call with this tool call id while the active turn is waiting on it; `undefined` once it has settled or when no turn is running. `answer` gives the model the result and `fail` an `execution` error carrying the message — the two outcomes `onToolCall` has. Whichever of the handler, this, the tool's `timeout`, and `cancel()` comes first settles the call. ## onSettled() ```typescript onSettled(callback: SettledCallback): () => void ``` Fires once for every operation that started, however it ended — one send, one call: after its turn and its continuation, before `operation:end` is emitted and its handle settles. Inline turns a continuation sent do not fire it on their own; their outcome arrives under the send's `result.after`. The agent is at rest and the next queued operation has not started, so a host that reads its `Transcript.turns` inside the callback gets turns and messages that match. An operation cancelled while still queued never ran and does not fire. ```typescript type SettledCallback = ( session: AgentSession, operation: SettledOperation, ) => void | Promise; type SettledOperation = | { kind: "send"; id: string; // the id its `pending:queued` turn carried result: PromiseSettledResult | AgentErrorResult>; } | { kind: "compaction"; id: string; result: PromiseSettledResult }; ``` The session is the one `snapshot()` returns; unlike `snapshot()`, it does not wait behind queued operations. The operation carries exactly what the handle is about to settle with: the result on success, the rejection reason otherwise. A callback may return a promise. The handle does not settle and the next queued operation does not start until every callback has settled; all callbacks run together. A callback that throws or rejects cannot affect the operation: the error is recorded on the trace and the other callbacks still run. Do not await `send()`, `compact()`, or `snapshot()` on this agent from inside a callback: the callback holds the queue they wait for, so the nested call deadlocks. ```typescript declare const report: (reason: unknown) => void; agent.onSettled(async (session, operation) => { await db.save(session.sessionId, { session, turns: transcript.turns }); if (operation.result.status === "rejected") report(operation.result.reason); }); ``` ## onIdle() ```typescript onIdle(callback: IdleCallback): () => void ``` Called each time the agent goes from busy to idle: an operation finished and nothing is queued behind it. Fires after the last operation's `onSettled` callbacks have settled, and also when the queue was emptied by `clear()` while they ran. Work scheduled during those callbacks keeps the agent busy, so it does not fire until that work is done too. ```typescript type IdleCallback = () => void; ``` The callback is not awaited — the agent is already free, so a `send()` from inside it starts at once. A callback that throws is recorded on the trace and the other callbacks still run. Use it to close whatever the host opened when work began: ```typescript declare const notifyClients: (event: { type: string }) => void; agent.onIdle(() => notifyClients({ type: "run:stop" })); ``` ## context() ```typescript context(): ContextUsage ``` ```typescript interface ContextUsage { total: number; system: number; tools: number; mcpTools: number; providerTools: number; messages: number; limit?: number; free?: number; } ``` Locally estimated, not provider-reported. `context()` supplies no `limit`, so `limit` and `free` are always absent from its result; to fill them, call [`estimateContextUsage`](/reference/providers#context-estimation) yourself with a limit from the [model catalog](/concepts/model-catalog#budgeting-the-window). ## snapshot() ```typescript snapshot(): Promise ``` Resolves at once when the agent is idle, and otherwise when it next goes idle, so the capture is always at rest — a snapshot never contains a streaming or running turn, and it includes everything queued before the agent went idle. It is not queued work: it does not make the agent busy, fires no `onIdle`, and is not cancelled by `clear()`. Returns `{ sessionId, messages }`. Excludes transcripts and all runtime objects. **Deprecated** — read `session` instead, which returns the same value without waiting. To save a state at rest, read it in an `onSettled` or `onIdle` callback. **Do not await from inside a running send or an `onSettled` callback** — the agent cannot go idle until they return, so the nested call deadlocks. To save after each operation, use `onSettled` instead of awaiting `snapshot()` in a loop. ## compact() and setCompaction() ```typescript setCompaction(config: CompactionConfig): void compact(options?: { signal?: AbortSignal }): Promise ``` `setCompaction` replaces any previous configuration. `compact()` resolves `false` when no config is registered, otherwise enqueues the work and resolves `true` once applied. A queued manual compaction previews as a `pending` agent turn with one `pending` compaction part (see [Transcript & events](/reference/transcript#pending-lifecycle)). It bypasses `shouldCompactOnTrigger`. Cancellation rejects with `AxleAgentAbortError`. **Do not await from inside a running send** — it deadlocks. See [Configuration](/reference/configuration#compaction) for `CompactionConfig`. ## MCP methods ```typescript addMcp(mcp: MCP): void addMcps(mcps: MCP[]): void hasTools(): boolean ``` MCP tools resolve lazily on the first send after registration, once per client. The client must already be connected. ## Serializable sessions `AgentSession` (`{ sessionId, messages }`) is the saved form of a conversation. There is no serializable agent recipe in core (`AgentDefinition`, `createAgentConfig()`, and friends were removed in 0.35.0): a host that saves which recipe an agent ran stores that in its own shape (a path, a name, the parsed recipe) and rebuilds `AgentConfig` from it directly. ```typescript declare const providers: Record; declare const tools: Record; const agent = new Agent( { provider: providers[saved.recipe.provider], model: saved.recipe.model, system: saved.recipe.system, tools: saved.recipe.tools?.map((name) => tools[name]), }, saved.session, ); ``` --- # Instruct Source: https://axle.fifthrevision.com/reference/instruct _Constructor options, methods, and rendering rules for Instruct._ ```typescript import { Instruct } from "@fifthrevision/axle"; new Instruct(options: InstructOptions) ``` Conceptual guide: [Instruct](/concepts/instruct). ## InstructOptions | Option | Type | Default | Description | | --- | --- | --- | --- | | `prompt` | `string` | — | **Required.** Prompt text, may contain `{{variables}}`. | | `schema` | `OutputSchema` (Standard Schema object or JSON Schema) | — | Output schema. Its presence switches `response` to the parsed value. Zod schemas work unchanged; any Standard Schema or plain JSON Schema object works too. | | `vars` | `"required" \| "optional"` | `"required"` | Whether missing variables throw. | | `metadata` | `MessageMetadata` | — | Host metadata attached to the compiled message. | ## Properties | Property | Type | | --- | --- | | `prompt` | `string` | | `schema` | `TSchema` | | `vars` | `"required" \| "optional"` | | `inputs` | `InstructInputs` (`Record`) | | `files` | `FileInfo[]` | | `textReferences` | `Array<{ content: string; name?: string }>` | | `contextSections` | `Array<{ content: string; title?: string }>` | | `metadata` | `MessageMetadata \| undefined` | ## Inputs ```typescript withInputs(inputs: InstructInputs): Instruct // returns a new instance withInput(name: string, value: InstructInput): Instruct // returns a new instance setInputs(inputs: InstructInputs): void // mutates, replaces all addInput(name: string, value: InstructInput): void // mutates, adds one ``` `withInputs` / `withInput` clone first, so the receiver is never modified — this is what makes an `Instruct` a reusable template. ## Content ```typescript addFile(file: FileInfo | string, options?: { name?: string }): void addContext(content: string, options?: { title?: string }): this hasFiles(): boolean ``` `addFile` routes by kind: | Input | Becomes | | --- | --- | | `string` | A text reference (`## Reference N` section) | | `FileInfo` with `kind: "text"` and an inline text source | A text reference | | Any other `FileInfo` | A file part, converted to the provider's native format | `addContext` returns `this` and is chainable. Context sections perform **no** variable substitution. ## Lifecycle ```typescript clone(): Instruct validate(options?: { vars?: "required" | "optional" }): void render(options?: { vars?: "required" | "optional" }): string toMessage(options?: { metadata?: MessageMetadata; id?: string }): AxleUserMessage parse(final: AxleAssistantMessage | undefined): Promise | null> toJSON(): InstructData fromJSON(data: InstructData): Instruct ``` `validate()` throws `AxleInstructVariableError` when `vars` resolves to `"required"` and inputs are missing, and validates the schema converts to JSON Schema. `render()` validates first and returns the prompt alone — prompt with variables filled in, plus `## Reference` and `## Context` sections. It no longer includes output instructions; the schema travels on the message as `output: { schema }`. `toMessage()` uses the passed `metadata`, falling back to the instance's. `parse()` is async and returns `null` for a missing final message; otherwise parses the message text against the schema, or returns the raw text when there is no schema. `toJSON()` serializes the `Instruct` as plain data (the schema as JSON Schema); `fromJSON()` rebuilds one from it. A revived `Instruct` holds a JSON Schema, so its answer is parsed as JSON without validation. ## Rendering order `render()` assembles, in order: 1. **The prompt**, with `{{variables}}` substituted. 2. **`## Reference N[: name]`** — one fenced block per text reference. 3. **`## Context N[: title]`** — one fenced block per context section. Output instructions are not in the stored message. Each request's copy of the message gets the JSON Schema prepended as output-format instructions ahead of the prompt. Saved conversations from 0.36 keep the old instructions in their message text and have no `output`. Fences auto-widen past any backtick run in the content, so fenced content nests safely. ## Types ```typescript type InstructInput = string | number | boolean | null; type InstructInputs = Record; type InstructVarsMode = "required" | "optional"; interface InstructRenderOptions { vars?: InstructVarsMode } interface InstructContextSection { content: string; title?: string } type OutputSchema = StandardOutputSchema | JsonSchema; // JsonSchema = Record type InstructResponse = TSchema extends OutputSchema ? ParsedSchema : string; interface InstructData { prompt: string; inputs?: InstructInputs; vars?: InstructVarsMode; references?: Array<{ content: string; name?: string }>; context?: InstructContextSection[]; files?: FileInfo[]; metadata?: MessageMetadata; schema?: JsonSchema; } ``` `parseResponse(text, schema)` is exported separately for parsing a response outside an `Instruct`. It returns a promise. --- # Providers Source: https://axle.fifthrevision.com/reference/providers _Provider factories, request options, and the model catalog._ Conceptual guide: [Providers & models](/concepts/providers). ## Factories A provider says two things separately: the wire `protocol` it speaks and the `id` of the service it reaches (the models.dev provider id, stamped on usage rows). ```typescript import { anthropic, openai, gemini, openrouter, togetherai, bedrock } from "@fifthrevision/axle"; anthropic(apiKey: string, options?: ProviderClientOptions): AIProvider openai(apiKey: string, options?: ProviderClientOptions): AIProvider gemini(apiKey: string, options?: ProviderClientOptions): AIProvider openrouter(apiKey: string, options?: Omit & { baseUrl?: string }): AIProvider togetherai(apiKey: string, options?: Omit): AIProvider bedrock(apiKey: string, options: BedrockOptions): AIProvider ``` ```typescript interface BedrockOptions extends ProviderClientOptions { protocol: "messages" | "responses" | "chatCompletions"; region: string; // e.g. "us-east-1" } ``` `bedrock()` follows the model: `messages` for Claude, `responses` or `chatCompletions` for what Mantle serves. Claude on Bedrock takes inference-profile ids (`us.anthropic.claude-haiku-4-5-20251001-v1:0`). ### Protocol constructors Each protocol builds a provider at any base URL. A preset is one of these with a base URL, an `id` and (where it applies) a `dialect` or `resolveModel` already filled in — see [Presets](/concepts/providers#presets). ```typescript import { messages, responses, generateContent, chatCompletions } from "@fifthrevision/axle"; messages(options: ProtocolOptions & { baseUrl: string; id?: string; resolveModel?: (model: string) => string }): AIProvider responses(options: ProtocolOptions & { baseUrl: string; id?: string; resolveModel?: (model: string) => string }): AIProvider generateContent(options: ProtocolOptions & { baseUrl: string; id?: string; resolveModel?: (model: string) => string }): AIProvider chatCompletions(options: ChatCompletionsOptions & { baseUrl: string }): AIProvider ``` ```typescript interface ChatCompletionsOptions extends ProviderClientOptions { baseUrl: string; apiKey?: string; id?: string; // usage-row label, e.g. "openrouter" dialect?: ChatCompletionsDialect; // openrouterDialect | togetheraiDialect resolveModel?: (model: string) => string; webSearch?: ExecutableTool; // serves `web_search` requests on this provider } ``` Every constructor infers `id` from the base URL's hostname when it recognizes one, and `chatCompletions()` infers `dialect` the same way. A hostname matches its own subdomains too (`api.openrouter.ai` resolves through `openrouter.ai`). Anything else leaves `id` `undefined`, and usage rows from that provider carry no `provider`. | Constructor | Hostname | `id` | `dialect` | | --- | --- | --- | --- | | `messages()` | `api.anthropic.com` | `anthropic` | — | | `responses()` | `api.openai.com` | `openai` | — | | `generateContent()` | `generativelanguage.googleapis.com` | `google` | — | | `chatCompletions()` | `openrouter.ai` | `openrouter` | `openrouterDialect` | | `chatCompletions()` | `api.together.ai`, `api.together.xyz` | `togetherai` | `togetheraiDialect` | A `chatCompletions()` provider without the OpenRouter dialect no longer reads OpenRouter's `reasoning_details` or the `content` of a citation from responses; behind a proxy to OpenRouter, pass `dialect: openrouterDialect` to keep reasoning continuity and cited text. Model IDs are never rewritten — pass the slug the gateway lists. `vendor` and `inferChatCompletionsVendor` were removed in 0.35.0; `chatCompletions({ baseUrl }).id` gives what the hostname implies. `ChatCompletionsVendor` is removed. See [Upgrading](/upgrading). ### webSearch ```typescript import { chatCompletions, braveWebSearch, openrouterDialect } from "@fifthrevision/axle"; const provider = chatCompletions({ baseUrl: "https://api.together.xyz/v1", apiKey, webSearch: braveWebSearch({ apiKey: braveKey }), }); ``` `chatCompletions()` hosts no search of its own. When a request carries the `web_search` provider tool, the provider sends the attached tool to the model as an ordinary function tool and the loop runs it as an ordinary tool call — so the transcript shows `tool` parts, not `provider-tool` parts. An attached tool is used wherever it is attached, including on OpenRouter, which hosts a search of its own: don't attach one if you want OpenRouter's. A provider asked for a provider tool it has nothing attached for fails the request (`ok: false`, `error.kind` `"api"`, naming the tool). See [Web search](/cookbook/web-search) and [Provider tools](/cookbook/provider-tools). ## ProviderClientOptions Applied when the client is constructed, not per request. | Option | Type | Default | Description | | --- | --- | --- | --- | | `maxRetries` | `number` | `2` | Retries after the first request. `0` disables. Must be ≥ 0. | | `timeoutMs` | `number` | SDK default (`chatCompletions()`: 10 minutes per attempt) | Timeout for one request attempt. Must be ≥ 1. | | `headers` | `Record` | — | Extra headers sent with every request. | | `fetch` | `typeof fetch` | global `fetch` | Replaces the global for this provider's requests. Called as `(url, init)` and must return a real `Response`; retries, `timeoutMs`, and the abort signal apply unchanged. A test that stubbed `globalThis.fetch` can pass a fake here instead. | Non-integer or out-of-range values throw `AxleError` (`INVALID_OPTIONS`) at construction. `baseUrl` on the first-party factories was removed in 0.35.0 — they are presets at the service's own base URL. To send the same requests elsewhere, call the protocol constructor with that base URL. `typesafe()` keeps its `baseUrl`, and `openrouter()` takes one for OpenRouter's regional hosts. ## AxleModelRequestOptions Portable per-request options. Settable on `AgentConfig`, on `SendMessageOptions`, and on `GenerateParams` / `StreamParams`. | Option | Type | Description | | --- | --- | --- | | `reasoning` | `ReasoningSetting` | Portable thinking/reasoning control: `"default"` or `{ enabled?, effort?: "minimal" \| "low" \| "medium" \| "high" \| "xhigh" \| "max", display?: "visible" \| "hidden" }`. | | `maxOutputTokens` | `number` | Output token cap. | | `toolChoice` | `ToolChoice` | Tool-use constraint. | | `parallelToolCalls` | `boolean` | Ask the provider to avoid parallel tool calls. | | `cache` | `boolean` | Whether Axle asks the provider to cache the prompt prefix where asking is required (Anthropic, OpenRouter). Defaults to `true`. Providers that cache on their own (OpenAI, Gemini, Together) are unaffected by either value. An explicit `providerOptions.cache_control` overrides the default. | | `providerOptions` | `Record` | Raw fields, applied **after** normalized mappings. | | `signal` | `AbortSignal` | Aborts the in-flight request. | `temperature`, `topP`, and `stop` were removed in 0.33.0. Send them through `providerOptions` using the provider's own field names (`top_p` on Anthropic / OpenAI / Chat Completions, `topP` on Gemini; `stop_sequences` on Anthropic, `stopSequences` on Gemini, `stop` on Chat Completions, unsupported on OpenAI). See [Upgrading](/upgrading). ```typescript type ToolChoice = "auto" | "none" | "required" | { type: "tool"; name: string }; type ReasoningEffort = "minimal" | "low" | "medium" | "high" | "xhigh" | "max"; // = REASONING_EFFORTS, lowest first type ReasoningDisplay = "visible" | "hidden"; type ReasoningSetting = "default" | { enabled?: boolean; effort?: ReasoningEffort; display?: ReasoningDisplay }; ``` `display` (default `"visible"`) asks the provider to disclose its thinking wherever a request field exists. Enabling reasoning (`{ effort }` or `{ enabled: true }`) now requests disclosure on Anthropic (`display: "summarized"`), OpenAI (`summary: "auto"`), and Gemini (`includeThoughts: true`), so Claude and OpenAI models that streamed no thinking under 0.31 now do. Pass `{ effort, display: "hidden" }` to keep the 0.31 wire behaviour — the turn receives no thinking content while the message keeps whatever the wire carried. Fine-grained values (OpenAI `concise` / `detailed`, Anthropic `updates`) stay in `providerOptions`; overriding `thinking` on Anthropic replaces the whole object, `type` included. See [Reasoning models](/cookbook/reasoning#disclosure-vs-form). Agent-level and send-level options merge shallowly, with send-level winning. `providerOptions` merges key by key rather than replacing wholesale. ## Model naming Providers accept plain vendor ids (`"claude-sonnet-4-5"`) and publisher-namespaced ids (`"anthropic/claude-sonnet-4-5"`). Presets strip a matching prefix and **throw** (`INVALID_OPTIONS`) on a mismatched one: ```typescript anthropic(key); // model "openai/gpt-5.1" → throws ``` | Preset | Accepted prefixes | | --- | --- | | `anthropic()` | `anthropic/` | | `openai()` | `openai/` | | `gemini()` | `google/`, `gemini/` | | `openrouter()` / `togetherai()` / `chatCompletions()` | Any — passed through (a raw protocol constructor sends the id as given; pass `resolveModel` to strip) | Because namespaced ids are also what OpenRouter's API expects, the same model string works against a first-party provider and an inference gateway without change. See [One model string, any inference provider](/concepts/providers#one-model-string-any-inference-provider). OpenRouter slugs are sent unchanged. If OpenRouter lists a model under a slug that differs from the publisher's canonical form (casing, or a different author prefix — `z-ai/glm-5.3`, not `zai/glm-5.3`), pass OpenRouter's slug. IDs that were already OpenRouter slugs are unaffected. ## Model catalog and cost Conceptual guide: [Model catalog & cost](/concepts/model-catalog). The `@fifthrevision/axle/models` entry point (`Models`, `ModelInfo`, `ModelMetadata`) no longer exists (removed in 0.33.0). Pass model IDs as plain strings. **Experimental** `ModelCatalog`, `ModelCatalogStore`, the catalog functions and `computeCost` are marked `@experimental`: they are new in 0.35.0 and may change in a minor release. ```typescript import { ModelCatalogStore, catalogFile } from "@fifthrevision/axle"; const file = catalogFile("./.cache/axle-models.json"); const catalogs = new ModelCatalogStore({ providers: ["anthropic"] }); catalogs.load(await file.read()); const snapshot = await catalogs.refreshIfStale(); if (snapshot) await file.write(snapshot); const catalog = catalogs.current; // ModelCatalog | undefined const hit = catalog?.contextWindow("openai/gpt-5.5", { provider: "openai" }); // { window, id, match } | undefined ``` ### ModelCatalog ```typescript class ModelCatalog { constructor(data: CatalogData); get fetchedAt(): string; // ISO 8601, read back from the data get coverage(): "all" | string[]; // the provider filter the data was fetched with lookup(model: string, options?: { provider?: string; publisher?: string }): CatalogMatch | undefined; contextWindow(model: string, options?: { provider?: string; publisher?: string }): ContextWindowMatch | undefined; } ``` A synchronous, immutable index over `CatalogData` (version 4: a canonical `publisher/model` layer plus a per-provider layer with each provider's own ids, limits and prices). It never fetches — new data means a new catalog — and takes its data as given, so read saved JSON with `parseCatalogData`, not `JSON.parse`. Loading and refreshing live in `ModelCatalogStore`, which never touches storage. `lookup` resolves in three steps and `match` reports which one answered. Both options are optional; `{ provider }` and `{ publisher }` replace the old `{ host }`. | `match` | How it matched | | --- | --- | | `"provider"` | `options.provider`'s own ids, compared case-insensitively. When the model id's publisher *is* the provider, the bare name is tried too (`anthropic/claude-sonnet-5` matches the provider's `claude-sonnet-5`). The only match that carries `cost`. | | `"exact"` | the canonical `publisher/model` key — a bare id is qualified with `options.publisher` when one is given — or a unique exact match on the normalized model name | | `"prefix"` | a unique prefix match on the normalized name | Normalizing drops trailing build tags (`mlx`, `latest`, `gguf`, `q4_0`, `fp16`, `bf16`) and ignores punctuation, case and the publisher, which is what makes a local runtime's `gemma4:26b-mlx` findable. An ambiguous name — two models normalize alike, or several share the prefix — returns `undefined`, as does no match at all. ```typescript interface CatalogMatch { id: string; // the canonical publisher/model id, or provider/id for a model only that provider lists match: "provider" | "exact" | "prefix"; model: CatalogModel; cost?: ModelCost; // provider matches only } interface ContextWindowMatch { window: number; // model.limit.context id: string; match: "provider" | "exact" | "prefix"; } ``` A provider match merges that provider's own `limit` over the canonical model's, so `model.limit` is the limit for the service you named. ### CatalogModel and ModelCost ```typescript interface CatalogModel { name: string; limit: { context: number; output?: number; input?: number }; reasoning: boolean; toolCall: boolean; structuredOutput?: boolean; attachment: boolean; modalities: { input: string[]; output: string[] }; knowledge?: string; // training cutoff } interface ModelCost { input: number; // USD per million tokens output: number; cacheRead?: number; cacheWrite?: number; reasoning?: number; tiers?: { size: number; input: number; output: number; cacheRead?: number; cacheWrite?: number; reasoning?: number; }[]; } ``` A `tiers` entry prices a request whose context exceeds `size`; entries ascend by size, and the last one a request exceeds wins. ### ModelCatalogStore ```typescript class ModelCatalogStore { constructor(options?: ModelCatalogStoreOptions); get current(): ModelCatalog | undefined; load(json: string | undefined): void; refresh(): Promise; refreshIfStale(): Promise; snapshot(): string | undefined; } interface ModelCatalogStoreOptions extends Omit { providers?: string[]; // models.dev provider ids to keep; omit for all, [] to skip the layer maxAge?: number; // ms past which refreshIfStale() fetches; default one day timeout?: number; // fetch timeout; default 10s baseUrl?: string; // catalog origin; default https://models.dev signal?: AbortSignal; } ``` - `load(json)` takes the saved JSON and ignores anything that is not usable `CatalogData` — missing, corrupt, or written by an older Axle. It never throws, and `current` stays as it was. - `refresh()` fetches with the current data's ETags and makes the result current. It resolves the JSON snapshot to save, or `undefined` when the fetch failed: it never rejects for the network. Concurrent calls share one fetch. Nothing refreshes on its own. - `refreshIfStale()` is `refresh()` when there is no data or it is older than `maxAge`, and otherwise resolves `undefined`. - `snapshot()` is the current data as JSON, or `undefined` when there is none. ### Storage ```typescript catalogFile(path: string): CatalogStorage interface CatalogStorage { read(): Promise; write(json: string): Promise; } ``` `catalogFile` writes atomically (temp file, then rename) and creates the parent directory; an unreadable or missing file reads as `undefined`. The store only ever hands out and takes JSON text, so any `CatalogStorage` — a database row, an object store — works the same way. ### fetchModelsDev ```typescript fetchModelsDev(options?: FetchModelsDevOptions): Promise interface FetchModelsDevOptions { providers?: string[]; // models.dev provider ids to keep; omit for all, [] skips the provider layer previous?: CatalogData; // send its ETags; an unchanged layer downloads nothing timeout?: number; // whole-fetch budget in ms; default 10_000 baseUrl?: string; // default https://models.dev signal?: AbortSignal; } class CatalogFetchError extends Error {} // cause holds the underlying error ``` Fetches both layers and slims them to what the catalog reads. It rejects with `CatalogFetchError` when either layer cannot be fetched or parsed — a network failure, the timeout, an HTTP error status, a body of the wrong shape — and there is no partial result, so the data you already had remains the best you have. `fetchedAt` is always the time of this fetch, even for a layer that came back `304`. The `providers` filter is recorded as `coverage`, and a `previous` fetched under a different filter is not reused for the provider layer (its canonical layer still is). ### CatalogData ```typescript interface CatalogData { version: 4; fetchedAt: string; // ISO 8601 etags: { models?: string; api?: string }; coverage: "all" | string[]; models: Record; // keyed publisher/model providers: Record>; // provider id → its own model ids } interface ProviderEntry { canonical?: string; // key into models model?: CatalogModel; // for a model only this provider lists limit?: Partial; // overrides the canonical limit cost?: ModelCost; } ``` Plain JSON, and yours to edit before building a catalog: a negotiated price, a self-hosted model, a test fixture with no network. `parseCatalogData(json)` returns it, or `undefined` for text that is not JSON or is another version or shape — which means there is no usable copy and the answer is to fetch. `ProviderEntry` is not exported; it is the shape inside `CatalogData.providers`. ### computeCost ```typescript import { computeCost } from "@fifthrevision/axle"; const cost = computeCost(usage, catalog); // { usd, priced: PricedEntry[], unpriced: UnpricedEntry[], pricedWith? } ``` ```typescript computeCost(usage: Stats, catalog?: ModelCatalog): Cost; ``` Synchronous, never throws. It prices each `breakdown` row on its own: the row's `provider` and `model` (then `requestedModel`) are looked up in the provider layer, the tier is the one the row's own `in` selects, and cached, cache-write and reasoning tokens are priced at their own rates where the provider lists them, the rest at the plain input/output rate. `usd` sums `priced` only. `pricedWith` is the catalog's `fetchedAt`, absent when no row was priced. Unpriced rows carry `reason`: | `reason` | Meaning | | --- | --- | | `no-catalog` | no catalog was passed | | `no-provider` | the row has no `provider` id | | `unlisted` | the catalog has no `"provider"` match for that provider and model | | `no-price` | the provider lists the model but no price | Full `Cost`, `PricedEntry` and `UnpricedEntry` shapes are in the [Observability reference](/reference/observability#usage-stats-breakdown-and-cost). ## Context estimation ```typescript import { estimateContextUsage } from "@fifthrevision/axle"; estimateContextUsage({ system?: string; tools?: ToolDefinition[]; mcpTools?: ToolDefinition[]; providerTools?: ProviderTool[]; messages: AxleMessage[]; limit?: number; }): ContextUsage ``` ```typescript interface ContextUsage { total: number; system: number; tools: number; mcpTools: number; providerTools: number; messages: number; limit?: number; free?: number; // max(0, limit - total), only when limit is given } ``` Heuristic and computed locally — not provider-reported. `agent.context()` calls this with the agent's own state and no `limit`, so its result carries neither `limit` nor `free`; pass one yourself — from [`catalog.contextWindow()`](#modelcatalog), say — to get them. ## AIProvider ```typescript interface AIProvider { readonly protocol: Protocol; // "messages" | "responses" | "generateContent" | "chatCompletions" readonly id?: string; // models.dev provider id; stamped on usage rows tools?: ExecutableTool[]; createStreamingRequest(model: string, params: ProviderStreamParams): AsyncGenerator; } ``` `name` was replaced by `protocol` + `id` in 0.35.0 (`"anthropic"` → `protocol: "messages", id: "anthropic"`; `"OpenAI"` → `responses`/`openai`; `"Gemini"` → `generateContent`/`google`; `"ChatCompletions"` → `chatCompletions`/vendor id). A provider with no `id` (a local server) leaves usage rows without `provider`. `tools` are executable tools the provider brings: when the model calls a tool whose name is not among the caller's tools, the loop runs the provider's tool of that name. The caller's tool wins on a name collision. `chatCompletions()` uses this for an attached `webSearch`. (`resolveProviderToolName` was removed in 0.34.0 — the loop no longer asks a provider what it supports. See [Upgrading](/upgrading).) The request method is internal, and so are its types: `ProviderStreamParams` and `AnyStreamChunk` are declared by the package but not exported, so you can't name them from outside. (`createGenerationRequest`, `ProviderGenerationParams`, and `ModelResult` were removed in 0.32.0 when `generate()` was unified onto the streaming transport — see [Upgrading](/upgrading).) You *can* implement this interface to add your own provider, but it isn't supported — the chunk and conversion contracts aren't stable across releases, so expect to keep fixing it. A custom provider receives `providerTools` unchanged, as before — core does not read the names and holds no fallback. Serve a name yourself (as a hosted tool or via `AIProvider.tools`) or fail the request before sending it: throwing an `AxleError` from `createStreamingRequest` surfaces per the [Errors](/reference/errors) rules. ## AxleStopReason ```typescript enum AxleStopReason { Stop = "stop", Length = "length", FunctionCall = "function_call", Cancelled = "cancelled", } ``` Surfaces as `AxleAssistantMessage.finishReason`. (`Error` and `Custom` were removed in 0.33.0 — unknown stop reasons now fail the request. See [Upgrading](/upgrading).) --- # Decisions Source: https://axle.fifthrevision.com/reference/decisions _decide(), the question and answer types, and the typesafe() provider._ Conceptual guide: [Typed decisions](/concepts/decisions). **Experimental** Decisions are marked `@experimental`: the question, answer, and provider shapes may change in a minor release. ## decide() ```typescript import { decide, noul, choice, score } from "@fifthrevision/axle"; decide(options: DecideParams): Promise> ``` Asks a decision model typed questions about one input. One request, one answer per question, no conversation. ```typescript interface DecideParams { provider: DecisionProvider; model: string; /** The content every question is asked about. */ input: DecisionInput; /** Questions keyed by a name of your choosing; answers come back under the same keys. */ questions: TQuestions; signal?: AbortSignal; span?: Span; } interface DecideResult { model: string; answers: DecisionAnswers; usage: Stats; } type DecisionInput = string | DecisionJson[] | { [key: string]: DecisionJson }; ``` `input` is a string or a JSON value (TypeSafe's wire name for it is `state`; Axle names it `input` because "state" already means agent state). Throws `DECISION_ANSWER_MISMATCH` when a question's answer is missing or mistyped, and rejects — never resolves `ok: false` — on request, transport, timeout, or abort failures. ## Questions ```typescript noul(instructions: string, criteria?: { true: string; false: string }): NoulQuestion choice(instructions: string, criteria: Record): ChoiceQuestion score(instructions: string, criteria: string[]): ScoreQuestion type DecisionQuestion = NoulQuestion | ChoiceQuestion | ScoreQuestion; type DecisionQuestions = Record; ``` `choice` criteria map each option to its description, or `null`. `score` criteria list the ordered levels, lowest first. ## Answers ```typescript type DecisionAnswer = NoulAnswer | ChoiceAnswer | ScoreAnswer | DecisionRefusal; interface NoulAnswer { type: "noul"; noul: number } interface ChoiceAnswer { type: "choice"; choice: TOption; probabilities: Record; confidence: number; } interface ScoreAnswer { type: "score"; score: number; probabilities: Record; legend: Record; confidence: number; } interface DecisionRefusal { type: "refusal" } type AnswerFor = TQuestion extends NoulQuestion ? NoulAnswer | DecisionRefusal : TQuestion extends ChoiceQuestion ? ChoiceAnswer | DecisionRefusal : TQuestion extends ScoreQuestion ? ScoreAnswer | DecisionRefusal : never; ``` `confidence` summarizes how concentrated a choice or score answer's probabilities are — it is not the probability of the chosen answer, and it is not comparable across models. A refusal belongs to one question; the rest of the decision stands. ## DecisionProvider ```typescript interface DecisionProvider { get name(): string; /** @internal */ createDecisionRequest(model: string, params: DecisionRequestParams): Promise; } ``` Separate from `AIProvider`; a provider may implement either or both. `typesafe()` implements only this one, so passing it to `stream()`, `generate()`, or an `Agent` is a type error. ## typesafe() ```typescript import { typesafe } from "@fifthrevision/axle"; typesafe(apiKey: string, options?: TypesafeOptions): DecisionProvider type TypesafeOptions = ProviderClientOptions; ``` `baseUrl` is the shared client option: the API root serving `/v1/systemone` (default `https://api.typesafe.ai`). Point it at `https://openrouter.ai/api` with an OpenRouter key to route through it. `timeoutMs` defaults to ten seconds per attempt, matching TypeSafe's own SDKs. A non-2xx response throws `DECISION_REQUEST_FAILED` with the status and body in `details`; a body Axle cannot read throws `DECISION_RESPONSE_INVALID`. The model id is passed through unchanged. --- # generate() & stream() Source: https://axle.fifthrevision.com/reference/generate-stream _Parameters, handles, results, and the full StreamEvent union._ Conceptual guide: [generate() & stream()](/concepts/generate-and-stream). ## generate() ```typescript generate(options: GenerateParams): Promise generate(options: GenerateInstructParams): Promise> ``` `generate(o)` is `stream(o).final` — the same request, the same tool loop, and the same result, resolved as a promise instead of a handle. (Unified onto the streaming transport in 0.32.0; there is no non-streaming request anymore.) ## stream() ```typescript stream(options: StreamParams): StreamHandle stream(options: StreamInstructParams): StreamInstructHandle ``` Processing begins on the next microtask, so callbacks registered synchronously after the call receive every event. ## Parameters `GenerateParams` and `StreamParams` are identical apart from their return type. Both extend `AxleModelRequestOptions`. | Option | Type | Description | | --- | --- | --- | | `provider` | `AIProvider` | **Required.** | | `model` | `string` | **Required.** | | `messages` | `AxleMessage[]` | **Required** (optional with `instruct`). | | `system` | `string` | System instruction. | | `tools` | `AnyTool[]` | Executable and deferred tools. | | `providerTools` | `ProviderTool[]` | Provider-managed tools. | | `onToolCall` | `ToolCallCallback` | Answers calls to the deferred tools in `tools`. Executable tools never reach it. | | `maxSteps` | `number` | Cap on model requests. Must be ≥ 1. | | `maxContextTokens` | `number` | Context budget in tokens. Must be ≥ 1. | | `streamStallMs` | `number` | Longest gap in milliseconds between two chunks from the provider on one step's stream, the wait for the first included. When it passes, the request aborts and the run ends `ok: false` with `{ kind: "api", type: "StreamStall" }`; nothing is retried. Unset by default. Must exceed a reasoning model's silent thinking. | | `span` | `Span` | Parent tracing span. | | `fileResolver` | `FileResolver` | Resolves deferred file references. | | `sessionId` | `string` | Conversation identity forwarded to the provider on every step. Only OpenRouter uses it today (as `session_id`, for sticky routing, cache affinity, and dashboard grouping); other providers ignore it. `Agent` passes its own `sessionId`; a call without one gets a fresh id so the steps of its own tool loop stay together. Pass the same id to separate calls to share OpenRouter cache reads across them. | | ...request options | | See [Providers](/reference/providers#axlemodelrequestoptions). | Non-positive limits throw with code `INVALID_OPTIONS`. (`StreamParams.registry` was removed in 0.34.0 — the loop builds every request from the `tools` and `providerTools` it was given and never reads a registry, so a tool added to a `ToolRegistry` mid-loop no longer appears. See [Upgrading](/upgrading).) ### Instruct variants ```typescript interface GenerateInstructParams extends Omit { messages?: AxleMessage[]; // prior context instruct: Instruct; } ``` The `Instruct` is cloned, rendered, and appended after `messages`. `response` becomes the parsed value instead of a message. ### onToolCall ```typescript import type { DeferredCall, ToolCallCallback, ToolContext } from "@fifthrevision/axle"; import type { ToolResultPart } from "@fifthrevision/axle"; type ToolCallCallback = ( call: DeferredCall, ctx: ToolContext, ) => string | ToolResultPart[] | void | Promise; ``` Answers calls to the deferred tools in `tools`. The call arrives with its arguments already validated against the tool's schema (`{ id, name, input }`); the handler returns what an `execute` would, throws to hand the model an `execution` error result, and returns nothing for a call it does not answer — which stays waiting for `toolCall(id)`, the tool's `timeout`, or cancellation. Executable tools never reach the handler; the call's arguments are validated before the handler runs, and a mismatch returns a `validation` error tool result without calling it. `generate()` has no handle, so a call the handler does not answer — or any call when there is no handler — fails at once with an `execution` error naming the tool. ## Handles ```typescript interface StreamHandle { on(callback: (event: StreamEvent) => void): void; onToolBatchComplete(callback: ToolBatchCompleteCallback): void; onStep(callback: StreamStepCallback): void; cancel(reason?: unknown): void; toolCall(id: string): WaitingToolCall | undefined; readonly final: Promise; } /** * One step of a run, handed to `onStep` when it ends: a model call and the * tool batch it asked for, if any. `usage` is what the step added to the * run's usage, and `messages` what it added to the conversation. */ interface StreamStep { usage: Stats; messages: AxleMessage[]; } type StreamStepCallback = (step: StreamStep) => void | Promise; type ToolBatchCompleteCallback = ( message: AxleToolCallMessage, ) => ToolBatchDecision | Promise; /** * What the tool-batch boundary decides: `"finish"` ends the loop without * another request; `"continue"` sends the next one as is; an object continues * with that prompt and those tools replacing the current ones, exactly as the * initial call set them. (The object form was added in 0.34.0.) */ type ToolBatchDecision = | "continue" | "finish" | Pick; ``` `StreamInstructHandle` is the same with `final: Promise>`. `onStep(callback)` installs one awaited callback that runs each time a step ends, however it ended: after the tool results are written, or after a model call that asked for no tools. The next model call is not sent until it returns. A `cancel()` while it is pending takes effect when it returns; a callback that throws rejects `final` with that error. Unlike `agent.on()`, `stream().on()` does not return an unsubscribe function. ## Results ```typescript type GenerateResult = | { ok: true; response: TResponse; messages: AxleMessage[]; final: AxleAssistantMessage; error?: undefined; usage?: Stats; stopped?: "max-steps" | "token-limit"; } | { ok: false; response?: undefined; final?: AxleAssistantMessage; messages: AxleMessage[]; error: AxleProviderFailure; usage?: Stats; stopped?: "max-steps" | "token-limit"; }; type StreamResult = GenerateResult; ``` `stopped` on a success means a limit ended the loop; the conversation is well-formed and continuable, and `final.finishReason` keeps the provider's own reason. `stopped` on a `parse` error means the limit landed before parseable output existed. ## StreamEvent ### Step and batch boundaries | Event | Fields | | --- | --- | | `step:start` | `id`, `model` | | `step:complete` | `message`, `usage?` | | `tool-results:start` | `id` | | `tool-results:complete` | `message` | ### Text | Event | Fields | | --- | --- | | `text:start` | `index` | | `text:delta` | `index`, `delta`, `accumulated` | | `text:citation` | `index`, `citation`, `citations` | | `text:end` | `index`, `final` | | `citation` | `citations`, `providerMetadata?` — unanchored source list | ### Thinking | Event | Fields | | --- | --- | | `thinking:start` | `index`, `continuity?` (Anthropic: only once a signature or redacted data has arrived), `providerMetadata?` | | `thinking:raw-delta` | `index`, `delta`, `accumulated` | | `thinking:summary-delta` | `index`, `delta`, `accumulated` | | `thinking:update` | `index`, `continuity?`, `providerMetadata?` | | `thinking:end` | `index`, `summary?`, `raw?` — each present only if a delta wrote it | Every text and thinking event carries the required `index`: the part's position in the step's assistant message. Code that only reads these events is unaffected; code that constructs them (a custom `StreamHandle`, a test fixture) adds the field. (`index` was added in 0.37.0 — it fixes grounding citations that arrived after their text, which Gemini sends, being lost from turns.) ### Tools Correlated by `id`. | Event | Fields | | --- | --- | | `tool:request` | `id`, `name`, `kind?` (`"tool"` \| `"agent"` \| `"deferred"`) | | `tool:args-delta` | `id`, `name`, `delta`, `accumulated` | | `tool:exec-start` | `id`, `name`, `parameters` — never fires for deferred calls | | `tool:waiting` | `id`, `name`, `input` — the validated deferred call, handed to `onToolCall`; answer it or wait for `toolCall(id)` | | `tool:exec-delta` | `id`, `name`, `chunk` | | `tool:exec-complete` | `id`, `name`, `result`, `usage?` | | `tool:exec-error` | `id`, `name`, `error: { type: "fatal" \| "aborted"; message }`, `usage?` | ### Provider tools and errors | Event | Fields | | --- | --- | | `provider-tool:start` | `id`, `name` — `name` is Axle's portable name | | `provider-tool:input` | `id`, `name`, `input` — what the tool was asked to do | | `provider-tool:complete` | `id`, `name`, `output?` — the tool's printed output when the provider reports one stream | | `provider-tool:error` | `id`, `name`, `error: { type, message }` — the provider reported failure | | `error` | `error: AxleProviderFailure` | `provider-tool:input` (added in 0.33.0) fires when the provider says what the tool was asked to do — before the search runs on Anthropic, together with the result on OpenAI. `provider-tool:error` replaces `complete` when the provider reports failure; a consumer that waits for `complete` to close a provider tool must handle `error` as well. On `complete`, `output` carries the tool's printed output when the provider reports one stream (code execution); search results live on the finished message part's `continuity`, not on the event. See [Messages & parts](/reference/messages#providertool-parts). --- # Tools Source: https://axle.fifthrevision.com/reference/tools _Tool types, the registry, subagents, batching, and web search._ Conceptual guide: [Tools](/concepts/tools). ## ExecutableTool ```typescript import type { ZodObject, z } from "zod"; interface ExecutableTool = ZodObject> { type?: "function"; kind?: "tool" | "agent"; name: string; description: string; schema: TSchema; execute(input: z.infer, ctx: ToolContext): Promise; configure?(config: Record): void; summarize?(input: z.infer): string; } ``` | Field | Notes | | --- | --- | | `name` | Must be unique across local, MCP, and provider tools. | | `description` | Sent to the model. This is prompt text. | | `schema` | Must be a Zod **object**. Use `.describe()` on fields. Call arguments are parsed with it before `execute` runs — `execute` receives the parsed value (defaults and transforms applied), and a mismatch returns a `validation` error tool result without calling `execute`. | | `kind` | Presentation only. `"agent"` renders as a subagent; execution is identical. | | `summarize` | Optional human-readable one-liner for a UI. | | `configure` | Optional hook for host-supplied configuration. | ## ToolContext ```typescript interface ToolContext { signal: AbortSignal; emit: (chunk: ToolProgressChunk) => void; reportUsage?: (usage: Stats) => void; // @experimental span?: Span; } type ToolProgressChunk = string | { type: "turn-event"; event: TurnEvent }; ``` `signal` is the batch's signal, not the run's: it aborts when the run's signal aborts, with the run's reason, and when a sibling call in the same batch fails fatally, with that sibling's error as the reason. A tool that rethrows its signal's reason is reported as `aborted`, not as a second fatal. `emit` with a string surfaces as `action:progress`. Emitting a wrapped `TurnEvent` is how nested agents forward their own event stream — it becomes `action:child-event`. (`registry` was removed from `ToolContext` in 0.34.0. A tool that changes the agent it runs under uses that agent in closure scope — `agent.registry.add(...)`, `agent.skills.add(...)`. See [Upgrading](/upgrading).) ## ToolResultPart ```typescript type ToolResultPart = | { type: "text"; text: string } | { type: "file"; file: FileInfo }; ``` ## DeferredTool ```typescript import type { ZodObject, z } from "zod"; interface DeferredTool = ZodObject> { type: "deferred"; name: string; description: string; schema: TSchema; summarize?(input: z.infer): string; timeout?: number; // ms a call may wait for its answer before it fails with `timeout`; unbounded when absent } ``` A tool definition with no `execute`: the model calls it like any other tool, and the caller answers. Calls go to the `onToolCall` handler on `stream()`, `generate()`, or `agent.onToolCall()`, or are answered from outside with `toolCall(id).answer()` / `.fail()`. Conceptual guide: [Deferred tools](/concepts/tools#deferred-tools). | Field | Notes | | --- | --- | | `name` | Must be unique across local, deferred, MCP, and provider tools. | | `description` | Sent to the model. This is prompt text. | | `schema` | Must be a Zod **object**. Call arguments are parsed with it before the handler runs — a mismatch returns a `validation` error tool result without calling it. | | `summarize` | Optional human-readable one-liner for a UI. | | `timeout` | Milliseconds a call may wait for its answer before it fails with a `timeout` error result (`No answer for within ms`). Unset, a call waits until answered or cancelled. | ## DeferredCall ```typescript interface DeferredCall> { id: string; // the tool call id — pass it to toolCall(id) name: string; input: TInput; // already validated against the tool's schema } ``` What an `onToolCall` handler receives, with the `ToolContext` an `execute` would get. Return the result (`string | ToolResultPart[]`), throw for an `execution` error with the message as reason, or return nothing and leave the call waiting. ## WaitingToolCall ```typescript interface WaitingToolCall { answer(content: string | ToolResultPart[]): void; fail(message: string): void; } ``` The deferred call the loop is waiting on, reached through `toolCall(id)` on a stream handle or an `Agent` — `undefined` once it has settled. The first settle wins; later ones do nothing. ## isCall / isActionOf ```typescript import { isActionOf, isCall, type DeferredCall, type DeferredTool, type TurnPart, } from "@fifthrevision/axle"; declare const tool: DeferredTool; declare const call: DeferredCall; declare const part: TurnPart; isCall(tool, call); // narrows DeferredCall to DeferredCallOf, input typed isActionOf(tool, part); // narrows a TurnPart to that tool's deferred action (pending parts excluded) ``` Both are also exported from `@fifthrevision/axle/ui`. ```typescript type AnyTool = ExecutableTool | DeferredTool; ``` `StreamParams.tools`, `AgentConfig.tools`, `ToolRegistry.add()`, and the registry constructor take `AnyTool`. Code that passes `ExecutableTool[]` is unaffected. `ToolRegistry.get()` still returns executable tools only — use `getDeferred()` / `deferred()` for the other kind. ## ProviderTool ```typescript interface ProviderTool { type: "provider"; name: string; config?: Record; } ``` Portable names and their native mappings: | Portable | Anthropic | OpenAI | Gemini | | --- | --- | --- | --- | | `web_search` | `web_search_20260318` | `web_search` | `googleSearch` | | `code_execution` | `code_execution_20260521` | `code_interpreter` | `codeExecution` | Unmapped names pass through unchanged. `config` is raw passthrough — field names and placement are not portable. On Anthropic, `web_search` defaults to `allowed_callers: ["direct"]`; see [Provider tools](/cookbook/provider-tools). ## ToolDefinition ```typescript type ToolDefinition = Pick; ``` The schema-only shape sent to providers. ## ToolRegistry Conceptual guide: [The tool registry](/concepts/tool-registry). ```typescript new ToolRegistry(init?: { tools?: AnyTool[]; providerTools?: ProviderTool[] }) ``` | Method | Returns | Notes | | --- | --- | --- | | `add(tool \| tools)` | `void` | Local or deferred tools — the kind is on the tool. Throws `TOOL_REGISTRY_DUPLICATE` on a name collision. | | `addMcp(tool \| tools)` | `void` | MCP tools. Same duplicate check. | | `addProvider(tool \| tools)` | `void` | Provider tools. Same duplicate check. | | `remove(name)` | `boolean` | Removes from all four maps. | | `has(name)` | `boolean` | Across all four. | | `get(name)` | `ExecutableTool \| undefined` | Local, then MCP. Not provider or deferred tools. | | `getDeferred(name)` | `DeferredTool \| undefined` | | | `getProvider(name)` | `ProviderTool \| undefined` | | | `executable()` | `ExecutableTool[]` | Local + MCP. | | `deferred()` | `DeferredTool[]` | | | `local()` | `ExecutableTool[]` | | | `mcp()` | `ExecutableTool[]` | | | `provider()` | `ProviderTool[]` | | | `size` | `number` | Total across all four. | Names are unique across all four maps — a local tool, a deferred tool, an MCP tool, and a provider tool cannot share a name. ## createAgentTool() ```typescript createAgentTool(options: CreateAgentToolOptions): ExecutableTool ``` ```typescript interface CreateAgentToolOptions { name: string; description: string; schema: TSchema; createAgent: (input: z.infer, ctx: ToolContext) => MaybePromise; prompt?: string | ((input: z.infer) => string); request?: AxleModelRequestOptions; } ``` **Experimental** Subagent rendering shapes may change in a minor release. **:** - Returns a tool with `kind: "agent"`. - `createAgent` runs per call. Return a **fresh** agent. - `prompt` defaults to `` `Complete this delegated task. Input: ${JSON.stringify(input)}` ``. - Child turn events are forwarded via `ctx.emit`; the subscription is removed when the call ends. - Child usage is reported via `ctx.reportUsage`. - A non-`ok` child result throws `Error("Subagent failed (): ")` naming the failure kind and message. - A non-string child response is `JSON.stringify`'d. - `AxleToolFatalError` and `AxleAbortError` from the child are rebuilt without the child's `messages`/`partial`, so the parent never adopts another conversation's history. `usage` is preserved. - `ctx.signal` is forwarded to the child send. ## parallelize() ```typescript parallelize( tool: ExecutableTool, options?: ParallelizeOptions, ): ExecutableTool }>> ``` ```typescript interface ParallelizeOptions { name?: string; // default `${tool.name}_batch` description?: string; maxItems?: number; // default 50 maxConcurrency?: number; // default 8, floor 1 maxResultBytes?: number; // default 20 MiB } interface ParallelToolResult { index: number; input: TInput; ok: boolean; output?: string | ToolResultPart[]; error?: { type: "execution"; message: string }; } ``` **Experimental** The generated tool's result parts may change in a minor release. **preserve input order. Ordinary execution errors are reported per item;** fatal and abort errors propagate and terminate the run. The call's arguments are validated as a whole before anything runs, so one invalid item rejects the call with a `validation` error naming the item's path (for example `items.1.description`). The generated schema requires at least one item and at most `maxItems`. The wrapped tool's `kind` is inherited, so parallelized subagents still render as subagent activity. ## Web search ```typescript braveWebSearch(options: BraveWebSearchOptions): ExecutableTool ``` An executable tool named `web_search` — pass it as `webSearch` to the `chatCompletions()` provider that needs it, and request `web_search` as a provider tool as usual. (It used to return a backend registered with `configureAxle`; both are gone in 0.34.0. See [Upgrading](/upgrading).) ```typescript import { chatCompletions, braveWebSearch } from "@fifthrevision/axle"; const provider = chatCompletions({ baseUrl: "https://api.together.ai/v1", apiKey, webSearch: braveWebSearch({ apiKey: braveKey }), }); ``` ```typescript interface BraveWebSearchOptions { apiKey: string; // required and non-empty endpoint?: string; // default https://api.search.brave.com/res/v1/llm/context maxResults?: number; // default 5, range 1–50 candidateCount?: number; maxTokens?: number; maxSnippets?: number; maxTokensPerUrl?: number; maxSnippetsPerUrl?: number; contextThresholdMode?: string; country?: string; searchLanguage?: string; freshness?: "pd" | "pw" | "pm" | "py" | `${string}to${string}`; timeoutMs?: number; } ``` ```typescript interface WebSearchResult { title: string; url: string; snippets: string[]; } ``` Register it on the provider (above). The process-global `configureAxle` fallback it used to replace was removed in 0.34.0 — see [Upgrading](/upgrading). ### Custom search tools Any search API works — write an `ExecutableTool` named `web_search` whose `execute` returns the results as a string, and pass it as `webSearch`: ```typescript import { chatCompletions, type ExecutableTool } from "@fifthrevision/axle"; import * as z from "zod"; declare const searchIndex: (query: string, signal: AbortSignal) => Promise<{ title: string; url: string; passages: string[] }[]>; const internalSearchSchema = z.object({ query: z.string().trim().min(1).max(400) }); const internalSearch: ExecutableTool = { name: "web_search", description: "Search the internal docs index for current information.", schema: internalSearchSchema, async execute({ query }, { signal }) { const hits = await searchIndex(query, signal); return JSON.stringify({ query, results: hits.map((h) => ({ title: h.title, url: h.url, snippets: h.passages })), }); }, }; const provider = chatCompletions({ baseUrl: "http://localhost:11434/v1", webSearch: internalSearch, }); ``` This is also how you point `web_search` at an internal corpus rather than the public web. Your agent code doesn't change at all — only what "search" means. Do forward `signal`, so a cancelled send doesn't leave a search running. The generated tool takes `{ query: string }` (trimmed, 1–400 characters). The Brave tool returns JSON `{ query, results }` where each result is `{ title, url, snippets }`. --- # Skills Source: https://axle.fifthrevision.com/reference/skills _The Skill type, SkillRegistry, skill loading, and the view-skill tool._ Conceptual guide: [Skills](/concepts/skills). ## Skill ```typescript interface Skill { name: string; description: string; /** The SKILL.md body with its frontmatter stripped. */ instructions: string; /** Opaque base the host's tools accept; printed to the model verbatim. */ root?: string; /** Relative to root, forward slashes, listed not read. */ files?: string[]; /** Remaining frontmatter fields as written. */ frontmatter?: SkillFrontmatter; } interface SkillDefinitionRef { name: string; } type SkillFrontmatter = { license?: string; compatibility?: string; metadata?: Record; "allowed-tools"?: string; } & Record; ``` ## SkillRegistry ```typescript import { SkillRegistry } from "@fifthrevision/axle"; new SkillRegistry(tools: ToolRegistry, skills?: Skill[]) ``` The skills an `Agent` discloses, changeable at any time. Owns the `view-skill` tool: published into the agent's tool registry while at least one skill is present, withdrawn when the last one goes, rebuilt from the current list on every change. | Method | Returns | Notes | | --- | --- | --- | | `add(skill \| skills)` | `void` | Throws `SKILL_REGISTRY_DUPLICATE` on a name already registered, `SKILL_INVALID` on a forbidden name. | | `set(skills)` | `void` | Replaces the whole list atomically: checks every name first, so a throw leaves the old list; republishes once. A name already registered is not an error here. | | `remove(name)` | `boolean` | Republishes when something was removed. | | `has(name)` | `boolean` | | | `get(name)` | `Skill \| undefined` | | | `list()` | `Skill[]` | | | `size` | `number` | | Reachable as `agent.skills`; seeded by `config.skills`. Changes are visible on the next provider request, including the next step of a running turn. ## Loading ```typescript import { loadSkill, parseSkillMarkdown } from "@fifthrevision/axle"; loadSkill(dir: string): Promise parseSkillMarkdown(text: string): Omit ``` `loadSkill` loads a skill from a directory holding `SKILL.md` — the other files under it are listed (dotfiles excluded, bounded in depth and count) but never read. Throws `SKILL_NOT_FOUND` when there is no `SKILL.md`, `SKILL_INVALID` when the frontmatter is missing, empty, or malformed. `parseSkillMarkdown` parses text directly. Every frontmatter scalar is read as text (YAML failsafe schema), so an unquoted `version: 1.0` under `metadata` stays `"1.0"`. ## Catalog and activation ```typescript import { renderSkillsCatalog, createViewSkillTool } from "@fifthrevision/axle"; renderSkillsCatalog(skills: Skill[]): string createViewSkillTool(skills: Skill[]): ExecutableTool ``` `renderSkillsCatalog` is the system-prompt section: a heading, a short instruction to call `view-skill`, one `- name: description` line per skill. Descriptions are escaped (angle brackets neutralised, line breaks collapsed). `createViewSkillTool` is the activation tool: its `name` argument is an enum of the loaded skills, and it returns the skill's instructions wrapped in ``, with `Compatibility:`, the skill directory, and the `Files:` listing when present. `agent.system` is the configured prompt plus this catalog when skills are present, and is read-only. ## Agent wiring | Field | Type | Notes | | --- | --- | --- | | `AgentConfig.skills` | `Skill[]?` | Seeds `agent.skills`. | | `Agent.skills` | `SkillRegistry` | readonly. | --- # MCP Source: https://axle.fifthrevision.com/reference/mcp _The MCP client — configuration, connection lifecycle, and tool discovery._ ```typescript import { MCP } from "@fifthrevision/axle"; new MCP(config: MCPConfig) ``` Conceptual guide: [Tools](/concepts/tools#mcp-servers). ## Configuration ```typescript type MCPConfig = MCPStdioConfig | MCPHttpConfig; interface MCPStdioConfig { transport: "stdio"; name?: string; command: string; args?: string[]; env?: Record; } interface MCPHttpConfig { transport: "http"; name?: string; url: string; headers?: Record; } ``` `http` uses the MCP streamable HTTP transport. ## Properties | Property | Type | Notes | | --- | --- | --- | | `name` | `string \| undefined` | The configured name, falling back to the server's advertised name once connected. | | `connected` | `boolean` | | ## Methods ```typescript connect(options?: { span?: Span; signal?: AbortSignal }): Promise listTools(options?: { prefix?: string; span?: Span; signal?: AbortSignal }): Promise listToolDefinitions(options?: { prefix?: string; span?: Span; signal?: AbortSignal }): Promise refreshTools(): Promise close(options?: { span?: Span }): Promise ``` | Method | Notes | | --- | --- | | `connect()` | No-op when already connected. Failures propagate. | | `listTools()` | Throws if not connected. Results are cached after the first call. `prefix` namespaces every tool name. | | `listToolDefinitions()` | Same, returning schema-only definitions. | | `refreshTools()` | Clears the cache and re-lists. Use when a server's tools change at runtime. | | `close()` | No-op when not connected. Clears the client, transport, and cache. | Calling `listTools()` before `connect()` throws `Error("MCP not connected. Call connect() first.")` — the most common mistake here. ## Use with Agent ```typescript const fs = new MCP({ transport: "stdio", name: "fs", command: "npx", args: ["-y", "@modelcontextprotocol/server-filesystem", "/tmp"], }); await fs.connect(); const agent = new Agent({ provider, model, mcps: [fs] }); // or later: agent.addMcp(fs); agent.addMcps([fs, other]); ``` The agent resolves each client's tools **lazily**, on the first send after registration, and only once per client instance. It passes the client's `name` as the tool prefix and registers the results as MCP tools in the registry. The agent will **not** connect for you, so connect before the first send. MCP tools are validated like any other tool: call arguments are parsed with the converted schema before they reach the server, and unknown top-level keys are stripped — matching a default `z.object()` — rather than rejected. The schema advertised to the provider carries `additionalProperties: false`, as vendors like OpenAI require. Tool names mustn't collide with local or provider tools, or you'll get `TOOL_REGISTRY_DUPLICATE`. Giving each client a distinct `name` is what keeps two servers' identically-named tools apart. ## Serializable configuration `MCPConfig` is serializable, so it can live in your own saved recipe shape alongside the session (core carries no `AgentDefinition` since 0.35.0). Construct `MCP` instances from your recipe's `mcps` when rebuilding the `AgentConfig` — though those instances still need connecting. --- # Transcript & turn events Source: https://axle.fifthrevision.com/reference/transcript _The Transcript class, the Turn/TurnPart shapes, and the full TurnEvent union._ Conceptual guide: [Turns & Transcripts](/concepts/transcripts). Everything on this page is also exported from `@fifthrevision/axle/ui` — the types, and `Transcript` itself — which doesn't pull in the provider SDKs. Use that import in UI code. ## Transcript ```typescript class Transcript { constructor(turns?: readonly Turn[], pending?: readonly Turn[]); get turns(): readonly Turn[]; get pending(): readonly Turn[]; getTurn(turnId: string): Turn | undefined; apply(event: TranscriptInput): TranscriptApplyResult; } ``` The constructor shallow-copies the arrays. `turns` is readonly; all structural change goes through `apply()`. The second constructor argument seeds `pending` to mirror a live transcript for a client that receives the server's `turns`, `pending`, and stream position in one read — it discards any entry whose id is already in `turns`. This changes nothing about what is saved: persist `turns` only. ```typescript type TranscriptApplyResult = | { handled: true; event: TurnEvent } | { handled: false; event: THostEvent }; ``` `UnknownEvent` and `TimingInfo` are exported from `@fifthrevision/axle/ui` only, not from the package root. Unrecognized event types pass through with `handled: false`, so a single dispatcher can carry both Axle events and your own. ## Turn ```typescript interface Turn { id: string; owner: "user" | "agent"; parts: TurnPart[]; status: TurnStatus; annotations?: TAnnotation[]; metadata?: Record; threadId?: string; // on a user turn sent inline by a continuation — the send's id, rooting the thread cursor?: string; // where this turn closed on a served event stream, when folded from events carrying one timing?: TimingInfo; usage?: Stats; failure?: TurnFailure; error?: TurnError; cancelReason?: TimeoutReason; reason?: "stop" | "length"; } type TurnStatus = "pending" | "streaming" | "complete" | "cancelled" | "error"; interface TimingInfo { start: string; end?: string } // ISO timestamps type TurnFailure = | { kind: "api"; type: string; message: string; status?: number } | { kind: "incomplete"; type: string; message: string } | { kind: "refusal"; message: string; text?: string; category?: string } | { kind: "parse"; message: string }; ``` ```typescript // A thrown error that ended the turn `error`, instead of a failure. interface TurnError { message: string; code?: AxleErrorCode; // only when Axle threw the error } // Why a `cancelled` turn was cancelled. Present only when `turnTimeoutMs` // did it (`{ type: "timeout", limitMs }`); absent on a caller cancel. type TimeoutReason = { type: "timeout"; limitMs: number }; ``` A `pending` turn is a preview of a turn the Agent accepted but hasn't opened — the user turn a queued `send()` will commit, or an agent turn with one `pending` compaction part for a queued manual compaction. It carries the id the real turn will have, and leaves `pending` when that turn opens or when the operation is dropped. See [Pending lifecycle](#pending-lifecycle). ## TurnPart ```typescript type TurnPart = | TextPart | CitationPart | FilePart | ThinkingPart | ActionPart | CompactionPart; ``` Every part has `id`, `type`, optional `annotations`, and optional `timing`. | Part | Additional fields | | --- | --- | | `TextPart` | `text: string`, `citations?: Citation[]`, `providerMetadata?` | | `CitationPart` | `citations: Citation[]`, `providerMetadata?` | | `FilePart` | `file: FileInfo` | | `ThinkingPart` | `summary?`, `raw?`, `continuity?`, `providerMetadata?` | | `CompactionPart` | `trigger: "manual" \| "beforeTurn" \| "afterTurn"`, `status: "pending" \| "running" \| "complete" \| "cancelled" \| "error"`, `summary?`, `progress?`, `error?` | ### ThinkingPart ```typescript interface ThinkingPart { id: string; type: "thinking"; summary?: string; // the provider's condensed account of its reasoning raw?: string; // the chain of thought itself; open-weight models only continuity?: ThinkingContinuity; providerMetadata?: Record; } ``` Each content field is named for what the provider handed back; neither present is the withheld state. Render `summary ?? raw`. A field appears only once a delta wrote it, so never test for `""`. (`text` / `redacted` on the turn part were removed in 0.32.0 — `redacted` now lives only on the message layer; see [Messages & parts](/reference/messages) and [Upgrading](/upgrading).) ### ActionPart ```typescript type ActionPart = ToolAction | SubagentAction | ProviderToolAction; ``` All share `status: "pending" | "running" | "complete" | "cancelled" | "error"` and discriminate on `kind`. | `kind` | `detail` | | --- | --- | | `"tool"` | `{ name, parameters, pendingArgs?, result? }` | | `"agent"` | `{ name, config?, children: Turn[], result? }` | | `"provider-tool"` | `{ name, input?, result? }` | | `"deferred"` | `{ name, callId, input, pendingArgs?, result? }` — a call answered through `onToolCall`; never `running` | ```typescript type ActionResult = | { type: "in-progress"; content: string } | { type: "success"; content?: string | ConsoleOutput | ToolResultPart[] } | { type: "error"; error: { type: string; message: string } }; interface ConsoleOutput { stdout: string; stderr?: string; exitCode?: number; } ``` `ConsoleOutput` (added in 0.33.0) arrives only from provider code execution that separates its streams (Anthropic today); OpenAI and Gemini report one stream, so their output arrives as a string. A renderer that narrows `content` with `typeof content === "string"` and treats the rest as parts must add the object case. Local tools still return strings or parts. `pendingArgs` holds accumulated argument JSON before it can be parsed into `parameters`. Render it during streaming so there's something on screen. ```typescript interface DeferredAction { id: string; type: "action"; kind: "deferred"; status: "pending" | "waiting" | "complete" | "cancelled" | "error"; detail: { name: string; callId: string; // the tool call id — what the handler's DeferredCall carries as id input: Record; // the validated input once the call is waiting; empty before pendingArgs?: string; result?: ActionResult; }; } ``` A deferred call never runs, so it is never `running`: `pending` while its arguments stream, `waiting` from `action:waiting` until the answer, timeout, or cancellation settles it. `isActionOf(tool, part)` narrows a part to one deferred tool's action with its input typed (a `pending` part carries no input yet and is excluded). `SubagentAction.detail.children` is a nested `Turn[]`, so subagent rendering is recursive. ### Annotations ```typescript interface Annotation { id: string; kind: TKind; label: string; placement?: "before" | "after"; // defaults to "after" when accumulated status?: "running" | "complete" | "cancelled" | "error"; data?: TData; timing?: TimingInfo; } ``` Your own UI state, attached to a turn or a part and never sent to a provider. Omit `status` for static annotations that have no lifecycle. ## TurnEvent `agent.on` delivers `AgentEvent` — every `TurnEvent` below, plus the operation lifecycle framing it. `Transcript.apply` reports the lifecycle events handled and folds nothing from them, so `agent.on(transcript.apply)` is unchanged. Events folded from a served stream may carry a `cursor` beside their fields; `apply` records it on the turn that `turn:user` or `turn:end` closes. ### Operation lifecycle | Event | Fields | | --- | --- | | `operation:start` | `id`, `kind` (`"send"` \| `"compaction"`) | | `after:start` | `id` | | `after:end` | `id` | | `operation:end` | `id`, `outcome` (`{ type: "complete" }` \| `{ type: "cancelled", reason? }` \| `{ type: "error", error: { message } }`) | | `agent:idle` | — | ### Pending lifecycle | Event | Fields | | --- | --- | | `pending:queued` | `turn` — the preview turn (`status: "pending"`, the id the real turn will carry) | | `pending:dropped` | `id`, `reason: PendingDropReason` — the operation ended before opening its turn | ```typescript type PendingDropReason = | { type: "cancelled" } | { type: "error"; error: { type: string; message: string } }; ``` A queued handle cancelled (`handle.cancel()`, `agent.clear()`, an already-aborted signal) drops as `cancelled`; a setup failure (an `onStart` refusal, say) drops as `error`. Nothing is committed in either case. A `switch` over `event.type` with an exhaustiveness check must handle both; a renderer that reads `turns` alone can ignore them. `apply()` folds `pending:queued` into `pending`, removes the entry on `pending:dropped`, on the matching `turn:user`, and on the matching `turn:start` — so `[...turns, ...pending]` renders with one component keyed by id. ### Turn lifecycle | Event | Fields | | --- | --- | | `turn:user` | `turn` — the complete user turn | | `turn:start` | `turnId`, `timing?` | | `turn:end` | `turnId`, `status`, `usage`, `failure?`, `error?`, `cancelReason?`, `reason?`, `timing?` | `failure` is a `TurnFailure` (the provider's answer that ended the turn `ok: false`, without `usage`/`raw`/`cause`); `reason` is `"stop"` or `"length"` when the turn ended with a final answer. `error` is a `TurnError` (a thrown error the send rejected with, not a provider answer — a turn carries `failure` or `error`, never both); `cancelReason` is present only when `turnTimeoutMs` cancelled the turn. The old `error` event is gone — match `turn:end`'s `failure` instead. ### Part streaming | Event | Fields | | --- | --- | | `part:start` | `turnId`, `part` — the whole part object | | `text:delta` | `turnId`, `partId`, `delta` | | `text:citation` | `turnId`, `partId`, `citation` | | `thinking:raw-delta` | `turnId`, `partId`, `delta` | | `thinking:summary-delta` | `turnId`, `partId`, `delta` | | `thinking:update` | `turnId`, `partId`, `continuity?`, `providerMetadata?` | | `part:end` | `turnId`, `partId`, `timing?` | Openings carry the full part; deltas carry only ids and the delta. ### Actions | Event | Fields | | --- | --- | | `action:args-delta` | `turnId`, `partId`, `delta`, `accumulated` | | `action:running` | `turnId`, `partId`, `parameters?` — never fires for deferred calls | | `action:waiting` | `turnId`, `partId`, `callId`, `name`, `input` — the validated deferred call, handed to `onToolCall` | | `action:input` | `turnId`, `partId`, `input` — what the provider tool was asked to do (added in 0.33.0) | | `action:progress` | `turnId`, `partId`, `chunk` | | `action:complete` | `turnId`, `partId`, `result`, `timing?` | | `action:cancelled` | `turnId`, `partId`, `timing?` — the call never ran or was interrupted; `status: "cancelled"`, no `result` | | `action:error` | `turnId`, `partId`, `error`, `timing?` | | `action:child-event` | `turnId`, `partId`, `event` — a nested `TurnEvent` | ### Compaction | Event | Fields | | --- | --- | | `compaction:update` | `turnId`, `partId`, `update: { summary?; progress? }` | | `compaction:complete` | `turnId`, `partId`, `summary?`, `timing?` | | `compaction:cancelled` | `turnId`, `partId`, `timing?` — stopped by a cancel; `status: "cancelled"`, no `error` | | `compaction:error` | `turnId`, `partId`, `error`, `timing?` — the compactor failed | The part itself arrives through `part:start` with `status: "running"`. `compaction:complete` sets `progress: 1`. ### Annotations | Event | Fields | | --- | --- | | `annotation:start` | `target`, `annotation` | | `annotation:update` | `target`, `annotation` | | `annotation:end` | `target`, `annotation` | ```typescript type AnnotationTarget = | { type: "turn"; turnId: string } | { type: "part"; turnId: string; partId: string }; ``` ## TurnEventBuilder ```typescript import { TurnEventBuilder } from "@fifthrevision/axle"; ``` Converts `StreamEvent`s into `TurnEvent`s — the same translation `Agent` does internally. You'd only need this if you're driving `stream()` directly but still want render-layer events. ## renderTerminalMarkdown ```typescript renderTerminalMarkdown(text: string): string; ``` Markdown in, ANSI-styled terminal text out. Exported from `@fifthrevision/axle/ui` only — it's what a terminal renderer needs for a turn's text parts, and it's the same rendering `SimpleWriter`'s [`markdown` option](/reference/observability#simplewriter) applies to event messages. --- # Remote agents Source: https://axle.fifthrevision.com/reference/remote _RemoteAgent, its transports, the served side's event store, and the wire types._ **Experimental** Remote agents are under active design and may change in any release. **guide: [Remote agents](/concepts/remote-agents).** ## RemoteAgent ```typescript import { RemoteAgent, type AgentTransport } from "@fifthrevision/axle"; declare const transport: AgentTransport; const client = new RemoteAgent(transport); ``` Drives an agent served elsewhere. Holds no transcript — it folds each turn only long enough to hand back `turn` and `response` on the send's result, as `Agent` does. | Member | Type | Notes | | --- | --- | --- | | `on(callback)` | `(event: StoredEvent) => void` → unsubscribe | Every event on the served side's stream, in order: the agent's events and the host's, each with its cursor. | | `onConnection(callback)` | `(connection: RemoteConnection) => void` → unsubscribe | The link's state. | | `onToolCall(handler)` | `ToolCallCallback` → unsubscribe | Answers the served agent's deferred calls from here. Receives the call and no `ToolContext`: no `emit`, no `signal`. | | `toolCall(id)` | `(id: string) => RemoteWaitingToolCall \| undefined` | The deferred call this consumer has seen waiting and not yet seen settle. | | `send(message, options?)` / `send(instruct, options?)` | → `RemoteHandle` | Like `Agent.send`, minus `after`: the `Instruct` crosses as data (`InstructData`) and the served side renders it; the schema still parses `response`. A 0.36 client and a 0.37 host do not interoperate — deploy both sides together. Returns `{ final }` only — no `cancel`, since a queued remote send cannot be cancelled by id. `final` settles when the served operation ends, after its continuation and `onSettled`: `complete` resolves with the result, `cancelled` rejects with `AxleAgentAbortError`, `error` rejects with an `AxleError` carrying the message. | | `cancel()` / `stop()` / `clear()` | `() => Promise` | The `Agent` meanings — the active turn now, the active turn at its batch boundary, the queue — each posted as one command. | | `close()` | `() => void` | Stops listening. Open sends reject; the served agent is untouched. | | `connection` | `RemoteConnection` | `connecting` until the stream opens, `open` while it runs, then `ended` or `error`. | | `status` | `AgentStatus` | The served agent's status: the stream's opening status, then moved by `operation:start` (busy with its id) and `agent:idle` — already updated when `on` delivers the event that moved it. `idle` until the stream opens. | ```typescript type RemoteConnection = | { phase: "connecting" } | { phase: "open" } | { phase: "ended" } | { phase: "error"; error: Error }; ``` ```typescript interface RemoteSendOptions { id?: string; // the user turn's id, as SendMessageOptions.id — generated when omitted metadata?: MessageMetadata; } interface RemoteHandle { readonly final: Promise | AgentErrorResult>; } interface RemoteWaitingToolCall { answer(content: string | ToolResultPart[]): Promise; fail(message: string): Promise; } ``` Two gaps against `Agent`, both from what cannot cross: a remote result carries no `after` list, and an `error` outcome crosses as its message. A remote `onToolCall` handler's signal is not the served run's — cancellation is visible from the events. ## Transports ```typescript import { httpTransport, loopbackTransport } from "@fifthrevision/axle"; ``` `httpTransport` speaks to one URL: `GET` opens the event stream as Server-Sent Events, `POST` sends a command as JSON and reads the outcome back. A dropped stream reopens with `Last-Event-ID` set to the last cursor delivered; reconnecting retries a network failure or a `5xx` after `reconnectDelayMs`, doubling to `maxReconnectDelayMs`, with no cap on attempts. A `404` or `410` ends the agent — there is no agent at that URL, and every open `final` rejects. Any other failed response fails the connection. The first connection does not retry. `loopbackTransport` is the same contract with no wire: the store's events straight out, each command straight to the handler. For tests, and for a hop that serves an agent in its own process. ```typescript function httpTransport( url: string | URL, options?: HttpTransportOptions, ): AgentTransport; interface HttpTransportOptions { after?: string; // cursor to resume from on the first connection, e.g. a stored Turn.cursor headers?: HeadersInit | (() => HeadersInit | Promise); // sent with every request reconnectDelayMs?: number; // default 1000 — wait before the first reconnect maxReconnectDelayMs?: number; // default 30000 — ceiling on the doubling wait fetch?: typeof fetch; } class HttpTransportError extends Error { readonly status: number; } function loopbackTransport( store: InMemoryEventStore, handle: (command: AgentCommand) => Promise, ): AgentTransport; ``` ## The served side ```typescript import { InMemoryEventStore, toEventStreamResponse, parseAgentCommand } from "@fifthrevision/axle"; ``` `InMemoryEventStore` keeps one served agent's events — every agent event, and every host event given to `push` — stamped with a cursor `-` in the order it happened. It keeps the agent's status too, folded from its own log. `subscribe(signal, after?)` opens with that status, replays what the consumer has not seen (every event when the store does not own the cursor), and continues live. `close()` stops listening to the agent and ends every open subscription once it has delivered what it holds; a later `subscribe` replays and ends, and a later `push` is dropped. ```typescript class InMemoryEventStore { constructor(agent: Agent | RemoteAgent); // any served agent — a hop consumes upstream and serves downstream get lastCursor(): string; // cursor of the last event; "-0" before the first owns(cursor: string | null | undefined): boolean; // whether a cursor names a position in this store push(event: THostEvent): void; // a host event, stamped in sequence with the agent's subscribe(signal: AbortSignal, after?: string | null): AgentSubscription; close(): void; } ``` `toEventStreamResponse(subscription, request?)` answers an HTTP request with a subscription as Server-Sent Events: the welcome first as `event: welcome` with no `id`, then each event as JSON in `data:` with its cursor in `id:`. Ends the items when the request aborts or the body is cancelled. `parseAgentCommand(body)` reads a `POST` body against the spec and returns the typed command, or `null` for anything it does not describe. ```typescript function toEventStreamResponse( subscription: AgentSubscription, request?: Request, ): Response; function parseAgentCommand(body: unknown): AgentCommand | null; ``` ## Wire types ```typescript type AgentCommand = | { type: "send"; id: string; instruct: InstructData } | { type: "answer"; callId: string; content: string | ToolResultPart[] } | { type: "fail"; callId: string; message: string } | { type: "cancel" } | { type: "stop" } | { type: "clear" }; type CommandOutcome = | { accepted: true } | { accepted: false; reason: { type: "not-waiting" | "idle"; message: string } }; ``` ```typescript type StoredEvent = (TurnEvent | THostEvent) & { cursor: string; }; interface AgentWelcome { type: "welcome"; status: AgentStatus; // the served agent's status as the stream opened } type StreamItem = StoredEvent | AgentWelcome; interface AgentSubscription { welcome: AgentWelcome; items: AsyncIterable>; } interface AgentTransport { events(signal: AbortSignal): Promise | undefined>; command(command: AgentCommand, signal?: AbortSignal): Promise; } ``` The cursor's format is the store's — transports and `Turn.cursor` treat it as an opaque string. A `StreamItem` narrows to its welcome on `item.type === "welcome"`; the shipped transports do that for you, so only a transport of your own needs it. --- # Messages & parts Source: https://axle.fifthrevision.com/reference/messages _The wire format — AxleMessage, content parts, files, and citations._ The model-facing conversation format. You'll need these types when you're reading `agent.messages`, writing a [compactor](/concepts/compaction), or calling [`generate()` / `stream()`](/reference/generate-stream) directly. Otherwise you can happily ignore them. Conceptual guide: [Anatomy of a send](/concepts/anatomy-of-a-send#message-the-wire-lens). ## AxleMessage ```typescript type AxleMessage = AxleUserMessage | AxleAssistantMessage | AxleToolCallMessage; ``` ```typescript interface AxleUserMessage { role: "user"; id?: string; name?: string; content: string | ContentPart[]; metadata?: MessageMetadata; threadId?: string; // on a message sent inline by a continuation — the send's id, rooting the thread } interface AxleAssistantMessage { role: "assistant"; id: string; model?: string; content: Array< ContentPartText | ContentPartThinking | ContentPartToolCall | ContentPartProviderTool | ContentPartProviderToolResult | ContentPartCitation >; finishReason?: AxleStopReason; } interface AxleToolCallMessage { role: "tool"; id: string; content: AxleToolCallResult[]; } interface AxleToolCallResult { id: string; // the tool call id this answers name: string; content: string | ToolResultPart[]; isError?: boolean; } ``` `MessageMetadata` is `Record`. Providers ignore it; it exists so hosts can carry presentation hints through history and into turns. ## Content parts ```typescript type ContentPart = | ContentPartText | ContentPartFile | ContentPartToolCall | ContentPartThinking | ContentPartProviderTool | ContentPartProviderToolResult | ContentPartCitation; ``` | Part | Fields | | --- | --- | | `ContentPartText` | `type: "text"`, `text`, `citations?`, `providerMetadata?` | | `ContentPartFile` | `type: "file"`, `file: FileInfo` | | `ContentPartThinking` | `type: "thinking"`, `id?`, `text?`, `summary?`, `redacted?`, `continuity?`, `providerMetadata?` | | `ContentPartToolCall` | `type: "tool-call"`, `id`, `name`, `parameters`, `providerMetadata?` | | `ContentPartProviderTool` | `type: "provider-tool"`, `id`, `name`, `input?`, `result?`, `continuity?` | | `ContentPartProviderToolResult` | `type: "provider-tool-result"`, `id`, `name`, `result`, `continuity?` | | `ContentPartCitation` | `type: "citation"`, `citations`, `providerMetadata?` | ### ProviderTool parts ```typescript type ProviderToolInput = | { type: "search"; queries: string[] } | { type: "open"; url: string } | { type: "find"; url: string; pattern: string } | { type: "code"; code: string } | { type: "command"; command: string }; type ProviderToolResult = | { type: "success"; output?: string | ConsoleOutput } | { type: "error"; error: { type: string; message: string } }; interface ConsoleOutput { stdout: string; stderr?: string; exitCode?: number; } ``` `name` is Axle's portable name (`"web_search"`, `"web_fetch"`, `"code_execution"`, `"file_search"`). `input` says what the tool was asked to do and is absent for tools Axle has no shape for; `result` is absent while the tool has not run in that message. A successful code execution carries what it printed as `output` — a string when the provider returns one stream (OpenAI, Gemini), `{ stdout, stderr?, exitCode? }` when it separates them (Anthropic). `continuity` is the provider's own objects, sent back only to the provider that made them — a part with another provider's `continuity`, or none, is left out of the request. `ContentPartProviderToolResult` holds the result of a provider tool call an earlier assistant message made. Only Anthropic produces it, when Claude calls an Anthropic-run tool and one of your tools in the same response. Code that switches exhaustively over assistant content parts needs a case for it. ### ThinkingContinuity ```typescript type ThinkingContinuity = | { provider: "openai"; encrypted: string } | { provider: "anthropic"; signature?: string; redactedData?: string } | { provider: "gemini"; thoughtSignature: string } | { provider: "openrouter"; type: string; id?: string; format?: string; index?: number; signature?: string; data?: string; }; ``` Opaque provider state that lets a model continue reasoning across requests. Preserve it verbatim through storage and restoration — strip it and multi-turn reasoning breaks. The `openrouter` member carries the `reasoning_details` entry's identity so Claude through OpenRouter keeps its signatures across tool calls. On Anthropic the field itself is absent until a signature or redacted data has arrived, so a thinking part with no `continuity` yet is normal — not a stripped one. `ContentPartThinking` keeps the wire vocabulary — `text`, `summary`, `redacted` — because it exists to be echoed back to the provider's next request, not read. `redacted` means only that the provider substituted an opaque payload (Anthropic `redacted_thinking`, OpenRouter `reasoning.encrypted`); a hidden block is never marked redacted. Read the [turn part](/reference/transcript#thinkingpart), echo the message part. ## Files ```typescript type FileKind = "image" | "document" | "text"; type FileInfo = TextFileInfo | BinaryFileInfo; type TextFileInfo = { kind: "text"; mimeType: string; name: string; size?: number; source: { type: "text"; content: string } | { type: "url"; url: string } | { type: "ref"; ref: unknown }; }; type BinaryFileInfo = { kind: "image" | "document"; mimeType: string; name: string; size?: number; source: { type: "base64"; data: string } | { type: "url"; url: string } | { type: "ref"; ref: unknown }; }; ``` ### loadFileContent() ```typescript loadFileContent(filePath: string): Promise loadFileContent(filePath: string, encoding: "utf-8"): Promise loadFileContent(filePath: string, encoding: "base64"): Promise ``` Encoding defaults to `utf-8` for text files and `base64` for everything else. Throws on a missing file, on files over 20 MiB, and when reading a non-text file as text. ### Deferred references A `{ type: "ref" }` source is host-owned and resolved only when a provider request needs it — useful for expiring URLs and access-controlled content, which should not be persisted in history. ```typescript type FileResolver = (request: FileResolveRequest) => Promise; interface FileResolveRequest { file: DeferredFileInfo; ref: unknown; protocol: Protocol; // "messages" | "responses" | "generateContent" | "chatCompletions" model: string; accepted: FileResolveFormat[]; // "base64" | "url" | "text" | "gemini-file-uri" signal?: AbortSignal; } type ResolvedFileSource = | { type: "base64"; data: string; mimeType?: string; name?: string } | { type: "url"; url: string; mimeType?: string; name?: string } | { type: "text"; content: string; mimeType?: string; name?: string } | { type: "gemini-file-uri"; uri: string; mimeType?: string; name?: string }; ``` Return a source whose `type` appears in `accepted`, or Axle throws. `mimeType` and `name` fall back to the file's own values if you omit them. A deferred file with no resolver configured throws `No fileResolver configured for deferred file: `. Set a resolver on `AgentConfig`, per send in `SendMessageOptions`, or on `GenerateParams` / `StreamParams`. ## Citations ```typescript interface Citation { source: CitationSource; outputSpan?: { start?: number; end?: number }; providerMetadata?: Record; } type CitationSource = | { type: "web"; title?: string; url: string; citedText?: string } | { type: "document"; title?: string; fileId?: string; citedText?: string; locator?: DocumentLocator } | { type: "search-result"; title?: string; url?: string; citedText?: string; locator?: DocumentLocator } | { type: "retrieved-context"; title?: string; uri?: string; citedText?: string; locator?: DocumentLocator } | { type: "unknown"; citedText?: string }; type DocumentLocator = | { type: "char"; start?: number; end?: number } | { type: "page"; start?: number; end?: number } | { type: "block"; start?: number; end?: number } | { type: "part"; index?: number }; ``` `outputSpan` gives you offsets into the generated text — that's how you underline the cited span in a UI. Text-anchored citations live on `ContentPartText.citations`; provider-emitted source lists arrive as their own `ContentPartCitation`. Axle doesn't ask providers for document citations: since 0.36.1, documents sent to Anthropic carry no `citations` request field, so answers about PDFs and text files arrive as plain text parts. The `document` source shape below still matters — conversations stored by earlier versions can hold answers with document citations, which stay on the stored messages but are left out of Anthropic requests (replaying them would be a 400). Citations from hosted web search are unaffected. ## Usage ```typescript interface TokenStats { in: number; // effective input; includes cachedIn and cacheWriteIn out: number; // includes reasoningOut cachedIn?: number; cacheWriteIn?: number; reasoningOut?: number; } interface UsageEntry extends TokenStats { provider: string; model: string; } interface Stats extends TokenStats { breakdown: UsageEntry[]; // @experimental — one row per request } ``` `breakdown` entries **explain** the aggregate rather than adding to it, so don't sum them on top. Helpers: `createStats()`, `addStats(total, usage?)`, `mergeStats(...)`, `attributeStats(tokens, source)`, and `computeCost(usage, catalog)`. `breakdown` rows carry `provider`, `model`, `requestedModel`, `agent?`, and `at`. ## Compaction helpers ```typescript getCompactionStamp(message: AxleMessage): CompactionStamp | undefined validateCompactedMessages(messages: AxleMessage[]): void interface CompactionStamp { id: string; role: "summary" | "appendix"; } ``` The stamp lives under `metadata.axleCompaction`, on **user** messages only. The engine never reads it — it's purely a compactor-side convention for recognizing your own prior output. See [Compaction](/concepts/compaction#recognizing-your-own-output). `validateCompactedMessages` throws `AxleError` with code `COMPACTION_INVALID_MESSAGES` when tool calls and results are not correctly paired and adjacent. --- # Errors Source: https://axle.fifthrevision.com/reference/errors _The error classes, their codes, and the failure union._ Conceptual guide: [Results & errors](/concepts/results-and-errors). Quick orientation: failures you should expect resolve as `{ ok: false }`. Everything documented on this page throws instead — except the failure union itself, which is what `ok: false` carries. ## AxleProviderFailure The resolved-failure union carried in `result.error`. ```typescript type AxleProviderFailure = | { kind: "api"; type: string; message: string; status?: number; usage?: Stats; raw?: unknown } | { kind: "incomplete"; type: string; message: string; usage?: Stats; raw?: unknown } | { kind: "refusal"; message: string; text?: string; category?: string } | { kind: "parse"; message: string; cause: unknown }; ``` `message` is always present, whatever the kind. (`AxleFailure` and `GenerateError` were removed in 0.35.0 — import `AxleProviderFailure`.) An `api` failure is a request that didn't complete — rejected, failed mid-way, connection broke. It carries what `model` carried before 0.35.0: `type`, `message`, `status?`, `usage?`, `raw?`. `type` is `"authentication"` when the provider rejected the API key or token (HTTP 401 on Anthropic, OpenAI, and Chat Completions, or Gemini's `API_KEY_INVALID`); every other failure keeps the provider's own error type. `status` is the HTTP status when the failure was an HTTP response, and absent for transport or mid-stream errors. A Chat Completions non-2xx JSON body in the OpenAI shape reports the body's `error.type` (else `error.code`) as `type` and `error.message` as `message` — match on `status`, not on `type === "404"`. An `incomplete` failure is a request that completed but stopped for a reason that isn't a usable end. `type` is the stop reason verbatim, or one of `FinishReasonError`, `IncompleteStream`, `RESPONSES_API_INCOMPLETE`. `usage` is present — the call was charged. (Gemini's `LANGUAGE` finish reason maps to a `refusal`, not here.) A `refusal` means the provider declined the request or blocked its output (added in 0.33.0). `text` is the refusal text or explanation when the provider gave one; `category` is the provider's own name for the reason. Either can be absent. The refused step is not stored and `step:complete` does not fire. A `parse` failure carries the schema error as `cause` (renamed from `error` in 0.33.0). ```typescript // @check-skip — shows the pre-0.35 shape type AxleFailure = | { kind: "model"; type: string; message: string; status?: number } | { kind: "refusal"; message: string } | { kind: "parse"; message: string; cause: unknown }; ``` ## AxleError Base class for everything Axle throws. ```typescript class AxleError extends Error { readonly code: AxleErrorCode; readonly id?: string; readonly details?: Record; toJSON(): object; } new AxleError(message: string, options?: { code?: AxleErrorCode; id?: string; details?: Record; cause?: unknown; }) import { AxleErrorCode, isAxleError } from "@fifthrevision/axle"; try { await agent.send("...").final; } catch (error) { if (!isAxleError(error)) throw error; switch (error.code) { case AxleErrorCode.ABORTED: break; case AxleErrorCode.TOOL_FATAL_ERROR: break; case AxleErrorCode.PROVIDER_UNSUPPORTED: break; } } ``` `code` is `AxleErrorCode`, a union of string literals. `details` is `Record`. The payload classes (`AxleAbortError`, `AxleToolFatalError`, `AxleInstructVariableError`) declare their `code` as a literal so a `switch` on `error.code` narrows to the class. `isAxleError` tests for an `Error` carrying an `AxleErrorCode`, not `instanceof` — so it holds when a host has two copies of the package. Prefer it over `instanceof AxleError`. `toJSON()` serializes name, message, code, id, details, and the whole `cause` chain, so it's safe to log directly. ### Codes | Code | Thrown when | | --- | --- | | `INVALID_OPTIONS` | A loop limit below 1; a non-integer `maxRetries` or `timeoutMs`; a bad model id; an unsupported reasoning setting; a tool choice naming an absent tool; a tool schema Zod cannot express as JSON Schema; a Brave option out of range | | `PROVIDER_UNSUPPORTED` | A feature this provider has no wire shape for: a non-PDF document, an unsupported image type, a content source with no block type, Gemini `parallelToolCalls: false` or provider tool choice, a Chat Completions provider tool with nothing to serve it, a PDF on Together AI. `details: { protocol, feature }` names the `protocol` | | `FILE_UNREADABLE` | A host file that could not be resolved: not found, too large, unsupported type, wrong category, no `fileResolver`. `details: { path?, name? }` | | `MCP_NOT_CONNECTED` | An MCP tool called before `connect()` | | `TOOL_REGISTRY_DUPLICATE` | A tool name is already registered | | `SKILL_REGISTRY_DUPLICATE` | A skill name is already registered, or listed twice in `set()` | | `SKILL_INVALID` | A `SKILL.md` has no frontmatter block, a missing or empty `name`/`description`, invalid YAML, a mistyped optional field, or a name containing `<`, `>`, `"`, or a line break | | `SKILL_NOT_FOUND` | `loadSkill(dir)` found no `SKILL.md` in the directory | | `INSTRUCT_VARIABLE_ERROR` | On `AxleInstructVariableError` | | `COMPACTION_INVALID_MESSAGES` | A compactor returned malformed messages | | `COMPACTION_GENERATION_FAILED` | Compaction generation failed | | `COMPACTION_EMPTY_SUMMARY` | A compactor returned an empty summary | | `DECISION_REQUEST_FAILED` | A decision provider request failed with a non-2xx status | | `DECISION_RESPONSE_INVALID` | A decision provider returned a body Axle could not read | | `DECISION_ANSWER_MISMATCH` | `decide()` got a missing or mistyped answer for a question | | `TOOL_FATAL_ERROR` | On `AxleToolFatalError` | | `ABORTED` | On `AxleAbortError` | | `AXLE_ERROR` | Default for `new AxleError(message)` | (`TOOL_OPTIONS_CONFLICT` and `WEB_SEARCH_FALLBACK_NOT_CONFIGURED` were removed in 0.34.0 with `StreamParams.registry` and `configureAxle`. `TASK_ERROR` is gone in 0.35.0 with `TaskError`. See [Upgrading](/upgrading).) `decide()` throws its `DECISION_*` failures instead of resolving them — there is no partial state to hand back, so there is no `ok` flag. See [Decisions](/concepts/decisions). A `chatCompletions()` request that times out fails as an `api` failure with `type: "TimeoutError"` and message `"Request timed out after ms"` (changed from `AbortError` / `"Request aborted"` in 0.34.0). Match on `TimeoutError` to detect it; aborting through your own signal still reports `AbortError`. ## AxleAbortError ```typescript class AxleAbortError extends AxleError { readonly reason: unknown; readonly messages?: AxleMessage[]; readonly partial?: AxleAssistantMessage; readonly usage?: Stats; } ``` Note that `name` is `"AbortError"` rather than `"AxleAbortError"`, so the conventional `error.name === "AbortError"` check works as you'd expect. Carries `reason`, `usage`, and partial output — `code` is `"ABORTED"`. Thrown by a cancelled `stream()` handle. It holds on to whatever was produced before the abort — including the tool results message when the abort landed mid-tool-batch (each unfinished call reads `cancelled`), so `messages` ends in the `tool` message and the history stays sendable. ## AxleAgentAbortError ```typescript class AxleAgentAbortError extends AxleAbortError { readonly turn?: Turn; } ``` Thrown by a cancelled `Agent` handle and by every handle dropped by `agent.clear()`. Adds the cancelled turn. Also `name === "AbortError"`. When the cancel landed mid-tool-batch, `messages` (and `agent.messages`) end in the committed tool results message rather than in unanswered calls, so a follow-up send is accepted. When it landed while the model was still writing its response, the partial keeps only written parts and is `undefined` when nothing was written (no assistant message is added). ## AxleToolFatalError ```typescript class AxleToolFatalError extends AxleError { readonly toolName?: string; readonly messages?: AxleMessage[]; readonly partial?: AxleAssistantMessage; readonly usage?: Stats; } new AxleToolFatalError(message?: string, options?: { toolName?: string; messages?: AxleMessage[]; partial?: AxleAssistantMessage; usage?: Stats; cause?: unknown; }) ``` Throw this from `execute` when you want to terminate the run. An ordinary `Error` becomes a tool error result handed back to the model instead, which is usually what you want. `code` is `"TOOL_FATAL_ERROR"`. The batch's other calls are aborted and answered as `cancelled`, the fatal call itself is answered as `fatal`, and the tool results message commits before the error is thrown — so `messages` ends in the `tool` message and the conversation stays sendable. Subagent fatal errors are rebuilt without the child's `messages`/`partial` before reaching the parent, with the original as `cause`. ## AxleInstructVariableError ```typescript class AxleInstructVariableError extends AxleError { readonly missingVariables: string[]; } ``` (`AxleInstructVariableError` was renamed in 0.35.0.) Thrown by `Instruct.validate()` and `render()` — and therefore synchronously from `agent.send()` — when `vars` is `"required"` and inputs are missing. The message lists the missing names. `code` is `"INSTRUCT_VARIABLE_ERROR"`. ## Catching ```typescript import { AxleAbortError, AxleToolFatalError, AxleError, isAxleError } from "@fifthrevision/axle"; try { const result = await agent.send("...").final; if (!result.ok) { // api / incomplete / refusal / parse — expected return; } } catch (error) { if (error instanceof Error && error.name === "AbortError") { // cancelled } else if (error instanceof AxleToolFatalError) { // a tool killed the run } else if (isAxleError(error)) { // configuration or usage bug — error.code says which } else { throw error; } } ``` --- # Observability Source: https://axle.fifthrevision.com/reference/observability _Tracer, spans, writers, and log entries._ Conceptual guide: [Observability](/concepts/observability). ## ObservabilityOptions ```typescript interface ObservabilityOptions { level?: EventLevel; // default "info" log?: LogFn; trace?: Tracer | Span; } type EventLevel = "trace" | "debug" | "info" | "warn" | "error"; ``` Supply `log` and Axle creates and owns a tracer, flushing it after each operation. Supply `trace` to bring your own — Axle attaches spans but never ends or flushes it. `level` governs only the tracer Axle creates from `log`. ## Tracer ```typescript class Tracer { constructor(options?: TracerOptions); get minLevel(): EventLevel; set minLevel(level: EventLevel); addWriter(writer: TraceWriter): void; removeWriter(writer: TraceWriter): void; startSpan(name: string, options?: SpanOptions): Span; flush(): Promise; } interface TracerOptions { minLevel?: EventLevel; writers?: TraceWriter[]; } ``` ## Span ```typescript interface Span { startSpan(name: string, options?: SpanOptions): Span; end(status?: SpanStatus): void; trace(message: string, attributes?: Record): void; debug(message: string, attributes?: Record): void; info(message: string, attributes?: Record): void; warn(message: string, attributes?: Record): void; error(message: string, attributes?: Record): void; setAttribute(key: string, value: unknown): void; setAttributes(attributes: Record): void; setResult(result: SpanResult): void; } type SpanStatus = "ok" | "error" | "cancelled"; interface SpanOptions { type?: SpanType; attributes?: Record } type SpanType = string; // conventions: "workflow" | "llm" | "tool" | "action" | "internal" ``` `end()` defaults to `"ok"`. ## SpanData What writers receive. ```typescript interface SpanData { traceId: string; spanId: string; parentSpanId?: string; name: string; type?: SpanType; startTime: number; endTime?: number; status: SpanStatus; attributes: Record; events: SpanEvent[]; result?: SpanResult; } interface SpanEvent { name: string; timestamp: number; level: EventLevel; attributes?: Record; } ``` ## SpanResult ```typescript type SpanResult = LLMResult | ToolResult; interface LLMResult { kind: "llm"; model: string; request: { messages: unknown[]; system?: string; tools?: unknown[] }; response: { content: unknown }; usage?: TokenUsage; finishReason?: string; } interface ToolResult { kind: "tool"; name: string; input: unknown; output: unknown; } interface TokenUsage { inputTokens?: number; outputTokens?: number; totalTokens?: number; cachedInputTokens?: number; cacheWriteInputTokens?: number; reasoningOutputTokens?: number; } ``` `TokenUsage` is the observability shape; `Stats` is the result shape. They carry the same numbers under different names. ## Usage: Stats, breakdown, and cost ```typescript interface TokenStats { in: number; out: number; cachedIn?: number; // already inside in cacheWriteIn?: number; // already inside in reasoningOut?: number; // already inside out } interface UsageEntry extends TokenStats { provider?: string; // provider id; absent when unknown model: string; // what the response reported (or the requested model) requestedModel: string; // what you passed in agent?: string; // Agent name, when it has one at: string; // ISO 8601, when the provider finished } interface Stats extends TokenStats { breakdown: UsageEntry[]; // one row per request, in request order (@experimental) } ``` `addStats(total, usage)` appends rows; `mergeStats(...usages)` sums totals and concatenates rows. `createStats()` is `{ in: 0, out: 0, breakdown: [] }`. `attributeStats(tokens, { provider, model, requestedModel, agent?, requests? })` builds a `Stats` from a raw count — what `ctx.reportUsage` takes when a tool calls a model API directly. ```typescript import { computeCost } from "@fifthrevision/axle"; computeCost(usage: Stats, catalog?: ModelCatalog): Cost; interface Cost { usd: number; priced: PricedEntry[]; // UsageEntry & { usd } unpriced: UnpricedEntry[]; // UsageEntry & { reason } pricedWith?: string; // fetchedAt of the pricing catalog } type UnpricedReason = "no-catalog" | "no-provider" | "unlisted" | "no-price"; ``` ## TraceWriter ```typescript interface TraceWriter { onSpanStart(span: SpanData): void; onSpanUpdate?(span: SpanData): void; onSpanEnd(span: SpanData): void; onEvent?(span: SpanData, event: SpanEvent): void; flush?(): Promise; } ``` ## LogWriter ```typescript class LogWriter implements TraceWriter { constructor(log: LogFn); } type LogFn = (entry: LogEntry) => void; interface LogEntry { level: EventLevel; message: string; fields?: Record; } ``` Projects the span tree into flat, correlated log entries. Each completed span becomes one line whose `message` is the span name and whose `fields` carry the span attributes plus `type`, `status`, `traceId`, `spanId`, `parentSpanId`, and `durationMs`. Level mapping for completed spans: | Span | Level | | --- | --- | | `status === "error"` | `error` | | `type` is `"tool"` or `"workflow"` | `info` | | everything else | `debug` | So the info stream reads as a narrative — the run and its tool calls — while the full tree is available at debug. ## SimpleWriter ```typescript class SimpleWriter implements TraceWriter { constructor(options?: SimpleWriterOptions); } ``` ```typescript interface SimpleWriterOptions { minLevel?: EventLevel; // default "info" showInternal?: boolean; // default false showTimestamp?: boolean; // default true showDuration?: boolean; // default true markdown?: boolean; // default false — renders events flagged markdown: true output?: (line: string) => void; // default console.log } ``` Human-readable console output for development. `showInternal: true` is the equivalent of a `--debug` flag. ## Span names and attributes | Span | Type | Attributes | | --- | --- | --- | | `agent.send` | `workflow` | `sessionId`, `agentName?`, `finishReason?`, `inputTokens`, `outputTokens` | | `agent.compact` | `workflow` | `sessionId`, `trigger`, `agentName?`, `outcome`, `beforeTokens?`, `afterTokens?` | | `stream` | `internal` | — | | `step-N` | `llm` | Set by the provider adapter; carries an `LLMResult`. | | `` | `tool` | Carries a `ToolResult`. Available in `execute` as `ctx.span`. | | `mcp:connect` | `internal` | — | `agent.compact` sets `outcome` to `complete`, `skipped`, or `error`. --- # Configuration Source: https://axle.fifthrevision.com/reference/configuration _Compaction wiring and entry points._ ## Compaction **Experimental** Compaction is under active design and may change in any release. ```typescript agent.setCompaction(config: CompactionConfig): void ``` ```typescript interface CompactionConfig { compact: CompactionCallback; shouldCompactOnTrigger?: ShouldCompactOnTriggerCallback; triggers?: { beforeTurn?: boolean; afterTurn?: boolean; }; } type CompactionTrigger = "manual" | "beforeTurn" | "afterTurn"; type AutomaticCompactionTrigger = "beforeTurn" | "afterTurn"; ``` ### CompactionCallback ```typescript type CompactionCallback = ( state: { messages: AxleMessage[] }, context: { usage: ContextUsage; signal?: AbortSignal; trigger: CompactionTrigger; id: string; emit: (update: CompactionUpdate) => void; }, ) => MaybePromise<{ messages: AxleMessage[]; summary?: string }>; interface CompactionUpdate { summary?: string; progress?: number; // 0 to 1 } ``` Return the **complete** new conversation. There is no decline path; failures throw. `context.id` is the compaction id, shared with the emitted `CompactionPart`. Returned messages are checked by `validateCompactedMessages` and rejected with `COMPACTION_INVALID_MESSAGES` if tool calls and results are not paired and adjacent. ### ShouldCompactOnTriggerCallback ```typescript type ShouldCompactOnTriggerCallback = ( state: { messages: AxleMessage[] }, context: { usage: ContextUsage; trigger: AutomaticCompactionTrigger }, ) => boolean; ``` Must be synchronous. Runs at every configured automatic boundary, so keep it cheap. `agent.compact()` bypasses it. ## PromptCompactor ```typescript import { PromptCompactor } from "@fifthrevision/axle"; new PromptCompactor(options: PromptCompactorOptions) ``` ```typescript interface PromptCompactorOptions { provider: AIProvider; model: string; prompt: string; thresholdTokens: number; summaryWords?: number; // default 1000 appendixTokens?: number; // default thresholdTokens / 10; 0 disables reasoning?: ReasoningSetting; // default unset providerOptions?: ProviderOptions; } ``` Exposes two readonly members matching the callback types: ```typescript agent.setCompaction({ compact: compactor.compact, shouldCompactOnTrigger: compactor.shouldCompactOnTrigger, triggers: { beforeTurn: true }, }); ``` Behavior: - `shouldCompactOnTrigger` returns `true` when estimated context reaches `thresholdTokens` and there is at least one message. - `compact` summarizes with a streaming call to `provider`/`model`, appending the most recent user messages verbatim. The appendix is budgeted in tokens by `appendixTokens` (up to the last ten user messages, evicted oldest-first); the summary is steered in words by `summaryWords`. The summarizer request sends no `maxOutputTokens`, so the provider's own ceiling bounds thinking plus summary. - `reasoning` and `providerOptions` are passed through to the summary call, so a thinking-capable model can be used for compaction. `reasoning` defaults to unset (the model's own default); `providerOptions` defaults to none. - Progress is emitted continuously while the summary streams. - Messages carrying a [compaction stamp](/reference/messages#compaction-helpers) are treated as already-compacted and are not re-summarized. - The transcript being summarized is declared untrusted data in the compactor's own system prompt. Throws `INVALID_OPTIONS` when `thresholdTokens`, `summaryWords` is non-positive, or `appendixTokens` is negative. ## Entry points | Import | Contains | | --- | --- | | `@fifthrevision/axle` | The full runtime surface. | | `@fifthrevision/axle/ui` | The render and client surface: the render-layer types plus `Transcript`, `Instruct`, `computeCost`, `isCall` / `isActionOf` / `isTimeoutReason`, `renderTerminalMarkdown`, `RemoteAgent`, `httpTransport` and `HttpTransportError` — no provider SDKs. | --- # Tool-using agent Source: https://axle.fifthrevision.com/cookbook/tool-using-agent _A complete agent that calls tools, streams progress, and continues the conversation._ This is the recipe most agents start from: one tool, live progress in the terminal, and a follow-up question that reuses the conversation. ```typescript import { Agent, anthropic, type ExecutableTool } from "@fifthrevision/axle"; import * as z from "zod"; const setName: ExecutableTool = { name: "set_name", description: "Record the character's name in the app", schema: z.object({ name: z.string().describe("The character's name"), }), async execute({ name }, ctx) { ctx.emit(`Saving ${name}…`); await db.save(name); return "success"; }, }; const agent = new Agent({ provider: anthropic(process.env.ANTHROPIC_API_KEY!), model: "claude-sonnet-4-5", tools: [setName], }); agent.on((event) => { switch (event.type) { case "part:start": if (event.part.type === "action") { console.log(`\n[tool] ${event.part.detail.name} requested`); } break; case "text:delta": process.stdout.write(event.delta); break; case "action:running": console.log(`[tool] executing`); break; case "action:progress": console.log(`[tool] ${event.chunk}`); break; case "action:complete": console.log(`[tool] done`); break; case "action:cancelled": console.log(`[tool] cancelled`); break; case "action:error": console.error(`[tool] failed: ${event.error.message}`); break; } }); const result = await agent.send( "Tell me a three-sentence story with a named character, then record the name.", ).final; if (!result.ok) throw new Error(result.error.message); console.log(`\nusage: ${result.usage.in} in / ${result.usage.out} out`); // Follow-up — same callbacks, no re-wiring, history already there const followUp = await agent.send("What was the character's name again?").final; if (followUp.ok) console.log(followUp.response); ``` ## A few things worth noticing **The description and schema are the prompt.** That's where the model decides whether to call your tool and what to pass it. Adding `.describe()` to each field is the cheapest quality improvement available — nothing else in this recipe moves tool-call accuracy as much. **One send, several model requests.** The agent calls the model, runs the tool, and calls the model again with the result — all inside that single `await`. Those are [steps](/concepts/anatomy-of-a-send#step-the-execution-lens), and you mostly don't have to think about them. **`ctx.emit` is there for slow tools.** Whatever you pass shows up as `action:progress` while `execute` is still running. Leave it out and a ten-second tool just looks frozen to your user. **You wire callbacks once.** `agent.on()` applies to every send from then on, so there's no per-turn setup. **This example handles events directly because it's a terminal program.** For a UI, pass them to a [`Transcript`](/concepts/transcripts) instead and render `transcript.turns` — you get the same information already assembled, and you don't maintain a reducer. See [Streaming to a UI](/cookbook/streaming-ui). ## Handling tool failures Arguments are checked before your code runs: when the model passes parameters that don't match your schema, `execute` is not called and the model gets a `validation` error result naming each issue, which it can correct in the same turn. Your `execute` receives the parsed value, so schema defaults and transforms already apply. Most of the time, just throw. The model sees the error and usually works around it, and the run continues: ```typescript async execute({ city }) { const res = await fetch(url); if (!res.ok) throw new Error(`Weather service returned ${res.status}`); return await res.text(); } ``` To terminate the run instead, throw `AxleToolFatalError`: ```typescript import { AxleToolFatalError } from "@fifthrevision/axle"; async execute(input, ctx) { if (!sandboxAlive) { throw new AxleToolFatalError("Sandbox destroyed", { toolName: "run_command" }); } } ``` Default to ordinary throws — models are surprisingly good at recovering from a tool that says "that didn't work." Save fatal for when carrying on would be incoherent. ## Asking the caller instead When the answer needs a person — an approval, a missing credential, a choice only the user can make — don't throw and hope. Declare a deferred tool and let the caller answer: ```typescript import { isCall, type DeferredTool } from "@fifthrevision/axle"; const approveDeploy = { type: "deferred", name: "approve_deploy", description: "Ask the person whether to deploy, and wait for their answer", schema: z.object({ summary: z.string() }), } satisfies DeferredTool; const agent = new Agent({ provider, model, tools: [setName, approveDeploy] }); agent.onToolCall((call) => { if (!isCall(approveDeploy, call)) return; return prompt(`Deploy? ${call.input.summary} (yes/no)`); }); ``` The model calls `approve_deploy` like any other tool, `prompt` resolves with the person's answer, and the turn continues with it. A branch that returns nothing leaves the call waiting — answer it later from anywhere that holds the agent with `agent.toolCall(id)?.answer("yes")`, or bound the wait with the tool's `timeout`. See [Deferred tools](/concepts/tools#deferred-tools). ## Forwarding cancellation Please pass `ctx.signal` into your I/O. Without it, `handle.cancel()` stops the agent but leaves your fetch running, which is the kind of leak that only shows up under load: ```typescript async execute({ url }, ctx) { const res = await fetch(url, { signal: ctx.signal }); return await res.text(); } ``` ## Bounding the loop An agent with tools can, occasionally, go around in circles. Worth capping: ```typescript const agent = new Agent({ provider, model, tools, maxOutputTokens: 4096 }); ``` For a hard cap on model requests, drive the loop yourself with [`stream()`](/concepts/generate-and-stream) and `maxSteps`, or interrupt with [`agent.stop()`](/cookbook/cancellation). ## See also - [Tools](/concepts/tools) — provider tools, deferred tools, MCP, subagents - [Streaming to a UI](/cookbook/streaming-ui) - [Subagents & parallelism](/cookbook/subagents) --- # Structured output Source: https://axle.fifthrevision.com/cookbook/structured-output _Typed responses with Zod schemas, with and without an agent._ Hand a schema to `Instruct` — a Zod schema (or any Standard Schema), or a plain JSON Schema object — and `result.response` comes back parsed and typed. No JSON parsing on your side, no casting. ```typescript import { Agent, Instruct, anthropic } from "@fifthrevision/axle"; import * as z from "zod"; const agent = new Agent({ provider: anthropic(process.env.ANTHROPIC_API_KEY!), model: "claude-sonnet-4-5", }); const instruct = new Instruct({ prompt: "Tell me about {{planet}}.", schema: z.object({ name: z.string(), distanceFromSunKm: z.number(), moons: z.array(z.string()).describe("Named moons, largest first"), habitable: z.boolean(), }), }).withInput("planet", "Mars"); const result = await agent.send(instruct).final; if (!result.ok) throw new Error(result.error.message); result.response.moons; // string[] — fully typed result.response.distanceFromSunKm; // number ``` Axle shows the model your schema as output-format instructions, prepended to the prompt, and parses the reply back. `.describe()` text flows into those instructions, so it's worth adding wherever a field name isn't self-explanatory. Because the model sees the JSON Schema itself, constraints like `.min()` and `.regex()` reach it — and schemas that used to throw (`.nullable()`, unions, tuples, records, non-object roots) are accepted. ## Without an agent For a one-shot call with no history, pass the same `Instruct` to `generate()`: ```typescript import { generate } from "@fifthrevision/axle"; const result = await generate({ provider, model, instruct, }); if (result.ok) result.response.moons; ``` `stream()` works identically and gives you deltas as the JSON arrives — useful for a progress indicator, less so for rendering, since partial JSON is not parseable. ## Reusable templates `withInputs()` and `withInput()` return new instances, so one schema serves many calls: ```typescript const template = new Instruct({ prompt: "Extract the key facts from {{document}}.", schema: z.object({ facts: z.array(z.string()) }), }); const results = await Promise.all( documents.map((doc) => generate({ provider, model, instruct: template.withInput("document", doc) })), ); ``` Note these run concurrently because `generate()` has no queue. The same code through `agent.send()` would serialize. ## When parsing fails A malformed response resolves as an error, not a throw: ```typescript const result = await agent.send(instruct).final; if (!result.ok) { if (result.error.kind === "parse") { console.error("Model returned unparseable output:", result.error.message); // retry, fall back, or surface it } return; } ``` One subtlety that looks alarming the first time — and this applies to `generate()` and `stream()`, not to `Agent`. If a loop limit ended the run before the model got to its final answer, you'll get a parse error **with** a `stopped` marker. That isn't the model misbehaving; the conversation is perfectly continuable: ```typescript const result = await generate({ provider, model, instruct, tools, maxSteps: 5 }); if (!result.ok && result.error.kind === "parse" && result.stopped) { // hit maxSteps or the token budget — compact and continue rather than retrying } ``` `Agent` has no loop budgets, so its results carry no `stopped`. Use [`agent.stop()`](/cookbook/cancellation) if you need to bound an agent run. ## Making schemas easier for the model If you're seeing more parse failures than you'd like, these usually help: - **Keep schemas flat.** Deeply nested objects fail noticeably more often. - **Prefer `z.enum([...])`** to a free-form string when you know the value set. - **`.describe()` anything ambiguous** — units, formats, ordering. - **Ask for fewer fields per call.** Two reliable calls beat one flaky one. - **Watch your required fields.** Optional ones are genuinely optional to the model, but a required field it can't determine is a common cause of failures. ## Structured output with tools These compose happily. The model can call tools and still return a schema-shaped final answer: ```typescript const agent = new Agent({ provider, model, tools: [searchTool] }); const result = await agent.send( new Instruct({ prompt: "Research {{topic}} and summarize.", schema: z.object({ summary: z.string(), sources: z.array(z.string()), }), }).withInput("topic", "Rust async runtimes"), ).final; ``` The schema instructions apply to the final message, after the tool loop has settled — so intermediate tool calls don't have to produce JSON. ## See also - [Instruct](/concepts/instruct) - [Results & errors](/concepts/results-and-errors) - [Instruct reference](/reference/instruct) --- # Streaming to a UI Source: https://axle.fifthrevision.com/cookbook/streaming-ui _Fold turn events into a transcript, render it, and persist it._ The integration itself is three lines. Everything else on this page is about what you do once you have it. ```typescript import { Agent, Transcript } from "@fifthrevision/axle"; const transcript = new Transcript(); agent.on((event) => transcript.apply(event)); await agent.send(userInput).final; // transcript.turns is now ready to render ``` `Transcript` handles all the render bookkeeping — opening parts, applying deltas, settling statuses — so your UI only ever has to draw `turns`. ## Driving a React view ```typescript const [turns, setTurns] = useState([]); useEffect(() => { const transcript = new Transcript(); return agent.on((event) => { transcript.apply(event); setTurns([...transcript.turns]); }); }, [agent]); ``` `agent.on()` returns an unsubscribe function, which means returning it from `useEffect` is your entire cleanup. Do copy the array before setting state. `turns` is a stable readonly reference, so React won't re-render if you hand it the same one — a subtle bug that looks like "streaming doesn't work." If the stream is busy, throttle: apply every event, but batch the state update to an animation frame. ## Rendering a turn ```tsx function TurnView({ turn }: { turn: Turn }) { return (
{turn.parts.map((part) => { switch (part.type) { case "text": return ; case "thinking": return ; case "file": return ; case "citation": return ; case "compaction": return ; case "action": return ; } })}
); } ``` Part ids stay stable for the life of the turn, which is exactly what makes them correct React keys. ## Rendering an action Actions move through several states, and each one wants slightly different UI: ```tsx function ActionView({ part }: { part: ActionPart }) { if (part.kind === "agent") { // Recursive — a subagent's turns render with the same component return (
{part.detail.name} ({part.status}) {part.detail.children.map((t) => )}
); } const args = part.kind === "tool" && part.status === "pending" ? part.detail.pendingArgs // still-incomplete JSON : JSON.stringify(part.kind === "tool" ? part.detail.parameters : part.detail.input); return (
{part.detail.name}({args}) {part.detail.result?.type === "error" && }
); } ``` `pendingArgs` exists precisely for that window where arguments are still streaming in and can't be parsed yet — so you have something to show instead of an empty box. A deferred call never shows `running` — it moves `pending` → `waiting` while it needs the caller, with `action:waiting` carrying the call id (`callId`) and the validated `input`. Render `waiting` as a prompt, not a spinner: something is waiting on the person, not working. `detail.callId` is what `toolCall(id)` takes when they answer. ## Keeping the UI out of provider SDKs Your render code probably shouldn't drag the Anthropic, OpenAI, and Google SDKs into a browser bundle. Import from the `/ui` subpath instead: ```typescript import { Transcript } from "@fifthrevision/axle/ui"; import type { Turn, TurnPart, ActionPart, TurnEvent } from "@fifthrevision/axle/ui"; ``` ## Streaming across a network boundary `TurnEvent` is plain JSON. Serialize it on the server, apply it on the client: ```typescript // server agent.on((event) => socket.send(JSON.stringify(event))); // client const transcript = new Transcript(); socket.onmessage = (msg) => { transcript.apply(JSON.parse(msg.data)); render(transcript.turns); }; ``` If your socket also carries application events, `apply()` tells you what it did not recognize: ```typescript const outcome = transcript.apply(incoming); if (!outcome.handled) myReducer(outcome.event); ``` For more than a one-way pipe — reconnection with cursors, commands back to the server, driving a deferred tool's answer from the client — reach for [Remote agents](/concepts/remote-agents) instead of hand-rolling the socket. ## Persisting and restoring Two things to save, not one — this is the step people miss: ```typescript await db.save(sessionId, { session: agent.session, // for the model turns: transcript.turns, // for the reader }); // later const saved = await db.load(sessionId); const agent = new Agent(config, saved.session); const transcript = new Transcript(saved.turns); agent.on((event) => transcript.apply(event)); ``` Save only the session and you get an agent that remembers the conversation perfectly, next to a UI with nothing to show. ## Annotations Want to attach UI state — a sandbox booting, an eval result — to a turn without it becoming model state? Emit annotation events into the same transcript: ```typescript transcript.apply({ type: "annotation:start", target: { type: "turn", turnId }, annotation: { id, kind: "sandbox", label: "Starting sandbox…", status: "running" }, }); ``` They live on `turn.annotations` and `part.annotations`, and never reach a provider — which is the whole point of having them. Annotations are the main extension point in a transcript, and there's more to them than one event: lifecycles, typed unions, and a generic renderer that handles kinds you haven't written yet. See [Annotations & evals](/cookbook/annotations). ## See also - [Turn events](/concepts/turn-events) - [Turns & Transcripts](/concepts/transcripts) - [Transcript & turn events reference](/reference/transcript) --- # Annotations & evals Source: https://axle.fifthrevision.com/cookbook/annotations _Attaching your own UI to a turn — eval scores, sandbox status, anything Axle has no concept of._ Annotations are the extension point in a transcript. Parts are Axle's vocabulary; annotations are yours. If you want something rendered next to a turn that isn't text, thinking, or a tool call — an eval score, a sandbox booting, a deploy status — this is the mechanism. The running example here is an eval pipeline: after each agent turn, score the output on a few dimensions and show the results inline. It's the pattern [Sunnyday](https://www.sunnyday.run) uses in production. ## The shape ```typescript import type { Annotation } from "@fifthrevision/axle/ui"; type EvalAnnotation = Annotation< { score: "pass" | "fail"; rationale: string }, "objectives_eval" >; type SandboxAnnotation = Annotation<{ image: string }, "sandbox">; type AppAnnotation = EvalAnnotation | SandboxAnnotation; ``` Parameterize the transcript with your union and it flows everywhere: ```typescript import { Transcript } from "@fifthrevision/axle/ui"; import type { TurnEvent } from "@fifthrevision/axle/ui"; const transcript = new Transcript(); // However your app publishes events — a channel, a socket, a local callback. declare function emit(event: TurnEvent): void; ``` Now `turn.annotations` is `AppAnnotation[]`, and a `switch` on `kind` in your renderer is exhaustive and type-checked. ## Wrapping async work Most annotations are asynchronous — you kick off an eval, it takes a few seconds, then you have a score. That maps onto the annotation lifecycle directly: emit a `running` annotation, do the work, then replace it with a settled one under the same `id`. This helper is worth writing once: ```typescript import type { TurnEvent } from "@fifthrevision/axle/ui"; async function withTurnAnnotation( emit: (event: TurnEvent) => void, turnId: string, opts: { kind: AppAnnotation["kind"]; label: string; placement?: "before" | "after"; labelDone?: (result: T) => string; }, run: () => Promise, ): Promise { const id = crypto.randomUUID(); const base = { id, kind: opts.kind, placement: opts.placement ?? "after" }; emit({ type: "annotation:start", target: { type: "turn", turnId }, annotation: { ...base, label: `${opts.label}…`, status: "running" }, } as TurnEvent); try { const result = await run(); emit({ type: "annotation:end", target: { type: "turn", turnId }, annotation: { ...base, label: opts.labelDone?.(result) ?? `${opts.label}: done`, status: "complete", data: result, }, } as TurnEvent); return result; } catch (error) { emit({ type: "annotation:end", target: { type: "turn", turnId }, annotation: { ...base, label: `${opts.label}: error`, status: "error" }, } as TurnEvent); return null; } } ``` Three things it gets right, and they're the ones easy to miss: - **The same `id` throughout.** That's what makes `annotation:end` replace the running annotation instead of appending a second one. - **The label changes.** `"Evaluating objectives…"` while running becomes `"Objectives: pass"` when it settles. The label is the UI, so compute the final one from the result. - **Failures still settle.** An eval that throws emits an `error` annotation rather than leaving a spinner running forever. Swallowing the error and returning `null` keeps a failed eval from taking down the turn. ## Running it after a turn ```typescript declare function evaluateObjectives( turn: Turn, ): Promise<{ score: "pass" | "fail"; rationale: string }>; const result = await agent.send(userInput).final; if (!result.ok) return; const turnId = result.turn.id; const objectives = await withTurnAnnotation( emit, turnId, { kind: "objectives_eval", label: "Evaluating objectives", labelDone: (r) => `Objectives: ${r.score}`, }, () => evaluateObjectives(result.turn), ); ``` `result.turn.id` is the anchor — that's how the annotation finds its turn. Evals run *after* the send settles, out of band from the agent. They're not tools and not part of the loop, which is exactly why they need somewhere to live that isn't the conversation. For an instant, informational annotation with no async work, emit a single `annotation:start` that's already `complete`: ```typescript emit({ type: "annotation:start", target: { type: "turn", turnId }, annotation: { id: crypto.randomUUID(), kind: "objectives_eval", label: "No deliverables to evaluate", placement: "after", status: "complete", }, } as TurnEvent); ``` ## Rendering Because `label` is required, one generic component handles every kind — including kinds added later: ```tsx function AnnotationView({ annotation }: { annotation: AppAnnotation }) { const body = annotation.data != null ? JSON.stringify(annotation.data, null, 2) : null; return (
{annotation.label} {body ?
{body}
: null}
); } ``` That's a complete, useful renderer: label, a shimmer while running, an error state, and the payload on demand. Specialize individual kinds later, when one earns a real component. Placement is yours to honour: ```tsx function AgentTurnView({ turn }: { turn: Turn }) { const annotations = turn.annotations ?? []; const before = annotations.filter((a) => a.placement !== "after"); const after = annotations.filter((a) => a.placement === "after"); return (
{before.map((a) => )} {turn.parts.map((part) => )} {after.map((a) => )}
); } ``` `placement` defaults to `"after"` when accumulated, so evals naturally land below the turn they scored. ## Annotating a part instead of a turn The target can be narrower — point at one part instead of the whole turn: ```typescript declare const partId: string; emit({ type: "annotation:start", target: { type: "part", turnId, partId }, annotation: { id: crypto.randomUUID(), kind: "sandbox", label: "Touched a protected path", status: "complete", }, } as TurnEvent); ``` Useful for flagging one specific tool call — a sandbox command that touched something sensitive, say — rather than the whole turn. ## Feeding results back to the model Annotations are display-only, so if a failed eval should change what the agent does next, that's a separate, deliberate step: send the feedback as a message. ```typescript if (objectives?.score === "fail") { await agent.send( `Quality checks failed:\n${objectives.rationale}\nPlease address this and try again.`, ).final; } ``` The separation is the point. The annotation is what your user sees; the message is what the model sees. Keeping them apart means you can show a rich eval panel without inflating the context window, and retry with a terse instruction without that instruction cluttering the UI. ## Across a network boundary Annotation events are plain JSON like every other `TurnEvent`, so evals can run on your server and render on a client with no extra plumbing: ```typescript // server — evals run here, next to your database const event: TurnEvent = { type: "annotation:end", target: { type: "turn", turnId }, annotation: { id, kind: "objectives_eval", label: "Objectives: pass", status: "complete", data: { score: "pass", rationale: "All deliverables met." }, }, }; socket.send(JSON.stringify(event)); // client — same transcript that folds the agent's own events transcript.apply(JSON.parse(payload) as TurnEvent); ``` If your transport also carries application events, `apply()` returns `handled: false` for anything it doesn't recognize — see [Transcripts](/concepts/transcripts#mixing-in-your-own-events). ## See also - [Turns & Transcripts](/concepts/transcripts#annotations-the-extension-point) - [Streaming to a UI](/cookbook/streaming-ui) - [Transcript & turn events reference](/reference/transcript#annotations) --- # Files, images & PDFs Source: https://axle.fifthrevision.com/cookbook/files-and-images _Attaching local files, URLs, tool-returned files, and deferred references._ ## A local image ```typescript import { Agent, Instruct, loadFileContent, anthropic } from "@fifthrevision/axle"; const instruct = new Instruct({ prompt: "Describe this chart in one sentence." }); instruct.addFile(await loadFileContent("./chart.png")); const agent = new Agent({ provider: anthropic(apiKey), model: "claude-sonnet-4-5" }); const result = await agent.send(instruct).final; ``` `loadFileContent` works out the kind from the MIME type and picks an encoding for you — `utf-8` for text, `base64` for everything else. You can override it: ```typescript await loadFileContent("./chart.png", "base64"); await loadFileContent("./notes.md", "utf-8"); ``` It throws on files over 20 MiB, and on trying to read a binary file as text. ## A PDF Exactly the same — documents are just another binary kind: ```typescript instruct.addFile(await loadFileContent("./report.pdf")); instruct.prompt = "Summarize the key findings in this report."; ``` Not every model accepts PDFs, though. Check the provider's model docs for document support, and prefer a model that mentions it specifically. An answer about a document arrives as plain text — Axle doesn't ask providers for document citations, so don't expect `citations` with a `document` source on fresh answers. Stored conversations from before 0.36.1 can still carry them; Axle keeps them on the message but leaves them out of Anthropic requests. ## An image by URL You can skip the download entirely and hand the provider a URL: ```typescript instruct.addFile({ kind: "image", mimeType: "image/png", name: "chart.png", source: { type: "url", url: "https://example.com/chart.png" }, }); ``` The URL has to be reachable by the provider, not just by you. Providers also differ on whether they'll fetch URLs at all, so base64 is the portable choice if you need this to work everywhere. ## Inline text A string, or a text file, becomes a `## Reference N` section in the message body rather than a file part: ```typescript instruct.addFile("Q3 revenue: $4.2M\nQ4 revenue: $5.1M", { name: "financials.csv" }); ``` The content gets fenced, and the fence widens past any backticks inside it — so markdown and code nest safely without you thinking about it. ## A tool that returns a file ```typescript import { loadFileContent, type ExecutableTool } from "@fifthrevision/axle"; import * as z from "zod"; const showChart: ExecutableTool = { name: "show_chart", description: "Return a chart image for the given topic", schema: z.object({ topic: z.string() }), async execute({ topic }) { const image = await loadFileContent(`./charts/${topic}.png`, "base64"); return [ { type: "text", text: "Chart attached." }, { type: "file", file: image }, ]; }, }; ``` The model sees the image in the tool result and can describe it in the same send. ## Deferred references Sometimes file content is expiring, access-controlled, or expensive to load. In those cases you can store an opaque reference and resolve it only when a request actually needs it — so nothing sensitive ends up sitting in your message history. ```typescript import type { ExecutableTool, FileResolver } from "@fifthrevision/axle"; const readFile: ExecutableTool = { name: "read_file", description: "Read a file from the sandbox", schema: z.object({ id: z.string() }), async execute({ id }) { return [ { type: "file", file: { kind: "text", mimeType: "text/plain", name: "result.txt", source: { type: "ref", ref: { id } }, // opaque — yours }, }, ]; }, }; const fileResolver: FileResolver = async ({ ref, protocol, accepted, signal }) => { const { id } = ref as { id: string }; await authorize(id); // the ref crossed a model boundary — re-check it if (!accepted.includes("text")) { throw new Error(`Text not accepted here: ${accepted.join(", ")}`); } return { type: "text", content: await sandbox.readText(id, { signal }) }; }; const agent = new Agent({ provider, model, tools: [readFile], fileResolver }); ``` Three things to get right here: - **Always check `accepted`.** It varies by provider, by model, and by whether the file is in a user message or a tool result. Returning a type that isn't accepted throws. - **Authorize inside the resolver.** That ref travelled through the model, so treat it as untrusted input rather than as a capability. This is the security boundary. - **Configure a resolver, or it throws.** A deferred file with none gives you `No fileResolver configured for deferred file: `. Set the resolver on `AgentConfig`, per send in `SendMessageOptions`, or on `GenerateParams` / `StreamParams`. The per-send one wins. ## Rendering files in a UI Files attached to a user turn arrive as `file` parts: ```typescript case "file": return ; ``` ## See also - [Instruct](/concepts/instruct) - [Messages & parts reference](/reference/messages#files) - [Tools](/concepts/tools) --- # MCP servers Source: https://axle.fifthrevision.com/cookbook/mcp-servers _Connecting stdio and HTTP MCP servers to an agent._ ## stdio ```typescript import { Agent, MCP, anthropic } from "@fifthrevision/axle"; const fs = new MCP({ transport: "stdio", name: "fs", command: "npx", args: ["-y", "@modelcontextprotocol/server-filesystem", "/tmp/sandbox"], }); await fs.connect(); const agent = new Agent({ provider: anthropic(process.env.ANTHROPIC_API_KEY!), model: "claude-sonnet-4-5", mcps: [fs], }); const result = await agent.send("What files are in the sandbox?").final; await fs.close(); ``` **Connect before the first send.** The agent resolves tools lazily, but it won't connect for you — an unconnected client throws `MCP not connected. Call connect() first.` This is the most common stumble with MCP, so it's worth putting `await mcp.connect()` right next to the constructor. ## HTTP ```typescript const remote = new MCP({ transport: "http", name: "docs", url: "https://mcp.example.com/mcp", headers: { Authorization: `Bearer ${token}` }, }); await remote.connect(); ``` Same shape, using the MCP streamable HTTP transport. ## Several servers ```typescript const agent = new Agent({ provider, model, mcps: [fs, github, docs] }); ``` Each client's `name` prefixes the tools it contributes, which is how two servers can both expose a `read_file` without colliding. Do set `name` on every client. Without it, the prefix falls back to whatever the server advertises about itself, and two servers can end up colliding with `TOOL_REGISTRY_DUPLICATE` at registration time. ## Adding one later ```typescript agent.addMcp(newServer); agent.addMcps([a, b]); ``` Tools resolve on the next send. Each client resolves once and caches the result, so call `refreshTools()` if a server's tool list changes while you're running. ## Lifecycle in a long-running process ```typescript const servers = [fs, github]; await Promise.all(servers.map((s) => s.connect())); try { // ... many agents, many sends } finally { await Promise.all(servers.map((s) => s.close())); } ``` For a stdio server, `close()` shuts down the child process — skip it and you'll leak one per session, which adds up fast in a long-running server. ## Mixing MCP with local tools They all share one registry, and the model sees one flat list: ```typescript const agent = new Agent({ provider, model, tools: [myLocalTool], providerTools: [{ type: "provider", name: "web_search" }], mcps: [fs], }); ``` Names have to be unique across all three, though the MCP prefix usually keeps them apart without you doing anything. ## Inspecting what a server offers ```typescript await fs.connect(); const tools = await fs.listTools({ prefix: "fs" }); console.log(tools.map((t) => `${t.name}: ${t.description}`)); ``` Worth doing once when you integrate a new server. A server offering forty tools will noticeably degrade tool-selection accuracy, and you may decide to wrap a subset of them yourself instead. ## Trust One thing to keep in mind: MCP tool descriptions come from the server, and they go to the model as instructions. So a server you don't control can put text into your prompt. Treat third-party servers the way you'd treat any untrusted plugin — sandbox what they can reach, and don't grant write access you haven't reviewed. ## See also - [Tools](/concepts/tools#mcp-servers) - [MCP reference](/reference/mcp) --- # Provider tools Source: https://axle.fifthrevision.com/cookbook/provider-tools _Hosted web search and code execution, and rendering their results._ Provider tools run on the provider's own infrastructure. You name one, and that's it — there's nothing to implement. ```typescript import { Agent, anthropic, type ProviderTool } from "@fifthrevision/axle"; const webSearch: ProviderTool = { type: "provider", name: "web_search" }; const agent = new Agent({ provider: anthropic(process.env.ANTHROPIC_API_KEY!), model: "claude-sonnet-4-5", providerTools: [webSearch], }); agent.on((event) => { switch (event.type) { case "part:start": if (event.part.type === "action" && event.part.kind === "provider-tool") { console.log(`\n[${event.part.detail.name}] searching…`); } break; case "text:delta": process.stdout.write(event.delta); break; case "text:citation": console.log(`\n[source] ${event.citation.source.type}`); break; } }); const result = await agent.send("What are today's top news headlines?").final; ``` The event switch above is terminal-shaped. In a UI, apply events to a [`Transcript`](/concepts/transcripts) and render the `provider-tool` action parts it builds. ## Portable names Axle maps two names to each vendor's native equivalent: | Portable | Anthropic | OpenAI | Gemini | | --- | --- | --- | --- | | `web_search` | `web_search_20260318` | `web_search` | `googleSearch` | | `code_execution` | `code_execution_20260521` | `code_interpreter` | `codeExecution` | Anything else passes through untouched, so a vendor-specific tool works by naming it directly. What each provider does with a name beyond this table — including which `chatCompletions()` vendors host, attach, or fail — is the provider's own decision; core hands `providerTools` over unchanged. See [Web search](/cookbook/web-search) for the attached-search case. ```typescript const custom: ProviderTool = { type: "provider", name: "computer_20250124" }; ``` On Anthropic, `web_search` sends `allowed_callers: ["direct"]` so searches run directly rather than from inside code execution (dynamic filtering) — a model without programmatic tool calling requires that setting. Opt in to dynamic filtering with `config: { allowed_callers: ["code_execution_20260120"] }`, or pin the old version with `config: { type: "web_search_20250305" }`. ## What a provider-tool part carries Every provider reports these calls differently; Axle normalizes what your UI reads into one shape (normalized in 0.33.0): ```typescript { type: "provider-tool", id, name, // "web_search", "web_fetch", "code_execution", "file_search" input?, // { type: "search", queries } | { type: "open", url } | { type: "find", url, pattern } | { type: "code", code } | { type: "command", command } result?, // { type: "success", output? } | { type: "error", error: { type, message } } continuity?, // the provider's own objects, sent back to that provider only } ``` `input` is absent for tools Axle has no shape for; `result` is absent while the tool has not run in that message. A successful code execution carries what it printed as `output` — a string for OpenAI and Gemini, `{ stdout, stderr?, exitCode? }` for Anthropic. Search results live in `continuity` (Anthropic's result blocks, OpenAI's items), so read them there. A provider tool call goes back only to the provider that made it. And when Claude calls an Anthropic-run tool and one of your tools in the same response, the server tool's result arrives a step later in its own `provider-tool-result` part — handle both part types if you switch exhaustively. ## Events `provider-tool:start` opens the call, `provider-tool:input` carries what it was asked to do, and then either `provider-tool:complete` (success) or `provider-tool:error` (the provider reported failure, e.g. a search past `max_uses`) closes it. If you wait for `complete` to close a provider tool in a UI, handle `error` too. The turn stream mirrors `input` as `action:input`. ## Configuration is not portable ```typescript const search: ProviderTool = { type: "provider", name: "web_search", config: { max_uses: 5 }, // Anthropic-shaped — not portable }; ``` `config` is raw passthrough. Field names and placement differ per vendor, so anything you put here ties that agent to that provider — which is fine when that's what you want, as long as you know you're doing it. One exception: when the tool is served by an attached executable rather than a hosted definition (an attached `web_search`, say), there is no vendor definition to merge it into, so `config` is ignored without a warning. ## Rendering citations Search results usually arrive as citations, in two forms: **Anchored** to a span of generated text, on the text part: ```typescript case "text": return ; ``` Each citation carries `outputSpan` with `start`/`end` offsets into the text — that is how you underline the exact cited passage. **Unanchored**, as their own ordered part — a source list: ```typescript case "citation": return ; ``` Source shapes vary: ```typescript switch (citation.source.type) { case "web": return {citation.source.title ?? citation.source.url}; case "document": // Stored history from before 0.36.1 can still carry these; fresh // Anthropic answers no longer request document citations. return ; case "search-result": case "retrieved-context": case "unknown": return ; } ``` Do handle `unknown`. Providers add source types faster than any normalizer keeps up with them, and you don't want a new one crashing your renderer. ## Mixing with your own tools Provider tools and your own executable tools live happily in the same registry: ```typescript const agent = new Agent({ provider, model, providerTools: [{ type: "provider", name: "web_search" }], tools: [myDatabaseTool], }); ``` Just keep the names unique across both. ## When the provider has no native support Ask for `web_search` on a provider that doesn't host one and the request fails — unless you've attached a search to that `chatCompletions()` provider, in which case the attached tool runs as an ordinary tool call (rendered as `tool` parts, not `provider-tool` parts). See [Web search](/cookbook/web-search). ## See also - [Tools](/concepts/tools#provider-tools) - [Tools reference](/reference/tools#providertool) - [Messages & parts reference](/reference/messages#citations) --- # Web search Source: https://axle.fifthrevision.com/cookbook/web-search _One web_search that works on every provider, native or attached._ `web_search` is a [provider tool](/cookbook/provider-tools) on Anthropic, OpenAI, and Gemini. But on a local model or a plain OpenAI-compatible endpoint, there's nothing native to call. So Axle lets you attach a search tool to the `chatCompletions()` provider that needs one, and the same agent code runs everywhere. ## Attaching a search ```typescript import { chatCompletions, braveWebSearch, Agent } from "@fifthrevision/axle"; const provider = chatCompletions({ baseUrl: "http://localhost:11434/v1", webSearch: braveWebSearch({ apiKey: process.env.BRAVE_API_KEY!, maxResults: 5, country: "US", freshness: "pw", // past week }), }); const agent = new Agent({ provider, // no native search model: "qwen3:32b", providerTools: [{ type: "provider", name: "web_search" }], }); const result = await agent.send("What happened in the news this week?").final; ``` The request still names `web_search` as a provider tool. When the provider sees it, it sends the attached tool to the model as an ordinary function tool and drops `web_search` from the provider tools it translates — the loop then runs it as an ordinary tool call. What a provider can do is fixed when the provider is constructed, so two providers in one process can serve the same name differently. ## How the serving works Each provider decides how to serve a provider-tool name: as a tool the vendor hosts, as an executable tool the provider brings, or not at all. - **Hosted** (Anthropic, OpenAI, Gemini) → the provider tool is used. No attached tool is involved. - **Attached** (`chatCompletions()` with `webSearch`) → the attached tool runs as an ordinary tool call. This wins wherever it is attached — including on OpenRouter, which hosts a search of its own. Don't attach one if you want OpenRouter's. - **Neither** → the request fails before anything is sent: `ok: false` with `error.kind` `"api"` and a message naming the tool. There is no error code. The nice property here is that the failure is loud. You won't accidentally ship an agent that quietly can't search. ## What changes when it's attached The behaviour isn't identical, and it's worth knowing which one you got: | | Native provider tool | Attached tool | | --- | --- | --- | | Renders as | `provider-tool` action part | `tool` action part | | Citations | Provider-supplied, often anchored to text spans | None — results are JSON in the tool result | | Cost | Provider's search pricing | Your search API, plus tokens for the results | | Latency | Inside the provider's request | An extra round trip | One practical consequence: if your UI keys off `part.kind === "provider-tool"` to show a search indicator, remember to add the `tool` case too, or search will look invisible on attached providers. ## The generated tool - Name: `web_search` - Input: `{ query: string }`, trimmed, 1–400 characters - Output: JSON `{ query, results }` where each result is `{ title, url, snippets }` ## Brave options ```typescript interface BraveWebSearchOptions { apiKey: string; endpoint?: string; maxResults?: number; candidateCount?: number; maxTokens?: number; maxSnippets?: number; maxTokensPerUrl?: number; maxSnippetsPerUrl?: number; contextThresholdMode?: string; country?: string; searchLanguage?: string; freshness?: "pd" | "pw" | "pm" | "py" | `${string}to${string}`; timeoutMs?: number; } ``` `freshness` takes `pd` (day), `pw` (week), `pm` (month), `py` (year), or a `START` to `END` date range. Do pay attention to the token and snippet caps. Search results are verbose, and an uncapped result set can eat a large share of your context window in a single tool call. ## A custom search tool Any search API works — you just write an `ExecutableTool` named `web_search` whose `execute` returns the results as a string, and attach it as `webSearch`: ```typescript import { chatCompletions, type ExecutableTool } from "@fifthrevision/axle"; import * as z from "zod"; declare const searchIndex: (query: string, signal: AbortSignal) => Promise<{ title: string; url: string; passages: string[] }[]>; const internalSearchSchema = z.object({ query: z.string().trim().min(1).max(400) }); const internalSearch: ExecutableTool = { name: "web_search", description: "Search the internal docs index for current information.", schema: internalSearchSchema, async execute({ query }, { signal }) { const hits = await searchIndex(query, signal); return JSON.stringify({ query, results: hits.map((h) => ({ title: h.title, url: h.url, snippets: h.passages })), }); }, }; const provider = chatCompletions({ baseUrl: "http://localhost:11434/v1", webSearch: internalSearch, }); ``` This is also how you point `web_search` at an internal corpus rather than the public web. Your agent code doesn't change at all — only what "search" means. Do forward `signal`, so a cancelled send doesn't leave a search running. ## See also - [Provider tools](/cookbook/provider-tools) - [Providers reference](/reference/providers#websearch) - [Tools reference](/reference/tools#web-search) --- # Reasoning models Source: https://axle.fifthrevision.com/cookbook/reasoning _Enabling thinking, rendering it, and preserving continuity across turns._ ```typescript import { Agent, anthropic } from "@fifthrevision/axle"; const agent = new Agent({ provider: anthropic(process.env.ANTHROPIC_API_KEY!), model: "claude-opus-4-5", reasoning: { effort: "medium" }, }); agent.on((event) => { switch (event.type) { case "part:start": if (event.part.type === "thinking") console.log("\n[thinking]"); if (event.part.type === "text") console.log("\n[answer]"); break; case "thinking:raw-delta": process.stdout.write(event.delta); break; case "thinking:summary-delta": process.stdout.write(event.delta); break; case "text:delta": process.stdout.write(event.delta); break; } }); const result = await agent.send("Prove that the square root of 2 is irrational.").final; console.log(`\nreasoning tokens: ${result.usage.reasoningOut ?? 0}`); ``` `reasoning` is a portable setting that maps onto each provider's own controls — a named effort level plus a disclosure choice: ```typescript import type { ReasoningEffort, ReasoningSetting } from "@fifthrevision/axle"; type ReasoningEffort = "minimal" | "low" | "medium" | "high" | "xhigh" | "max"; // = REASONING_EFFORTS, lowest first type ReasoningSetting = "default" | { enabled?: boolean; effort?: ReasoningEffort; display?: "visible" | "hidden" }; ``` - `"default"` (or omitted) sends no reasoning fields; the model runs at its provider's own default, which may be thinking-on or thinking-off. - `{ effort }` picks a named level — `{ effort: "medium" }` is a moderate choice. Reach for `{ effort: "high" }` on purpose when you want deeper thinking, `{ effort: "max" }` for the deepest. Levels are relative within a model, not comparable compute across models, and the provider rejects one the model lacks. - `{ enabled: false }` sends the provider's explicit disable shape. Some always-thinking models reject it; the provider error surfaces unchanged. - `{ enabled: true }` turns thinking on without naming a depth, where the provider has a switch — Anthropic, Together AI, OpenRouter, and Gemma 4 on Gemini. Anywhere else it throws `INVALID_OPTIONS`; name an effort instead. - `{ effort, display: "hidden" }` keeps thinking out of the turn while the message still carries whatever the wire returned, so provider continuity keeps working. See [Disclosure vs form](#disclosure-vs-form). Set it per agent, or per send when one question doesn't need it: ```typescript await agent.send("Quick question.", { reasoning: { enabled: false } }).final; await agent.send("Think, but keep it out of the transcript.", { reasoning: { effort: "high", display: "hidden" } }).final; ``` For provider-specific knobs — thinking budgets, effort levels — use `providerOptions`, which is applied after Axle's mapping and can override it: ```typescript const agent = new Agent({ provider, model, reasoning: { effort: "medium" }, providerOptions: { thinking: { type: "enabled", budget_tokens: 10_000 } }, }); ``` Bear in mind that ties the agent to one provider, so keep it out of code you want to stay portable. On Anthropic, overriding the whole `thinking` object replaces it — `type` included — so restate the fields you still want. As always, that switch is fine for a terminal. In a UI, apply the events to a [`Transcript`](/concepts/transcripts) and render the `thinking` parts it assembles. ## Disclosure vs form `display` says whether the provider should show its thinking. It never decides *in what form* thinking arrives — that part is the model's, and the thinking part records which one showed up. Enabling reasoning (`{ effort }` or `{ enabled: true }`) now asks for disclosure wherever a request field exists: Anthropic gets `display: "summarized"`, OpenAI gets `summary: "auto"`, Gemini gets `includeThoughts: true`. Which means Claude and OpenAI models that previously streamed no thinking now stream it — and time to first text token on Anthropic rises, since thinking tokens arrive first. If that's not what you want, opt out per request: ```typescript await agent.send("...", { reasoning: { effort: "high", display: "hidden" } }).final; ``` `"hidden"` sends the provider's own hide value on the same routes (`omitted` on Anthropic, no summary field on OpenAI, `includeThoughts: false` on Gemini, `reasoning: { exclude: true }` on OpenRouter) and withholds thinking content from the turn on every route. Generic chat-completions endpoints and Together have no field and send nothing either way. `"default"` and `{ enabled: false }` are unchanged and send nothing for display. Fine-grained values stay in `providerOptions`: OpenAI `concise` and `detailed` summaries, Anthropic's `updates` display. ## Picking a setting for a model you choose at run time There is no setting that means "on" for every model — `"on"` used to mean medium, and medium is missing from many models' effort lists. When the model is chosen at run time, ask the catalog what to send: ```typescript declare const thinkingOn: boolean; const found = catalog.reasoningControl(model, { provider: "anthropic" }); new Agent({ provider, model, reasoning: thinkingOn ? (found?.suggested ?? { effort: "medium" }) : { enabled: false }, }); ``` `reasoningControl()` reports the kind of control a model has, the efforts to offer, and the setting to send when the choice is only on or off. It is advisory — requests are never checked against it — and `undefined` when the catalog has no record of the model's reasoning controls. `found.control` is `"levels"` (efforts listed, `suggested` nearest medium), `"toggle"` (an on/off switch, `suggested` is `{ enabled: true }`), or `"none"`. See [Model catalog & cost](/concepts/model-catalog). `{ enabled: true }` alone sends the switch each route spells: Anthropic gets `thinking: { type: "adaptive" }`, Together AI and OpenRouter get `reasoning: { enabled: true }`, Gemma 4 on Gemini gets `thinkingLevel: "high"`. On a route with no switch — OpenAI, generic endpoints, other Gemini models, budget-only models — Axle rejects it with `INVALID_OPTIONS`, so name an effort there. `{ enabled: true, effort }` is the same as `{ effort }`. For Gemma 4, `{ enabled: false }` sends `thinkingLevel: "minimal"`, which is how Google spells off for those models. `xhigh` and `max` exist only on newer models, and budget-only models map every level to a token budget (`minimal` through `max` get progressively larger budgets). An effort the model lacks is rejected by the provider. ## What you get back Reasoning surfaces as `thinking` parts. Each content field is named for what the provider handed back — and neither present is the withheld state: ```typescript interface ThinkingPart { id: string; type: "thinking"; summary?: string; // the provider's condensed account of its reasoning raw?: string; // the chain of thought itself; open-weight models only continuity?: ThinkingContinuity; // opaque state — preserve it } ``` Your UI needs to handle two cases, and it's easiest to write both up front: - **`summary` present** — the provider's condensed account. Render it, usually collapsed by default. This is what Anthropic, OpenAI, and Gemini return. - **`raw` present** — the chain of thought itself, from open-weight models through OpenAI's `gpt-oss` and chat-completions endpoints. Render it the same way. ```tsx case "thinking": if (!part.summary && !part.raw) return Reasoning withheld; return (
Thinking
{part.summary ?? part.raw}
); ``` A part opens with no content field; a field appears only once a delta wrote it. So render `summary ?? raw` and never test for `""`. `continuity` follows the same rule on Anthropic: it appears only once the signature (or redacted data) has arrived — first on the `thinking:update` that carries it — so a thinking part whose signature never arrived has no `continuity` field. Testing `part.continuity` for a signed part is enough; no need to also check the signature. Summaries and raw text stream on separate channels — `thinking:summary-delta` and `thinking:raw-delta` — because a part can receive both kinds of delta. Some providers (OpenAI's reasoning models, DeepSeek) give you the raw thinking text; others (OpenRouter's hosted reasoning models, Gemini) expose only a summary. On OpenRouter, Claude summaries stream as summary deltas — they used to land in the raw channel, and no longer do — so handle both events even if you're only used to one. One vocabulary note: the message-layer thinking part (`ContentPartThinking` on `AxleMessage`) keeps the wire vocabulary — `text`, `summary`, `redacted` — because it exists to be echoed back to the provider, not read. `redacted` there means only that the provider substituted an opaque payload (Anthropic `redacted_thinking`, OpenRouter `reasoning.encrypted`); a merely hidden block is not marked redacted. Read the turn part, echo the message part. ## Continuity across turns `continuity` is opaque provider state — an encrypted blob, a signature, a thought signature — that lets a model continue reasoning across requests. ```typescript type ThinkingContinuity = | { provider: "openai"; encrypted: string } | { provider: "anthropic"; signature?: string; redactedData?: string } | { provider: "gemini"; thoughtSignature: string } | { provider: "openrouter"; type: string; id?: string; format?: string; index?: number; signature?: string; data?: string; }; ``` Axle carries it through `agent.messages` automatically, so normally you never think about it. Claude through OpenRouter is worth knowing about: OpenRouter's `reasoning_details` are read and echoed back on assistant messages, so summaries render as summaries and multi-turn tool loops keep their signatures. But there are two places where **you** have to preserve it verbatim: - **Persistence.** If you serialize and restore sessions, do not strip it. `agent.session` keeps it; hand-rolled message filtering often does not. - **Compaction.** A compactor that rewrites assistant messages must preserve `continuity` on any thinking part it keeps — or drop the whole part. Half a thinking part with a mangled signature is worse than none. ## Reasoning tokens and cost ```typescript result.usage.reasoningOut; // included in usage.out — do not add it again ``` Reasoning tokens bill as output. A reasoning model can easily spend far more on thinking than on the answer itself — which is why `maxOutputTokens` may need to be much larger than the length of the answer would suggest. If a reasoning model keeps truncating, that's usually the cause. ## Reasoning with tools These compose naturally: the model thinks, calls tools, thinks about the results, and answers. Each step can produce its own thinking part, and they all accumulate into the same agent turn. ## Reasoning with structured output This works, with one caveat worth knowing in advance: reasoning models are more prone to prefixing their JSON with commentary. If parse errors climb after you enable `reasoning`, restate the bare-JSON requirement in your system prompt, or simplify the schema. ## Turning it off Some models reason by default, which isn't always what you want. `reasoning: { enabled: false }` turns it off wherever the provider supports that — it sends the provider's explicit disable shape rather than just omitting the field, so a model that thinks by default actually stops. It's worth setting explicitly on latency-sensitive paths — and on [compaction](/concepts/compaction) calls, where `PromptCompactor` leaves `reasoning` unset by default (so the model follows its own default). If you *do* want a reasoning model to drive the summary, pass an explicit setting such as `reasoning: { effort: "medium" }` (and `providerOptions` for the provider-specific knobs) when you construct the compactor — it's opt-in, because a cheap summary rarely benefits from the extra latency. ## See also - [Providers & models](/concepts/providers#request-options) - [Messages & parts reference](/reference/messages#thinkingcontinuity) --- # Interrupting & cancelling Source: https://axle.fifthrevision.com/cookbook/cancellation _stop, clear, cancel, and the interjection pattern._ There are four mechanisms here, and they're genuinely not interchangeable: `agent.stop()`, `agent.cancel()`, `agent.clear()` and `handle.cancel()` (a `signal` on the send behaves like `handle.cancel()`). [Agent → Interrupting](/concepts/agent#interrupting-four-different-things) is where the four are compared; this page is the recipes. ## stop(): let the work finish ```typescript const running = agent.send("Refactor the auth module."); // later, from a UI event const wasRunning = agent.stop(); // false if nothing was executing ``` The tool batch that's in flight — including parallel calls — runs to completion and commits. Then the handle settles without another provider request. Nothing gets wasted, and the history stays coherent. What comes back may surprise you the first time: a stopped turn ends on its tool-call exchange, so there is often no final answer to resolve with. `stop()` also won't interrupt a provider request or a tool that's already running — if you need a hard stop, that's `cancel()`. ## The steer playbook Three calls, in this order. This is the pattern you'll use most: ```typescript agent.stop(); // active turn wraps up cleanly agent.clear(); // drop anything queued behind it agent.send("Actually, make the button blue."); // becomes the very next turn ``` **Stop, clear, send.** It gracefully halts what the agent is doing and inserts the user's new instruction as the next turn — which is exactly what a user expects when they interrupt. Wiring it to a chat box is about as simple as it looks: ```typescript function onUserSubmit(text: string) { agent.stop(); agent.clear(); return agent.send(text); } ``` That's safe to call whether or not the agent is busy. `stop()` returns `false` and `clear()` returns `0` when there's nothing to interrupt, so the same handler covers the idle case. The new turn runs against a linear committed history that includes the tools that already finished — so the agent knows what it did before you redirected it, and won't repeat that work. **Order matters** Call `clear()` before `stop()` and you leave a window where the active turn can finish and pull in the queued work you were about to drop. ## cancel(): stop now ```typescript const handle = agent.send("Write a very long essay."); setTimeout(() => handle.cancel({ reason: "timeout", afterMs: 5000 }), 5000); try { const result = await handle.final; } catch (error) { if (error instanceof Error && error.name === "AbortError") { console.log("cancelled"); } else { throw error; } } ``` This is local to that one handle — other sends carry on unaffected. ### What survives ```typescript import { AxleAgentAbortError } from "@fifthrevision/axle"; catch (error) { if (error instanceof AxleAgentAbortError) { error.reason; // what you passed to cancel() error.usage; // tokens already spent — still billable error.partial; // the partially-streamed assistant message (undefined when nothing was written) error.messages; // messages completed before the abort error.turn; // the cancelled turn, for rendering } } ``` Showing partial output after a cancel is usually the right call. Your user paid for those tokens, and half an essay beats a blank screen. ```typescript const text = error.partial?.content.find((p) => p.type === "text"); if (text?.type === "text") render(text.text); ``` ### What commits Whether the user message sticks around depends on timing, and the line is whether the turn opened: - **Before** it — queued, or during MCP setup — the handle is dropped and nothing commits. The transcript shows `pending:queued` followed by `pending:dropped`. - **After** it, the user message stays committed and the turn is marked `cancelled` — always `cancelled`, even when the provider rethrows something that doesn't look like an abort. This includes cancelling during `beforeTurn` compaction: compaction is work inside an already-open turn, and cancelling does not unwind the transcript. - **Cancelling mid-tool-batch still commits the tool results.** When the abort lands while tool calls are running, the batch answers every call before the handle rejects — finished calls keep their real results, the rest read `cancelled` (`fatal` for the call that threw `AxleToolFatalError`). So the history ends in the `tool` message rather than in unanswered calls, and the next send is accepted. The same holds for a `turnTimeoutMs` elapsing mid-batch, and for `stream()` / `generate()` (where the error's `messages` ends in the `tool` message too). - **Cancelling mid-response keeps only what was written.** When the abort lands while the model is still writing its reply, the partial assistant message holds just the parts with content in them: a `tool-call` part is never kept, a `text` part only when its text is non-empty, a `thinking` part only when it holds text, a summary, redacted content, or `continuity`. Text written before a cut-short tool call is kept without the call. When nothing was written, there is no partial at all (`error.partial` is `undefined`, no assistant message commits) — and the next send is accepted either way. The turn still records what was shown: its action part settles `cancelled` even though the call never reaches the conversation. ## agent.cancel(): stop the active operation ```typescript agent.cancel("user-navigated-away"); // false if nothing was running ``` Same immediacy as `handle.cancel()`, but aimed at whatever is active rather than one handle. The active operation aborts, an opened turn settles `cancelled` with its partial work committed, and queued operations are unaffected — the next one starts. Use `stop()` when you want the in-flight tool batch to finish first, and `agent.cancel()` when you don't care about it. While `onSettled` callbacks run, the operation is already done, so both `cancel()` and `stop()` return `false` in that window. ## AbortSignal If you already have abort plumbing, it slots straight in: ```typescript const controller = new AbortController(); const result = await agent.send("...", { signal: controller.signal }).final; ``` A signal that's already aborted fails the send before anything commits. ## clear(): drain the queue ```typescript const dropped = agent.clear(); console.log(`cancelled ${dropped} queued sends`); ``` Each cleared handle rejects with `AxleAgentAbortError`, having committed nothing. The active turn is left alone. ## Cancelling a stream() Same shape, one class up the hierarchy: ```typescript import { stream, AxleAbortError } from "@fifthrevision/axle"; const handle = stream({ provider, model, messages }); setTimeout(() => handle.cancel("timeout"), 4000); try { await handle.final; } catch (error) { if (error instanceof AxleAbortError) { console.log(error.reason, error.usage, error.partial); } } ``` `AxleAgentAbortError` extends `AxleAbortError`, so an `instanceof AxleAbortError` check catches both. ## Cancellation inside tools Your tools have to cooperate here. Without forwarding the signal, cancelling stops the agent while your work keeps running in the background. `ctx.signal` also aborts when a sibling call in the same batch throws `AxleToolFatalError`, so forwarding it is what keeps a doomed batch from being held open by the calls that were still working. (In a deferred handler the same signal also aborts when anything else settles that call — see [Deferred tools](/concepts/tools#deferred-tools).) ```typescript async execute({ url }, ctx) { const res = await fetch(url, { signal: ctx.signal }); // forward it return await res.text(); } ``` For a long CPU-bound loop, poll it: ```typescript for (const item of items) { if (ctx.signal.aborted) throw new Error("Aborted"); await handleItem(item); } ``` ## Timeouts ```typescript const result = await agent.send("...", { signal: AbortSignal.timeout(30_000) }).final; ``` That's a wall-clock cap on the whole send, tool loop included. If you'd rather cap the number of model requests, use `maxSteps` with [`stream()`](/concepts/generate-and-stream) — which is a stop rather than an error, so you keep everything produced so far. Two built-in timeouts cover the cases a signal can't. `turnTimeoutMs` bounds a whole turn — every model step, tool call, and deferred wait included — and cancels it with `{ type: "timeout", limitMs }` as the abort reason (narrow it with `isTimeoutReason`) when it elapses. `streamStallMs` fails a step whose provider stream goes silent, without retrying. Both are unset by default, and both can be set on the agent or per send: ```typescript const agent = new Agent({ provider, model, turnTimeoutMs: 120_000 }); await agent.send("...", { streamStallMs: 15_000 }).final; ``` ## See also - [Agent](/concepts/agent#interrupting-four-different-things) - [Results & errors](/concepts/results-and-errors#cancellation) - [Errors reference](/reference/errors) --- # Subagents & parallelism Source: https://axle.fifthrevision.com/cookbook/subagents _Delegating to child agents and running a tool over many inputs at once._ **Experimental** `createAgentTool` and `parallelize` are marked experimental. Their rendering and result shapes may change in a minor release. ## A subagent as a tool `createAgentTool` turns an `Agent` into an executable tool. The parent hands off bounded work and gets back only the final answer — the child's whole conversation never enters the parent's context. ```typescript import { Agent, createAgentTool, anthropic } from "@fifthrevision/axle"; import * as z from "zod"; const provider = anthropic(process.env.ANTHROPIC_API_KEY!); const research = createAgentTool({ name: "research", description: "Research a topic in depth and report the key findings", schema: z.object({ topic: z.string() }), createAgent: () => new Agent({ provider, model: "claude-haiku-4-5", // cheaper model for the grunt work system: "You are a thorough researcher. Report only what you verified.", providerTools: [{ type: "provider", name: "web_search" }], }), prompt: ({ topic }) => `Research ${topic}. Report the three most important findings.`, }); const lead = new Agent({ provider, model: "claude-opus-4-5", tools: [research], }); const result = await lead.send("Compare Rust and Go for building a network proxy.").final; ``` That's the whole point of the pattern. The parent's context holds three findings rather than forty pages of search results, and your expensive model never has to read the raw material. **Do create a fresh child per call.** `createAgent` runs on every invocation for exactly this reason — a shared child accumulates history across unrelated calls, and gets confused in ways that are hard to debug. ## What crosses the boundary | Direction | What flows | | --- | --- | | Parent → child | The rendered `prompt`, `request` overrides, `ctx.signal` | | Child → parent | The final response string, token usage, turn events | Notably *not* flowing: the child's messages. If the child fails, the parent gets `Error("Subagent failed (): ")` naming the failure kind and message, and fatal or abort errors are rebuilt without the child's `messages`/`partial` so the parent never adopts another conversation's history. Usage is kept, since you still paid for it. ## Rendering a nested run Child turn events get forwarded through `ctx.emit`, so the subagent shows up as a `SubagentAction` part carrying its own `children` turns: ```tsx if (part.kind === "agent") { return (
{part.detail.name} — {part.status} {part.detail.children.map((turn) => ( ))}
); } ``` It's recursive — the same component that renders top-level turns renders the nested ones, which is a nice property to get for free. ## Accounting across models Usage rolls up automatically, and `breakdown` tells you where it all went: ```typescript result.usage.in; // total across parent and children for (const entry of result.usage.breakdown) { console.log(entry.provider, entry.model, entry.agent, entry.in, entry.out); } ``` Entries *explain* the aggregate rather than adding to it, so don't sum them on top. If you write a tool that calls a model directly instead of going through `createAgentTool`, report the usage yourself: ```typescript async execute(input, ctx) { const r = await generate({ provider, model, messages }); if (r.usage) ctx.reportUsage?.(r.usage); return "..."; } ``` ## Running one tool over many inputs `parallelize` wraps any tool in a parallelized tool: ```typescript import { parallelize } from "@fifthrevision/axle"; const researchBatch = parallelize(research, { maxItems: 20, maxConcurrency: 4, }); const lead = new Agent({ provider, model, tools: [researchBatch] }); ``` The generated tool is called `research_batch` and takes `{ items: [...] }`. Now a single model turn can fan out over twenty topics instead of making twenty sequential tool calls. What you're guaranteed: - Results preserve input order. - The call is validated as a whole first: one invalid item rejects the call before anything runs, with the item's path (for example `items.2.question`) in the `validation` message. - Ordinary per-item execution failures are reported per item, not as a batch failure. - Fatal and abort errors still propagate and terminate the run. - The wrapped tool's `kind` is inherited, so parallelized subagents still render as subagent activity. ```typescript interface ParallelToolResult { index: number; input: TInput; ok: boolean; output?: string | ToolResultPart[]; error?: { type: "execution"; message: string }; } ``` Defaults: `maxItems: 50`, `maxConcurrency: 8`, `maxResultBytes: 20 MiB`. You can offer both the single and the parallelized version and let the model choose: ```typescript tools: [research, parallelize(research)]; ``` ## Choosing a shape | Situation | Reach for | | --- | --- | | Isolating a noisy subtask from the parent's context | `createAgentTool` | | Using a cheaper model for bulk work | `createAgentTool` | | The same operation over a known list | `parallelize` | | Both | `parallelize(createAgentTool(...))` | | Fan-out you control, not the model | `Promise.all` over `generate()` | That last row is worth dwelling on. If *your code* already knows the work list, you don't need a tool at all. `generate()` has no queue, so a plain `Promise.all` is simpler, cheaper, and far more predictable than teaching a model to fan out for you. ## See also - [Tools](/concepts/tools#subagents) - [Tools reference](/reference/tools#createagenttool) - [Observability](/concepts/observability#token-usage) --- # Judging a turn with a continuation Source: https://axle.fifthrevision.com/cookbook/judge-continuation _A critic that runs before the next send lands — a typed judge, a bounded retry, and what the result carries._ Two things have to be true for a critic to be worth having. It has to see the answer before the user's next message does, and it has to be able to make the agent try again. A [continuation](/concepts/continuations) is both: it runs when the turn settles, holds the queue while it works, and `ctx.send()` puts the revision in the same conversation rather than a side channel. ```typescript const handle = agent.send("Summarize the incident report for the status page.", { after: async (result, ctx) => { let answer = result; for (let attempt = 0; attempt < 2; attempt++) { if (!answer.ok) return; const verdict = await judge(answer.response, ctx.signal); if (verdict.pass) return; answer = await ctx.send(`${verdict.feedback}\n\nRewrite the summary.`); } }, }); const result = await handle.final; const final = result.after?.at(-1)?.response ?? result.response; ``` Three decisions are already baked into those twelve lines, and they're the ones that matter: the loop is **bounded**, a failed turn is **not** judged, and the caller reads the *last* answer rather than the first. The rest of this page is each of those, plus the judge itself. ## A judge that returns a verdict, not prose [`decide()`](/concepts/decisions) is built for this: one request, one typed answer per question, no conversation and nothing to parse. ```typescript import { decide, noul, score, type DecisionProvider } from "@fifthrevision/axle"; declare const decisionProvider: DecisionProvider; async function judge(answer: string, signal: AbortSignal) { const { answers, usage } = await decide({ provider: decisionProvider, model: "jev-latest", input: answer, questions: { grounded: noul("Is every claim supported by the incident report?", { true: "Every claim traces to the report", false: "At least one claim is invented or unsupported", }), clarity: score("How clear would this be to someone paging in at 3am?", [ "Unreadable", "Understandable after a re-read", "Clear on first read", ]), }, signal, }); const grounded = answers.grounded.type === "refusal" ? 0 : answers.grounded.noul; const clarity = answers.clarity.type === "refusal" ? 0 : answers.clarity.score; return { pass: grounded > 0.8 && clarity >= 2, feedback: `Grounding ${grounded.toFixed(2)}, clarity ${clarity}. Fix the unsupported claims and tighten the opening.`, usage, }; } ``` `noul` gives you a probability rather than a yes, which is what you want for a threshold you'll tune. `score` gives you an ordinal with the legend you wrote. Both can come back as a `refusal` for that one question while the rest of the decision stands — treat a refusal as "no evidence", as above, rather than letting `undefined` decide for you. ### Or judge with the model you already have No decision model? Use `generate()` with an `Instruct` and a schema. You own the parsing contract, and you get prose rationale the retry can quote: ```typescript import { generate, Instruct } from "@fifthrevision/axle"; const critique = new Instruct({ prompt: "Judge whether the summary below is fully supported by the report.\n\n{{answer}}", schema: z.object({ pass: z.boolean(), feedback: z.string().describe("What to fix, addressed to the writer"), }), }); declare const answer: string; const verdict = await generate({ provider, model, instruct: critique.withInputs({ answer }), }); if (verdict.ok) console.log(verdict.response.pass, verdict.response.feedback); ``` A `generate()` call is a plain request with no conversation, so the judge can't see — or pollute — the agent's messages. That's the property you're paying for either way; a critic that reads the transcript it's judging tends to agree with it. ## What the result carries The handle resolves when the continuation returns, and the shape is the original send's result with the inline turns appended: ```typescript result.response; // the FIRST answer — the one the judge rejected result.after; // InlineTurn[] — each { userTurn, ok, response, turn, usage } result.after?.at(-1)?.response; // the answer you want to show ``` This trips people once. The top-level fields never move: they are the reply to the message you sent. The revisions live under `after`, in order, so "the final answer" is the last entry — and when the judge passed on the first try there are no entries at all, which is why the recipe above falls back to `result.response`. ## Accounting A judge costs tokens and they do not appear by themselves. ```typescript import { mergeStats, computeCost } from "@fifthrevision/axle"; declare const judgeUsage: Stats; // the `usage` decide() returned const turnUsage = mergeStats(result.usage, ...(result.after ?? []).map((t) => t.usage)); const total = mergeStats(turnUsage, judgeUsage); const cost = computeCost(total, catalog); ``` Inline turns are the agent's own work, so each carries its usage and none of it is rolled into the top-level `usage` — merge them yourself. A `decide()` or `generate()` judge is a separate call on a separate provider, so its `usage` is its own, with its own rows in `breakdown`. Merged, every row keeps its provider and model, and [`computeCost`](/concepts/model-catalog#what-a-run-cost) prices each at its own tier — which is how you find out that three retries of a cheap critic cost less than the one revision it bought. ## When things go wrong - **A failed turn.** The continuation runs whether the send resolved `ok` or not, so decide what a failure means before you judge it. Judging an `AxleProviderFailure` is judging the absence of an answer; returning early, as above, leaves the error on the result for the caller. - **A judge that throws.** A continuation that throws rejects the handle, and the user's answer goes with it. Wrap the judge so a flaky critic degrades to "accept the answer" rather than losing it: ```typescript const verdict = await judge(answer.response, ctx.signal).catch(() => ({ pass: true, feedback: "" })); ``` - **Cancellation.** Pass `ctx.signal` into the judge, as above. `cancel()` during a continuation aborts that signal and any inline turn in flight, then rejects the handle — so a cancelled judge should stop, not fall through to a retry. - **A loop with no bound.** The queue is held while the continuation runs: every send behind it waits, including the one the user just typed. Two attempts and a cap on the judge's own latency keeps that honest. ## Showing it in the UI Inline turns are ordinary turns — they emit the usual events and fold into your `Transcript`, drawn as replies via each one's `threadId`. The verdict itself isn't a turn and doesn't belong in the conversation; it's render state, which is what annotations are for. [Annotations & evals](/cookbook/annotations) has the plumbing, including the version that runs an eval *after* the send settles and out of band — reach for that one when the judgement doesn't need to gate anything. ## See also - [Continuations](/concepts/continuations) — the mechanism, the queue, and the boundaries - [Typed decisions](/concepts/decisions) — `noul`, `choice`, `score` - [Annotations & evals](/cookbook/annotations) — surfacing a verdict to a reader - [Model catalog & cost](/concepts/model-catalog) — pricing the retries --- # Remote agents over HTTP Source: https://axle.fifthrevision.com/cookbook/remote-over-http _Two routes on the server, one RemoteAgent on the client, and what to do when the stream drops._ [Remote agents](/concepts/remote-agents) explains the pieces and shows the whole thing over `loopbackTransport`, in one process. This is the HTTP version: two routes on the server, a client that folds the stream, and the reconnect that makes a dropped Wi-Fi connection a non-event. **Experimental** Remote agents are under active design and may change in any release. **shape to keep in mind: **commands go in over `POST`, everything else comes** back out over one `GET` stream.** The client never asks for state — it reads the events. ## One agent, two routes The server owns the agents: it builds them from the provider key and the tools whose `execute` only works there, and keeps an `InMemoryEventStore` beside each one. ```typescript import { Agent, InMemoryEventStore, toEventStreamResponse, parseAgentCommand } from "@fifthrevision/axle"; type Served = { agent: Agent; store: InMemoryEventStore }; const live = new Map(); const ended = new Set(); function serve(sessionId: string): Served { const agent = new Agent({ provider, model, tools: [askUser] }); const served = { agent, store: new InMemoryEventStore(agent) }; live.set(sessionId, served); return served; } ``` Both routes sit on the same URL — that's what `httpTransport` expects — and differ only by method: ```typescript async function handle(request: Request, sessionId: string): Promise { if (ended.has(sessionId)) return new Response("Agent ended", { status: 410 }); const served = live.get(sessionId); if (!served) return new Response("No such agent", { status: 404 }); if (request.method === "GET") { const after = request.headers.get("last-event-id"); const subscription = served.store.subscribe(request.signal, after); return toEventStreamResponse(subscription, request); } if (request.method === "POST") { const command = parseAgentCommand(await request.json()); if (!command) return new Response("Unrecognized command", { status: 400 }); const outcome = await runCommand(served.agent, command); return new Response(JSON.stringify(outcome), { headers: { "content-type": "application/json" }, }); } return new Response("Method not allowed", { status: 405 }); } ``` Three things in there are load-bearing: - **`last-event-id` is the resume cursor.** The client sets that header — on its first connection when you gave `httpTransport` an `after`, and on every reconnect with the last cursor it actually received. Pass it straight to `subscribe`, which replays what the consumer missed and then goes live. `request.headers.get()` returns `string | null`, which is exactly what `subscribe` takes. - **`request.signal` ends the subscription** when the client disconnects, so a closed tab doesn't leave a subscriber behind. - **`404` and `410` are terminal.** The client stops and rejects every open `final` on either, rather than retrying. Anything `5xx` it *will* retry, which is what you want mid-deploy — so don't answer a dead agent with a `500`. ## The command switch `parseAgentCommand` hands you a typed `AgentCommand`; turning it into `Agent` calls is yours, because only the server knows how to find the agent: ```typescript import { Instruct, type AgentCommand, type CommandOutcome } from "@fifthrevision/axle"; const accepted: CommandOutcome = { accepted: true }; const notWaiting = (callId: string): CommandOutcome => ({ accepted: false, reason: { type: "not-waiting", message: `No waiting call ${callId}` }, }); async function runCommand(agent: Agent, command: AgentCommand): Promise { switch (command.type) { case "send": { const handle = agent.send(Instruct.fromJSON(command.instruct), { id: command.id }); handle.final.catch(() => {}); // the result reaches the client as events return accepted; } case "answer": { const call = agent.toolCall(command.callId); if (!call) return notWaiting(command.callId); await call.answer(command.content); return accepted; } case "fail": { const call = agent.toolCall(command.callId); if (!call) return notWaiting(command.callId); await call.fail(command.message); return accepted; } case "cancel": case "stop": { const took = command.type === "cancel" ? agent.cancel() : agent.stop(); return took ? accepted : { accepted: false, reason: { type: "idle", message: "No active turn" } }; } case "clear": agent.clear(); return accepted; } } ``` Note the `handle.final.catch(() => {})`. The response to a `send` says only whether the agent took it; the turn, the answer and any failure travel as events. Without that `catch`, a send that fails takes down the process with an unhandled rejection — the client is reading the outcome, nobody is awaiting the handle. ## The client ```typescript import { RemoteAgent, Transcript, httpTransport, isCall } from "@fifthrevision/axle"; declare function setOffline(offline: boolean): void; const remoteAgent = new RemoteAgent(httpTransport(`/agents/${sessionId}`)); const transcript = new Transcript(); remoteAgent.on((event) => transcript.apply(event)); remoteAgent.onConnection((connection) => setOffline(connection.phase !== "open")); remoteAgent.onToolCall((call) => { if (!isCall(askUser, call)) return; return prompt(call.input.question); }); const result = await remoteAgent.send("Summarize today's incidents.").final; ``` That is the same code you'd write against a local `Agent`, with three differences worth planning for: - **A remote send's handle has `final` and nothing else.** There is no `handle.cancel()`, because a queued send can't be cancelled by id across a wire. Use `remoteAgent.cancel()`, `stop()` or `clear()` — each posts one command and resolves `true` when the served agent took it, `false` when the switch answered `accepted: false` (nothing running, in the case of a cancel). - **A remote `onToolCall` handler gets no `ToolContext`.** No `emit` for progress, no `signal`; cancellation shows up in the events instead. - **The agent's work is not your connection.** `remoteAgent.status` is the served agent's idle/busy; `remoteAgent.connection` is the link. A spinner driven by the wrong one lies to the user — see [Status and connection are separate](/concepts/remote-agents#status-and-connection-are-separate). ## Resuming after a drop Every event carries a cursor and every turn keeps the one it was folded from, so the thing you persist for resume is already in your transcript: ```typescript const resumed = new RemoteAgent( httpTransport(`/agents/${sessionId}`, { after: saved.turns.at(-1)?.cursor }), ); ``` Reconnects inside a live `RemoteAgent` need nothing from you: the transport reopens with the last cursor it delivered, waiting `reconnectDelayMs` and doubling up to `maxReconnectDelayMs`, for as long as it takes. `after` is for the *first* connection — a reload, a second device, a client that was away long enough to be restarted. A cursor the store doesn't recognize replays everything rather than nothing, which is the safe direction: a client that resumes against a restarted server rebuilds its transcript instead of silently missing the middle. ## Ending an agent The server decides when an agent is over. Close the store so open streams finish what they hold, then answer that URL with `410`: ```typescript function end(sessionId: string): void { const served = live.get(sessionId); served?.store.close(); live.delete(sessionId); ended.add(sessionId); } ``` On the client that ends the `RemoteAgent`: the connection goes to `ended` and every open `final` rejects. `remoteAgent.close()` is the same ending chosen from the other side — it stops listening and leaves the served agent alone. ## Auth `headers` is sent with every request, and a function is called per request, so a token that expires mid-stream is a one-liner: ```typescript declare function freshToken(): Promise; const authed = httpTransport(url, { headers: async () => ({ authorization: `Bearer ${await freshToken()}` }), }); ``` Each reconnect calls it again, which is what makes a long-lived stream survive a rotation. ## Keeping the browser bundle clean Import the client half from `@fifthrevision/axle/ui`: ```typescript import { RemoteAgent, Transcript, httpTransport, isCall } from "@fifthrevision/axle/ui"; ``` `RemoteAgent`, `httpTransport`, `Transcript` and the narrowing helpers all live there, and that entry point depends only on `chalk`, `marked` and `zod` — no provider SDKs. The browser never had the key anyway; now it doesn't have the SDKs either. ## See also - [Remote agents](/concepts/remote-agents) — the pieces, and the loopback version - [Remote agents reference](/reference/remote) — every method, transport and wire type - [Streaming to a UI](/cookbook/streaming-ui) — rendering the stream you receive - [Tools](/concepts/tools#deferred-tools) — the deferred calls a client answers --- # Changelog Source: https://axle.fifthrevision.com/changelog _Notable changes by release._ Mirrored from [`CHANGELOG.md`](https://github.com/johncch/axle/blob/main/CHANGELOG.md) in the library repository. For upgrade instructions, see [Upgrading](/upgrading). ## [0.37.0] - 2026-11-19 - **Breaking:** `reasoning` now names a model's own knobs: `"default"` or `{ enabled?, effort?, display? }`. `"off"` becomes `{ enabled: false }` and `"on"` is gone; use `{ effort: "medium" }` for the same request. `enabled: true` turns thinking on without naming an effort where the provider has a switch (Anthropic, Together AI, OpenRouter, Gemma 4 on Gemini) and throws `INVALID_OPTIONS` elsewhere. See [Upgrading](/upgrading). - **Breaking:** `ReasoningEffort` has six levels, `minimal`, `low`, `medium`, `high`, `xhigh` and `max`, sent to the provider as written. `xhigh` and `max` no longer need `providerOptions`. Added `REASONING_EFFORTS`, and budget-only models get a token budget for every level. See [Upgrading](/upgrading). - Added `ModelCatalog.reasoningControl()` and `reasoningOptions`, which report the efforts a model offers and a suggested setting. Saved `CatalogData` is now version 5, so older copies are refetched. - **Breaking:** an `Instruct` schema is a JSON Schema: pass a plain JSON Schema object or any Standard Schema such as Zod. The model is shown the JSON Schema in place of an example object, so constraints like `.min()` and `.regex()` reach it, and schemas that used to throw (`.nullable()`, unions, tuples, records, non-object roots) are accepted. See [Upgrading](/upgrading). - **Breaking:** `parseResponse()` and `Instruct.parse()` now return a promise. `instruct.render()` returns the prompt alone, and the schema is stored on the message as `output`. `InstructInputs` values are limited to strings, numbers, booleans and `null`. See [Upgrading](/upgrading). - Added `Instruct.toJSON()` and `Instruct.fromJSON()`. - **Breaking:** a remote `send` command now carries the `Instruct` as data instead of a rendered prompt. A 0.36 client and a 0.37 host do not interoperate, so deploy both sides together. See [Upgrading](/upgrading). - Added `agent.onStep()` (and `handle.onStep()` on `stream()`), an awaited hook at the end of each step so a host can save usage and state while a turn runs. Custom `StreamHandle` implementations must add it. - Added `agent.session`, which returns the session synchronously and works inside hooks, continuations and tools where `snapshot()` would deadlock. `agent.snapshot()` is deprecated. - `agent.messages` now grows as each step ends instead of when the turn ends. `turn:end` usage now includes failed requests and keeps subagent rows in call order. - Added `@fifthrevision/axle/analyze`: `analyze()` reads stored turns into segments (turns, tools, subagents, compactions, texts and errors), with the predicates `failed`, `completed`, `cancelled`, `byUser`, `byAgent` and `named`, and the functions `streaks`, `repeats`, `sum`, `flatten`, `partOf` and `simplify`. Experimental. - `turn:end` and `Turn` now record how a turn ended: `error` for a thrown error and `cancelReason` when `turnTimeoutMs` cancelled it. - A send that fails or is cancelled while listing MCP tools now keeps its user message and ends the turn with `error` or `cancelled`, instead of being dropped. - A failed subagent's tool error now names the failure kind and message instead of embedding the failure as JSON. - Text and thinking stream events now carry `index`. This fixes grounding citations that arrived after their text, which Gemini sends, being lost from turns. ## [0.36.3] - 2026-11-14 - Fixed an agent becoming unusable after a turn was cancelled or timed out while the model was still writing its response. A tool call that had started streaming was kept with no result, and a text part opened but not yet written to was kept as an empty string; providers rejected every later request. A cancelled model call now keeps only what was written: no tool calls, no empty text and no empty thinking parts. When nothing was written, `error.partial` is `undefined` and no assistant message is added. See [Upgrading](/upgrading). - Anthropic thinking parts now carry `continuity` only once a signature or redacted data has arrived, instead of starting with an empty signature. ## [0.36.2] - 2026-11-12 - Fixed an agent becoming unusable after a turn was cancelled, timed out, or hit a fatal tool error while a tool was running. The tool call was left without a result, and providers rejected every later request. Each call in the batch now gets a result: its real one if it finished, or an error of type `cancelled` or `fatal`. `agent.messages` and the error's `messages` therefore end in a tool results message. See [Upgrading](/upgrading). ## [0.36.1] - 2026-11-12 - **Breaking:** Axle no longer requests citations for documents sent to Anthropic, and there is no option to re-enable them. Answers about PDF or text documents now arrive as plain text parts. Document citations already stored in a conversation are kept on the messages but left out of requests to Anthropic, which would otherwise reject them. Citations from hosted web search are unchanged. See [Upgrading](/upgrading). ## [0.36.0] - 2026-11-08 - Added deferred tools: a tool definition with no `execute` that the caller answers. Calls go to `onToolCall` on `stream()`, `generate()` and `agent.onToolCall()`, or are answered from outside with `toolCall(id).answer()` / `.fail()`. A call with no answer keeps waiting instead of failing (`generate()` still fails fast). Added the `tool:waiting` and `action:waiting` events, the `deferred` action part, and the `isCall` / `isActionOf` helpers. - **Breaking:** `onToolCall` now receives a single `{ id, name, input }` call plus the tool context, and only handles deferred tools; it no longer intercepts executable tools. Unanswered calls no longer produce an `unanswered` error result. - Added experimental remote agents: `RemoteAgent` drives an Agent served elsewhere over `httpTransport` or `loopbackTransport`, with `InMemoryEventStore` and `toEventStreamResponse` on the served side. Streams resume from the last cursor after a dropped connection, and a 404 or 410 ends the agent. A runnable example is in `examples/remote`. - Added the agent operation lifecycle: `agent.on` now delivers `operation:start`, `after:start`, `after:end`, `operation:end` and `agent:idle` events, and `agent.status` reports whether the agent is idle or busy. `TurnEventCallback` is now `AgentEventCallback`. - Added `agent.onStart()`, which runs before an operation's turn opens and can refuse it. Turns sent inline from a continuation now carry a `threadId`. - **Breaking:** `onSettled` now fires once per send or manual compaction, after the continuation finishes, instead of after every turn. - **Breaking:** removed `signal` from inline `ctx.send()` options; it was previously ignored. Cancel the operation to abort an inline turn. - Added `turnTimeoutMs` to bound a whole turn, and `streamStallMs` to fail a step when the provider stream goes silent. Both are unset by default. - `send()` accepts an `id` for its user turn. - Fixed the `stream-web-search-error` check failing for the wrong reason on Haiku 5.5, and documented check retries in the checks README. ## [0.35.0] - 2026-11-03 - **Breaking:** `AxleFailure` is now `AxleProviderFailure` (old names removed); `model` failures split into `api` and `incomplete`, and every setup mistake throws a coded `AxleError` (`INVALID_OPTIONS`, `PROVIDER_UNSUPPORTED`, `FILE_UNREADABLE`, `MCP_NOT_CONNECTED`, …) instead of resolving `ok: false`. `InstructVariableError` is now `AxleInstructVariableError`, `TaskError` is gone, and `isAxleError`/`AxleErrorCode` narrow catches. See [Upgrading](/upgrading). - **Breaking:** providers are a `protocol` (`messages`, `responses`, `generateContent`, `chatCompletions`) plus an `id`, replacing `AIProvider.name`; `ModelCatalog` says `provider` not `host`. New protocol constructors `messages()`, `responses()`, `generateContent()`, `chatCompletions({ baseUrl, … })`, plus `openrouter()`, `togetherai()`, and `bedrock()` presets. First-party `baseUrl` moved to the constructors; `chatCompletions()` takes one options object and `vendor` is now `id` + `dialect`. - **Breaking:** `ModelCatalog` no longer fetches — build it from `CatalogData` via `fetchModelsDev()` + `ModelCatalogStore` + `catalogFile()`; `lookup`/`contextWindow` take `{ provider }`, data is version 4. New `computeCost(usage, catalog)` prices per-request `breakdown` rows. - **Breaking:** `usage.breakdown` is one row per request (with `agent`, `at`, `requestedModel`), `Stats.breakdown` is required — use `attributeStats()` for hand-built usage. `UsageEntry.provider` is the provider `id` (`google`, `openai`, vendor id) and optional. - **Breaking:** `AgentDefinition` and `createAgentConfig()` are removed; rebuild `AgentConfig` from your own saved recipe plus `AgentSession`. Turns carry `failure` (not `error`), `turn:end` carries `reason` (`stop` | `length`), cancelled tool calls emit `action:cancelled`, cancelled compactions emit `compaction:cancelled`, and `CompactionPart` gains `trigger`. - Added `after` continuations on `send()`: run inline turns via `ctx.send()` after the turn settles, listed under `result.after`. `onSettled` now fires per committed turn, tool batches run concurrently, and the Gemini SDK floor is 2.31.0. ## [0.34.3] - 2026-10-28 - Tool call arguments are now parsed with the tool's schema before `execute`. Invalid arguments no longer reach `execute`: the model gets an error tool result with type `validation` naming each issue (for example `description: Invalid input: expected string, received undefined`) and can correct the call in the same turn. `execute` receives the parsed value, so schema defaults and transforms now apply. A parallelized tool's call is rejected as a whole when any item is invalid. MCP tools are validated too, and unknown top-level keys are dropped before the call reaches the server, matching a default `z.object()`, rather than rejected. ## [0.34.2] - 2026-10-24 - Added `baseUrl` to the shared provider client options, so `anthropic()`, `openai()` and `gemini()` can route requests through a proxy that speaks the vendor's API. `typesafe()` already had it. `chatCompletions()` keeps its base URL as the first argument and rejects the option. ## [0.34.1] - 2026-10-16 - Enabled prompt caching by default for Anthropic and OpenRouter, with a `cache` opt-out. OpenRouter tool-loop requests now stay on the same session, and Together cached-token usage is recognized. ## [0.34.0] - 2026-10-10 - **Breaking (CLI):** untrusted folders no longer load project `.axle/` configuration or credentials, and tools that can modify or execute (`exec`, `patch-file`, and `write-file`) are disabled until you run `axle trust` for that folder. - **Breaking (CLI):** schedule commands now register jobs with `axle schedule add`; use `axle -j` for a proof run. `remove` and `sessions` select schedules by name. - Added CLI skill discovery from user and trusted project skill directories; `axle info` reports loaded, shadowed, ignored, and invalid skills. - Added experimental typed decisions with `decide()` and the `typesafe()` provider. - Added live skill updates that take effect at the next provider request, plus safer skill-name validation and escaped skill output. - Added per-provider custom fetch support and moved web-search configuration into provider tools. - Added Agent `onIdle` callbacks, awaitable settlement hooks, queued-operation tracking, and cancellation support; snapshots now wait for the Agent to become idle. - CLI chat now tracks queued sends and compactions as pending work, supports queuing input during a turn, and improves interrupt and session-settlement behavior. - Added model-catalog context-window lookup and display in `axle info`; the CLI status bar now shows context use as a percentage. Removed `AXLE_CONTEXT_WINDOW`. - Improved CLI credential loading and development-build version reporting, and removed the generic chat-completions provider from the CLI. - Fixed OpenAI web-search citations that could crash core, and improved handling of dropped or malformed skill data. ## [0.33.0] - 2026-10-06 - **Breaking:** removed the model registry. The `@fifthrevision/axle/models` entry point no longer exists; pass model IDs as plain strings (`"openai/gpt-5.5"`), and OpenRouter IDs are sent unchanged. - **Breaking:** removed `temperature`, `topP`, and `stop` from `generate()`, `stream()`, and agent request options; send them through `providerOptions` using the provider's own field names. - **Breaking:** normalized provider tool parts across providers with portable `input` and `result` fields and per-provider `continuity`; added `provider-tool-result` content parts and `provider-tool:input`/`provider-tool:error` events, and removed `output` from `provider-tool:complete`. - **Breaking:** provider refusals are now reported as a dedicated `refusal` failure kind instead of empty or mislabeled successes. - **Breaking:** flattened failure results so `type`, `message`, `status`, and `usage` sit directly on `model` failures, and rejected API keys are detected as `type: "authentication"`. - **Breaking:** removed `AxleStopReason.Error` and `AxleStopReason.Custom`; unknown stop reasons now fail the request. - **Breaking (CLI):** local tools (`exec`, `read-file`, `write-file`, `patch-file`) are enabled by default in chat and recipes, and the `calculator` tool was removed. Add `tools: []` to keep a recipe tool-free. - Added `axle info` to print the version, config files, defaults, and every configured provider, showing where each value came from and API keys only as set or unset. - Added recipe scheduling on macOS: declare `schedule: { every: 1h }` or `at: "09:00"` in a recipe and use `axle schedule` commands to register, list, inspect sessions, and remove LaunchAgent-based runs. - CLI replies now render as markdown (headings, code, lists, tables), prompts use GitHub CLI-style glyphs, and a default `axle-help` tool lets the model answer questions about axle itself. - Thinking text now streams from Claude and OpenAI models when `request.reasoning` is enabled. - Anthropic `pause_turn` responses continue automatically within a single step, with usage summed across the follow-up requests. - Surfaced provider code execution output (stdout/stderr/exit code) in action results, newly enabled Anthropic code execution, and preserved Gemini code execution parts across turns. - Kept Anthropic server tool results when a server tool runs alongside client tools, so follow-up requests no longer fail. - Chat Completions HTTP errors now report the provider's error type and message instead of the raw status and body, and custom headers can be passed through provider client options. - Agent session IDs are forwarded to OpenRouter so conversations stick to one upstream provider. - OpenAI assistant items are replayed in their original order, fixing requests that reasoned between web searches. - Adjacent text parts are joined without separators, fixing broken sentences and unparseable `Instruct` JSON. - OpenAI responses cut off at `maxOutputTokens` and Anthropic's `model_context_window_exceeded` now finish with `length` and keep partial content. - `web_search` resolves to newer provider versions, and Gemini searches now surface a `provider-tool` part with the queries used. - Anthropic's implicit `max_tokens` default is now 128,000. ## [0.32.0] - 2026-09-12 - **Breaking:** renamed thinking stream events and separated displayable thinking summaries from raw reasoning content for clearer reasoning handling. - Unified generation request handling for streaming transports, improving consistency between standard and streaming responses. - Preserved OpenRouter and Gemini reasoning continuity metadata across generation, streaming, and assistant message conversion. - Added portable controls for displaying, hiding, or retaining reasoning only for provider continuity. - Improved usage reporting for OpenAI cached responses by tracking cache write tokens in standard and streaming flows. - Fixed Gemini thinking/signature handling and related provider issues. - Updated runtime support to require Node.js 22. ## [0.31.0] - 2026-09-08 - Added portable reasoning controls with named modes and effort levels, including validation and updated reasoning documentation. - Redesigned `axle-cli` around interactive chat by default, with batch and resume commands, persistent sessions, and improved terminal rendering. - Added CLI session resumption, automatic context compaction, and configurable compaction size controls for longer-running conversations. - Added layered CLI configuration loading and validation, support for the v3 job configuration schema, and timestamped CLI log files. - Improved CLI reliability for piped input, non-interactive runs, interrupted runs, failed batches, session cleanup, and credential handling. - Updated available model definitions. ## [0.30.2] - 2026-08-23 - Added support for OpenRouter streaming thinking deltas so reasoning output is handled correctly during chat completions. - Added reasoning option support for prompt compaction, enabling thinking-capable model configurations during compaction. - Updated available model definitions. ## [0.30.1] - 2026-08-13 - Fixed `PromptCompactor` progress reporting and summary handling so completed compactions are reported reliably without duplicating generated summaries. ## [0.30.0] - 2026-08-13 - **Breaking:** replaced agent-owned history with host-owned transcripts: use `agent.messages` for active conversation state and attach a `Transcript` to the event stream for persistence. - **Breaking:** renamed `TurnAccumulator` to `Transcript` and updated the related transcript exports and persistence APIs. - **Breaking:** removed built-in memory APIs and automatic recall/record behavior; use tools for model-directed memory and `Instruct.addContext()` for host-provided context. - **Breaking:** removed session-level annotations and transcript state; annotations now belong to turns or parts, with session-wide application state kept by the host. - **Breaking:** refactored compaction into trigger, policy, and compactor layers with stateful compaction parts and `compaction:update`/`complete`/`error` events; automatic compaction failures are now recorded without failing the user turn. - Improved `PromptCompactor` progress reporting and summary handling so repeated compactions avoid reusing prior summaries. - Updated the README, terminology docs, and 0.30.0 migration guide. ## [0.29.0] - 2026-08-05 - Added Qwen 3.7 Flash and Qwen 3.8 Max model definitions. - Updated Qwen model metadata with larger output limits for selected Qwen 3.6 and 3.7 models. - **Breaking:** renamed tool-loop terminology from “turn” to “step”: `maxIterations` is now `maxSteps`, `"max-iterations"` is now `"max-steps"`, stream events are now `step:start`/`step:complete`, and `generateTurn` is now `generateStep`. - Added a 0.29.0 migration guide and terminology reference for the step/turn naming changes. ## [0.28.0] - 2026-07-27 - Added `agent.stop()` to stop an active turn at the next tool-batch boundary without interrupting in-flight work. - Added `agent.clear()` to cancel queued agent operations while leaving the active turn untouched. - Added `PromptCompactor` and automatic before/after-turn compaction triggers for easier long-session management. - Improved compaction cancellation, history handling, and messages for repeated compactions. - Updated available model definitions and fixed Gemini thinking configuration for newer Gemini 3.x models. ## [0.27.1] - 2026-07-17 - Added support for the Kimi K3 model. ## [0.27.0] - 2026-07-10 - Improved model registry support for clearer model selection. - Updated TypeScript support and improved type narrowing definitions. ## [0.26.1] - 2026-07-09 - Fixed OpenAI tool schemas so optional properties are accepted correctly. - Improved generation failure handling and exposed the clearer `AxleFailure` name while keeping `GenerateError` as an alias. - Improved stream turn accumulation error handling for more reliable failures. - Removed the Gemini 3.5 Pro model option. ## [0.26.0] - 2026-07-06 - Added experimental context compaction: `agent.onCompaction(callback)` supplies the policy and strategy, `await agent.compact()` triggers it. Active history is replaced; `agent.history` now exposes `messages` (active), `archive` (raw append-only), and `compactions` (receipts). Compaction renders as an agent turn containing a new `compaction` part and emits `compaction:start`/`compaction:end` turn events. - Added `maxContextTokens` to `stream()`/`generate()`: a token budget for the tool loop, checked after each turn settles. - **Behavior change:** loop limits are stops, not errors. `maxIterations` and `maxContextTokens` return `ok: true` with `stopped: "max-iterations" | "token-limit"` instead of an error result. Non-positive limits throw at call time. - **Breaking:** `agent.history.log` is now `agent.history.messages`. - **Breaking:** `agent.snapshot()` is now async; it waits for in-flight work to settle so snapshots are always at rest. - **Breaking:** removed `Agent.restore()`; resume with `new Agent(config, session)`. - **Breaking:** removed `index` from `StreamEvent`. Correlate tool events by `id`; text/thinking deltas belong to the most recently opened part. - **Breaking:** removed the `createHandle` export. - Added an `agent-compaction` baseline check exercising compaction end to end against live providers. ## [0.25.5] - 2026-07-03 - Add Claude Fable, Sonnet 5; Gemini 3.5 models ## [0.25.4] - 2026-06-17 - Improved `parallelize` handling for more reliable batched tool execution. ## [0.25.3] - 2026-06-16 - Fixed OpenAI file handling so filenames and URLs are resolved correctly. ## [0.25.2] - 2026-06-15 - Fixed tool calls with syntactically invalid JSON parameters so they are handled gracefully instead of failing. ## [0.25.1] - 2026-06-13 - Consolidate vendor options for ChatCompletions ## [0.25.0] - 2026-06-12 - Added a web search fallback for more reliable search behavior. - Improved handling of non-text tool results. ## [0.24.0] - 2026-06-11 - Added experimental subagent tools for delegating bounded work to other agents, with child turn-event forwarding (`action:child-event`). - Added experimental parallel tool execution for running batched tool calls concurrently. - Added tool context helpers for reporting usage and adding contextual information during runs, including a flat per-provider/model `Stats.breakdown`. - Added the `tool:exec-error` stream event for fatal/aborted tool calls; `Agent.on()` now returns an unsubscribe function. - **Behavior change:** in `stream()`, a user-provided `onToolCall` returning `null`/`undefined` now falls through to executing the matching registry tool (matching `generate()`'s existing semantics) instead of producing a `not-found` result. - **Behavior change:** a tool throwing an error merely named `AbortError` while the run's signal is live is reported to the model as an ordinary tool error instead of aborting the run. - Fixed output fencing in generated content. ## [0.23.1] - 2026-06-08 - Updated Anthropic thinking configuration support ## [0.23.0] - 2026-06-08 - Improved observability with a simplified span-based tracing interface - Added richer trace events, span completion details, and token/content logging for agent and streaming runs - Added provider tool logging and support for routing observability data to multiple sinks ## [0.22.1] - 2026-06-07 - Improved handling of chat-completions streaming errors - Fixed Gemini citation handling ## [0.22.0] - 2026-06-06 - Added support for OpenRouter web search citations - Improved citation handling for web search results - Fixed tool handling for interleaved tool calls ## [0.21.0] - 2026-05-30 - Added support for Opus 4.8 - Added support for citations and thinking formats - Added configurable retry options - Added a convenience method for rehydrating agents - Added metadata support for turns and messages ## [0.20.0] - 2026-05-25 - Split the library and CLI into separate packages for clearer installation and usage - Added `AgentSession` and snapshot restore APIs for saving and resuming agent sessions - Added `createAgentConfig` for easier agent configuration - Updated memory handling so memory is managed separately from `AgentConfig` - Added documentation updates and removed Brave-related docs/support ## [0.19.0] - 2026-05-24 - Added a browser-only export for client-side bundles that omits server-only code - Added annotations support to Turns ## [0.18.0] - 2026-05-22 - Added support for Gemini 3.5 Flash - Standardized request options across providers, including output tokens, temperature, top-p, stop sequences, tool choice, and provider-specific options - Renamed provider option types and runtime parameters; see the 0.18.0 migration guide for update details - Updated usage stats to include cached tokens and thinking tokens - Added a simple context counter and split MCP tools for more flexible tool usage - Fixed bugs found during smoke testing ## [0.17.0] - 2026-05-13 - Updated the Instruct constructor to use object-style options - Improved Instruct schema typing to support any Zod schema - Added clearer errors for missing template variables - Improved result ergonomics for easier handling by applications ## [0.16.3] - 2026-05-13 - Added vars mode to Instruct for easier variable-based prompting - Fixed bugs found through live provider testing ## [0.16.2] - 2026-05-11 - Fixed OpenAI and Chat Completions providers: `reasoning: false` now sends no reasoning effort instead of minimal reasoning ## [0.16.1] - 2026-05-11 - Added `z.enum` and `z.literal` support to Instruct structured-output schemas ## [0.16.0] - 2026-05-11 - Added `instruct` support to generate and stream APIs for supplying structured instructions directly - Updated structured output instructions to use JSON for more reliable parsing - Added open-weight model options - Improved cancellation behavior by propagating abort signals through MCP tool calls ## [0.15.1] - 2026-05-08 - Added `AxleToolFatalError` for fatal tool failures, allowing generation, streaming, and agent runs to stop immediately without retrying or exposing the error to the model - Fatal tool errors now preserve available partial output, messages, usage, and tool context for easier handling by applications ## [0.15.0] - 2026-05-08 - Abort operations now throw errors, making cancellation behavior easier to detect and handle ## [0.14.0] - 2026-05-07 - Simplified the Agent and Instruct APIs for easier use and better TypeScript support - Added support for binding inputs to Instruct templates with `withInputs`, `withInput`, and `clone` - Improved template variable handling by consistently reporting missing required variables ## [0.13.0] - 2026-05-06 - Added provider tool registries for configuring and organizing available tools - Added streaming support for tool outputs and tool arguments - Improved tool execution with abort-signal support and streamed command output - Updated available models ## [0.12.0] - 2026-04-30 - Added basic thinking/reasoning support to the generation API - Added file support improvements: better `FileInfo` types, improved image type checks, file data support in chat completions, and new usage examples - Removed `instructions` as a concept from `Instruct`, simplifying the interface ## [0.11.0] - 2026-04-24 - Added support for OpenAI models - Provider models are now exported from the package ## [0.10.2] - 2026-04-24 - Added timing information to agent/generation output - Added support for Claude Opus 4.7 ## [0.10.1] - 2026-04-07 - Update distribution artifacts and config ## [0.10.0] - 2026-04-05 - Agent now emits Turns, with an updated agent interface to match - Agent history now carries both Turn and Message parts in parallel, improving fidelity when converting between representations - Added configuration support to hooks - Improved error semantics and error reporting for tool-call not found cases - Fixed a bug where history could be incorrectly committed when a cancellation was in flight - Updated to latest dependencies and models ## [0.9.0] - 2026-02-22 - Added procedural memory support, allowing agents to retain and recall information across interactions - Made the tool call callback optional when using `generate`, reducing boilerplate for simple use cases - Simplified tracing interfaces for easier integration and usage --- # Upgrading Source: https://axle.fifthrevision.com/upgrading _Breaking changes by version, and where to find the full migration guides._ Every release has a full migration guide in the repository under [`docs/`](https://github.com/johncch/axle/tree/main/docs), one file each from `0.13.0-migration.md` through `0.37.0-migration.md`. This page is the map to them — what changed, and which ones you actually need to read. Current release: **0.37.0**. ## 0.37.0 — the reasoning setting, JSON Schema instructs, onStep, analyze The full guide is [`docs/0.37.0-migration.md`](https://github.com/johncch/axle/blob/main/docs/0.37.0-migration.md) in the library repo. Read it end to end if you pass `reasoning`, use an `Instruct` schema, drive a remote agent, or construct `StreamEvent`s or `CatalogData` by hand — all four change shape. **`reasoning` is `"default"` or `{ enabled?, effort?, display? }`; `"off"` and `"on"` are gone.** `ReasoningSetting` was `"default" | "off" | "on" | { effort, display? }` and is now `"default" | { enabled?, effort?, display? }`. `ReasoningEffort` was `"low" | "medium" | "high"` and is now `"minimal" | "low" | "medium" | "high" | "xhigh" | "max"`, sent to the provider as written. Exhaustive switches and `Record` gain three members; `xhigh` and `max` no longer need `providerOptions`. ```typescript // @check-skip — shows the pre-0.37 API reasoning: "off"; reasoning: "on"; reasoning: { effort: "high" }; ``` becomes: ```typescript import { Agent } from "@fifthrevision/axle"; declare const provider: import("@fifthrevision/axle").AIProvider; new Agent({ provider, model: "claude-sonnet-4-5", reasoning: { enabled: false } }); new Agent({ provider, model: "claude-sonnet-4-5", reasoning: { effort: "medium" } }); new Agent({ provider, model: "claude-sonnet-4-5", reasoning: { effort: "high" } }); ``` `"on"` meant medium, which many models lack — there is no setting that means "on" for every model. When the model is chosen at run time, ask the catalog what to send: ```typescript declare const thinkingOn: boolean; const found = catalog.reasoningControl(model, { provider: "anthropic" }); new Agent({ provider, model, reasoning: thinkingOn ? (found?.suggested ?? { effort: "medium" }) : { enabled: false }, }); ``` `{ enabled: true }` turns thinking on without naming a depth where the provider has a switch (Anthropic, Together AI, OpenRouter, Gemma 4 on Gemini) and throws `INVALID_OPTIONS` elsewhere. An object that sets neither `enabled` nor `effort`, or sets `enabled: false` beside an effort, is rejected. Saved `CatalogData` is version 5 — a file saved by 0.36 is refetched, like any older copy. See [Reasoning models](/cookbook/reasoning). **An `Instruct` schema is a JSON Schema.** `OutputSchema` was `z.ZodTypeAny` and is now a Standard Schema object (Zod 4.2+, ArkType, and others) or a plain JSON Schema object. A Zod schema keeps working unchanged and `response` keeps its type; code that names the type and calls Zod methods on it (`schema.parse()`, `schema.shape`) needs its own Zod type. The prompt carries the JSON Schema in place of the old field list plus example object, so constraints like `.min()` and `.regex()` now reach the model, and schemas that used to throw (`.nullable()`, unions, tuples, records, `z.email()` and other formats, non-object roots) are accepted. With `.transform()` the model is shown the input side and a defaulted key is not required. `InstructInputs` is `Record` — render dates and arrays to strings yourself, and pass `null` instead of `undefined`. `parseResponse()` and `Instruct.parse()` return a promise: ```typescript declare const reply: import("@fifthrevision/axle").AxleAssistantMessage | undefined; const parsed = await parseResponse(text, schema); const same = await instruct.parse(reply); ``` `instruct.render()` returns the prompt alone — the schema is stored on the message as `output`. New `Instruct.toJSON()` / `Instruct.fromJSON()` round-trip an `Instruct` as data. A remote `send` command carries that data (`{ type: "send", id, instruct }`) instead of a rendered prompt: a 0.36 client and a 0.37 host do not interoperate, so deploy both sides together. A host's `send` case becomes `agent.send(Instruct.fromJSON(command.instruct), { id: command.id })`. See [Instruct](/concepts/instruct) and [Remote agents](/concepts/remote-agents). **`agent.onStep()` saves usage and state mid-turn.** The awaited hook fires at the end of each step — however it ended — with `{ turnId, index, usage, messages, signal }`, and the agent waits before sending the next request. `stream()` has the same hook as `handle.onStep(callback)` with `{ usage, messages }`. A step's `usage` is the early copy; `turn:end` carries the authoritative totals. `agent.session` returns `{ sessionId, messages }` synchronously and works inside `onStep`, `onStart`, `onSettled`, continuations, and tools — read it there instead of awaiting `snapshot()`, which is deprecated. Custom `StreamHandle` implementations add `onStep`. See [Agent](/concepts/agent) and [Sessions & persistence](/concepts/sessions). Additions with no migration cost: `@fifthrevision/axle/analyze` (`analyze()`, the `failed` / `completed` / `cancelled` / `byUser` / `byAgent` / `named` predicates, `streaks` / `repeats` / `sum` / `flatten` / `partOf` / `simplify` — see [Analyzing a conversation](/concepts/analyze)); `Turn` and `turn:end` gain `error` (`{ message, code? }`, for a thrown error) and `cancelReason` (`{ type: "timeout", limitMs }`); text and thinking stream events gain a required `index` (custom `StreamHandle` fixtures and hand-built events add it); `agent.messages` grows as each step ends; `turn:end` usage includes failed requests and keeps subagent rows in call order; a failed or cancelled MCP tool listing keeps its user message and ends the turn `error` / `cancelled` instead of dropping the send; a failed subagent's tool error names the failure kind and message. `CatalogData` version 5 entries may carry `reasoningOptions`, read through `ModelCatalog.reasoningControl()`. ## 0.36.3 — a cancelled response keeps only what was written No signature changes. The full guide is [`docs/0.36.3-migration.md`](https://github.com/johncch/axle/blob/main/docs/0.36.3-migration.md) in the library repo. **A turn cancelled (or timed out via `turnTimeoutMs`) while the model was still writing its response now keeps only the parts something was written to.** Through 0.36.2, the partial assistant message kept every part the response had opened: a tool call that had started streaming stayed with no result, and a text part opened but not yet written to stayed as an empty string. The next request carried them and providers rejected it, so after one such turn every later send on that agent failed. From 0.36.3 a `tool-call` part is never kept (finished arguments included), a `text` part is kept only when its text is non-empty, and a `thinking` part only when it holds text, a summary, redacted content, or `continuity`. Written text and thinking are kept as before, and a step that completed is unaffected — its tool calls are answered as 0.36.2 describes. When nothing was written, `error.partial` is `undefined` and no assistant message is added (`agent.messages` stays at `["user"]`), so code that reads `error.partial` unconditionally needs a guard. Code that read `error.partial` to see which tool the model was about to call no longer finds it there — the `tool:request` and `tool:args-delta` stream events still fire, and the turn still holds the action part, settled `cancelled`. A session saved by an earlier version that already ends in an unanswered tool call or an empty text part is not repaired — remove the trailing assistant message before sending on it again. **Anthropic thinking parts carry `continuity` only once a signature or redacted data has arrived.** Through 0.36.2 a thinking part started with `continuity: { provider: "anthropic", signature: "" }` on `thinking:start`, and gained the real signature later. From 0.36.3 `continuity` is absent until the signature (or redacted data) arrives with a `thinking:update`. Code that tested `part.continuity` to find a signed thinking part now works without also checking the signature. Requests are unchanged: unsigned thinking was never sent back. ## 0.36.2 — a tool batch that ends early answers every call No signature changes. The full guide is [`docs/0.36.2-migration.md`](https://github.com/johncch/axle/blob/main/docs/0.36.2-migration.md) in the library repo. **A tool batch cut short by a cancel or a fatal error still commits its tool results message.** Through 0.36.1, cancelling a turn (or a `turnTimeoutMs` elapsing) while a tool was running — or a tool throwing `AxleToolFatalError` — left the assistant's tool-call message with no tool results message behind it. The next request carried those calls unanswered and providers rejected it, so after one such turn every later send on that agent failed. From 0.36.2 the message is written before the error is thrown, with one result per call in request order: a call that returned keeps its real result, a call that threw `AxleToolFatalError` gets an `isError` result with `{"error":{"type":"fatal","message":…}}`, and a call cut short by the abort gets an `isError` result with `{"error":{"type":"cancelled","message":…}}`. The send still rejects with the same error (`AxleAbortError`, `AxleAgentAbortError`, or `AxleToolFatalError` from `stream()`, `generate()`, and `agent.send()`) and makes no further request — only what the rejection leaves behind changes. `agent.messages` and the error's `messages` now end in the `tool` message (`["user", "assistant", "tool"]` on the agent; `["assistant", "tool"]` on the error), so code that assumed the last message after a cancelled turn is the assistant's needs updating, and a follow-up send is accepted. A session saved by an earlier version that already ends in unanswered tool calls is not repaired — drop the trailing assistant message, or append a tool results message for its calls, before sending on it again. ## 0.36.1 — Anthropic documents no longer return citations One breaking behavior change, no signature changes. The full guide is [`docs/0.36.1-migration.md`](https://github.com/johncch/axle/blob/main/docs/0.36.1-migration.md) in the library repo. **Anthropic documents are sent without asking for citations, and answers arrive as plain text.** Every PDF or text document sent to Anthropic used to carry `citations: { enabled: true }`, so an answer about one could arrive as several text parts each carrying `citations` with `source.type` `"document"`. Axle no longer asks, and there is no option to turn it back on — the answer arrives as plain text parts. Citations from hosted web search are unchanged on every provider. A conversation stored by an earlier version can still hold answers with document citations: they stay on the stored messages, and Axle leaves them out of the requests it sends to Anthropic (which would otherwise reject a replayed document citation with a 400). If your UI rendered `document` citations, keep the case — old history can still carry it. ## 0.36.0 — deferred tools, the operation lifecycle, remote agents The full guide is [`docs/0.36.0-migration.md`](https://github.com/johncch/axle/blob/main/docs/0.36.0-migration.md) in the library repo. Read it end to end if you use `onToolCall`, switch exhaustively on turn events, or save in `onSettled` — all three change shape. **`onToolCall` answers deferred tools, and takes a call.** The old `onToolCall(name, parameters, ctx)` ran before every tool's `execute` and could replace any result. It now receives one `DeferredCall` (`{ id, name, input }`, with `input` already validated) plus the `ToolContext`, returns what an `execute` returns, and is consulted only for tools with `type: "deferred"`. Executable tools run through their own `execute` unconditionally. A callback that answered calls to names with no registered tool now has no effect on them — register a `DeferredTool` under that name to keep answering it. To return an error result, throw; a branch that returns nothing leaves the call waiting for `toolCall(id)`, the tool's `timeout`, or cancellation. There is no `unanswered` error result anymore (`generate()` still fails fast, with an `execution` error naming the tool). ```typescript // @check-skip — shows the pre-0.36 API stream({ tools: [search], onToolCall: async (name, params) => name === "search" ? { type: "success", content: await lookup(params) } : null, }); ``` becomes a deferred tool answered by the new shape: ```typescript import type { DeferredTool, ExecutableTool } from "@fifthrevision/axle"; import { isCall } from "@fifthrevision/axle"; declare const search: ExecutableTool; const askUser = { type: "deferred", name: "ask-user", description: "Ask the person a question", schema: z.object({ question: z.string() }), } satisfies DeferredTool; stream({ tools: [search, askUser], onToolCall: (call) => { if (!isCall(askUser, call)) return; return prompt(call.input.question); }, }); ``` **`onSettled` fires once per operation, after the continuation.** It used to fire after every turn — the send's turn, then each inline turn under its own id. Now it fires once per send or manual compaction, after the continuation returns and before the handle settles, with what the handle settles with. A callback that filtered out inline ids drops the filter; one that saved after each inline turn moves that work into the continuation. Inline turns fire no hook of their own, and carry the send's id as `threadId` on their user turn and `Turn`. **`agent.on` delivers the operation lifecycle; `TurnEventCallback` is gone.** Beside the turn events, `on` now emits `operation:start { id, kind }`, `after:start { id }` / `after:end { id }` around a continuation, `operation:end { id, outcome }`, and `agent:idle`. The callback type is `AgentEventCallback`; `TurnEventCallback` is removed — rename the annotation. Exhaustive switches gain cases, and so do switches on `StreamEvent.type` (`tool:waiting`), `TurnEvent["type"]` (`action:waiting`), and part `kind` (`deferred`). `agent.status` (`{ phase: "idle" }` or `{ phase: "busy", id }`) reports what the agent is doing, and already reads the new value when the event that moved it is delivered. New `agent.onStart()` runs before an operation's turn opens and can refuse it by throwing. **`ctx.send()` no longer accepts `signal`.** In 0.35.0 the type accepted it and the agent ignored it. Remove the option and cancel the operation (the handle's `cancel()` or `agent.cancel()`) to abort an inline turn. `send()` accepts an `id` for its user turn, and `AgentConfig` / `SendMessageOptions` gain `turnTimeoutMs` (bound a whole turn, deferred waits included) and `streamStallMs` (fail a step on a silent provider stream) — both unset by default. Additions with no migration cost: deferred tools and `toolCall(id)` on `stream()` handles and `Agent` (`generate()` has no handle, so nothing outside its handler can answer); experimental remote agents (`RemoteAgent` over `httpTransport` or `loopbackTransport`, `InMemoryEventStore` and `toEventStreamResponse` on the served side — see [Remote agents](/concepts/remote-agents)); `turn` gains `threadId` and `cursor`; `send()` gains `id`. ## 0.35.0 — errors that throw, providers as protocol + id, per-request usage, continuations The full guide is [`docs/0.35.0-migration.md`](https://github.com/johncch/axle/blob/main/docs/0.35.0-migration.md) in the library repo. Read it end to end — this is the largest breaking release since 0.30.0. **`AxleFailure` is `AxleProviderFailure`, and `model` is two kinds.** `result.error.kind` is now `api | incomplete | refusal | parse`. `api` is a rejected/failed request (with `status` when there was one); `incomplete` is a completed request that stopped without a usable end (with `usage`). Update `switch` exhaustiveness checks and `error.type === "Error"` setup-fix branches. **Setup mistakes throw.** Bad options, unsupported features, unreadable files, and unconnected MCP calls throw `AxleError` with a `code` (`INVALID_OPTIONS`, `PROVIDER_UNSUPPORTED`, `FILE_UNREADABLE`, `MCP_NOT_CONNECTED`, …) before any request. Move config-fix code from `if (!result.ok)` into `catch`, guarded by `isAxleError(error)`. A bad key still resolves `ok: false` as `api`/`authentication`. **Providers split into `protocol` + `id`.** `AIProvider.name` is gone. Use the protocol constructors — `messages({ baseUrl, apiKey, … })`, `responses(…)`, `generateContent(…)`, `chatCompletions({ baseUrl, apiKey, id?, dialect? })` — or the presets `anthropic()`, `openai()`, `gemini()`, `openrouter()`, `togetherai()`, `bedrock()`. First-party `baseUrl` moved to the constructors (SDK env vars no longer redirect presets); `chatCompletions()` takes one options object and `vendor` is now `id` + `dialect` (`openrouterDialect` / `togetheraiDialect` behind a proxy). `FileResolver` and `PROVIDER_UNSUPPORTED` details name `protocol`, and `UsageEntry.provider` is the `id`. **`ModelCatalog` is built from data.** `ModelCatalog.open()`, `cachePath`, `ready`, `refresh()`, `state`, `hosts`, and ` inferChatCompletionsVendor` are gone. New flow: `catalogFile(path)` storage + `new ModelCatalogStore({ providers })` → `load()` → `refresh()`/`refreshIfStale()` → `current`. `fetchModelsDev()` fetches `CatalogData` (version 4); `parseCatalogData()` reads saved JSON; `lookup`/`contextWindow` take `{ provider }`. New `computeCost(usage, catalog)` prices each row at its own tier. **`usage.breakdown` is per request, and required.** Rows carry `agent`, `at`, and `requestedModel`; totals are unchanged. Group rows to aggregate (don't key tables by `provider + model`). Hand-built `Stats` need rows — use `attributeStats()`. `FileResolver`-style custom usage and `ctx.reportUsage` must include `requestedModel`. **Turns and events.** `turn.error` and the `error` event are gone — read `turn.failure` / `turn:end`'s `failure`. `turn:end` also carries `reason` (`stop` | `length`). Cancelled tool calls are `action:cancelled` (`status: "cancelled"`), cancelled compactions are `compaction:cancelled`, and `CompactionPart` gains `trigger`. `AgentDefinition`/`createAgentConfig()` are removed — rebuild `AgentConfig` from your own recipe shape. New `after` continuations run inline turns after the send settles (see [Agent](/concepts/agent#after-continuations-run-after-the-turn-settles)). ## 0.34.3 — tool arguments validated before `execute` No signature changes and no migration guide — nothing to rename. This is a behavior change inside `execute` dispatch, worth reading because what your `execute` receives is now the schema-parsed value rather than the raw parameters. **Invalid tool arguments no longer reach `execute`.** Each call's parameters are parsed with the tool's schema first. When they don't match, `execute` is not called and the model gets an error tool result with type `validation` — `Invalid arguments for getWeather: city: Invalid input: expected string, received undefined` — which it can correct in the same turn. Previously the raw parameters went straight to `execute`, so a missing or mistyped argument surfaced as your own runtime error (usually an `execution` tool error) rather than a structured validation message. **`execute` now receives the parsed value.** Schema defaults and transforms apply before your code runs — a `z.number().default(10)` field your tool declares arrives as `10` when the model omits it, and a `.transform()` runs first. If your `execute` was defensively applying its own defaults, the schema value wins; keep them consistent. **A parallelized tool's call is rejected as a whole when any item is invalid.** `parallelize()` builds `{ items: [...] }` from the wrapped tool's schema, so one bad item fails validation before any item runs, with the item's path (for example `items.2.question`) in the message. Per-item execution failures after validation still report per item. **MCP tools are validated too.** Unknown top-level keys are stripped before the call reaches the server — matching a default `z.object()` — rather than rejected. ## 0.34.1 — prompt caching on by default No signature changes. `AxleModelRequestOptions` gains an optional `cache` flag, and the default request now asks for caching where asking is required. The migration guide is [`docs/0.34.1-migration.md`](https://github.com/johncch/axle/blob/main/docs/0.34.1-migration.md) in the library repo. **Anthropic and OpenRouter requests now carry `cache_control`.** Every request from `Agent`, `generate()`, and `stream()` to the Anthropic provider — and every chat-completions request to the OpenRouter vendor — carries a top-level `cache_control: { type: "ephemeral" }`. Before 0.34.1 nothing did, so no Anthropic request through Axle was ever served from cache. In a tool loop each step reads the conversation so far at 0.1x and writes only the new tail at 1.25x; a one-shot prompt that is never repeated pays a 25% write premium for no read, and a prompt under the model's minimum cacheable length is silently not cached. `usage.cachedIn` and `usage.cacheWriteIn` now carry non-zero values on these providers. Pass `cache: false` (on the `Agent`, or per `generate()` / `stream()` call) to omit the field — it means "do not ask", not "do not cache", so OpenAI, Gemini, and Together, which cache automatically, are unaffected by either value. An explicit `providerOptions.cache_control` still wins over the default, which is how a host gets Anthropic's one-hour TTL. See [Providers & models](/concepts/providers#prompt-caching). **`stream()` and `generate()` without a `sessionId` get one for the call.** OpenRouter forwards the cache field to the upstream host, and a hit needs the next request to reach the same host — which OpenRouter pins by `session_id`. From 0.34.1 a bare call generates an id and sends it on every step of its own tool loop, so step 2 onward reads what step 1 wrote. Two separate calls still get two ids; pass the same `sessionId` to both to get reads across them. `Agent` always sends its own `sessionId`, so agent loops are unchanged. **Together cached-token usage is recognized.** Some Together models report hits as a top-level `usage.cached_tokens` instead of inside `prompt_tokens_details`; the usage mapping now reads both, so `cachedIn` reflects it. Nothing to change on your side. ## 0.34.0 — pending turns, skills, provider-owned search Eleven breaking changes in the library surface (plus CLI changes, which are out of scope for this site). The migration guide is [`docs/0.34.0-migration.md`](https://github.com/johncch/axle/blob/main/docs/0.34.0-migration.md) in the library repo. **`TurnEvent` gains `pending:queued` and `pending:dropped`.** The Agent now announces a `send()` or manual `compact()` when it is accepted, and again if it ends before opening its turn. A `switch` over `event.type` with an exhaustiveness check stops compiling until it handles both; a renderer that has no use for them can ignore them, since `Transcript.apply` already folds them. The first event of a send is now `pending:queued`, not `turn:user`. **`TurnStatus` and the compaction part's status gain `"pending"`.** A queued operation previews as a `Turn` with `status: "pending"` — a user turn a send will commit, or an agent turn with one `pending` compaction part for a queued manual compaction. Pending turns live only in `transcript.pending`, never in `turns`, so a renderer that reads `turns` alone can treat the case as unreachable. **`StreamParams.registry` is removed; pass `tools` and `providerTools`.** The loop builds every request from the values it was given and never reads a registry, so a tool added to a `ToolRegistry` after the call no longer appears mid-loop. To change tools or the prompt mid-loop, return them from `onToolBatchComplete`, which may now return `{ system?, tools?, providerTools? }` (typed as `ToolBatchDecision`). Passing `registry` is a type error, and the `TOOL_OPTIONS_CONFLICT` error no longer exists. **`ToolContext.registry` is gone.** A tool's `execute(input, ctx)` no longer receives `ctx.registry`. A tool that changes the agent it runs under uses that agent in closure scope: `agent.registry.add(...)`, `agent.skills.add(...)`. **`configureAxle` and the web search fallback are gone.** Web search on a provider without hosted search is now a tool attached to the `chatCompletions()` provider that needs it — `chatCompletions(url, { apiKey, webSearch: braveWebSearch({ apiKey: braveKey }) })` — instead of a process-wide setting. `braveWebSearch()` returns an `ExecutableTool` named `web_search`, and `WebSearchBackend`, `WebSearchRequest`, `WebSearchResponse`, and `AxleConfiguration` are removed. The `providerTools: [{ type: "provider", name: "web_search" }]` request is unchanged. A `chatCompletions()` provider asked for a provider tool it cannot serve now fails the request (`ok: false`, `error.kind` `"api"`, no error code) instead of dropping the tool or throwing `WEB_SEARCH_FALLBACK_NOT_CONFIGURED`. **`AIProvider.resolveProviderToolName` is gone; `AIProvider.tools` is added.** The loop no longer asks a provider whether it supports a provider tool. A custom `AIProvider` that implemented `resolveProviderToolName` can delete it; a custom provider that relied on the fallback now lists the tool in `AIProvider.tools`, which the loop runs when the caller's tools have no tool of that name. `ResolvedProviderTool` and `nativeName` are gone. **`agent.system` is read-only.** It is now a getter returning the configured system prompt plus the skills catalog when skills are present. Code that assigned `agent.system = ...` stops compiling; set the prompt at construction. **The Together vendor id is `togetherai`.** `chatCompletions()`'s `vendor` option takes `"togetherai"` where it took `"together"`, matching the id models.dev uses. Only an explicit `vendor` needs editing; the official Together hostnames are still recognized without it. **`zod` is a peer dependency.** Axle requires `^4.2.0` and uses your project's copy. npm 7+ and pnpm install a missing peer automatically; Yarn Classic does not, so add it by hand. The ranges of Axle's other dependencies are wider, so an existing provider SDK install is reused instead of duplicated. **`snapshot()` waits for idle instead of taking a place in the queue.** It resolves at once when the Agent is idle, otherwise when the Agent next goes idle — so `send("a"); const s = agent.snapshot(); send("b"); await s` now holds both turns, not just `"a"`. `clear()` no longer cancels a waiting snapshot. To save after each operation, use the new `onSettled` hook. **`chatCompletions()` requests time out after ten minutes per attempt**, and a timeout now fails as `TimeoutError` (`"Request timed out after ms"`) instead of `AbortError` (`"Request aborted"`). Code that matched `AbortError` to detect a timeout should match `TimeoutError`. Additions in 0.34.0 (not breaking): `agent.skills` (`SkillRegistry` with `add`, `remove`, `set`, `has`, `get`, `list`, `size`), `agent.onSettled()` and `agent.onIdle()`, `agent.cancel()`, `Transcript.pending` (plus `new Transcript(turns, pending)`), `fetch` in every provider factory's client options, `ModelCatalog` context-window lookup, and experimental typed decisions with `decide()` and the `typesafe()` provider. See [Skills](/concepts/skills), [Decisions](/concepts/decisions), and the [migration guide](https://github.com/johncch/axle/blob/main/docs/0.34.0-migration.md). ## 0.33.0 — no registry, flat failures, portable provider tools Six breaking changes in the library surface (plus CLI changes, which are out of scope for this site). The migration guide is [`docs/0.33.0-migration.md`](https://github.com/johncch/axle/blob/main/docs/0.33.0-migration.md) in the library repo. **The model registry is removed.** The `@fifthrevision/axle/models` entry point no longer exists — no `Models`, no `ModelInfo`, no `ModelMetadata`. Pass model IDs as plain strings (`"openai/gpt-5.5"`); first-party providers still accept both the publisher-qualified form (`"openai/gpt-5.5"`) and the bare id (`"gpt-5.5"`). An application that needs a context window or an output ceiling keeps its own table or asks the provider's models API. OpenRouter IDs are sent unchanged — the alias table (`zai/glm-5.3` → `z-ai/glm-5.3`) is gone, so pass the slug OpenRouter lists. ```typescript // @check-skip — shows the pre-0.33 API import { Models } from "@fifthrevision/axle/models"; const model = Models.OpenAI.GPT_5_5; ``` ```typescript const model = "openai/gpt-5.5"; ``` **`temperature`, `topP`, and `stop` are removed.** They are gone from `AxleModelRequestOptions`, and so from `generate()`, `stream()`, `Agent`, `agent.send()`, and an agent definition's `request` block. Send them through `providerOptions` using the provider's own field names: ```typescript // @check-skip — shows the pre-0.33 API await generate({ provider, model, messages, temperature: 0.2 }); ``` ```typescript await generate({ provider, model, messages, providerOptions: { temperature: 0.2 } }); ``` | Removed option | Anthropic | OpenAI | Gemini | Chat Completions | | --- | --- | --- | --- | --- | | `temperature` | `temperature` | `temperature` | `temperature` | `temperature` | | `topP` | `top_p` | `top_p` | `topP` | `top_p` | | `stop` | `stop_sequences` | not supported | `stopSequences` | `stop` | **Provider tool parts have one shape on every provider.** A `provider-tool` part now carries portable `input` and `result` plus per-provider `continuity`, and a new `provider-tool-result` part holds results that arrive a step later. There is a new `ConsoleOutput` shape for code execution output, and two new stream/turn events (`provider-tool:input`, `provider-tool:error` / `action:input`); `output` is gone from `provider-tool:complete`. See [Provider tools](/cookbook/provider-tools) and [Messages & parts](/reference/messages). **A refusal is its own failure kind.** `generate()`, `stream().final`, and `agent.send().final` now resolve `{ kind: "refusal", message, text?, category? }` when a provider declines or blocks output, instead of empty successes or mislabeled `model` failures. Code that switches over `error.kind` needs a `"refusal"` case. See [Results & errors](/concepts/results-and-errors). **Failures are flat, and a rejected key is `type: "authentication"`.** `AxleFailure` no longer nests under `error` — the `model` member carries `type`, `message`, `status?`, `usage?`, and `raw?` directly, `ModelError` is removed, the never-produced `tool` member is gone, and parse failures carry `cause` instead of `error`. HTTP 401 (and Gemini's `API_KEY_INVALID`) reports `type: "authentication"`. Chat Completions HTTP errors report the body's `error.type` / `error.message` with `status` alongside. See [Errors](/reference/errors). ```typescript // @check-skip — shows the pre-0.33 shape type AxleFailure = | { kind: "model"; error: ModelError; message: string } | { kind: "tool"; error: { name: string; message: string }; message: string } | { kind: "parse"; error: unknown; message: string }; ``` ```typescript type AxleFailure = | { kind: "model"; type: string; message: string; status?: number; usage?: Stats; raw?: unknown } | { kind: "refusal"; message: string; text?: string; category?: string } | { kind: "parse"; message: string; cause: unknown }; ``` **`AxleStopReason.Error` and `AxleStopReason.Custom` are removed.** `finishReason` is now `stop`, `length`, `function_call`, or `cancelled`. Unknown stop reasons fail the request instead of resolving `ok: true`. Behavior changes worth knowing: Anthropic `pause_turn` responses continue automatically within one step; `Agent` forwards its `sessionId` to OpenRouter; Anthropic's implicit `max_tokens` defaults to 128,000; adjacent text parts concatenate without separators; `web_search` resolves to newer provider versions (`web_search_20260318` with `allowed_callers: ["direct"]` on Anthropic, `web_search` on OpenAI) and Gemini searches surface a `provider-tool` part; OpenAI replays assistant items in order and truncations finish with `length`. [Full guide](https://github.com/johncch/axle/blob/main/docs/0.33.0-migration.md). ## 0.32.0 — thinking parts, disclosure control, one transport Three breaking changes, all on the reasoning surface, plus one removal. The migration guide is [`docs/0.32.0-migration.md`](https://github.com/johncch/axle/blob/main/docs/0.32.0-migration.md) in the library repo. **Turn thinking parts carry `summary` / `raw`, not `text` / `redacted`.** `ThinkingPart` on a turn now names each content field for what the provider handed back: `summary` is the provider's condensed account, `raw` is the chain of thought itself (open-weight models only). Neither present is the withheld state — render `summary ?? raw`. A part opens with no content field; a field appears only once a delta wrote it, so never test for `""`. Anthropic block content that used to land in `text` now lands in `summary`. The message-layer `ContentPartThinking` keeps the wire vocabulary (`text`, `summary`, `redacted`) because it exists to be echoed back, not read — and `redacted` there now means only that the provider substituted an opaque payload. ```typescript // @check-skip — shows the pre-0.32 shape interface ThinkingPart { text?: string; summary?: string; redacted?: boolean; } ``` ```typescript interface ThinkingPart { id: string; type: "thinking"; summary?: string; // the provider's condensed account raw?: string; // the chain of thought itself; open-weight models only } ``` Persisted 0.31 turns carry the old shape and Axle ships no shim — a host that stores turns decides whether to migrate rows or render both. **Thinking events are renamed and reshaped.** `thinking:delta` (stream and turn) is now `thinking:raw-delta`; the names say which field they grow. `thinking:summary-delta` and `thinking:update` keep their names but lose the `redacted` flag. Stream `thinking:start` loses `redacted` too, and stream `thinking:end` reports `{ summary?, raw? }` — each present only if written — instead of a single `final` string. | 0.31 | 0.32 | | --- | --- | | `thinking:delta` (stream and turn) | `thinking:raw-delta` | | stream `thinking:start` `.redacted` | removed | | stream and turn `thinking:update` `.redacted` | removed | | stream `thinking:end` `{ final: string }` | `{ summary?, raw? }`, each present only if written | **`reasoning` gains a `display` disclosure control.** The object form accepts `display: "visible" | "hidden"` (default `"visible"`): ```typescript type ReasoningSetting = "default" | "off" | "on" | { effort: ReasoningEffort; display?: ReasoningDisplay }; ``` `display` says whether the provider should show its thinking, never in what form — whether a summary or raw text comes back is the model's property, recorded on the thinking part. Enabling reasoning (`"on"` or `{ effort }`) now also requests disclosure wherever a request field exists (Anthropic `summarized`, OpenAI `summary: "auto"`, Gemini `includeThoughts: true`), so Claude and OpenAI models that previously streamed no thinking now do. To keep the 0.31 wire behaviour, pass `display: "hidden"` per request. Under `"hidden"` the turn receives no thinking content — the message keeps whatever the wire carried, so provider continuity still round-trips. Fine-grained values (OpenAI `concise` / `detailed`, Anthropic `updates`) stay in `providerOptions`; overriding `thinking` on Anthropic replaces the whole object, `type` included. **`generateStep` is removed.** The single non-streaming model request no longer exists — there is no non-streaming request to make. Call `stream()` with `maxSteps: 1` and read `final`, or `generate()` with the same option. Custom providers implement `createStreamingRequest` only; `createGenerationRequest` is gone from the `AIProvider` interface. Behaviourally, `generate()` is now exactly `stream().final`: Anthropic's implicit `max_tokens` on `generate()` rises to the model-registry ceiling (else 64,000), retryable failures surface at first byte, and `raw` on the error result preserves the adapter's raw error payload rather than the vendor's buffered response object. See [Reasoning models](/cookbook/reasoning) for the full story. [Full guide](https://github.com/johncch/axle/blob/main/docs/0.32.0-migration.md). ## 0.31.0 — portable reasoning & compaction sizing Two breaking changes, both in the request surface. The CLI was redesigned too, but it's out of scope for this site — see the library's [`packages/axle-cli/CHANGELOG.md`](https://github.com/johncch/axle/blob/main/packages/axle-cli/CHANGELOG.md) for that. **`reasoning` is a portable setting, not a boolean.** It was `reasoning?: boolean` on `Agent`, `generate()`, `stream()`, and `PromptCompactor`; it's now `reasoning?: ReasoningSetting`: ```typescript type ReasoningEffort = "low" | "medium" | "high"; type ReasoningSetting = "default" | "off" | "on" | { effort: ReasoningEffort }; ``` Booleans are now a type error. The nearest replacements and what changes on the wire: | 0.30 | 0.31 | What changes | | ------- | ---------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------- | | omitted | omitted or `"default"` | none; no reasoning fields are sent | | `true` | `"on"` | **medium effort, not high.** Pass `{ effort: "high" }` to keep the old depth. | | `false` | `"off"` | **Anthropic sends `thinking: { type: "disabled" }`** and **Gemini sends `thinkingBudget: 0`** instead of nothing; some always-thinking models reject it. | See [Reasoning models](/cookbook/reasoning) for the full story. [Full guide](https://github.com/johncch/axle/blob/main/docs/0.31.0-migration.md). **`PromptCompactor` sizing changed.** `targetTokens` and `recentUserMessages` are removed; `summaryWords` and `appendixTokens` replace them: ```typescript // @check-skip — shows the pre-0.31 API new PromptCompactor({ provider, model, prompt, thresholdTokens: 100_000, targetTokens: 30_000, recentUserMessages: 10, }); ``` ```typescript new PromptCompactor({ provider, model, prompt: "Summarize this conversation, preserving decisions and open questions.", thresholdTokens: 100_000, summaryWords: 1_500, // default 1000 appendixTokens: 15_000, // default: thresholdTokens / 10; 0 disables }); ``` The summary is steered in **words** (not capped by an output token budget), and the recent-user-message appendix is budgeted in **tokens** directly (not by message count). The summarizer request no longer sends `maxOutputTokens`, so thinking models summarize reliably at any reasoning setting. See [Compaction](/concepts/compaction). **Housekeeping:** the unused `FileStore` type export was removed. ## 0.30.0 — host-owned transcripts This is the big one — the largest breaking change in the library's history. If you're on 0.29 or earlier, it's worth reading [the full guide](https://github.com/johncch/axle/blob/main/docs/0.30.0-migration.md) rather than just this summary. **Transcripts moved to the host.** The agent no longer keeps renderable history. ```typescript // @check-skip — shows the pre-0.30 API // before — agent owned it agent.history; // after — you own it const transcript = new Transcript(); agent.on((event) => transcript.apply(event)); transcript.turns; ``` Use `agent.messages` for the active model-facing conversation. Persist `transcript.turns` alongside `agent.snapshot()` — the session no longer carries render state. See [Transcripts](/concepts/transcripts). **`TurnAccumulator` → `Transcript`.** Renamed, with the related persistence exports. **Built-in memory APIs removed.** There's no automatic recall/record behaviour any more. Replace it with tools for model-directed memory, and [`Instruct.addContext()`](/concepts/instruct#host-context-vs-your-prompt) for host-provided context. **Session-level annotations removed.** Annotations now attach to turns or parts instead. Session-wide application state is yours to keep. **Compaction restructured** into three layers — `triggers`, `shouldCompactOnTrigger`, and `compact` — with stateful compaction parts and `compaction:update` / `:complete` / `:error` events. Automatic compaction failures are now recorded on the transcript without failing the user turn. See [Compaction](/concepts/compaction). ## 0.29.0 — step terminology The tool-loop unit was renamed from "turn" to "step", because "turn" already meant the render-layer unit. | Before | After | | --- | --- | | `maxIterations` | `maxSteps` | | `"max-iterations"` | `"max-steps"` | | `turn:start` / `turn:complete` (stream events) | `step:start` / `step:complete` | | `generateTurn` | `generateStep` | If you're wondering why the rename happened: "turn" was already taken by the render layer, so the same word meant two different things. [Glossary](/glossary) has the current vocabulary. ## 0.28.0 - Added `agent.stop()` and `agent.clear()`. - Added `PromptCompactor` and automatic before/after-turn compaction triggers. ## 0.26.0 - **Loop limits became stops, not errors.** `maxSteps` and `maxContextTokens` return `ok: true` with `stopped` instead of an error result. Non-positive limits throw at call time. See [Results & errors](/concepts/results-and-errors#stops-arent-errors). - `agent.history.log` → `agent.history.messages` (and later `agent.messages`). - `agent.snapshot()` became async. - `Agent.restore()` removed — resume with `new Agent(config, session)`. - `index` removed from `StreamEvent`; correlate tool events by `id`. - `createHandle` export removed. ## 0.25.0 - Added the [web search fallback](/cookbook/web-search). ## 0.24.0 - Added experimental [subagent tools](/cookbook/subagents) and `parallelize`. - `Agent.on()` began returning an unsubscribe function. - **Behavior change:** in `stream()`, an `onToolCall` returning `null`/`undefined` falls through to the matching registry tool, matching `generate()`. - **Behavior change:** a tool throwing an error merely *named* `AbortError` while the run's signal is live is reported as an ordinary tool error rather than aborting the run. ## 0.20.0 - **The library and CLI split into separate packages.** `@fifthrevision/axle` is the library; `@fifthrevision/axle-cli` is the `axle` command. - Added `AgentSession`, snapshot/restore, and `createAgentConfig`. ## 0.18.0 - Request options were standardized across providers — output tokens, temperature, top-p, stop sequences, tool choice, and provider-specific options. Provider option types and runtime parameters were renamed; [see the guide](https://github.com/johncch/axle/blob/main/docs/0.18.0-migration.md). ## 0.17.0 - `Instruct` moved to object-style constructor options. - `Instruct` schema typing widened to any Zod schema. - Clearer errors for missing template variables. [Full guide](https://github.com/johncch/axle/blob/main/docs/0.17.0-migration.md). ## 0.15.0 - Aborts throw instead of resolving. See [Interrupting & cancelling](/cookbook/cancellation). ## 0.13.0 - Provider tool registries, streamed tool output and arguments. [Full guide](https://github.com/johncch/axle/blob/main/docs/0.13.0-migration.md). ## About the CLI `@fifthrevision/axle-cli` is being reworked, so it isn't documented on this site yet. You can still install it separately: ```bash npm install -g @fifthrevision/axle-cli ``` ## See also - [Changelog](/changelog) - [Glossary](/glossary) --- # Glossary Source: https://axle.fifthrevision.com/glossary _The normative vocabulary. Code, docs, and events use these words with exactly these meanings._ Names in Axle are load-bearing — they show up in event types, span names, option names, and your own code. So these definitions are normative: if a page on this site contradicts one, the page is wrong and we'd like to know. If you're meeting these for the first time, [Anatomy of a send](/concepts/anatomy-of-a-send) walks through them properly. This page is the quick-reference version. ## The three strata | Layer | Unit | Contains | Lives at | | --- | --- | --- | --- | | Wire | Message | content parts | `agent.messages` | | Execution | Step | one request + its fallout | the `send()` loop | | Render | Turn | parts (+ annotations) | the host's `Transcript` | One `send()` = one or more **steps**, producing one user **turn** and one agent **turn**, carried on the wire as **messages**. ## Terms **Message** — the wire-layer unit: a role-tagged (`user` / `assistant` / `tool`) `AxleMessage` whose `content` is a list of parts. Messages are what providers consume and what compaction rewrites. Never render state; never host-level chat input. **Part** — the atomic content unit: text, thinking, tool-call, file, citation. Parts are the shared vocabulary of the wire layer (`AxleMessage.content`) and the render layer (`Turn.parts`) — the same concept at both. A subagent invocation is a tool-call part like any other. **Step** — one pass of the execution loop inside a `send()`: one provider request, the assistant message it yields, and the tool batch that message requests, if any. A send ends with the first step whose message requests no tools, or when a budget (`maxSteps`, `maxContextTokens`) or a boundary control stops the loop. Steps are invisible in conversation state — each step's output is flattened into messages and into the agent turn's parts. Spans are named `step-N`; stream events are `step:start` / `step:complete`. **Turn** — the render-layer unit only: one conversation entry in a transcript, a user turn or an agent turn. A send's own exchange is one user turn and one agent turn; the agent turn accumulates parts from every step of that send, and a continuation adds further pairs, threaded under the first. Turns can also be opened and closed by compaction. A turn's `status` runs `pending` → `streaming` → `complete` | `cancelled` | `error`; a user turn skips `streaming`, and a `pending` turn lives only in `Transcript.pending`. Turns are what people see; the _operation_ that produced them is not a turn. Never a single assistant message; never a provider request. **Turn reason** — how an agent turn's final answer ended, carried on `turn:end` and kept on the `Turn` as `reason`: `"stop"` when the model finished, `"length"` when it hit the output token limit. Absent when the turn ended before a final answer arrived; a step that asked for tools never ends one. **Turn failure** — how an agent turn failed, carried on `turn:end` and kept on the `Turn` as `failure`: the provider's answer from a send that resolved `ok: false`, minus what only the result needs (`usage`, `raw`, `cause`). Present only on a turn whose `status` is `error` and whose send resolved — a turn that ended because the call threw has none. **Turn error** — how an agent turn ended when its send rejected with a thrown error instead of resolving: carried on `turn:end` and kept on the `Turn` as `error` (`message`, plus `code` when Axle threw it). A fatal tool error, a failed MCP tool listing, a throwing `onStep`, a failed manual compaction. A turn has `failure` (the provider's answer) or `error` (a thrown error), never both. `cancelReason` (`{ type: "timeout", limitMs }`) says `turnTimeoutMs` cancelled the turn; it is absent on a caller's cancel. **Send** — the Agent API verb: one scheduled conversation exchange (`agent.send(...)`), executed as a FIFO queue item. The host-facing unit of "the agent took its turn." **Operation** — a queued unit of agent work: a send or a manual compaction. Operations run one at a time in FIFO order. An operation is _pending_ from the call until its turn opens; it runs from `operation:start` to `operation:end`, and `onStart` and `onSettled` fire once each. An operation produces turns, and the two are not one-to-one: a send produces its own user and agent turn and, with a continuation, the inline turns it sends; a manual compaction produces one agent turn; one dropped before its turn opened produces none. The lifecycle belongs to the operation, and the turns it produces are its output. An operation cancelled while still queued never ran and does not settle. `agent.snapshot()` opens no turn, is not queued, and is not an operation. **Idle** — the Agent has no operation running and none queued. It is _busy_ from the first call that schedules an operation until the last queued one has settled; `agent.onIdle(...)` fires at each change from busy to idle, and `agent.snapshot()` resolves there. **Agent status** — `agent.status`: `{ phase: "idle" }`, or `{ phase: "busy", id }` with the id of the operation holding the queue (the send's user turn id, or the compaction's id). Busy covers the operation's `onStart` callbacks, its continuation, and its `onSettled` callbacks. It changes only at `operation:start` and `agent:idle`. Not to be confused with `Turn.status`, which describes one turn. **Pending turn** — a preview of a turn the Agent has accepted but not yet opened: the user turn a queued `send()` will commit, or an agent turn with one `pending` compaction part for a queued manual compaction. It is a `Turn` with `status: "pending"` and the id the real turn will carry, and it lives in `Transcript.pending`, never in `turns`. Pending turns are live state: they are not saved, a transcript restored from saved turns has none, and a host seeds them through the constructor only to mirror a live transcript. **Skill** — a unit of on-demand instruction in the Agent Skills format: a `SKILL.md` (frontmatter `name` and `description`, Markdown body) with optional bundled files. In core a `Skill` is plain data — name, description, `instructions`, an opaque `root`, a `files` listing — disclosed in the system prompt as a _catalog_ line and _activated_ when the model calls `view-skill`. `agent.skills` is the `SkillRegistry` that holds them; like `agent.registry` for tools, it changes at any time and the next provider request reads it. A skill is not a tool: it adds instructions, and reaches files only through the tools the host registered. See [Skills](/concepts/skills). **Decision** — one `decide()` call: an input and a set of typed questions sent to a decision model in a single request, answered with one typed value per question. A decision is not a step, a send, or a message: it has no conversation and produces no turn. See [Decisions](/concepts/decisions). **Decision model / decision provider** — a model that answers typed questions and cannot generate text, and the `DecisionProvider` that reaches it. Distinct from `AIProvider`; a provider may be either or both. **Noul** — a yes/no question. Its answer `noul` is the probability of yes, from 0 to 1. A value near 0.5 means the model is unsure, not that the answer is "partly". **Choice** — a question that picks one option from a set the caller defines. Its answer carries the chosen option, a probability per option, and a confidence. **Score** — a question that places the input on an ordered scale the caller defines, lowest level first. Its answer `score` is a probability-weighted position on that scale, zero-based, and can fall between levels. **Criteria** — the caller's description of a question's possible answers: what yes and no mean for a noul, the options for a choice, the ordered levels for a score. **Refusal (decision)** — a provider declining one question in a decision. The answer for that question is `{ type: "refusal" }`; the rest of the decision stands. Unrelated to the chat-side `Refusal`, which describes a declined request or blocked output. **Display** — the request-side reasoning disclosure control: `display: "visible" | "hidden"` on the object form of `reasoning`. It says whether the provider should show its thinking, never in what form. The form that arrives — a `summary` or `raw` text — is recorded on the thinking part and is the model's property. `"hidden"` withholds thinking content from the turn while the message keeps whatever the wire carried, so continuity still round-trips. **Summary / raw** — the two content fields of a turn's thinking part, each named for what the provider handed back: `summary` is the provider's condensed account of its reasoning, `raw` is the chain of thought itself (open-weight models only). Neither present is the withheld state. The message-layer thinking part keeps the wire vocabulary (`text`, `summary`, `redacted`) because it exists to be echoed, not read. **Redacted** — a wire-layer flag only: the provider substituted an opaque payload for the content and wants it echoed on the next turn. Never a turn-part or event field, and never set because thinking was merely hidden. **Transcript** — the host-owned, reader-facing fold of `TurnEvent`s into turns and annotations. The exported `Transcript` class is the shipped in-memory implementation; hosts persist its `turns` and pass them to the constructor on restore. Its `pending` view holds operations the Agent has accepted but not started; that is live state and is never saved. The Agent holds no transcript — it emits events and keeps only the active `messages`. Lose the turns, lose the transcript. **Sink** — a consumer-owned fold over the `TurnEvent` stream, attached with `agent.on(sink.apply)`. A sink folds what it needs from each event and ignores the rest, exposes a readonly view, and is restored by seeding its constructor with the persisted view. `Transcript` is the shipped sink; the Agent knows none of them. **Session** — the continuable identity of a conversation (`sessionId`). `AgentSession` is its serialized form: the pure continuation `{ sessionId, messages }` that `agent.session` returns and the `Agent` constructor restores. `snapshot()` resolves when the Agent goes idle, so the capture is always at rest. The transcript is not part of it. **Compaction** — replacing the active conversation with a condensed rewrite, recorded on the transcript as a `compaction` turn part. Old messages cease to exist; lookback is served by the transcript. **Trace** — observability only: the span tree produced by the tracer and consumed by span writers. Never the conversation transcript. **Annotation** — host-owned render state attached to a turn or a part. Never model state, never sent to a provider. **Tool** — an executable capability. Five sources: local `ExecutableTool`s, deferred tools, provider-managed tools, MCP tools, and subagents. All share one `ToolRegistry` and one flat namespace. **Tool batch** — the set of separate tool calls one assistant message requests. Each call in a tool batch is validated, executed, and answered with its own tool result. The calls run concurrently; the results answer in request order. See [One batch, all at once](/concepts/tools#one-batch-all-at-once). **Parallelized tool** — the single tool `parallelize(tool)` returns: one call whose arguments carry an `items` array, each item run through the wrapped tool's `execute` concurrently, with one ordered result. It is one tool call, not a tool batch: its arguments are validated as a whole, so one invalid item rejects the call. Not "batch tool". **Deferred tool** — a tool definition with no `execute` (`type: "deferred"`, name, description, schema, optional `timeout`). The model calls it like any other tool; the loop validates the arguments and hands the call to the consumer's `onToolCall` handler, which returns what an `execute` would. **Deferred call** — one call to a deferred tool as the handler receives it: `{ id, name, input }`, with `input` already validated. `id` is the tool call id, carried on the `DeferredAction` part as `detail.callId`. **Waiting** — the status of a `DeferredAction` from the moment its validated call is handed to `onToolCall` (`tool:waiting`, `action:waiting`) until something settles it: the handler's return or throw, `toolCall(id)`, the tool's `timeout`, or a cancellation. A deferred action is never `running`: it is `pending` while its arguments stream, then `waiting`. **Waiting tool call** — the handle `toolCall(id)` returns on a stream handle or an `Agent` while the call with that tool call id is waiting: `{ answer, fail }`. The first settle wins; the lookup returns `undefined` once the call has settled. **Continuation** — a program a send carries under `after`: runs once the turn settles, holds the queue, and runs inline turns via `ctx.send()`. See [Continuations](/concepts/continuations). **Inline turn** — a turn a continuation runs through `ctx.send()`. An ordinary send turn in every way but one: it starts at once in the held slot, so it has no pending phase, announces no `pending:queued`, and fires no hook of its own. It commits to messages, carries its operation's id as `threadId`, and is recorded on its operation's result under `after`. Inline turns run one at a time, FIFO, like operations. See [Continuations](/concepts/continuations). **Thread** — the turns an operation produced: its own user turn, which roots the thread, and the inline turns its continuation sent, whose user turns carry the root's id as `threadId`. A renderer draws an inline turn as a reply; the transcript stays a flat list. **Model** — the model id as the provider names it: what goes on the request, and what the response reported back. The same weights carry different ids at different providers (`claude-sonnet-4-5-20250929` at `anthropic`, `anthropic.claude-sonnet-4-5-v1:0` at `amazon-bedrock`), which is why Axle keeps no model table. See [Providers & models](/concepts/providers#naming-models). **Protocol** — the wire format a provider speaks (`messages`, `responses`, `generateContent`, `chatCompletions`). A provider is a `protocol` plus an `id` (the models.dev provider id stamped on usage rows). See [Providers & models](/concepts/providers). **Provider** — the service that serves and bills a request, named by its models.dev id (`anthropic`, `amazon-bedrock`, `openrouter`). In code, the `AIProvider` an `Agent` takes: a protocol configured with a base URL, auth and (on `chatCompletions`) a dialect, carrying that id as `id`. A provider whose service Axle doesn't recognize — a local server — has no `id`. Two providers can share one (Bedrock in two regions). Presets like `anthropic()` are shorthand for a protocol constructor with the configuration filled in. Prices are per provider and model, so usage is priced by `id`. One exception to the naming: the `provider` field of a thinking or provider-tool `continuity` names the wire format the continuity came from, because continuity is stored in conversation history. **Publisher** — who trained and released the model, and the first half of a canonical `publisher/model` id. A model's publisher never changes with where it is served, which is what makes the namespaced form portable. **Host** — whose hardware ran a request, when that differs from the provider: a router such as OpenRouter bills the request and forwards it to a host. Axle records no hosts, and models.dev doesn't price by them. **Catalog data** — `CatalogData`, the plain JSON a `ModelCatalog` indexes: a canonical layer of models keyed `publisher/model`, a provider layer of each provider's own ids with its limits and prices, plus `fetchedAt`, `etags` and `coverage` (the provider filter it was fetched with). `fetchModelsDev()` produces it, you store it, `parseCatalogData()` reads it back, and you may amend it. The catalog itself never fetches; `ModelCatalogStore` is what loads and refreshes it. Not the *skills* catalog, which is a section of the system prompt. See [Model catalog & cost](/concepts/model-catalog). **Failure** — the `ok: false` arm of a result: an `AxleProviderFailure` of kind `api`, `incomplete`, `refusal` or `parse`. A failure is always the provider's answer to a request that went out. It is a value on a result, never thrown. **Rejection** — a handle or promise that throws an `AxleError`: a mistake in the setup or the message, a local file that could not be read, a tool that ended the run, a cancel, or a broken invariant. Nothing was sent, or what was sent is carried on the error. See [Results & errors](/concepts/results-and-errors). **UsageEntry** — one row of `Stats.breakdown`: the usage of one provider request, tagged with the provider that served it (its `AIProvider.id`, absent when it has none), `model` (what the response reported, or the requested one when it reported none), `requestedModel` (what the caller passed, before `resolveModel`), `agent` when the `Agent` that made it has a name, and `at`. Rows stay in request order and are never summed per model, because a provider bills each request at the tier its own prompt size selects. They explain the aggregate `in` / `out` and are never added to it again. **Cost** — what `computeCost(usage, catalog)` returns for a `Stats`: `usd`, the sum of `priced` (rows with their own `usd`), and `unpriced` (rows with a `reason`: `no-catalog`, `no-provider`, `unlisted` or `no-price`). `pricedWith` is the `fetchedAt` of the catalog that priced the rows. Each row is priced by the catalog's provider layer at the tier its own `in` selects, cache and reasoning tokens at their own rate where the provider lists one. ## Renamed terms | Was | Is | Since | | --- | --- | --- | | turn (execution loop) | **step** | 0.29.0 | | `maxIterations` | `maxSteps` | 0.29.0 | | `"max-iterations"` | `"max-steps"` | 0.29.0 | | `generateTurn` | `generateStep` | 0.29.0 | | `TurnAccumulator` | `Transcript` | 0.30.0 | | `agent.history.log` | `agent.messages` | 0.26.0 / 0.30.0 | | `ThinkingPart.text` | `ThinkingPart.summary` / `ThinkingPart.raw` | 0.32.0 | | `ThinkingPart.redacted` (turn) | removed — `redacted` is wire-layer only | 0.32.0 | | `thinking:delta` (stream and turn) | `thinking:raw-delta` | 0.32.0 | | `generateStep` | removed — use `stream()` with `maxSteps: 1` | 0.32.0 | | `Models` / `ModelInfo` / `ModelMetadata` (`@fifthrevision/axle/models`) | removed — pass model IDs as plain strings | 0.33.0 | | `temperature` / `topP` / `stop` (request options) | removed — send through `providerOptions` with provider field names | 0.33.0 | | `AxleFailure` `{ kind: "tool" }` | removed — nothing produced it | 0.33.0 | | `AxleFailure` nested `error` (`ModelError`, parse `error`) | flattened — `model` carries `type`/`status`/`usage`/`raw` directly; parse carries `cause` | 0.33.0 | | `provider-tool` part `output` | `input` / `result` / `continuity`; results in `continuity`, late results in `provider-tool-result` parts | 0.33.0 | | `provider-tool:complete` `output` (search) | search results live on the part's `continuity`; failures arrive as `provider-tool:error` | 0.33.0 | | `AxleStopReason.Error` / `AxleStopReason.Custom` | removed — unknown stop reasons fail the request | 0.33.0 | | `configureAxle` / `AxleConfiguration` | removed — attach `webSearch` to each `chatCompletions()` provider that needs it | 0.34.0 | | `WebSearchBackend` (+ `WebSearchRequest`, `WebSearchResponse`) | removed — a custom search is an `ExecutableTool` passed as `webSearch` | 0.34.0 | | `StreamParams.registry` | removed — pass `tools` / `providerTools`; change mid-loop via `onToolBatchComplete` | 0.34.0 | | `ToolContext.registry` | removed — mutate the agent in closure scope (`agent.registry`, `agent.skills`) | 0.34.0 | | `AIProvider.resolveProviderToolName` / `ResolvedProviderTool` / `nativeName` | removed — providers serve `providerTools` unchanged; bring tools via `AIProvider.tools` | 0.34.0 | | `agent.system` (writable) | read-only getter — configured prompt plus the skills catalog | 0.34.0 | | `vendor: "together"` | renamed to `"togetherai"` | 0.34.0 | | `WEB_SEARCH_FALLBACK_NOT_CONFIGURED` | removed — an unserved provider tool fails the request as an `api` failure with no code | 0.34.0 | | `TOOL_OPTIONS_CONFLICT` | removed — there is nothing left to conflict | 0.34.0 | | `AxleFailure` / `GenerateError` | `AxleProviderFailure` | 0.35.0 | | `AxleFailure` `{ kind: "model" }` | `{ kind: "api" }` + `{ kind: "incomplete" }` | 0.35.0 | | `InstructVariableError` | `AxleInstructVariableError` | 0.35.0 | | `TaskError` | removed — never thrown | 0.35.0 | | `AIProvider.name` | `AIProvider.protocol` + `AIProvider.id` | 0.35.0 | | `ModelCatalog.open()` / `cachePath` / `ready` / `refresh()` / `state` / `hosts` | `ModelCatalogStore` + `catalogFile()` + `fetchModelsDev()` + `parseCatalogData()`; `lookup`/`contextWindow` take `{ provider }` | 0.35.0 | | `anthropic()` / `openai()` / `gemini()` `baseUrl` | protocol constructors `messages()` / `responses()` / `generateContent()` with `baseUrl` | 0.35.0 | | `chatCompletions(url, …)` / `vendor` / `inferChatCompletionsVendor` | `chatCompletions({ baseUrl, … })`; `vendor` is `id` + `dialect` (`openrouterDialect` / `togetheraiDialect`) | 0.35.0 | | `ChatCompletionsVendor` | removed — `chatCompletions({ baseUrl }).id` gives what the hostname implies | 0.35.0 | | `Turn.error` / `error` turn event | `Turn.failure` / `turn:end` `failure` | 0.35.0 | | `error.type === "aborted"` tool result | `action:cancelled`, `status: "cancelled"` | 0.35.0 | | `AgentDefinition` / `createAgentConfig()` / `SavedAgent` | removed — rebuild `AgentConfig` from your own recipe shape + `AgentSession` | 0.35.0 | | `FileProviderId` / `provider` in file + `PROVIDER_UNSUPPORTED` details | `Protocol` / `protocol` | 0.35.0 | | `TurnEventCallback` | `AgentEventCallback` — `agent.on` delivers the operation lifecycle beside turn events | 0.36.0 | | `onToolCall(name, parameters, ctx)` intercepting any tool, returning `null` to fall through | `onToolCall(call, ctx)` answering deferred tools only — executable tools always run their own `execute` | 0.36.0 | | `unanswered` tool error result | removed — an unanswered deferred call waits for `toolCall(id)`, the tool's `timeout`, or cancellation (`generate()` fails fast instead) | 0.36.0 | | `onSettled` per turn, including inline turns | `onSettled` once per operation, after the continuation | 0.36.0 | | `InlineSendOptions` with `signal` | `signal` removed — it was ignored; cancel the operation to abort an inline turn | 0.36.0 | | `reasoning: "off"` / `"on"` | `{ enabled: false }` / `{ effort: "medium" }` — `ReasoningSetting` is `"default"` or `{ enabled?, effort?, display? }` | 0.37.0 | | `ReasoningEffort` (`"low" \| "medium" \| "high"`) | six levels: `"minimal" \| "low" \| "medium" \| "high" \| "xhigh" \| "max"`, sent as written | 0.37.0 | | `OutputSchema` as `z.ZodTypeAny` | a Standard Schema object or a plain JSON Schema; the model is shown the JSON Schema, constraints reach it | 0.37.0 | | sync `parseResponse()` / `Instruct.parse()` | both return a promise | 0.37.0 | | `instruct.render()` with output instructions | returns the prompt alone; the schema is stored on the message as `output` | 0.37.0 | | `InstructInputs` as `Record` | `Record` | 0.37.0 | | remote `send` command with a rendered `prompt` | carries the `Instruct` as data (`Instruct.fromJSON(command.instruct)`) — 0.36 and 0.37 do not interoperate | 0.37.0 | | `agent.snapshot()` | deprecated — read `agent.session` | 0.37.0 | See [Upgrading](/upgrading).