@cubicecho/agent-core 2.24.0 → 2.25.1

package/dist/agent-loop.js

@@ -1,229 +1,30 @@
-import { charsPerTokenFor } from "./calibration.js";
-import { capabilitiesFor, ceilingAndTemperature, effortFor, modelCapabilitiesFor, } from "./capabilities.js";
-import { firstTokenMs, getClient, NO_KEY, timeoutMs } from "./client.js";
-import { compactTranscript, planCompaction, summariser, } from "./compaction.js";
-import { continueTurn } from "./continuation.js";
-import { AgentLoopError, AgentLoopOverflow, errorMessage, ToolIterationLimit, } from "./errors.js";
-import { runMetrics, stamp } from "./events.js";
-import { configureHooks, gather, notify, turnIndex, turnMessages, withContext, } from "./hooks.js";
-import { rebaseLedger, recordRequest } from "./ledger.js";
-import { ContextOverflow, contextTokens, toolsChars } from "./retry.js";
-import { runTurn } from "./run-turn.js";
-import { relaxTools, sanitizeTools } from "./schema-compat.js";
-import { askJson, tryAsk } from "./side-task.js";
-import { noUsage } from "./stream.js";
-import { parseToolArguments, recoverToolCalls } from "./tool-calls.js";
-import { CALL_TOOL, catalogPrompt, expandNames, inCatalog, LOAD_TOOLS, LOAD_TOOLS_DEFINITION, loadedTools, loadResult, MAX_PER_LOAD, orderTools, PRESELECT_SCHEMA, PROXY_TOOLS, preselectByKeywords, preselectInput, preselection, preselectSystem, proxiedCall, proxyCatalogPrompt, proxyLoadResult, requestedNames, shownCall, toolName, } from "./tool-loading.js";
-/**
- * The loop above a turn: send, run the tools the model asked for, send again, until it stops
- * asking.
- *
- * Three servers wrote this loop separately after `runTurn` had already been pulled in here, and
- * the copies drifted the way the turn's own had — one noticed a turn cut off at the ceiling and
- * two did not, one tested the ceiling's spelling the other way round, one sent a reasoning effort
- * and two never did. What is here is the part that does not know what the run is for; the
- * prompts, the tools and what a run means stay with the caller.
- */
-/** The fields `extraBody` may not override, because the loop's request is built around them. */
-const RESERVED = new Set(["model", "messages", "stream", "tools"]);
-/**
- * The one place a streamed request's body is decided from a config and what the endpoint and
- * the model have refused.
- *
- * Every field that negotiates lives here: the ceiling's two spellings, a temperature only a
- * model that takes ours is sent, a reasoning effort only one that takes it is, `stream_options`
- * only where the server has heard of it, relaxed schemas only where it could not build a grammar,
- * and `extraBody` last, less whatever the model refused by name. The ceiling is tested
- * `=== false` — `modelCapabilitiesFor` starts a model at `legacyTokenLimit: true` and an absent
- * one has to read the same — which is the test one of the three copies had inverted.
- *
- * @param config What to ask for. `maxTokens` of zero or less sends no ceiling; `reasoningEffort`
- * absent or `"off"` sends no effort, and one the model has refused by value is stepped up to the
- * cheapest it takes by `effortFor`.
- * @param supports What the endpoint has refused, as `negotiate` hands it to `send`.
- * @param refused What the model has refused, as `negotiate` hands it over. Absent is a model
- * that has refused nothing.
- * @param messages The request's messages, system prompt included, sent as they are.
- * @param tools The tool definitions. Ordered by name, sanitised here — a lookup for a definition
- * seen before — and relaxed where the endpoint needs it. Empty sends no `tools` field at all.
- * @param order How to order them before sending. `true`, the default, is by name, which keeps the
- * cache when the caller's array is assembled differently from one request to the next. See
- * `orderTools`.
- */
-export function buildBody(config, supports, refused, messages, tools = [], order = true) {
-    const sorted = orderTools(tools, order);
-    const declared = supports.strictSchemas
-        ? sanitizeTools(sorted)
-        : relaxTools(sanitizeTools(sorted));
-    const effort = effortFor(refused, config.reasoningEffort);
-    const extra = Object.entries(config.extraBody ?? {}).filter(([field]) => !RESERVED.has(field) && !refused?.refusedFields.has(field));
-    return {
-        ...ceilingAndTemperature(refused, config.maxTokens, config.temperature),
-        ...(effort ? { reasoning_effort: effort } : {}),
-        ...(supports.usageInStream ? { stream_options: { include_usage: true } } : {}),
-        ...Object.fromEntries(extra),
-        model: config.model,
-        messages,
-        stream: true,
-        ...(declared.length ? { tools: declared } : {}),
-    };
-}
-/**
- * A long tool argument or result cut to what a watcher needs, with the full length said.
- *
- * For events, never for the transcript: the model reads the whole of what a tool returned.
- *
- * @param text What to show.
- * @param limit Characters kept, 2000 by default. Text at or under it comes back as it was.
- */
-export const preview = (text, limit = 2000) => text.length > limit ? `${text.slice(0, limit)}… (${text.length} chars)` : text;
-/** A count and its noun, plural unless the count is one: `1 tool`, `3 tools`. */
-const counted = (count, noun) => `${count} ${noun}${count === 1 ? "" : "s"}`;
-/** A base URL as two settings rows would agree on it: trimmed, without the trailing slash. */
-const sameUrl = (a, b) => a.trim().replace(/\/+$/, "") === b.trim().replace(/\/+$/, "");
-/**
- * The key to send, where an endpoint may inherit one from the settings it overrides.
- *
- * A credential issued for one endpoint has no business being posted to another. A profile that
- * names its own `baseUrl` and no key of its own is sent `NO_KEY` — not the operator's key, and
- * not `$OPENAI_API_KEY` — because "I pointed an agent at a friend's server and it sent my OpenAI
- * key" is not a mistake worth being able to make, and a local server wants no key anyway. One on
- * the same endpoint inherits the key as it inherits everything else, and the environment is the
- * last word on the endpoint that was configured rather than overridden.
- *
- * @param own The endpoint as the agent or profile states it. Its own key always wins. An empty or
- * absent `baseUrl` is one that inherits the endpoint too.
- * @param inherited The settings it overrides. Absent treats `own` as the configured endpoint, so
- * only its key and the environment's are in play.
- * @param env Where `OPENAI_API_KEY` is read from, `process.env` by default.
- */
-export function resolveApiKey(own, inherited, env = process.env) {
-    if (own.apiKey)
-        return own.apiKey;
-    const baseUrl = own.baseUrl?.trim();
-    if (inherited && baseUrl && !sameUrl(baseUrl, inherited.baseUrl))
-        return NO_KEY;
-    return inherited?.apiKey || env.OPENAI_API_KEY || NO_KEY;
-}
-/**
- * A side task's settings as the call that honours them: its endpoint, its model, and the options
- * `ask`, `askJson`, `summariser` and `preselect` take last.
- *
- * A helper rather than a second signature on each of the four, so a setting added to a task later
- * arrives through `options` without a host's call changing. What the task states wins over the
- * same field in `options`: the host's code is written once and the task is what an operator
- * configured over it, so a host passes its own ceiling as the value for a task that names none.
- * A setting the task leaves out and `options` does too is absent from the result, which is what
- * leaves it to the entry point's own default — 0.3, not the agent's temperature.
- *
- * A resolved spec carries no key, so a task on the agent's own endpoint would otherwise go out
- * unkeyed, and be remembered under a second capability entry beside the agent's. Given `agent`,
- * such a task is sent the agent's `baseUrl` as the agent spells it and, having no key of its own,
- * the agent's key, so `capabilitiesFor` answers both with one object; a task on another endpoint
- * is sent only a key of its own, as `resolveApiKey` has it. The environment is not read: the
- * agent's key is whatever the main turn is sent.
- *
- * @param task The task, ordinarily `resolved.tasks.<key>`.
- * @param options What the host adds — cancellation, notices, `keywords` — and its own defaults
- * for the settings a task may leave out.
- * @param agent The endpoint the main turn uses, key included. Absent sends the task's endpoint
- * as it stands.
- */
-export function taskCall(task, options, agent) {
-    const own = task.endpoint;
-    const shared = agent && (!own.baseUrl.trim() || sameUrl(own.baseUrl, agent.baseUrl));
-    const stated = {};
-    if (task.maxTokens !== undefined)
-        stated.maxTokens = task.maxTokens;
-    if (task.temperature !== undefined)
-        stated.temperature = task.temperature;
-    if (task.reasoningEffort !== undefined)
-        stated.reasoningEffort = task.reasoningEffort;
-    return {
-        endpoint: agent
-            ? {
-                ...own,
-                ...(shared ? { baseUrl: agent.baseUrl } : {}),
-                apiKey: resolveApiKey(own, agent, {}),
-            }
-            : own,
-        model: task.model,
-        options: { ...options, ...stated },
-    };
-}
-/**
- * The tools a request is likely to need, picked by a small model before the run starts, or none.
- *
- * On-demand loading otherwise spends a round trip on reading the catalogue and calling
- * `load_tools`; a small model reading the same catalogue usually names the right tools, and the
- * task model opens with them in hand. A wrong guess costs a few hundred tokens for one run, and
- * a failed one costs nothing — it is reported through `onNotice` and answered with an empty list,
- * since a side task is never worth failing the run. A stop still throws.
- *
- * With `keywords`, the request's own words are matched against the catalogue first and the model
- * is spent only on what they cannot settle, which on a local box is the difference between a run
- * starting now and starting in a few seconds. The words have to be clear about it; see
- * `preselectByKeywords` for what that means.
- *
- * @param config The endpoint the preselector is reached through.
- * @param model The preselector. An empty name picks nothing, which is what `toolSelectModel`
- * means by empty.
- * @param catalog The servers to choose from.
- * @param prompt The request being planned for. Only its head is read; see `preselectInput`.
- * @param options Cancellation, notices, the reply ceiling (256), the temperature and reasoning
- * effort as `ask` reads them (0.3 and none when absent), the cap the choice is held to
- * (`MAX_PER_LOAD`), and whether to try the words first.
- */
-export async function preselect(config, model, catalog, prompt, { signal, onNotice, maxTokens = 256, temperature, reasoningEffort, maxPerLoad = MAX_PER_LOAD, keywords, } = {}) {
-    if (!model || !catalog.some((server) => server.tools.length > 0))
-        return [];
-    if (keywords) {
-        const guess = preselectByKeywords(catalog, prompt, {
-            maxPerLoad,
-            ...(keywords === true ? {} : keywords),
-        });
-        if (guess.confident) {
-            onNotice?.(`chose ${counted(guess.names.length, "tool")} by name`);
-            return guess.names;
-        }
-    }
-    const reply = await tryAsk("preselect", () => askJson(config, model, preselectSystem(maxPerLoad), preselectInput(catalog, prompt), PRESELECT_SCHEMA, { name: "preselection", maxTokens, temperature, reasoningEffort, signal, onNotice }), { onNotice });
-    return preselection(reply, catalog, maxPerLoad);
-}
-/**
- * The four token counts of one usage added into another. Only those: the rest are measurements a
- * sum of would mean nothing, or would mean something only `runMetrics` knows how to weigh.
- */
-const accumulate = (total, turn) => {
-    total.prompt += turn.prompt;
-    total.completion += turn.completion;
-    total.total += turn.total;
-    total.cached += turn.cached;
-};
-/** Whether two messages say the same thing, by identity first since most of a transcript is. */
-const sameMessage = (a, b) => a === b || JSON.stringify(a) === JSON.stringify(b);
-/** The system messages a request opens with, which a template renders ahead of the history. */
-const leadingSystem = (messages) => {
-    const end = messages.findIndex((message) => message.role !== "system");
-    return messages.slice(0, end === -1 ? messages.length : end);
-};
-/**
- * Where a request stopped matching the one before it, earliest in the rendered prompt first — the
- * tool block, then the system prompt, then the history — or `none-known` where it only appended.
- */
-function breakReason(previous, messages, tools) {
-    if (previous.tools.length !== tools.length ||
-        previous.tools.some((name, at) => name !== tools[at]))
-        return "tools-changed";
-    const before = leadingSystem(previous.messages);
-    const now = leadingSystem(messages);
-    if (before.length !== now.length || before.some((message, at) => !sameMessage(message, now[at])))
-        return "system-changed";
-    if (previous.messages.length > messages.length ||
-        previous.messages.some((message, at) => !sameMessage(message, messages[at])))
-        return "history-rewritten";
-    return "none-known";
-}
+import { charsPerTokenFor } from './calibration.js';
+import { capabilitiesFor, modelCapabilitiesFor, } from './capabilities.js';
+import { firstTokenMs, getClient, loadingMs, timeoutMs } from './client.js';
+import { compactTranscript, planCompaction, summariser } from './compaction.js';
+import { ToolDiscovery } from './config.js';
+import { continueTurn } from './continuation.js';
+import { AgentLoopError, AgentLoopOverflow, errorMessage, ToolIterationLimit, } from './errors.js';
+import { RunEventKind, RunOutcome, runMetrics, stamp, } from './events.js';
+import { counted } from './guards.js';
+import { HookEvent } from './hook-events.js';
+import { configureHooks, gather, notify, turnIndex, turnMessages, withContext, } from './hooks.js';
+import { breakReason, rebaseLedger, recordRequest, } from './ledger.js';
+import { preselect } from './preselect.js';
+import { buildBody } from './request-body.js';
+import { ContextOverflow } from './retry.js';
+import { assistantMessage, definedAs, loadShortlist, readCalls, runCalls, } from './run-calls.js';
+import { runTurn } from './run-turn.js';
+import { taskCall, tryAsk } from './side-task.js';
+import { addCounts, noUsage } from './stream.js';
+import { contextTokens, toolsChars } from './tokens.js';
+import { recoverToolCalls, } from './tool-calls.js';
+import { CALL_TOOL, catalogPrompt, inCatalog, LOAD_TOOLS, LOAD_TOOLS_DEFINITION, loadedTools, orderTools, PROXY_TOOLS, proxyCatalogPrompt, toolName, } from './tool-loading.js';
+import { FinishReason, PartType, Role } from './wire.js';
+/** The `preselectRouting` that sends the first step the shortlist alone. */
+export const PRESELECT_EXCLUSIVE = 'exclusive';
+/** The `preselectRouting` that loads the shortlist after what was carried, and sends the first step like any other. */
+export const PRESELECT_APPEND = 'append';
 /**
  * The share of the previous prompt a cache that kept its prefix reports as hit. Short of it by
  * more than this is a break, not the few tokens a template re-renders at the join.
@@ -231,28 +32,45 @@ function breakReason(previous, messages, tools) {
 const CACHE_KEPT = 0.9;
 /**
  * What one turn's cache should have been and whether it was, against the request before it.
+ *
+ * @param previous - The request before this one, with what it reported. Absent, or with no prompt
+ * reported, diagnoses nothing.
+ * @param next - The request this turn sent, read only to say why a broken cache broke.
+ * @param usage - The turn's own report. Not written to. One with no `uncached` did not report its
+ * cache, and is told what to expect without being judged.
+ * @returns The fields to lay over the turn's usage: `cacheExpected`, the previous prompt plus its
+ * completion; `cacheBroken` where the cache was reported; and `cacheBreakReason` where it broke.
+ * Empty where nothing is diagnosed.
+ *
+ * @remarks
  * Nothing before the second request, or where the previous prompt was not reported.
  */
-function cacheDiagnosis(previous, messages, tools, usage) {
-    if (!previous || !(previous.prompt > 0))
+function cacheDiagnosis(previous, next, usage) {
+    if (!previous || !(previous.prompt > 0)) {
         return {};
+    }
     const found = { cacheExpected: previous.prompt + previous.completion };
-    if (usage.uncached === undefined)
+    if (usage.uncached === undefined) {
         return found;
+    }
     found.cacheBroken = usage.cached < previous.prompt * CACHE_KEPT;
-    if (found.cacheBroken)
-        found.cacheBreakReason = breakReason(previous, messages, tools);
+    if (found.cacheBroken) {
+        found.cacheBreakReason = breakReason(previous, next);
+    }
     return found;
 }
-/** What a tool call the run was stopped during is answered with, in place of a result. */
-const STOPPED_CALL = "Stopped before this call finished.";
-/** The same for a call of that step the loop never got to. */
-const UNRUN_CALL = "Not run: the run stopped first.";
 /**
  * Runs a question to its answer: one `runTurn` per step, the tools it asks for between them,
  * until a turn asks for none. Throws when `maxToolIterations` is spent, when stopped, and on
  * whatever `runTurn` throws — `ContextOverflow` among them, however it was found out.
  *
+ * @param options - The config, transcript, tools and dispatcher, plus the optional hooks, events
+ * and cancellation. See `AgentLoopOptions`.
+ * @returns The turn that asked for no tools and the run around it: the transcript with what the
+ * run added, usage, every call, what is loaded and used, the hooks' notes and context, metrics
+ * and the ledger. See `AgentLoopResult`.
+ *
+ * @remarks
  * What it throws carries the run as it stood — `messages`, `usage`, `toolCalls`, `loaded` and
  * `used` — because the steps before a failure were real and a host that stores its transcript
  * has nothing else to store them from. A spent budget is a `ToolIterationLimit`, an overflow is
@@ -290,9 +108,6 @@ const UNRUN_CALL = "Not run: the run stopped first.";
  * `compact` has it fold the transcript, each by the task `config.tasks` carries for it and on
  * that task's own settings — a setting the task leaves out is the side task's default, never the
  * run's `temperature` or `maxTokens`.
- *
- * @param options The config, transcript, tools and dispatcher, plus the optional hooks, events
- * and cancellation. See `AgentLoopOptions`.
  */
 export async function runAgentLoop(options) {
     // Until the steps have set themselves up there is only what the caller handed over.
@@ -317,37 +132,56 @@ export async function runAgentLoop(options) {
             ? new AgentLoopOverflow(error.message, standing.read(), { cause: error })
             : new AgentLoopError(errorMessage(error), standing.read(), { cause: error });
     }
-    if (result)
+    if (result) {
         return result;
+    }
     throw new ToolIterationLimit(`Stopped after ${options.config.maxToolIterations} tool iterations.`, standing.read());
 }
-/** A message's words, as the preselector is asked about them: its string, or its text parts. */
+/**
+ * A message's words, as the preselector is asked about them: its string, or its text parts.
+ *
+ * @param message - The message to read. Absent, or with content that is neither a string nor
+ * parts, reads as empty.
+ * @returns The string as it is, or the text parts joined by newlines with parts of any other kind
+ * left out. Not trimmed.
+ */
 const userText = (message) => {
     const content = message?.content;
-    if (typeof content === "string")
+    if (typeof content === 'string') {
         return content;
-    if (!Array.isArray(content))
-        return "";
-    return content.flatMap((part) => (part.type === "text" ? part.text : [])).join("\n");
+    }
+    if (!Array.isArray(content)) {
+        return '';
+    }
+    return content.flatMap((part) => (part.type === PartType.Text ? part.text : [])).join('\n');
 };
 /**
  * The loop's own preselection: by the task where the config carries one, and by the flattened
- * name on its own endpoint where it does not. `preselect` answers an empty model with nothing, so
- * a config that names neither asks nothing.
+ * name on its own endpoint where it does not.
+ *
+ * @param options - The run's options. Read for the config, the catalogue, the signal, what
+ * `preselect` passes through, and the last user message, whose text is what is asked about.
+ * @param notice - Hears the preselector's notices, a failure among them.
+ * @returns The names picked. Empty where there is no user message or its text is blank — nothing
+ * is asked — and where the preselection picked nothing or failed. An aborted request still rejects.
+ *
+ * @remarks
+ * `preselect` answers an empty model with nothing, so a config that names neither asks nothing.
  */
 async function chooseTools(options, notice) {
     const { config, catalog = [], signal } = options;
-    const prompt = userText(options.messages.findLast((message) => message.role === "user"));
-    if (!prompt.trim())
+    const prompt = userText(options.messages.findLast((message) => message.role === Role.User));
+    if (!prompt.trim()) {
         return [];
+    }
     const asked = {
-        ...(typeof options.preselect === "object" ? options.preselect : {}),
+        ...(typeof options.preselect === 'object' ? options.preselect : {}),
         signal,
         onNotice: notice,
     };
     const selector = config.tasks?.toolSelect;
     if (!selector?.model) {
-        return preselect(config, config.toolSelectModel ?? "", catalog, prompt, asked);
+        return preselect(config, config.toolSelectModel ?? '', catalog, prompt, asked);
     }
     const call = taskCall(selector, asked, config);
     return preselect(call.endpoint, call.model, catalog, prompt, call.options);
@@ -355,72 +189,70 @@ async function chooseTools(options, notice) {
 /**
  * The loop's own summariser, which is the compaction task's or nothing: a summary the main model
  * writes is a second full-price request the operator did not ask for.
+ *
+ * @param options - The run's options. Read for `compact`, `config.tasks.compaction` and the signal.
+ * @param notice - Hears the task's notices, and a summary that failed.
+ * @returns A summariser resolving to the summary, or to an empty string where writing it failed —
+ * an aborted request still rejects. `undefined` where `compact` is off or the task names no model.
  */
 function ownSummariser(options, notice) {
     const { config, signal } = options;
     const compactor = options.compact ? config.tasks?.compaction : undefined;
-    if (!compactor?.model)
+    if (!compactor?.model) {
         return undefined;
+    }
     const call = taskCall(compactor, { signal, onNotice: notice }, config);
     const write = summariser(call.endpoint, call.model, call.options);
     // A summary that fails folds nothing, and the step goes out as it was.
-    return async (text) => (await tryAsk("compaction", () => write(text), { onNotice: notice })) ?? "";
+    return async (text) => (await tryAsk('compaction', () => write(text), { onNotice: notice, signal })) ?? '';
 }
 /**
  * A step's transcript after the loop's own compaction: folded where a fold was due and its summary
  * came back, and otherwise the array it was given.
+ *
+ * @param transcript - The step's messages, after `beforeStep`. Not written to.
+ * @param reported - The last request's prompt tokens as `used`, where they still describe this
+ * transcript. Empty plans from an estimate instead.
+ * @param summarise - Writes the summary. Not called where no fold is due.
+ * @param context - The run's options, read for `compact`'s thresholds, the window, the compaction
+ * task's ceiling and the hooks; the characters per token an estimate is made at; and `notice`,
+ * told of a fold.
+ * @returns `transcript` itself where nothing was folded, otherwise a new array with the folded
+ * stretch replaced by its summary.
  */
-async function foldBeforeStep(transcript, reported, summarise, { options, charsPerToken, notice, }) {
+async function foldBeforeStep(transcript, reported, summarise, { options, charsPerToken, notice }) {
     const { config, hooks } = options;
     const compactor = config.tasks?.compaction;
     const plan = planCompaction(transcript, {
-        ...(typeof options.compact === "object" ? options.compact : {}),
+        ...(typeof options.compact === 'object' ? options.compact : {}),
         limit: config.contextLength ?? 0,
         ...reported,
         charsPerToken,
         ...((compactor?.maxTokens ?? 0) > 0 ? { summaryTokens: compactor?.maxTokens } : {}),
     });
-    if (!plan)
+    if (!plan) {
         return transcript;
+    }
     const folded = await compactTranscript(transcript, plan, summarise, {
         ...(hooks ? { hooks: { run: hooks.run, context: hooks.context, onNote: hooks.onNote } } : {}),
     });
-    if (folded !== transcript)
+    if (folded !== transcript) {
         notice(`compacted ${plan.cut - plan.from} messages into a summary`);
+    }
     return folded;
 }
-/**
- * A turn's calls with their arguments read. A server that parses replayed arguments refuses the
- * almost-JSON a model wrote, so each is normalised here, and one that could not be read at all is
- * replayed as no arguments.
- */
-const readCalls = (calls, finishReason) => calls.map((call) => {
-    try {
-        const args = parseToolArguments(call.function.arguments, { finishReason });
-        return { call, args, normal: JSON.stringify(args) };
-    }
-    catch (error) {
-        return { call, error, normal: "{}" };
-    }
-});
-/** The assistant message a turn is written into the transcript as, its calls' arguments repaired. */
-const assistantMessage = (content, parsed) => ({
-    role: "assistant",
-    content: content || null,
-    ...(parsed.length
-        ? {
-            tool_calls: parsed.map(({ call, normal }) => ({
-                ...call,
-                function: { ...call.function, arguments: normal },
-            })),
-        }
-        : {}),
-});
 /**
  * Tells the `afterTurn` hooks what was answered, with the turn it closed where the question is
- * still in the transcript. Resolves to their notes — failures only, as `notify` returns them.
+ * still in the transcript.
+ *
+ * @param hooks - The run's hooks: the runner, the context the hooks are told, and who hears a note.
+ * @param messages - The transcript as the run ended, the answer on the end.
+ * @param at - Where the question is in `messages`. Negative — there was none, or it has been
+ * folded away — tells the hooks the reply and no `turn`.
+ * @param reply - The answer's text.
+ * @returns A promise of their notes — failures only, as `notify` returns them.
  */
-const tellAfterTurn = (hooks, messages, at, reply) => notify(hooks.run, "afterTurn", {
+const tellAfterTurn = (hooks, messages, at, reply) => notify(hooks.run, HookEvent.AfterTurn, {
     ...hooks.context,
     reply,
     ...(at >= 0
@@ -432,263 +264,172 @@ const tellAfterTurn = (hooks, messages, at, reply) => notify(hooks.run, "afterTu
         }
         : {}),
 }, hooks.onNote);
-/** The definitions the host gave for these names, in the order the names are given. */
-const definedAs = (definitions, names) => [...names].flatMap((name) => definitions.get(name) ?? []);
 /**
- * What a call is shown, counted and dispatched as: a `call_tool` as the tool it names. Read from
- * the repaired arguments where there are any, since the model's own may be almost-JSON.
+ * The loop's own record of what it emitted, less the token deltas, for `runMetrics` at the end.
+ *
+ * @param heard - The host's `onEvent`, still told of every event, deltas included. Absent records
+ * all the same.
+ * @returns `recorded`, the array each event is added to as it is emitted, and `onEvent`, which the
+ * loop emits through in place of the host's.
+ *
+ * @remarks
+ * Stamped here rather than by the bus, which the loop does not know about.
  */
-const shownAs = (run, { call, args, normal }) => run.proxies && call.function.name === CALL_TOOL
-    ? shownCall(CALL_TOOL, args ? normal : call.function.arguments)
-    : { name: call.function.name, input: call.function.arguments };
-/** Answers a `load_tools`, counting what it loaded. Not ok where it named nothing loadable. */
-function answerLoad(run, args) {
-    const { catalog, proxied, definitions, loaded, loads } = run;
-    const resolved = expandNames(requestedNames(args), catalog);
-    const content = proxied
-        ? proxyLoadResult(resolved, catalog, definedAs(definitions, resolved.matched), loaded)
-        : loadResult(resolved, catalog, loaded);
-    // Proxied, a load is only of what the result could define: a catalogued name the host
-    // gave no definition for was not loaded, and is not counted or remembered as though it was.
-    const hits = proxied ? resolved.matched.filter((hit) => definitions.has(hit)) : resolved.matched;
-    for (const hit of hits)
-        loads[loaded.has(hit) ? "redundantLoads" : "toolsLoaded"]++;
-    loads.unknownToolNames += resolved.unknown.length;
-    for (const hit of hits)
-        loaded.add(hit);
-    return { content, ok: hits.length > 0 };
+function recorder(heard) {
+    const recorded = [];
+    const onEvent = (input) => {
+        if (input.kind !== RunEventKind.Thinking && input.kind !== RunEventKind.Output) {
+            recorded.push(stamp(input, '', recorded.length + 1, Date.now()));
+        }
+        heard?.(input);
+    };
+    return { recorded, onEvent };
 }
 /**
- * Runs one call to its result, telling the host of both. A tool that throws is that call's answer
- * rather than the run's end, unless the run was stopped.
+ * How this run finds its tools, and what it starts with in hand: the loop's own preselection
+ * where it was asked for and the host has not already decided, and what an earlier question
+ * carried over.
  *
- * @param run The run the call belongs to.
- * @param entry The call, with its arguments read.
- * @param answered The step's calls already made, by tool and arguments, for `dedupeToolCalls`.
+ * @param options - The run's options. Read for the discovery mode, the catalogue, `loaded`,
+ * `preselected` and `preselect`.
+ * @param notice - Hears what the loop's own preselection has to say.
+ * @returns `proxied` and `onDemand`, the second true of both modes and both false where `catalog`
+ * is empty; `preselected`, the shortlist, empty in eager mode; and `loaded`, a new set of what was
+ * carried and then the shortlist — empty when eager or proxied.
  */
-async function runCall(run, entry, answered) {
-    const { catalog, onDemand, proxied, signal } = run;
-    const { call, args, error: unreadable, normal } = entry;
-    const proxy = run.proxies && call.function.name === CALL_TOOL;
-    const { name, input: raw } = shownAs(run, entry);
-    // Looked through before the call is announced, so a host is told of the tool it names with
-    // that tool's arguments. A name outside the catalogue is refused here, so `call_tool` reaches
-    // nothing a load could not, and the refusal is the call's answer below.
-    let inner = args ?? {};
-    let refused;
-    if (proxy && args) {
-        try {
-            inner = proxiedCall(args, catalog).input;
-        }
-        catch (error) {
-            inner = {};
-            refused = { error };
-        }
+async function discovery(options, notice) {
+    const { config, catalog = [] } = options;
+    // On demand, but with a tool array that never changes: definitions come back as `load_tools`
+    // results and run through `call_tool`. `onDemand` is true of both.
+    const proxied = config.toolDiscovery === ToolDiscovery.Proxy && catalog.length > 0;
+    const onDemand = proxied || (config.toolDiscovery === ToolDiscovery.OnDemand && catalog.length > 0);
+    // Proxied, `loaded` is what this run has put a definition in the history for, and starts empty.
+    const loaded = new Set(onDemand && !proxied ? (options.loaded ?? []) : []);
+    const chooses = options.preselect && options.preselected === undefined;
+    let preselected = [];
+    if (onDemand && chooses) {
+        preselected = await chooseTools(options, notice);
     }
-    // Built for every call rather than only the dispatched ones, so a host hears of the calls
-    // the loop answers itself in the same shape. Arguments that could not be read are none.
-    const request = { id: call.id, name, args: inner, raw };
-    run.onEvent({ kind: "tool-call", id: call.id, name, text: preview(raw) });
-    run.onToolCall?.(request);
-    let content;
-    let ok = true;
-    try {
-        if (!args)
-            throw unreadable;
-        // By the name the model called, not the one a `call_tool` wraps: `load_tools` is not in
-        // the catalogue, and one reached through `call_tool` is refused below like any other.
-        if (onDemand && call.function.name === LOAD_TOOLS) {
-            ({ content, ok } = answerLoad(run, args));
-        }
-        else {
-            if (refused)
-                throw refused.error;
-            // A model that skips `load_tools` and calls a catalogued tool by name is right about
-            // what it wants; load it and run it rather than refusing. Not proxied, where loaded
-            // means its definition is in the history, and this call put none there.
-            if (onDemand && !proxied && inCatalog(catalog, name))
-                run.loaded.add(name);
-            run.used.add(name);
-            // Keyed on the inner call, so one made through `call_tool` and one made natively share.
-            const key = `${name}\0${proxy ? JSON.stringify(inner) : normal}`;
-            content = run.dedupable(request)
-                ? await once(answered, key, () => run.dispatch(request, signal))
-                : await run.dispatch(request, signal);
+    else if (onDemand) {
+        preselected = [...(options.preselected ?? [])];
+    }
+    if (!proxied) {
+        for (const name of preselected) {
+            loaded.add(name);
         }
     }
-    catch (error) {
-        if (signal?.aborted)
-            throw error;
-        content = errorMessage(error);
-        ok = false;
+    return { proxied, onDemand, loaded, preselected };
+}
+/**
+ * The host's definitions by name, the first kept where two share one.
+ *
+ * @param tools - Every definition the host gave. One that is not a function has no name and is
+ * left out.
+ * @returns A new map, in the order of `tools`, holding the definitions themselves.
+ */
+function definitionsByName(tools) {
+    const definitions = new Map();
+    for (const tool of tools) {
+        const name = toolName(tool);
+        if (name !== undefined && !definitions.has(name)) {
+            definitions.set(name, tool);
+        }
     }
-    run.onEvent({ kind: "tool-result", id: call.id, name, ok, text: preview(content) });
-    const result = { id: call.id, name, ok, content };
-    run.onToolResult?.(result);
-    return result;
+    return definitions;
 }
 /**
- * Runs a step's calls and writes each result into the transcript, in the order asked.
+ * Offers each message written into the transcript to the host.
  *
- * A failure part-way leaves the transcript well-formed before it is rethrown: a call with no
- * result is a transcript no endpoint takes back, so every call of the step is answered — with what
- * it returned where it had, and otherwise with a line saying it was stopped, or never run.
+ * @param onMessage - The host's callback, awaited. Absent offers nothing.
+ * @returns The offer, taking a message, its step and the turn it came with: it resolves once the
+ * host has taken the message, and rejects with what the host threw — once.
  *
- * @param run The run the step belongs to.
- * @param parsed The step's calls, with their arguments read.
- * @param messages The transcript the results are written into.
- * @param step Which step this is, for the host told of each result.
+ * @remarks
+ * Once `onMessage` has thrown the run is ending on that, and the results still to be written are
+ * not offered to a host that has just failed to take one.
  */
-async function runCalls(run, parsed, messages, step) {
-    const { signal, toolCalls } = run;
-    // Per step, not per run: the answer to a call made two steps ago was true before the tools in
-    // between ran, and the file the model read may be the file it has since written.
-    const answered = new Map();
-    // By position, so a call that came back while another was being stopped is still found.
-    const outcomes = parsed.map(() => undefined);
-    // How many of the step's calls were handed off, and how many have their result in the
-    // transcript. Both count from the front, since results are written in the order asked.
-    let begun = 0;
-    let kept = 0;
-    const keep = async (id, content) => {
-        const result = {
-            role: "tool",
-            tool_call_id: id,
-            content,
-        };
-        messages.push(result);
-        kept++;
-        await run.announce(result, step);
-    };
-    try {
-        if (run.parallel) {
-            signal?.throwIfAborted();
-            begun = parsed.length;
-            await Promise.all(parsed.map(async (call, at) => {
-                outcomes[at] = await runCall(run, call, answered);
-            }));
-            for (const { id, name, ok, content } of outcomes.flatMap((outcome) => outcome ?? [])) {
-                toolCalls.push({ id, name, ok });
-                await keep(id, content);
-            }
+function announcer(onMessage) {
+    let heard = true;
+    return async (message, step, turn) => {
+        if (!onMessage || !heard) {
+            return;
         }
-        else {
-            for (const [at, call] of parsed.entries()) {
-                signal?.throwIfAborted();
-                begun = at + 1;
-                const { id, name, ok, content } = await runCall(run, call, answered);
-                toolCalls.push({ id, name, ok });
-                await keep(id, content);
-            }
+        try {
+            await onMessage(message, step, turn);
         }
-    }
-    catch (error) {
-        // Only a call that was made counts in `toolCalls`.
-        for (const [at, entry] of parsed.entries()) {
-            const { call } = entry;
-            if (at < kept)
-                continue;
-            const outcome = outcomes[at];
-            // Under the name it was announced by, which for a `call_tool` is the tool it names.
-            if (at < begun) {
-                toolCalls.push({ id: call.id, name: shownAs(run, entry).name, ok: outcome?.ok ?? false });
-            }
-            // The run is already ending on `error`; a host that cannot take this result does not
-            // get to replace it.
-            await keep(call.id, outcome?.content ?? (at < begun ? STOPPED_CALL : UNRUN_CALL)).catch(() => { });
+        catch (error) {
+            heard = false;
+            throw error;
         }
-        throw error;
-    }
+    };
 }
 /**
- * Writes a proxied preselection into the transcript as a `load_tools` exchange: the tool array is
- * fixed, so a shortlist has nowhere else to go, and it is answered as though the model had loaded
- * it. Told to the host as a call the model made would be, so one pairing calls with results by id
- * shows this one like the rest.
+ * The `usage` event a turn ends in: the run's totals so far, and the turn's own report.
  *
- * @param run The run it opens.
- * @param shortlist The definitions preselected, each of them in the catalogue.
- * @param messages The transcript, which the exchange is appended to.
+ * @param usage - The run's totals, this turn's already added.
+ * @param turn - The turn just finished, read for its usage and why it ended.
+ * @param ledger - The ledger as it stands. Carried on the event as it is, not copied.
+ * @returns The event, for the caller to emit.
  */
-async function loadShortlist(run, shortlist, messages) {
-    const { catalog } = run;
-    const names = shortlist.map((tool) => toolName(tool) ?? "");
-    // Numbered by where the call lands, so two questions in one transcript do not share an id.
-    const id = `preselect-${messages.length}`;
-    const args = JSON.stringify({ names });
-    // Held to its own length rather than `MAX_PER_LOAD`: that cap is for a model choosing, and a
-    // host that shortlisted more has already chosen.
-    const content = proxyLoadResult(expandNames(names, catalog, names.length), catalog, shortlist);
-    run.onEvent({ kind: "tool-call", id, name: LOAD_TOOLS, text: preview(args) });
-    run.onToolCall?.({ id, name: LOAD_TOOLS, args: { names }, raw: args });
-    run.onEvent({ kind: "tool-result", id, name: LOAD_TOOLS, ok: true, text: preview(content) });
-    run.onToolResult?.({ id, name: LOAD_TOOLS, ok: true, content });
-    run.toolCalls.push({ id, name: LOAD_TOOLS, ok: true });
-    run.loads.toolsLoaded += names.length;
-    for (const name of names)
-        run.loaded.add(name);
-    const exchange = [
-        {
-            role: "assistant",
-            content: null,
-            tool_calls: [{ id, type: "function", function: { name: LOAD_TOOLS, arguments: args } }],
-        },
-        { role: "tool", tool_call_id: id, content },
-    ];
-    // Both written before either is announced, so a host that throws on the first leaves a call
-    // with its result. Told as step zero's, with no turn: no request was made for them.
-    messages.push(...exchange);
-    for (const message of exchange)
-        await run.announce(message, 0);
+const usageEvent = (usage, turn, ledger) => ({
+    kind: RunEventKind.Usage,
+    usage: {
+        promptTokens: usage.prompt,
+        completionTokens: usage.completion,
+        totalTokens: usage.total,
+        cachedTokens: usage.cached,
+        turn: { ...turn.usage, finishReason: turn.finishReason },
+        ledger,
+    },
+});
+/**
+ * The calls a turn made and the answer beside them, with calls the model wrote as text taken out
+ * of the answer and counted as calls.
+ *
+ * @param turn - The turn as it came back. Not written to.
+ * @param recoverable - The names a call written as text may use. Absent recovers nothing, and
+ * nothing is looked for in a turn that made a named call of its own or has no text.
+ * @param notice - Told when calls were recovered, and how many.
+ * @returns `calls`, the turn's own less any with no name, and `content`, its text as it was — or,
+ * where calls were recovered, those calls and the text without them.
+ */
+function turnCalls(turn, recoverable, notice) {
+    // A call with no name is a fragment the server never finished sending: nothing to run, and
+    // an assistant message naming it would be answered by nothing.
+    const calls = turn.toolCalls.filter((call) => call.function.name);
+    if (!recoverable || calls.length || !turn.content) {
+        return { calls, content: turn.content };
+    }
+    const recovered = recoverToolCalls(turn.content, { names: recoverable });
+    if (!recovered.toolCalls.length) {
+        return { calls, content: turn.content };
+    }
+    notice(`recovered ${counted(recovered.toolCalls.length, 'tool call')} the model wrote as text; the server's tool-call parser does not match this model's template`);
+    return { calls: recovered.toolCalls, content: recovered.content };
 }
 /**
- * The steps of `runAgentLoop`, throwing what they caught as it was caught. Resolves to nothing
- * when `maxToolIterations` is spent, and tells `standing` how to read the run either way.
+ * The steps of `runAgentLoop`, throwing what they caught as it was caught.
+ *
+ * @param options - What `runAgentLoop` was given.
+ * @param standing - Written to: once the steps have set themselves up, its `read` is theirs, so the
+ * caller can read the run as it stands whether they return or throw.
+ * @returns The result of the turn that asked for no tools, or `undefined` when `maxToolIterations`
+ * is spent.
  */
 async function runSteps(options, standing) {
-    const { config, system = "", tools = [], catalog = [], dispatch, hooks, signal } = options;
-    const { onRequest, onTurn, onMessage, onToolCall, onToolResult, beforeStep, parallel = false, recoverToolCalls: recover = true, maxContinuations = 0, toolOrder = true, dedupeToolCalls = true, preselectRouting = "exclusive", } = options;
-    const dedupable = typeof dedupeToolCalls === "function" ? dedupeToolCalls : () => dedupeToolCalls;
+    const { config, system = '', tools = [], catalog = [], dispatch, hooks, signal } = options;
+    const { onRequest, onTurn, onMessage, onToolCall, onToolResult, beforeStep, parallel = false, recoverToolCalls: recover = true, maxContinuations = 0, toolOrder = true, dedupeToolCalls = true, preselectRouting = PRESELECT_EXCLUSIVE, } = options;
+    const dedupable = typeof dedupeToolCalls === 'function' ? dedupeToolCalls : () => dedupeToolCalls;
     const started = Date.now();
-    // What the loop emitted, less the token deltas, for `runMetrics` at the end. Stamped here rather
-    // than by the bus, which the loop does not know about.
-    const recorded = [];
-    const record = (input) => {
-        if (input.kind === "thinking" || input.kind === "output")
-            return;
-        recorded.push(stamp(input, "", recorded.length + 1, Date.now()));
-    };
-    const onEvent = (input) => {
-        record(input);
-        options.onEvent?.(input);
-    };
+    const { recorded, onEvent } = recorder(options.onEvent);
     const client = getClient(config);
     const supports = capabilitiesFor(config.baseUrl, config.apiKey);
     const maxRetries = Math.max(0, Number(config.maxRetries) || 0);
-    const notice = (text) => onEvent({ kind: "notice", text });
-    // On demand, but with a tool array that never changes: definitions come back as `load_tools`
-    // results and run through `call_tool`. `onDemand` is true of both.
-    const proxied = config.toolDiscovery === "proxy" && catalog.length > 0;
-    const onDemand = proxied || (config.toolDiscovery === "ondemand" && catalog.length > 0);
-    // Proxied, `loaded` is what this run has put a definition in the history for, and starts empty.
-    const loaded = new Set(onDemand && !proxied ? (options.loaded ?? []) : []);
-    // The loop's own preselection, where it was asked for and the host has not already decided.
-    const preselected = !onDemand
-        ? []
-        : options.preselect && options.preselected === undefined
-            ? await chooseTools(options, notice)
-            : [...(options.preselected ?? [])];
-    if (!proxied)
-        for (const name of preselected)
-            loaded.add(name);
+    const notice = (text) => onEvent({ kind: RunEventKind.Notice, text });
+    const { proxied, onDemand, loaded, preselected } = await discovery(options, notice);
     const summarise = ownSummariser(options, notice);
     const used = new Set();
-    const definitions = new Map();
-    for (const tool of tools) {
-        const name = toolName(tool);
-        if (name !== undefined && !definitions.has(name))
-            definitions.set(name, tool);
-    }
+    const definitions = definitionsByName(tools);
     // Looked through unless the host has a tool by that name, which is then the host's to answer.
     const proxies = onDemand && !definitions.has(CALL_TOOL);
     // What a call the model wrote as text may name: the host's tools, and the loop's own on demand.
@@ -700,7 +441,7 @@ async function runSteps(options, standing) {
     // in the order things were added, so a load appends and never reshuffles what went before.
     const byName = (names) => definedAs(definitions, names);
     let messages = [...options.messages];
-    const usage = noUsage();
+    let usage = noUsage();
     const toolCalls = [];
     standing.read = () => ({
         messages,
@@ -710,32 +451,19 @@ async function runSteps(options, standing) {
         loaded: proxied ? [] : [...loaded],
         used: [...used],
     });
-    // Once `onMessage` has thrown the run is ending on that, and the results still to be written
-    // into the transcript are not offered to a host that has just failed to take one.
-    let heard = true;
-    const announce = async (message, step, turn) => {
-        if (!onMessage || !heard)
-            return;
-        try {
-            await onMessage(message, step, turn);
-        }
-        catch (error) {
-            heard = false;
-            throw error;
-        }
-    };
+    const announce = announcer(onMessage);
     // Held by reference rather than by index, so a `beforeStep` that folds the head into a summary
     // moves the question without losing it — and one that summarises the question away takes the
     // hooks' context with it, which is right.
-    const question = messages.findLast((message) => message.role === "user");
+    const question = messages.findLast((message) => message.role === Role.User);
     const questionAt = () => (question ? messages.indexOf(question) : -1);
     const gathered = hooks
-        ? await gather(hooks.run, hooks.events ?? ["beforeTurn"], hooks.context, {
+        ? await gather(hooks.run, hooks.events ?? [HookEvent.BeforeTurn], hooks.context, {
             signal,
             onNote: hooks.onNote,
             maxTokens: hooks.maxTokens,
         })
-        : { context: "", notes: [] };
+        : { context: '', notes: [] };
     // Read once, so what the result hands back is what every step of this run said.
     const preface = hooks?.preface ?? configureHooks().preface;
     const loads = { toolsLoaded: 0, redundantLoads: 0, unknownToolNames: 0 };
@@ -771,8 +499,9 @@ async function runSteps(options, standing) {
         onToolResult,
         announce,
     };
-    if (shortlist.length)
+    if (shortlist.length) {
         await loadShortlist(calling, shortlist, messages);
+    }
     for (let step = 0; step < config.maxToolIterations; step++) {
         // A stop aborts the request in flight, but a tool call already handed off runs to its own
         // end — so the signal is read between steps as well.
@@ -795,24 +524,29 @@ async function runSteps(options, standing) {
             : given;
         // A rewrite may have folded a definition away, and a load answered "already loaded" would
         // then point at nothing. Forgetting costs a definition sent twice at worst.
-        if (proxied && next !== messages)
+        if (proxied && next !== messages) {
             loaded.clear();
+        }
         messages = next;
         ledger = rebaseLedger(ledger, before, messages);
-        onEvent({ kind: "turn", text: `turn ${step + 1}` });
+        onEvent({ kind: RunEventKind.Turn, text: `turn ${step + 1}` });
         // Appended, the shortlist is already in `loaded` — after what was carried, and once — so the
         // first step needs nothing of its own. Proxied, it is in the history.
-        const routed = !proxied && preselectRouting !== "append" && preselected.length > 0 && step === 0;
+        const routed = !proxied && preselectRouting !== PRESELECT_APPEND && preselected.length > 0 && step === 0;
         // Ordered here rather than left to `buildBody`, so `names` below is what the request actually
         // declared — a diagnosis reading an order the server never saw calls an untouched tool array
         // `tools-changed`.
-        const declared = orderTools(routed
-            ? byName(new Set(preselected))
-            : proxied
-                ? [...PROXY_TOOLS]
-                : onDemand
-                    ? loadedTools([LOAD_TOOLS_DEFINITION], byName(loaded))
-                    : tools, toolOrder);
+        let offered = tools;
+        if (routed) {
+            offered = byName(new Set(preselected));
+        }
+        else if (proxied) {
+            offered = [...PROXY_TOOLS];
+        }
+        else if (onDemand) {
+            offered = loadedTools([LOAD_TOOLS_DEFINITION], byName(loaded));
+        }
+        const declared = orderTools(offered, toolOrder);
         // Unmarked, so the system prompt is the same text on every step and a load does not throw
         // away the cache for the whole transcript. What is loaded is said in `declared` and in the
         // `load_tools` result instead. The preselected first step is the one exception, by design,
@@ -820,7 +554,7 @@ async function runSteps(options, standing) {
         const catalogue = proxied ? proxyCatalogPrompt(catalog) : catalogPrompt(catalog);
         const prompt = onDemand && !routed ? `${system}\n\n${catalogue}`.trim() : system;
         const request = [
-            ...(prompt ? [{ role: "system", content: prompt }] : []),
+            ...(prompt ? [{ role: Role.System, content: prompt }] : []),
             ...withContext(messages, questionAt(), gathered.context, preface),
         ];
         const build = (supported, refused) => buildBody(config, supported, refused, request, declared, toolOrder);
@@ -828,16 +562,14 @@ async function runSteps(options, standing) {
             model: config.model,
             droppable: Object.keys(config.extraBody ?? {}),
             maxRetries,
-            ...(config.loadingTimeoutSeconds === undefined
-                ? {}
-                : { loadingTimeoutMs: Math.max(0, config.loadingTimeoutSeconds) * 1000 }),
+            loadingTimeoutMs: loadingMs(config),
             contextLimit: config.contextLength ?? 0,
             signal,
             idleMs: timeoutMs(config),
             firstChunkMs: firstTokenMs(config) ?? 0,
             onNotice: notice,
-            onThinking: (text) => onEvent({ kind: "thinking", text }),
-            onOutput: (text) => onEvent({ kind: "output", text }),
+            onThinking: (text) => onEvent({ kind: RunEventKind.Thinking, text }),
+            onOutput: (text) => onEvent({ kind: RunEventKind.Output, text }),
         };
         // Built the way `negotiate` is about to build the first attempt — the same flags, the same
         // model's refusals — so what the host is told is what is sent unless something is refused.
@@ -846,13 +578,13 @@ async function runSteps(options, standing) {
             onRequest({ messages: opening.messages, tools: opening.tools ?? [], step });
         }
         const first = await runTurn(client, supports, build, turnOptions);
-        const names = declared.map((tool) => toolName(tool) ?? "");
+        const names = declared.map((tool) => toolName(tool) ?? '');
         // Compared before any continuation is joined on: the cache a request meets is the one its own
         // prompt found, and a continuation's prompt is this request's plus the reply so far.
         // The breakdown measures the array `toolSchemaTokens` does, so where no prompt was reported
         // the two give one number for the tool block rather than two.
         const charsPerToken = charsPerTokenFor(supports, config.model);
-        Object.assign(first.usage, cacheDiagnosis(previous, request, names, first.usage), {
+        Object.assign(first.usage, cacheDiagnosis(previous, { messages: request, tools: names }, first.usage), {
             toolsDeclared: declared.length,
             toolSchemaTokens: Math.ceil(toolsChars(declared) / charsPerToken),
             context: contextTokens({ model: config.model, stream: true, messages: request, tools: declared }, { charsPerToken, promptTokens: first.usage.prompt }),
@@ -867,8 +599,9 @@ async function runSteps(options, standing) {
             through: messages.length - 1,
         };
         const entered = recordRequest(ledger, measured, sent);
-        if (entered !== ledger)
+        if (entered !== ledger) {
             measured = sent;
+        }
         ledger = entered;
         const turn = maxContinuations > 0
             ? await continueTurn(client, supports, build, first, { ...turnOptions, maxContinuations })
@@ -879,33 +612,13 @@ async function runSteps(options, standing) {
             prompt: firstPrompt,
             completion: turn.usage.completion,
         };
-        accumulate(usage, turn.usage);
-        onEvent({
-            kind: "usage",
-            usage: {
-                promptTokens: usage.prompt,
-                completionTokens: usage.completion,
-                totalTokens: usage.total,
-                cachedTokens: usage.cached,
-                turn: { ...turn.usage, finishReason: turn.finishReason },
-                ledger,
-            },
-        });
-        if (turn.finishReason === "length") {
+        usage = addCounts(usage, turn.usage);
+        onEvent(usageEvent(usage, turn, ledger));
+        if (turn.finishReason === FinishReason.Length) {
             notice(`the model stopped at maxTokens (${config.maxTokens}); this turn is cut short`);
         }
-        // A call with no name is a fragment the server never finished sending: nothing to run, and
-        // an assistant message naming it would be answered by nothing.
-        let calls = turn.toolCalls.filter((call) => call.function.name);
-        let content = turn.content;
-        if (recover && !calls.length && content && (tools.length > 0 || onDemand)) {
-            const recovered = recoverToolCalls(content, { names: recoverable });
-            if (recovered.toolCalls.length) {
-                calls = recovered.toolCalls;
-                content = recovered.content;
-                notice(`recovered ${counted(calls.length, "tool call")} the model wrote as text; the server's tool-call parser does not match this model's template`);
-            }
-        }
+        const canRecover = recover && (tools.length > 0 || onDemand);
+        const { calls, content } = turnCalls(turn, canRecover ? recoverable : undefined, notice);
         const shown = { ...turn, content, toolCalls: calls };
         onTurn?.(shown, step);
         // Read before the assistant message is written, so what is replayed on every later request
@@ -917,9 +630,7 @@ async function runSteps(options, standing) {
         if (!calls.length) {
             // Not awaited: the answer is ready, and remembering it is not something to hold it for.
             // Handed back instead, for a host that wants its notes.
-            const afterTurn = hooks
-                ? tellAfterTurn(hooks, messages, questionAt(), turn.content)
-                : Promise.resolve([]);
+            const afterTurn = hooks ? tellAfterTurn(hooks, messages, questionAt(), turn.content) : Promise.resolve([]);
             const metrics = runMetrics(recorded, { contextLength: config.contextLength });
             return {
                 turn: shown,
@@ -936,7 +647,7 @@ async function runSteps(options, standing) {
                     ...metrics,
                     ...(onDemand ? loads : {}),
                     wallMs: Date.now() - started,
-                    outcome: turn.finishReason === "length" ? "truncated" : "answered",
+                    outcome: turn.finishReason === FinishReason.Length ? RunOutcome.Truncated : RunOutcome.Answered,
                 },
                 ledger,
             };
@@ -945,23 +656,3 @@ async function runSteps(options, standing) {
     }
     return undefined;
 }
-/**
- * Makes a call at most once per key, sharing the in-flight promise so two identical calls in one
- * step make one request between them whether they run together or one after the other. A call
- * that rejected is forgotten, so asking again is a real retry rather than a replayed failure.
- */
-async function once(answered, key, make) {
-    const previous = answered.get(key);
-    if (previous)
-        return previous;
-    const pending = make();
-    answered.set(key, pending);
-    try {
-        return await pending;
-    }
-    catch (error) {
-        if (answered.get(key) === pending)
-            answered.delete(key);
-        throw error;
-    }
-}