Skip to content

Upgrading ​

Every release has a full migration guide in the repository under 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 in the library repo. Read it end to end if you pass reasoning, use an Instruct schema, drive a remote agent, or construct StreamEvents 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<ReasoningEffort, …> 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.

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<string, string | number | boolean | null> — 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 and 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 and Sessions & persistence.

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); 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 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 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 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 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); 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 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).

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 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.

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.

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 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 <n>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, Decisions, and the migration guide.

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 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 optionAnthropicOpenAIGeminiChat Completions
temperaturetemperaturetemperaturetemperaturetemperature
topPtop_ptop_ptopPtop_p
stopstop_sequencesnot supportedstopSequencesstop

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 and Messages & parts.

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.

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.

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.

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 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.310.32
thinking:delta (stream and turn)thinking:raw-delta
stream thinking:start .redactedremoved
stream and turn thinking:update .redactedremoved
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 for the full story. Full guide.

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 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.300.31What changes
omittedomitted 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 for the full story. Full guide.

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.

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 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.

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() 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.

0.29.0 — step terminology ​

The tool-loop unit was renamed from "turn" to "step", because "turn" already meant the render-layer unit.

BeforeAfter
maxIterationsmaxSteps
"max-iterations""max-steps"
turn:start / turn:complete (stream events)step:start / step:complete
generateTurngenerateStep

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 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.
  • 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 ​

0.24.0 ​

  • Added experimental subagent tools 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.

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.

0.15.0 ​

0.13.0 ​

  • Provider tool registries, streamed tool output and arguments. Full guide.

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 ​