Glossary
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 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.
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.
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 TurnEvents 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 ExecutableTools, 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.
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.
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.
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.
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.
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.
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.
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<string, unknown> | Record<string, string | number | boolean | null> | 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.