@cubicecho/agent-core 2.23.0 → 2.25.0

package/dist/agent-loop.js

@@ -1,231 +1,30 @@
-import { charsPerTokenFor } from "./calibration.js";
-import { capabilitiesFor, 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 } 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 { 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, } 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 {
-        ...(config.maxTokens > 0
-            ? refused?.legacyTokenLimit === false
-                ? { max_completion_tokens: config.maxTokens }
-                : { max_tokens: config.maxTokens }
-            : {}),
-        ...(refused?.chosenTemperature === false ? {} : { temperature: 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 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 ${guess.names.length} tool${guess.names.length === 1 ? "" : "s"} 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.
@@ -233,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
@@ -292,16 +108,13 @@ 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.
     const standing = {
         read: () => ({
             messages: [...options.messages],
-            usage: { prompt: 0, completion: 0, total: 0, cached: 0 },
+            usage: noUsage(),
             toolCalls: [],
             loaded: [],
             used: [],
@@ -319,112 +132,316 @@ 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 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 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.
+ *
+ * @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 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 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({
-            runId: "",
-            seq: recorded.length + 1,
-            at: Date.now(),
-            text: "",
-            name: "",
-            step: "",
-            ok: null,
-            usage: null,
-            ...input,
-        });
+async function chooseTools(options, notice) {
+    const { config, catalog = [], signal } = options;
+    const prompt = userText(options.messages.findLast((message) => message.role === Role.User));
+    if (!prompt.trim()) {
+        return [];
+    }
+    const asked = {
+        ...(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);
+    }
+    const call = taskCall(selector, asked, config);
+    return preselect(call.endpoint, call.model, catalog, prompt, call.options);
+}
+/**
+ * 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) {
+        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 })) ?? '';
+}
+/**
+ * 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 }) {
+    const { config, hooks } = options;
+    const compactor = config.tasks?.compaction;
+    const plan = planCompaction(transcript, {
+        ...(typeof options.compact === 'object' ? options.compact : {}),
+        limit: config.contextLength ?? 0,
+        ...reported,
+        charsPerToken,
+        ...((compactor?.maxTokens ?? 0) > 0 ? { summaryTokens: compactor?.maxTokens } : {}),
+    });
+    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) {
+        notice(`compacted ${plan.cut - plan.from} messages into a summary`);
+    }
+    return folded;
+}
+/**
+ * Tells the `afterTurn` hooks what was answered, with the turn it closed where the question is
+ * 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, HookEvent.AfterTurn, {
+    ...hooks.context,
+    reply,
+    ...(at >= 0
+        ? {
+            turn: {
+                index: turnIndex(messages, at),
+                messages: turnMessages(hooks.context.session.id, messages, at),
+            },
+        }
+        : {}),
+}, hooks.onNote);
+/**
+ * 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.
+ */
+function recorder(heard) {
+    const recorded = [];
     const onEvent = (input) => {
-        record(input);
-        options.onEvent?.(input);
+        if (input.kind !== RunEventKind.Thinking && input.kind !== RunEventKind.Output) {
+            recorded.push(stamp(input, '', recorded.length + 1, Date.now()));
+        }
+        heard?.(input);
     };
-    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 });
+    return { recorded, onEvent };
+}
+/**
+ * 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 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 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 === "proxy" && catalog.length > 0;
-    const onDemand = proxied || (config.toolDiscovery === "ondemand" && catalog.length > 0);
+    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 ?? []) : []);
-    // The loop's own preselection, where it was asked for and the host has not already decided: 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 neither named asks nothing.
-    const choose = async () => {
-        const prompt = userText(options.messages.findLast((message) => message.role === "user"));
-        if (!prompt.trim())
-            return [];
-        const asked = {
-            ...(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);
-        }
-        const call = taskCall(selector, asked, config);
-        return preselect(call.endpoint, call.model, catalog, prompt, call.options);
-    };
-    const preselected = !onDemand
-        ? []
-        : options.preselect && options.preselected === undefined
-            ? await choose()
-            : [...(options.preselected ?? [])];
-    if (!proxied)
-        for (const name of preselected)
+    const chooses = options.preselect && options.preselected === undefined;
+    let preselected = [];
+    if (onDemand && chooses) {
+        preselected = await chooseTools(options, notice);
+    }
+    else if (onDemand) {
+        preselected = [...(options.preselected ?? [])];
+    }
+    if (!proxied) {
+        for (const name of preselected) {
             loaded.add(name);
-    // The loop's own compaction, which is the task's or nothing: a summary the main model writes is
-    // a second full-price request the operator did not ask for.
-    const compactor = options.compact ? config.tasks?.compaction : undefined;
-    const summarise = (() => {
-        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 })) ?? "";
-    })();
-    const used = new Set();
+        }
+    }
+    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) {
-        if (tool.type === "function" && !definitions.has(tool.function.name)) {
-            definitions.set(tool.function.name, tool);
+        const name = toolName(tool);
+        if (name !== undefined && !definitions.has(name)) {
+            definitions.set(name, tool);
         }
     }
+    return definitions;
+}
+/**
+ * Offers each message written into the transcript to the host.
+ *
+ * @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.
+ *
+ * @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.
+ */
+function announcer(onMessage) {
+    let heard = true;
+    return async (message, step, turn) => {
+        if (!onMessage || !heard) {
+            return;
+        }
+        try {
+            await onMessage(message, step, turn);
+        }
+        catch (error) {
+            heard = false;
+            throw error;
+        }
+    };
+}
+/**
+ * The `usage` event a turn ends in: the run's totals so far, and the turn's own report.
+ *
+ * @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.
+ */
+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.
+ *
+ * @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 = PRESELECT_EXCLUSIVE, } = options;
+    const dedupable = typeof dedupeToolCalls === 'function' ? dedupeToolCalls : () => dedupeToolCalls;
+    const started = Date.now();
+    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: RunEventKind.Notice, text });
+    const { proxied, onDemand, loaded, preselected } = await discovery(options, notice);
+    const summarise = ownSummariser(options, notice);
+    const used = new Set();
+    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.
+    const recoverable = [
+        ...tools.map(toolName).filter((name) => name !== undefined),
+        ...(onDemand ? [LOAD_TOOLS, ...(proxies ? [CALL_TOOL] : [])] : []),
+    ];
     // In the order the names are given, not the order of `tools`: `loaded` is a set, which iterates
     // in the order things were added, so a load appends and never reshuffles what went before.
-    const byName = (names) => [...names].flatMap((name) => definitions.get(name) ?? []);
+    const byName = (names) => definedAs(definitions, names);
     let messages = [...options.messages];
-    const usage = { prompt: 0, completion: 0, total: 0, cached: 0 };
+    let usage = noUsage();
     const toolCalls = [];
     standing.read = () => ({
         messages,
@@ -434,31 +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 };
@@ -467,94 +472,81 @@ async function runSteps(options, standing) {
     // The request the ledger's last entry came from, which is what the next one is measured against.
     // Nothing before this run's first: an earlier run's head is not something the loop can see.
     let measured;
-    // Proxied, a shortlist has nowhere to go but the history: the tool array is fixed, so it is
-    // answered as though the model had loaded it, and the definitions sit after the question.
+    // Proxied, a shortlist has nowhere to go but the history, where its definitions sit after the
+    // question.
     const shortlist = proxied
-        ? byName(new Set(preselected)).filter((tool) => tool.type === "function" && inCatalog(catalog, tool.function.name))
+        ? byName(new Set(preselected)).filter((tool) => {
+            const name = toolName(tool);
+            return name !== undefined && inCatalog(catalog, name);
+        })
         : [];
+    const calling = {
+        catalog,
+        onDemand,
+        proxied,
+        proxies,
+        definitions,
+        loaded,
+        loads,
+        used,
+        toolCalls,
+        dedupable,
+        dispatch,
+        parallel,
+        signal,
+        onEvent,
+        onToolCall,
+        onToolResult,
+        announce,
+    };
     if (shortlist.length) {
-        const names = shortlist.map((tool) => (tool.type === "function" ? tool.function.name : ""));
-        // 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);
-        // Announced as a call the model made would be, so a host pairing calls with results by id
-        // shows this one like the rest.
-        onEvent({ kind: "tool-call", id, name: LOAD_TOOLS, text: preview(args) });
-        onToolCall?.({ id, name: LOAD_TOOLS, args: { names }, raw: args });
-        onEvent({ kind: "tool-result", id, name: LOAD_TOOLS, ok: true, text: preview(content) });
-        onToolResult?.({ id, name: LOAD_TOOLS, ok: true, content });
-        toolCalls.push({ id, name: LOAD_TOOLS, ok: true });
-        loads.toolsLoaded += names.length;
-        for (const name of names)
-            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 announce(message, 0);
+        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.
         signal?.throwIfAborted();
         const before = messages;
+        const reported = previous && previous.prompt > 0 ? { used: previous.prompt } : {};
         const rewritten = await beforeStep?.(messages, step, {
-            ...(previous && previous.prompt > 0 ? { used: previous.prompt } : {}),
+            ...reported,
             limit: config.contextLength ?? 0,
             ledger,
         });
-        let next = rewritten ?? messages;
-        if (summarise) {
-            const plan = planCompaction(next, {
-                ...(typeof options.compact === "object" ? options.compact : {}),
-                limit: config.contextLength ?? 0,
-                // The last request's prompt describes this transcript only while nothing has rewritten it.
-                ...(next === messages && previous && previous.prompt > 0 ? { used: previous.prompt } : {}),
+        const given = rewritten ?? messages;
+        // The last request's prompt describes this transcript only while nothing has rewritten it.
+        const next = summarise
+            ? await foldBeforeStep(given, given === messages ? reported : {}, summarise, {
+                options,
                 charsPerToken: charsPerTokenFor(supports, config.model),
-                ...((compactor?.maxTokens ?? 0) > 0 ? { summaryTokens: compactor?.maxTokens } : {}),
-            });
-            if (plan) {
-                const folded = await compactTranscript(next, plan, summarise, {
-                    ...(hooks
-                        ? { hooks: { run: hooks.run, context: hooks.context, onNote: hooks.onNote } }
-                        : {}),
-                });
-                if (folded !== next)
-                    notice(`compacted ${plan.cut - plan.from} messages into a summary`);
-                next = folded;
-            }
-        }
+                notice,
+            })
+            : 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,
@@ -562,24 +554,22 @@ 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 }] : []),
-            ...withContext(messages, question ? messages.indexOf(question) : -1, gathered.context, preface),
+            ...(prompt ? [{ role: Role.System, content: prompt }] : []),
+            ...withContext(messages, questionAt(), gathered.context, preface),
         ];
         const build = (supported, refused) => buildBody(config, supported, refused, request, declared, toolOrder);
         const turnOptions = {
             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.
@@ -588,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) => (tool.type === "function" ? tool.function.name : ""));
+        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 }),
@@ -609,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 })
@@ -621,85 +612,25 @@ 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 names = tools.flatMap((tool) => (tool.type === "function" ? [tool.function.name] : []));
-            const recovered = recoverToolCalls(content, {
-                names: onDemand ? [...names, LOAD_TOOLS, ...(proxies ? [CALL_TOOL] : [])] : names,
-            });
-            if (recovered.toolCalls.length) {
-                calls = recovered.toolCalls;
-                content = recovered.content;
-                notice(`recovered ${calls.length} tool call${calls.length === 1 ? "" : "s"} 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
-        // is the repaired JSON: a server that parses replayed arguments refuses the almost-JSON, and
-        // one that could not be read at all is replayed as no arguments.
-        const parsed = calls.map((call) => {
-            try {
-                const args = parseToolArguments(call.function.arguments, {
-                    finishReason: turn.finishReason,
-                });
-                return { call, args, normal: JSON.stringify(args) };
-            }
-            catch (error) {
-                return { call, error, normal: "{}" };
-            }
-        });
-        const assistant = {
-            role: "assistant",
-            content: content || null,
-            ...(parsed.length
-                ? {
-                    tool_calls: parsed.map(({ call, normal }) => ({
-                        ...call,
-                        function: { ...call.function, arguments: normal },
-                    })),
-                }
-                : {}),
-        };
+        // is the repaired JSON.
+        const parsed = readCalls(calls, turn.finishReason);
+        const assistant = assistantMessage(content, parsed);
         messages.push(assistant);
         await announce(assistant, step, shown);
         if (!calls.length) {
-            let afterTurn = Promise.resolve([]);
-            if (hooks) {
-                const at = question ? messages.indexOf(question) : -1;
-                // 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.
-                afterTurn = notify(hooks.run, "afterTurn", {
-                    ...hooks.context,
-                    reply: turn.content,
-                    ...(at >= 0
-                        ? {
-                            turn: {
-                                index: turnIndex(messages, at),
-                                messages: turnMessages(hooks.context.session.id, messages, at),
-                            },
-                        }
-                        : {}),
-                }, hooks.onNote);
-            }
+            // 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 metrics = runMetrics(recorded, { contextLength: config.contextLength });
             return {
                 turn: shown,
@@ -716,170 +647,12 @@ 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,
             };
         }
-        // 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();
-        // A `call_tool` is shown, counted and dispatched as the tool it names. Read from the repaired
-        // arguments where there are any, since the model's own may be almost-JSON.
-        const named = ({ call, args, normal }) => proxies && call.function.name === CALL_TOOL
-            ? shownCall(CALL_TOOL, args ? normal : call.function.arguments)
-            : { name: call.function.name, input: call.function.arguments };
-        const run = async (entry) => {
-            const { call, args, error: unreadable, normal } = entry;
-            const proxy = proxies && call.function.name === CALL_TOOL;
-            const { name, input: raw } = named(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 };
-                }
-            }
-            // 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 };
-            onEvent({ kind: "tool-call", id: call.id, name, text: preview(raw) });
-            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) {
-                    const resolved = expandNames(requestedNames(args), catalog);
-                    content = proxied
-                        ? proxyLoadResult(resolved, catalog, byName(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);
-                    ok = hits.length > 0;
-                }
-                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))
-                        loaded.add(name);
-                    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 = dedupable(request)
-                        ? await once(answered, key, () => dispatch(request, signal))
-                        : await dispatch(request, signal);
-                }
-            }
-            catch (error) {
-                if (signal?.aborted)
-                    throw error;
-                content = errorMessage(error);
-                ok = false;
-            }
-            onEvent({ kind: "tool-result", id: call.id, name, ok, text: preview(content) });
-            const result = { id: call.id, name, ok, content };
-            onToolResult?.(result);
-            return result;
-        };
-        // 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 announce(result, step);
-        };
-        try {
-            if (parallel) {
-                signal?.throwIfAborted();
-                begun = parsed.length;
-                await Promise.all(parsed.map(async (call, at) => {
-                    outcomes[at] = await run(call);
-                }));
-                for (const { id, name, ok, content } of outcomes.flatMap((outcome) => outcome ?? [])) {
-                    toolCalls.push({ id, name, ok });
-                    await keep(id, content);
-                }
-            }
-            else {
-                for (const [at, call] of parsed.entries()) {
-                    signal?.throwIfAborted();
-                    begun = at + 1;
-                    const { id, name, ok, content } = await run(call);
-                    toolCalls.push({ id, name, ok });
-                    await keep(id, content);
-                }
-            }
-        }
-        catch (error) {
-            // A call with no result is a transcript no endpoint takes back, so every call of the step
-            // is answered before the throw: with what it returned where it had, and otherwise with a
-            // line saying it was stopped, or never run. 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: named(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(() => { });
-            }
-            throw error;
-        }
+        await runCalls(calling, parsed, messages, step);
     }
     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;
-    }
-}