@cubicecho/agent-core 2.23.0 → 2.24.0

package/dist/agent-loop.js

@@ -1,18 +1,19 @@
 import { charsPerTokenFor } from "./calibration.js";
-import { capabilitiesFor, effortFor, modelCapabilitiesFor, } from "./capabilities.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 } from "./events.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, } from "./tool-loading.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.
@@ -57,12 +58,7 @@ export function buildBody(config, supports, refused, messages, tools = [], order
     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 }),
+        ...ceilingAndTemperature(refused, config.maxTokens, config.temperature),
         ...(effort ? { reasoning_effort: effort } : {}),
         ...(supports.usageInStream ? { stream_options: { include_usage: true } } : {}),
         ...Object.fromEntries(extra),
@@ -81,6 +77,8 @@ export function buildBody(config, supports, refused, messages, tools = [], order
  * @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(/\/+$/, "");
 /**
@@ -185,7 +183,7 @@ export async function preselect(config, model, catalog, prompt, { signal, onNoti
             ...(keywords === true ? {} : keywords),
         });
         if (guess.confident) {
-            onNotice?.(`chose ${guess.names.length} tool${guess.names.length === 1 ? "" : "s"} by name`);
+            onNotice?.(`chose ${counted(guess.names.length, "tool")} by name`);
             return guess.names;
         }
     }
@@ -301,7 +299,7 @@ export async function runAgentLoop(options) {
     const standing = {
         read: () => ({
             messages: [...options.messages],
-            usage: { prompt: 0, completion: 0, total: 0, cached: 0 },
+            usage: noUsage(),
             toolCalls: [],
             loaded: [],
             used: [],
@@ -332,6 +330,317 @@ const userText = (message) => {
         return "";
     return content.flatMap((part) => (part.type === "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.
+ */
+async function chooseTools(options, notice) {
+    const { config, catalog = [], signal } = options;
+    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);
+}
+/**
+ * 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.
+ */
+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.
+ */
+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;
+}
+/**
+ * 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.
+ */
+const tellAfterTurn = (hooks, messages, at, reply) => notify(hooks.run, "afterTurn", {
+    ...hooks.context,
+    reply,
+    ...(at >= 0
+        ? {
+            turn: {
+                index: turnIndex(messages, at),
+                messages: turnMessages(hooks.context.session.id, messages, at),
+            },
+        }
+        : {}),
+}, 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.
+ */
+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 };
+}
+/**
+ * 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.
+ *
+ * @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`.
+ */
+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 };
+        }
+    }
+    // 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);
+        }
+    }
+    catch (error) {
+        if (signal?.aborted)
+            throw error;
+        content = errorMessage(error);
+        ok = false;
+    }
+    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;
+}
+/**
+ * Runs a step's calls and writes each result into the transcript, in the order asked.
+ *
+ * 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 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.
+ */
+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);
+            }
+        }
+        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);
+            }
+        }
+    }
+    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(() => { });
+        }
+        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.
+ *
+ * @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.
+ */
+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);
+}
 /**
  * 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.
@@ -347,17 +656,7 @@ async function runSteps(options, standing) {
     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,
-        });
+        recorded.push(stamp(input, "", recorded.length + 1, Date.now()));
     };
     const onEvent = (input) => {
         record(input);
@@ -373,58 +672,35 @@ async function runSteps(options, standing) {
     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: 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);
-    };
+    // 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 choose()
+            ? await chooseTools(options, notice)
             : [...(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 summarise = ownSummariser(options, notice);
     const used = new Set();
     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);
     }
     // 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 };
+    const usage = noUsage();
     const toolCalls = [];
     standing.read = () => ({
         messages,
@@ -452,6 +728,7 @@ async function runSteps(options, standing) {
     // 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 questionAt = () => (question ? messages.indexOf(question) : -1);
     const gathered = hooks
         ? await gather(hooks.run, hooks.events ?? ["beforeTurn"], hooks.context, {
             signal,
@@ -467,74 +744,55 @@ 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);
+        })
         : [];
-    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);
-    }
+    const calling = {
+        catalog,
+        onDemand,
+        proxied,
+        proxies,
+        definitions,
+        loaded,
+        loads,
+        used,
+        toolCalls,
+        dedupable,
+        dispatch,
+        parallel,
+        signal,
+        onEvent,
+        onToolCall,
+        onToolResult,
+        announce,
+    };
+    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.
         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)
@@ -563,7 +821,7 @@ async function runSteps(options, standing) {
         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),
+            ...withContext(messages, questionAt(), gathered.context, preface),
         ];
         const build = (supported, refused) => buildBody(config, supported, refused, request, declared, toolOrder);
         const turnOptions = {
@@ -588,7 +846,7 @@ 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
@@ -641,65 +899,27 @@ async function runSteps(options, standing) {
         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,
-            });
+            const recovered = recoverToolCalls(content, { names: recoverable });
             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`);
+                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 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,
@@ -721,145 +941,7 @@ async function runSteps(options, standing) {
                 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;
 }