@cubicecho/agent-core 2.18.0 → 2.19.0

package/README.md

@@ -2,6 +2,8 @@
 
 The endpoint-agnostic half of an OpenAI-compatible agent loop.
 
+Site: <https://cubicecho.github.io/agent-core/>
+
 Extracted from three servers that had each written it separately — `kanban_server`,
 `task_server` and `min-agent` — after the copies drifted far enough that a fix in one was a bug
 still live in another.
@@ -37,6 +39,7 @@ only, Node >=22.
 | `agent-loop` | `runAgentLoop`: the loop above a turn — `runTurn` per step, the tools between, `load_tools` and preselection handled, until the model stops asking. Plus the parts it is made of: `buildBody`, `preselect`, `preview`, and `resolveApiKey` for a caller deciding which key an endpoint gets. |
 | `tool-calls` | Reading what a model meant by a tool call it did not write cleanly: `parseToolArguments` repairs almost-JSON arguments and says when they were cut off, `recoverToolCalls` finds calls written into the reply as text. |
 | `compaction` | Keeping a long run inside its window: `pruneToolResults` clears stale tool results, `planCompaction` and `compactTranscript` fold the oldest stretch into a summary. |
+| `ledger` | What stretches of a transcript cost, read off the prompt counts the server reported rather than estimated: `recordRequest`, `tokensBetween`, `estimateFrom`, `rebaseLedger`. |
 | `snapshot` | `exportCapabilities` and `importCapabilities`: the latched refusals as a JSON blob a consumer stores, so a restart need not learn them again. |
 | `spec` | `parseSpec`, `resolveAgentSpec` and `exportSpec`: an agent as a versioned JSON document, layered into the flat config the loop takes. Imports nothing but types, and is published separately at `@cubicecho/agent-core/spec`. |
 | `reset` | `resetAll`: drops every cache and latch in one call, so a teardown cannot forget one. |
@@ -102,7 +105,7 @@ than zero otherwise:
 | `firstTokenMs` | `streamTurn`, from the request to the first chunk that carried something |
 | `wallMs`, `retries`, `timeouts` | `runTurn`: the whole turn with its backoff, the lost requests sent again, and how many of those went silent |
 | `continuations` | `continueTurn` |
-| `cacheExpected`, `cacheBroken`, `cacheBreakReason`, `toolsDeclared`, `toolSchemaTokens` | `runAgentLoop`, below |
+| `cacheExpected`, `cacheBroken`, `cacheBreakReason`, `toolsDeclared`, `toolSchemaTokens`, `context` | `runAgentLoop`, below |
 
 `reasoning` is the scratchpad `onThinking` was told, kept because two common families want it
 back. gpt-oss and DeepSeek in thinking mode read the analysis behind a tool call off the assistant
@@ -365,6 +368,10 @@ the total is `requestTokens`, and the tool block is counted the way `requestToke
 `TurnMetrics.toolSchemaTokens` count it rather than shared out, so the breakdown and the metrics
 line cannot disagree about the same tool list.
 
+A host on `runAgentLoop` has no body to hand it, since the loop builds the request. It does not
+need one: each `usage` event's `turn.context` is this breakdown for that step, and `onRequest` is
+handed the request itself for a host that cuts it some other way. Both are under the loop, below.
+
 ## The loop
 
 `runAgentLoop` is the part of an agent that three servers had each written, and that had drifted
@@ -404,6 +411,26 @@ predicate is asked per call — which is how `send_email` opts out, since twice
 nothing in an OpenAI tool definition says which tools those are. A pool that reads the MCP
 `readOnlyHint` and `idempotentHint` annotations can answer it; this package cannot.
 
+Three kinds of call never reach `dispatch`: `load_tools`, which the loop answers itself, a call
+whose arguments could not be read, and that identical repeat. A host that draws each call as a
+card and fills it in when the result lands hears of those through `onToolCall` and `onToolResult`,
+which are told of every call the model made — the request as `dispatch` would have been handed it
+(with empty `args` where they could not be read), then `{ id, name, ok, content }` with the whole
+text the model reads. A repeat gets a result of its own under its own id, carrying the answer it
+shares. Neither is awaited. The `tool-call` and `tool-result` events carry the same `id`, with
+`text` still cut by `preview`, and so does each entry of the result's `toolCalls` — which is what
+tells two calls to one tool apart when `parallel` lands their results out of order. An id is
+distinct within a step, and a server is free to use it again in a later one.
+
+```ts
+await runAgentLoop({
+  // ...
+  onToolCall: ({ id, name, args }) => send({ type: "tool_use", id, name, input: args }),
+  onToolResult: ({ id, ok, content }) =>
+    send({ type: "tool_result", toolUseId: id, content, isError: !ok }),
+});
+```
+
 Arguments go through `parseToolArguments`, which is lenient where the model's meaning is plain:
 JSON held in a string is opened, and the almost-JSON local models write — single quotes, Python's
 `True` and `None`, bare keys, a trailing comma — is repaired, without touching what is inside a
@@ -442,6 +469,20 @@ run. A preselection shapes the first step alone: those tools, no catalogue, no `
 a model with the menu still in front of it shops, reloading what it has or picking a sibling —
 and everything is back from the second step on.
 
+That first step has a request head of its own — a different system prompt and a different tool
+array from the last turn's final request, and from this turn's second step — so a prompt cache
+misses the whole transcript twice on a question that has a preselection. `preselectRouting:
+"append"` drops the separate head: the shortlist is loaded as a `load_tools` call would have loaded
+it, after whatever `loaded` carried and without declaring a carried name twice, and the first step
+is sent like every other, catalogue and `load_tools` included. The trade is the menu back in front
+of the model on the step the shortlist was meant to settle. Neither cost has been measured against
+the other, so `"exclusive"` stays the default.
+
+Appended is where the tools go before `toolOrder` orders them. With `toolOrder: false` a carried
+tool array stays a strict prefix of the new one. With name order, the default, a preselected tool
+is sorted in and moves every definition after it — the first step still matches the second, but
+the last turn's cache holds only as far as the first new name.
+
 That preselection costs a round trip to a model, which on a local box is a few seconds before the
 run has started, spent on a model doing term matching. `preselect(..., { keywords: true })` does
 the matching directly and spends the model only on what the words cannot settle:
@@ -503,6 +544,25 @@ reported — `cacheBroken`, a hit short of 90% of the previous prompt. A broken
 `history-rewritten` (a compaction or a prune in `beforeStep`), or `none-known` where the new request
 only appended, which points at the server — a slot evicted, a template that re-renders the tail.
 
+The same `turn` carries `context`, the request cut by `contextTokens` into `system`, `tools`,
+`history` and `toolResults`: shares of the prompt the endpoint reported for it, adding up to it, or
+an estimate where it reported none. A host that wants a different cut — the catalogue apart from the
+prompt it rides on, this turn's messages apart from the ones before — takes the request from
+`onRequest` and measures it itself:
+
+```ts
+await runAgentLoop({
+  ...options,
+  onRequest: ({ messages, tools, step }) => measure(step, messages, tools),
+});
+```
+
+It is called once a step, before the request goes out, with the messages and tools as the client
+is about to be sent them. It is for reading: `beforeStep` is where the transcript is changed. What
+it reports is the request as first built. A retry sends that again, but a refusal is answered with
+a lesser body and a continuation with the reply so far on the end, and neither is reported — and
+`context` is measured on the same first request, against the first prompt reported for the turn.
+
 `runMetrics(events)` adds a run up from those events — tokens, cache hit ratio and breaks by
 reason, prefill, decode and tool time, the slowest turn, mean time to first token, draft
 acceptance, the largest prompt against a `contextLength`, turns cut off, tool errors by name, and
@@ -519,9 +579,53 @@ What it cannot say: whether a failed run was stopped, errored or ran out of tool
 whether the host compacted — neither is in the events.
 
 `beforeStep` is handed the transcript before each request and may return a replacement, which is
-where compaction goes (below). Hooks are gathered once, onto the question, and never written into
+where compaction goes (below). Its third argument is `{ used, limit, ledger }` — the prompt the
+run's last request reported, the window, and the token ledger so far — so a host can compact
+mid-run without tracking usage itself; `used` is absent before the first step and where the
+endpoint reported nothing. Hooks are gathered once, onto the question, and never written into
 the transcript that comes back; `afterTurn` is told the reply without the run waiting on it.
 
+That leaves an earlier question's context to the host, because the loop only ever touches the
+current one. A question sent with `<context>` blocks one turn and bare the next is a different
+prompt from that message on, and the server's prefix cache is lost behind it — on every turn. So
+the result hands back what it said, `context` and the `preface` above it, for the host to keep
+beside the question and put back with `withContext` on every later call:
+
+```ts
+import { runAgentLoop, withContext } from "@cubicecho/agent-core";
+
+// Stored: what the user typed, and what the hooks added to it the turn it was asked.
+const history = session.messages.reduce(
+  (sent, message, at) => withContext(sent, at, message.hookContext ?? "", message.hookPreface),
+  session.messages.map(({ hookContext, hookPreface, ...message }) => message),
+);
+const result = await runAgentLoop({
+  config,
+  messages: [...history, { role: "user", content: prompt }],
+  dispatch,
+  hooks: { run, context: { session: { id }, prompt } },
+});
+session.messages.push(
+  { role: "user", content: prompt, hookContext: result.context, hookPreface: result.preface },
+  ...result.messages.slice(history.length + 1),
+);
+await result.afterTurn; // only if its notes are wanted, or the process is about to exit
+```
+
+`withContext` with those two arguments builds the question exactly as the loop sent it, whatever
+`configureHooks` has since been told, so the next request is the last one with its tail added.
+`result.messages` is the transcript the loop was given plus what the run added — earlier questions
+as the host passed them, this one as typed — which is why the snippet stores only the new tail.
+
+`afterTurn` on the result is the `afterTurn` hooks' notes as a promise. The loop still returns
+without waiting; a host that stores those notes with the turn, or would otherwise exit before the
+turn is remembered, awaits it once the answer is out.
+
+The loop gathers before its first request, and nothing of the host's can run beside that. A host
+with pre-turn work to overlap with the hooks — compaction, a preselection — calls `gather` itself,
+applies `withContext` to the current question as well, calls `notify` after, and passes no `hooks`
+(see [Hooks](#hooks)).
+
 `resolveApiKey` is exported and not applied, because which key an endpoint gets is a rule a
 consumer states and a library guessing it could send one where it was not meant to go. The rule
 it encodes is the conservative one: an endpoint's own key wins; one that names a base URL of its
@@ -607,6 +711,73 @@ way to save tokens.
 `pruneToolResults` keeps the transcript's indexes, so a plan made before pruning still applies to
 what it returns, as above.
 
+### What the messages cost, measured
+
+`planCompaction` decides where to cut by estimating each message, and a calibrated divisor fixes
+only the average: a transcript is tool results, JSON arguments, code and prose, each at its own
+ratio, plus whatever the chat template adds per message. The server has already said what they
+cost. A request that only appended to the one before it differs from it by exactly the cost of what
+was appended, so two reported prompts and a subtraction give a number with no tokenizer in it — the
+template's tokens and a tool result's real density included, and reasoning, which is never
+replayed, left out.
+
+`runAgentLoop` keeps that as a ledger — one `{ through, prompt, epoch }` per request: the index of
+the request's last message, the prompt it reported, and an epoch that changes whenever the prefix
+did. It comes back as `result.ledger`, rides on every `usage` event, and is handed to `beforeStep`;
+pass it back as `ledger` on the next run and it is continued. It is a plain array of three numbers
+an entry, so it stores as two columns on the message row `through` names or as JSON beside the
+session.
+
+```ts
+const result = await runAgentLoop({
+  ...options,
+  ledger: session.ledger,
+  beforeStep: async (messages, step, { used, limit, ledger }) => {
+    const plan = planCompaction(messages, {
+      limit,
+      used,
+      target: 0.5,
+      estimate: estimateFrom(ledger, messages, { charsPerToken }),
+    });
+    if (!plan) return;
+    return compactTranscript(messages, plan, summarise);
+  },
+});
+session.ledger = result.ledger;
+```
+
+`tokensBetween(ledger, from, to, messages)` is the cost of `messages.slice(from, to)`. Between two
+boundaries recorded in one epoch it is the subtraction, and exact. A boundary falls after a question
+and after each step's tool results, never after an assistant message, so a stretch that starts or
+ends inside a group gets that group's total by character share, the way `contextTokens` divides a
+reported prompt. Whatever no pair of entries covers is the calibrated estimate: the messages before
+the first entry, the group either side of an epoch's end, and what has not been sent yet.
+`estimateFrom(ledger, messages)` is the same thing one message at a time, which is the function
+`planCompaction` already takes as `estimate`.
+
+`target` is the share of the window the whole request should come down to. `keepRatio` bounds the
+kept tail alone, with the system prompt, the tool schemas and the summary sitting on top of it
+uncounted; given a `target`, the cut is the first user message at which `used`, less what is
+folded, plus the summary's ceiling (`summaryTokens`, 1024 unless given) is at or under it, and the
+plan's `after` says what that leaves. Where no cut reaches it the plan folds as far as the last
+user message and `after` says how far short it fell. Without `target` nothing changes.
+
+A new epoch starts whenever a request did more than append: a fold or a prune in `beforeStep`, a
+system prompt that moved, and a tool array that grew — a `load_tools` in on-demand mode adds a
+schema to the head, so the group beside it is left unmeasured rather than charged for it. When
+`beforeStep` returns a different transcript the loop moves the entries that still stand to their new
+indexes with `rebaseLedger(ledger, before, after)`, which a host that folds between runs calls
+itself. Differences inside an old epoch stay good, since the prefix they shared cancels.
+
+What is not measured: the first request of every run starts an epoch, because the loop cannot see
+whether the run before it had the same system prompt and tools, so a run's question and the answer
+before it are estimated; a step whose prompt was not reported has no entry, and the next one that
+does is measured across it; and the prompt recorded is the first request's, before any continuation.
+A difference of zero or less is not trusted, and neither is a prompt reported smaller than its own
+cache count — both are how a server reporting `prompt_tokens` net of its cache would show up.
+Whether any endpoint does that has not been checked, and one whose net counts kept rising would not
+be caught. A host with its own loop keeps a ledger with `recordRequest(ledger, previous, next)`.
+
 ### A fold you store, instead of a transcript you rewrite
 
 `compactTranscript` hands back a new array, which is the whole answer for a host whose transcript
@@ -746,7 +917,10 @@ void notify(run, "afterTurn", { ...context, reply, turn: { ...context.turn, mess
 
 The context goes on this turn's question and never into the system prompt — a prompt that changed
 every turn would miss the prompt cache every turn — and `withContext` returns a new array, so a
-host that stores what the user typed never stores the context as something they said. Every
+host that stores what the user typed never stores the context as something they said. It is stored
+beside the question instead, and put back on every later request: a question that loses its blocks
+on the next turn rewrites the prompt from there on, and the server's prefix cache with it.
+`runAgentLoop` hands back `context` and `preface` for the same purpose. Every
 injecting hook shares `HOOK_CONTEXT_TOKENS` (2000) by default, each held to its own `maxTokens`
 inside that, so a generous hook cannot crowd out the conversation it was meant to inform.
 

package/dist/agent-loop.d.ts

@@ -4,6 +4,7 @@ import type { CatalogServer } from "./catalog.ts";
 import type { Endpoint, ModelParams, RetryPolicy, ToolPolicy } from "./config.ts";
 import { type RunEventInput, type RunMetrics } from "./events.ts";
 import { type HookContext, type HookEvent, type HookNote, type HookRunner } from "./hooks.ts";
+import { type TokenLedger } from "./ledger.ts";
 import type { Turn, TurnUsage } from "./stream.ts";
 import { type KeywordPreselectOptions, type ToolOrder } from "./tool-loading.ts";
 /**
@@ -97,22 +98,67 @@ export declare function preselect(config: Endpoint, model: string, catalog: Cata
      */
     keywords?: boolean | KeywordPreselectOptions;
 }): Promise<string[]>;
-/** One call the model made, as `dispatch` is handed it. */
+/** One call the model made, as `dispatch` and `onToolCall` are handed it. */
 export interface ToolCallRequest {
     id: string;
     name: string;
-    /** Parsed by `parseToolArguments`, repairs and all. */
+    /**
+     * Parsed by `parseToolArguments`, repairs and all. Empty for a call whose arguments could not be
+     * read, which only `onToolCall` is ever handed.
+     */
     args: Record<string, unknown>;
     /** The arguments as the model wrote them, before any repair. */
     raw: string;
 }
 /** What one tool call did, in the order the model asked. */
 export interface ToolCallOutcome {
+    /**
+     * The id the model's reply gave the call, which is what tells two calls to one tool apart.
+     * Distinct within a step — `streamTurn` mints one where the server sent none or repeated one —
+     * but nothing stops a server using the same id again in a later step. `runAgentLoop` always
+     * sets it; optional so an outcome built before it existed still compiles.
+     */
+    id?: string;
     name: string;
     /** False when the arguments did not parse, the tool threw, or `load_tools` loaded nothing. */
     ok: boolean;
 }
-/** The hooks a loop runs around one question. See `hooks.ts`. */
+/**
+ * One step's request as `onRequest` is handed it: what the model is about to read.
+ *
+ * The loop assembles this and nothing else sees it — the system prompt with the catalogue on it,
+ * the hooks' context on the question, the tool array ordered and sanitised as it is sent — so a
+ * host that wants to say what is filling the window has nothing to measure without it.
+ */
+export interface AgentLoopRequest {
+    /** The messages as sent, system prompt first. The request's own array, not a copy. */
+    messages: readonly OpenAI.ChatCompletionMessageParam[];
+    /** The tools as sent: ordered, sanitised, relaxed where the endpoint needs it. Empty for none. */
+    tools: readonly OpenAI.ChatCompletionTool[];
+    /** Which step of the run this is, from zero, as `beforeStep` and `onTurn` count them. */
+    step: number;
+}
+/**
+ * One call's whole answer, as `onToolResult` is handed it.
+ *
+ * The `tool-result` event carries the same answer cut by `preview`, which is right for a readout
+ * and wrong for a host that renders or stores the result: this is the text the model reads.
+ */
+export interface ToolCallResult extends ToolCallOutcome {
+    id: string;
+    /**
+     * What went into the transcript for this call, uncut: what the tool returned, what it threw, the
+     * `load_tools` answer, or why the arguments could not be read.
+     */
+    content: string;
+}
+/**
+ * The hooks a loop runs around one question. See `hooks.ts`.
+ *
+ * The loop gathers before its first request and nothing else can run beside that, so a host with
+ * pre-turn work of its own to overlap with the hooks — compaction, a preselection — calls `gather`
+ * itself, puts the context on with `withContext`, calls `notify` after, and passes no `hooks`.
+ */
 export interface AgentLoopHooks {
     run: HookRunner;
     /** What the hooks are told. `reply` and `turn` are filled in for `afterTurn`. */
@@ -126,6 +172,20 @@ export interface AgentLoopHooks {
     /** Hears each note, from before the request and from `afterTurn`. */
     onNote?: (note: HookNote) => void;
 }
+/** How full the window is as a step is about to be sent, as `beforeStep` is told it. */
+export interface StepWindow {
+    /**
+     * The prompt tokens this run's last request reported. Absent before the first step — an earlier
+     * run's figure is the host's to vouch for, since the transcript may have been folded since —
+     * and where that request reported none. It does not count the reply and tool results added
+     * since.
+     */
+    used?: number;
+    /** The model's window, `config.contextLength`. Zero where the config names none. */
+    limit: number;
+    /** The run's ledger so far, indexed into the transcript `beforeStep` is handed beside it. */
+    ledger: TokenLedger;
+}
 /** What `runAgentLoop` takes. */
 export interface AgentLoopOptions {
     /**
@@ -156,9 +216,27 @@ export interface AgentLoopOptions {
     /**
      * What `preselect` picked. The first step is sent these and nothing else — no catalogue, no
      * `load_tools` — because a model with the menu still in front of it shops: it reloads what it
-     * has or picks a sibling. Everything comes back on the step after.
+     * has or picks a sibling. Everything comes back on the step after. `preselectRouting` trades
+     * that for a first step shaped like the rest.
      */
     preselected?: readonly string[];
+    /**
+     * What a preselection does to the first step. `"exclusive"`, the default, is the shortlist alone
+     * as `preselected` describes — and a system prompt and tool array unlike the last request's and
+     * unlike the next step's, so a prompt cache misses the whole transcript on the first step and
+     * again on the second. `"append"` loads the shortlist as a `load_tools` call would have and
+     * sends the first step like any other: the catalogue, `load_tools`, what `loaded` carried, then
+     * the shortlist after it, with a name already carried left where it is. The price is the menu
+     * back in front of the model. Which costs more has not been measured, which is why the default
+     * has not moved.
+     *
+     * Appended is before `toolOrder` has its say: sorted, a preselected tool lands at its name's
+     * place and moves every definition after it, so only `toolOrder: false` keeps a carried array
+     * a strict prefix. Either way the first step's system prompt is the second's, and so is its
+     * tool array until something else is loaded. Nothing to do without a preselection, or in eager
+     * mode.
+     */
+    preselectRouting?: "exclusive" | "append";
     /** Tools already loaded, carried from an earlier question. See `carryOver`. */
     loaded?: Iterable<string>;
     /** Runs one tool call and returns what the model reads. What it throws, the model reads too. */
@@ -184,13 +262,49 @@ export interface AgentLoopOptions {
      * `idempotentHint` annotations can answer it; nothing in an OpenAI tool definition can.
      */
     dedupeToolCalls?: boolean | ((call: ToolCallRequest) => boolean);
-    /** Hooks gathered onto the question before the first request, and told the reply after. */
+    /**
+     * Told of every call the model made, as it starts — the ones `dispatch` never sees included:
+     * `load_tools`, an identical repeat answered from the first, and a call whose arguments could
+     * not be read, which arrives with empty `args` and the model's own text in `raw`.
+     *
+     * For a host that shows each call as it is made and fills it in when its result lands, which
+     * `dispatch` alone cannot do for those three. Not awaited: a promise it returns is dropped.
+     */
+    onToolCall?: (call: ToolCallRequest) => void;
+    /**
+     * Told of every call's answer as it lands, whole, under the id `onToolCall` announced it by.
+     *
+     * One per call the model made: a deduplicated repeat gets its own, carrying the answer it
+     * shares with the first. With `parallel` they arrive as the calls finish, which need not be
+     * the order they were made in; the transcript and the result's `toolCalls` keep that order.
+     * Not awaited: a promise it returns is dropped.
+     */
+    onToolResult?: (result: ToolCallResult) => void;
+    /**
+     * Hooks gathered onto the question before the first request, and told the reply after.
+     *
+     * Only this question is touched — the last user message of `messages` — and the context is on
+     * the request, never in the transcript handed back. An earlier question's context is therefore
+     * the host's to send again: keep the result's `context` and `preface` beside the question, and
+     * put them back with `withContext` on every later call. A question sent bare that was first
+     * sent with context is a different prompt from that message on, and the server's prefix cache
+     * is lost behind it on every turn.
+     */
     hooks?: AgentLoopHooks;
     /**
      * Called before each step with the transcript, and what it returns replaces it — the point to
-     * compact or prune a run that has grown into its window. Returning nothing keeps it.
+     * compact or prune a run that has grown into its window. Returning nothing keeps it. `window`
+     * is what `planCompaction` wants to know, so a host need not track usage itself to compact
+     * mid-run.
      */
-    beforeStep?: (messages: readonly OpenAI.ChatCompletionMessageParam[], step: number) => OpenAI.ChatCompletionMessageParam[] | undefined | Promise<OpenAI.ChatCompletionMessageParam[] | undefined>;
+    beforeStep?: (messages: readonly OpenAI.ChatCompletionMessageParam[], step: number, window: StepWindow) => OpenAI.ChatCompletionMessageParam[] | undefined | Promise<OpenAI.ChatCompletionMessageParam[] | undefined>;
+    /**
+     * The ledger an earlier run handed back for this transcript, to be continued. Its indexes have
+     * to be into `messages` as given here — see `rebaseLedger` for a transcript rewritten since.
+     * This run's requests start a new epoch, because the loop cannot see whether the request before
+     * its first one had the same system prompt and tools. Absent starts an empty one.
+     */
+    ledger?: TokenLedger;
     /** Stops the run: the request in flight, and between steps and calls. */
     signal?: AbortSignal;
     /** Told what the run is doing, as the events a watcher reads. */
@@ -202,6 +316,16 @@ export interface AgentLoopOptions {
      * the answer. See `recoverToolCalls`.
      */
     recoverToolCalls?: boolean;
+    /**
+     * Each step's request as first built, before it goes out — for measuring what was sent, not for
+     * changing it, which is `beforeStep`'s.
+     *
+     * Called once a step, synchronously, and what it throws ends the run. It is not called again
+     * for what `runTurn` sends after that: a retry sends the same request, but a refusal is answered
+     * with a lesser body — relaxed schemas, a field dropped — and a continuation with the reply so
+     * far on the end, and neither is reported.
+     */
+    onRequest?: (request: AgentLoopRequest) => void;
     /** Each turn as it comes back, before its tools run. Recovered calls are in it as calls. */
     onTurn?: (turn: Turn, step: number) => void;
     /**
@@ -219,7 +343,7 @@ export interface AgentLoopResult {
     messages: OpenAI.ChatCompletionMessageParam[];
     /** Summed over every turn of the run. */
     usage: TurnUsage;
-    /** Every call, `load_tools` included, in the order they were made. */
+    /** Every call, `load_tools` included, in the order they were made, each under its call id. */
     toolCalls: ToolCallOutcome[];
     /** What is loaded at the end, for `carryOver`. Empty in eager mode. */
     loaded: string[];
@@ -227,11 +351,39 @@ export interface AgentLoopResult {
     used: string[];
     /** The hooks' notes from before the first request. */
     notes: HookNote[];
+    /**
+     * The `<context>` blocks the hooks added to this question, as `withContext` takes them. Empty
+     * when no hook added any, and without `hooks`. Not in `messages`, so a host that wants the next
+     * turn's request to begin with this one's stores it beside the question; see `hooks`.
+     */
+    context: string;
+    /**
+     * What was said above `context`: the hooks' own `preface`, or what `configureHooks` had set when
+     * the run began. Handed back because the second is not the host's to know later — with it,
+     * `withContext(messages, at, context, preface)` is the question as it was sent, whatever the
+     * process's preface has since become. Empty when the preface was turned off; with no `context`
+     * nothing was said either way, and `withContext` adds nothing.
+     */
+    preface: string;
+    /**
+     * The `afterTurn` hooks' notes, once they have run — failures only, as `notify` returns them.
+     * The loop does not wait for it, so the answer is never held for a hook; a host that stores the
+     * notes with the turn, or must not exit before the turn is remembered, awaits it. Each note
+     * reaches `onNote` as well. Already resolved and empty without `hooks`, and rejects only if
+     * `onNote` throws.
+     */
+    afterTurn: Promise<HookNote[]>;
     /**
      * The run summed and derived: what `runMetrics` makes of the events this loop emitted, plus the
      * `load_tools` findings only the loop sees, `wallMs` from the call to the return, and `outcome`.
      */
     metrics: RunMetrics;
+    /**
+     * What each step's request reported its prompt as, indexed into `messages` above, for
+     * `tokensBetween` and `estimateFrom`. The entries of a `ledger` passed in come first. A step
+     * whose prompt was not reported has no entry.
+     */
+    ledger: TokenLedger;
 }
 /**
  * Runs a question to its answer: one `runTurn` per step, the tools it asks for between them,
@@ -242,10 +394,18 @@ export interface AgentLoopResult {
  * prompt unchanged from step to step, a load adds to the tool array — which every request sends
  * in the stable order `toolOrder` asks for — and
  * a catalogued tool called without being loaded is loaded and run rather than refused, and a
- * preselection shapes the first step. A turn cut off at `maxTokens` is said so as a notice,
- * because it otherwise reads exactly like a finished one — or, given `maxContinuations`, is
+ * preselection shapes the first step unless `preselectRouting` says to append it. A turn cut off
+ * at `maxTokens` is said so as a notice, because it otherwise reads exactly like a finished one — or, given `maxContinuations`, is
  * continued first. Every turn ends in a `usage` event carrying the turn's own report, with the
- * cache compared against the request before it; see `TurnUsage` and `runMetrics`.
+ * cache compared against the request before it and the request broken down by what filled it; see
+ * `TurnUsage` and `runMetrics`.
+ *
+ * Each step's reported prompt goes on a token ledger, in the same epoch as the step before where
+ * the request only appended to it and in a new one where it did not — a `beforeStep` that rewrote
+ * the transcript, a tool array a load grew — so that what the messages between two steps cost can
+ * be read back as a subtraction. The prompt recorded is the first request's, before any
+ * continuation, and a step that reported none, or reported a cache count above its prompt, is not
+ * recorded. The ledger comes back in the result and on every `usage` event; see `tokensBetween`.
  *
  * @param options The config, transcript, tools and dispatcher, plus the optional hooks, events
  * and cancellation. See `AgentLoopOptions`.