@cubicecho/agent-core 2.19.0 → 2.21.0

package/dist/agent-loop.js

@@ -2,16 +2,16 @@ import { charsPerTokenFor } from "./calibration.js";
 import { capabilitiesFor, effortFor, modelCapabilitiesFor, } from "./capabilities.js";
 import { firstTokenMs, getClient, NO_KEY, timeoutMs } from "./client.js";
 import { continueTurn } from "./continuation.js";
-import { errorMessage } from "./errors.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 { contextTokens, toolsChars } from "./retry.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 { catalogPrompt, expandNames, inCatalog, LOAD_TOOLS, LOAD_TOOLS_DEFINITION, loadedTools, loadResult, MAX_PER_LOAD, orderTools, PRESELECT_SCHEMA, preselectByKeywords, preselectInput, preselection, preselectSystem, requestedNames, } 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, } from "./tool-loading.js";
 /**
  * The loop above a turn: send, run the tools the model asked for, send again, until it stops
  * asking.
@@ -198,11 +198,24 @@ function cacheDiagnosis(previous, messages, tools, usage) {
         found.cacheBreakReason = breakReason(previous, messages, tools);
     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.
  *
+ * 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
+ * an `AgentLoopOverflow`, which is still a `ContextOverflow`, and anything else is an
+ * `AgentLoopError` with what was caught as its `cause` and its message as its own; `failedRun`
+ * reads the run off any of the three. A failure while a step's tools run leaves the transcript
+ * well-formed: the results that came back are kept, and each call without one is answered with a
+ * line saying it was stopped or never run, since a call with no result is refused on replay.
+ *
  * On-demand loading is handled here, `load_tools` and all: the catalogue rides on the system
  * prompt unchanged from step to step, a load adds to the tool array — which every request sends
  * in the stable order `toolOrder` asks for — and
@@ -220,12 +233,50 @@ function cacheDiagnosis(previous, messages, tools, usage) {
  * continuation, and a step that reported none, or reported a cache count above its prompt, is not
  * recorded. The ledger comes back in the result and on every `usage` event; see `tokensBetween`.
  *
+ * Proxied discovery is the same catalogue behind a tool array that never moves: every step
+ * declares `PROXY_TOOLS` and nothing else, a load answers with the definitions themselves, and a
+ * `call_tool` is dispatched, counted and reported as the tool it names. A preselection has no
+ * tool array to go into, so it is written into the transcript as a `load_tools` exchange after
+ * the question. `call_tool` is honoured on demand too, unless the host has a tool of that name —
+ * a session switched out of proxied mode still has it in its history, and the model copies it.
+ *
  * @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 },
+            toolCalls: [],
+            loaded: [],
+            used: [],
+        }),
+    };
+    let result;
+    try {
+        result = await runSteps(options, standing);
+    }
+    catch (error) {
+        // Wrapped rather than annotated: an abort's reason is one object shared by every run under
+        // the signal, so the run cannot be hung on the error itself. An overflow keeps its class,
+        // because `instanceof ContextOverflow` is how a caller knows to compact and try again.
+        throw error instanceof ContextOverflow
+            ? new AgentLoopOverflow(error.message, standing.read(), { cause: error })
+            : new AgentLoopError(errorMessage(error), standing.read(), { cause: error });
+    }
+    if (result)
+        return result;
+    throw new ToolIterationLimit(`Stopped after ${options.config.maxToolIterations} tool iterations.`, standing.read());
+}
+/**
+ * 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.
+ */
+async function runSteps(options, standing) {
     const { config, system = "", tools = [], catalog = [], dispatch, hooks, signal } = options;
-    const { onRequest, onTurn, onToolCall, onToolResult, beforeStep, parallel = false, recoverToolCalls: recover = true, maxContinuations = 0, toolOrder = true, dedupeToolCalls = true, preselectRouting = "exclusive", } = 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
@@ -254,11 +305,16 @@ export async function runAgentLoop(options) {
     const supports = capabilitiesFor(config.baseUrl, config.apiKey);
     const maxRetries = Math.max(0, Number(config.maxRetries) || 0);
     const notice = (text) => onEvent({ kind: "notice", text });
-    const onDemand = config.toolDiscovery === "ondemand" && catalog.length > 0;
-    const loaded = new Set(onDemand ? (options.loaded ?? []) : []);
+    // On demand, but with a tool array that never changes: definitions come back as `load_tools`
+    // results and run through `call_tool`. `onDemand` is true of both.
+    const proxied = config.toolDiscovery === "proxy" && catalog.length > 0;
+    const onDemand = proxied || (config.toolDiscovery === "ondemand" && catalog.length > 0);
+    // Proxied, `loaded` is what this run has put a definition in the history for, and starts empty.
+    const loaded = new Set(onDemand && !proxied ? (options.loaded ?? []) : []);
     const preselected = onDemand ? [...(options.preselected ?? [])] : [];
-    for (const name of preselected)
-        loaded.add(name);
+    if (!proxied)
+        for (const name of preselected)
+            loaded.add(name);
     const used = new Set();
     const definitions = new Map();
     for (const tool of tools) {
@@ -266,10 +322,36 @@ export async function runAgentLoop(options) {
             definitions.set(tool.function.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);
     // 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) ?? []);
     let messages = [...options.messages];
+    const usage = { prompt: 0, completion: 0, total: 0, cached: 0 };
+    const toolCalls = [];
+    standing.read = () => ({
+        messages,
+        usage,
+        toolCalls,
+        // As the result would have said it: proxied, nothing is loaded that the history does not hold.
+        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;
+        }
+    };
     // 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.
@@ -283,43 +365,85 @@ export async function runAgentLoop(options) {
         : { 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 usage = { prompt: 0, completion: 0, total: 0, cached: 0 };
-    const toolCalls = [];
     const loads = { toolsLoaded: 0, redundantLoads: 0, unknownToolNames: 0 };
     let previous;
     let ledger = options.ledger ?? [];
     // 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.
+    const shortlist = proxied
+        ? byName(new Set(preselected)).filter((tool) => tool.type === "function" && inCatalog(catalog, tool.function.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);
+    }
     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;
-        messages =
-            (await beforeStep?.(messages, step, {
-                ...(previous && previous.prompt > 0 ? { used: previous.prompt } : {}),
-                limit: config.contextLength ?? 0,
-                ledger,
-            })) ?? messages;
+        const rewritten = await beforeStep?.(messages, step, {
+            ...(previous && previous.prompt > 0 ? { used: previous.prompt } : {}),
+            limit: config.contextLength ?? 0,
+            ledger,
+        });
+        // 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 && rewritten && rewritten !== messages)
+            loaded.clear();
+        messages = rewritten ?? messages;
         ledger = rebaseLedger(ledger, before, messages);
         onEvent({ kind: "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.
-        const routed = preselectRouting !== "append" && preselected.length > 0 && step === 0;
+        // first step needs nothing of its own. Proxied, it is in the history.
+        const routed = !proxied && preselectRouting !== "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))
-            : onDemand
-                ? loadedTools([LOAD_TOOLS_DEFINITION], byName(loaded))
-                : tools, toolOrder);
+            : proxied
+                ? [...PROXY_TOOLS]
+                : onDemand
+                    ? loadedTools([LOAD_TOOLS_DEFINITION], byName(loaded))
+                    : tools, 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,
         // and `preselectRouting: "append"` is the way out of it.
-        const prompt = onDemand && !routed ? `${system}\n\n${catalogPrompt(catalog)}`.trim() : system;
+        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),
@@ -402,7 +526,7 @@ export async function runAgentLoop(options) {
         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] : names,
+                names: onDemand ? [...names, LOAD_TOOLS, ...(proxies ? [CALL_TOOL] : [])] : names,
             });
             if (recovered.toolCalls.length) {
                 calls = recovered.toolCalls;
@@ -426,7 +550,7 @@ export async function runAgentLoop(options) {
                 return { call, error, normal: "{}" };
             }
         });
-        messages.push({
+        const assistant = {
             role: "assistant",
             content: content || null,
             ...(parsed.length
@@ -437,7 +561,9 @@ export async function runAgentLoop(options) {
                     })),
                 }
                 : {}),
-        });
+        };
+        messages.push(assistant);
+        await announce(assistant, step, shown);
         if (!calls.length) {
             let afterTurn = Promise.resolve([]);
             if (hooks) {
@@ -463,7 +589,7 @@ export async function runAgentLoop(options) {
                 messages,
                 usage,
                 toolCalls,
-                loaded: [...loaded],
+                loaded: proxied ? [] : [...loaded],
                 used: [...used],
                 notes: gathered.notes,
                 context: gathered.context,
@@ -481,11 +607,32 @@ export async function runAgentLoop(options) {
         // 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();
-        const run = async ({ call, args, error: unreadable, normal }) => {
-            const { name, arguments: raw } = call.function;
+        // 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: args ?? {}, raw };
+            const request = { id: call.id, name, args: inner, raw };
             onEvent({ kind: "tool-call", id: call.id, name, text: preview(raw) });
             onToolCall?.(request);
             let content;
@@ -493,24 +640,38 @@ export async function runAgentLoop(options) {
             try {
                 if (!args)
                     throw unreadable;
-                if (onDemand && name === LOAD_TOOLS) {
+                // 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 = loadResult(resolved, catalog, loaded);
-                    for (const hit of resolved.matched)
+                    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 resolved.matched)
+                    for (const hit of hits)
                         loaded.add(hit);
-                    ok = resolved.matched.length > 0;
+                    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.
-                    if (onDemand && inCatalog(catalog, name))
+                    // 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, `${name}\0${normal}`, () => dispatch(request, signal))
+                        ? await once(answered, key, () => dispatch(request, signal))
                         : await dispatch(request, signal);
                 }
             }
@@ -525,23 +686,65 @@ export async function runAgentLoop(options) {
             onToolResult?.(result);
             return result;
         };
-        const outcomes = [];
-        if (parallel) {
-            signal?.throwIfAborted();
-            outcomes.push(...(await Promise.all(parsed.map(run))));
-        }
-        else {
-            for (const call of parsed) {
+        // 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();
-                outcomes.push(await run(call));
+                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);
+                }
             }
         }
-        for (const { id, name, ok, content } of outcomes) {
-            toolCalls.push({ id, name, ok });
-            messages.push({ role: "tool", tool_call_id: 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;
         }
     }
-    throw new Error(`Stopped after ${config.maxToolIterations} tool iterations.`);
+    return undefined;
 }
 /**
  * Makes a call at most once per key, sharing the in-flight promise so two identical calls in one

package/dist/compaction.d.ts

@@ -42,7 +42,9 @@ export interface PruneOptions {
  * after it, and by then the model has usually taken what it wanted from it; the stub keeps the
  * call answered — a call with no result is a malformed transcript — and says how much was there,
  * so a model that does need it again knows to ask. Short results are kept, since a stub saves
- * nothing on them. Returns the same array when there was nothing to clear. Rewrites the prefix;
+ * nothing on them, and so is a proxied `load_tools` result carrying definitions, which is the
+ * only copy of them the model has (`holdsDefinitions`); either still counts as one of the latest
+ * few. Returns the same array when there was nothing to clear. Rewrites the prefix;
  * see the module comment on when to run it.
  *
  * @param messages The transcript. Not written to.

package/dist/compaction.js

@@ -1,6 +1,7 @@
 import { consult, notify, turnMessages, } from "./hooks.js";
 import { messageTokens } from "./retry.js";
 import { ask } from "./side-task.js";
+import { holdsDefinitions } from "./tool-loading.js";
 /** The fraction of the window in use before a summary is worth its own round trip. */
 export const COMPACT_AT = 0.75;
 /** The fraction of the window the kept tail may fill, leaving room for the run to grow again. */
@@ -65,7 +66,9 @@ const systemHead = (messages) => {
  * after it, and by then the model has usually taken what it wanted from it; the stub keeps the
  * call answered — a call with no result is a malformed transcript — and says how much was there,
  * so a model that does need it again knows to ask. Short results are kept, since a stub saves
- * nothing on them. Returns the same array when there was nothing to clear. Rewrites the prefix;
+ * nothing on them, and so is a proxied `load_tools` result carrying definitions, which is the
+ * only copy of them the model has (`holdsDefinitions`); either still counts as one of the latest
+ * few. Returns the same array when there was nothing to clear. Rewrites the prefix;
  * see the module comment on when to run it.
  *
  * @param messages The transcript. Not written to.
@@ -83,6 +86,10 @@ export function pruneToolResults(messages, { keepLast = 5, maxChars = 256 } = {}
         const text = textOf(message.content);
         if (text.length <= maxChars || text.startsWith("[result cleared"))
             continue;
+        // A proxied load's result is the schema itself; stubbed, the tool is one the model can still
+        // name and no longer call correctly.
+        if (holdsDefinitions(text))
+            continue;
         out ??= [...messages];
         out[at] = {
             ...message,

package/dist/config.d.ts

@@ -75,9 +75,11 @@ export interface ModelParams {
 export interface ToolPolicy {
     /**
      * "eager" sends every tool definition on every request. "ondemand" sends a name-only
-     * catalogue and lets the model pull in the schemas it needs. See `tool-loading.ts`.
+     * catalogue and lets the model pull in the schemas it needs. "proxy" is the same catalogue
+     * behind a tool array that never changes — `load_tools` and `call_tool` — for a server whose
+     * prompt cache a growing tool array throws away. See `tool-loading.ts`.
      */
-    toolDiscovery: "eager" | "ondemand";
+    toolDiscovery: "eager" | "ondemand" | "proxy";
     /** The model that does the preselection pass. Empty means don't preselect. */
     toolSelectModel: string;
     /** Hard stop on runaway tool loops. */

package/dist/errors.d.ts

@@ -1,3 +1,7 @@
+import type OpenAI from "openai";
+import type { ToolCallOutcome } from "./agent-loop.ts";
+import { ContextOverflow } from "./retry.ts";
+import type { TurnUsage } from "./stream.ts";
 /**
  * What went wrong, as a string.
  *
@@ -8,3 +12,88 @@
  * @param error Whatever a `catch` bound. Anything that is not an `Error` is stringified.
  */
 export declare const errorMessage: (error: unknown) => string;
+/**
+ * A run as it stood when `runAgentLoop` gave up on it.
+ *
+ * The loop works on its own copy of the transcript and hands it back only on success, so without
+ * this a spent budget, a stop or a refused request took every step before it along — steps whose
+ * assistant turns and tool results were real, and that a host storing its transcript has to keep.
+ */
+export interface AgentLoopFailure {
+    /**
+     * The transcript, as the result's `messages` would have been: every assistant turn and tool
+     * result the run added, and no system prompt. Well-formed — a call the run was stopped during
+     * has a result saying so. The reply of a request that was in flight is not in it.
+     */
+    messages: OpenAI.ChatCompletionMessageParam[];
+    /** Summed over the turns that came back. A request that failed or was stopped adds nothing. */
+    usage: TurnUsage;
+    /** Every call that was made, in order. One the run was stopped during is `ok: false`. */
+    toolCalls: ToolCallOutcome[];
+    /** What was loaded when the run failed, for `carryOver`. Empty in eager and proxied modes. */
+    loaded: string[];
+    /** The tools the model had called, `load_tools` excluded. */
+    used: string[];
+}
+/**
+ * What `runAgentLoop` throws, carrying the run as it stood and what was caught as `cause`.
+ *
+ * Its own class rather than fields hung on the error that was caught, because a stop throws the
+ * signal's reason and that is one object for every run under the signal. The message is the
+ * cause's own, so a host that logs `errorMessage(error)` logs what it always did. A stop is told
+ * the way it was before — by the signal the host aborted, not by the class of what came out.
+ */
+export declare class AgentLoopError extends Error implements AgentLoopFailure {
+    readonly name: string;
+    readonly messages: OpenAI.ChatCompletionMessageParam[];
+    readonly usage: TurnUsage;
+    readonly toolCalls: ToolCallOutcome[];
+    readonly loaded: string[];
+    readonly used: string[];
+    /**
+     * @param message What went wrong — the cause's own message, where there is a cause.
+     * @param run The run as it stood. Held, not copied.
+     * @param options The standard `cause`: what the loop caught, absent where the loop itself gave up.
+     */
+    constructor(message: string, run: AgentLoopFailure, options?: ErrorOptions);
+}
+/**
+ * `maxToolIterations` was spent with the model still asking for tools.
+ *
+ * Named so a host can tell it from a failure without matching the message, which is the same
+ * sentence it has always been. There is no `cause`: nothing was caught, the loop stopped itself.
+ */
+export declare class ToolIterationLimit extends AgentLoopError {
+    readonly name: string;
+}
+/**
+ * A `ContextOverflow` out of `runAgentLoop`, carrying the run as it stood.
+ *
+ * A subclass of `ContextOverflow` rather than an `AgentLoopError` around one, because
+ * `instanceof ContextOverflow` is how a caller knows to compact and send again, and wrapping
+ * would have made that test quietly false. The overflow the loop caught is the `cause`, and the
+ * endpoint's own error, where there was one, is that one's `cause` in turn.
+ */
+export declare class AgentLoopOverflow extends ContextOverflow implements AgentLoopFailure {
+    readonly messages: OpenAI.ChatCompletionMessageParam[];
+    readonly usage: TurnUsage;
+    readonly toolCalls: ToolCallOutcome[];
+    readonly loaded: string[];
+    readonly used: string[];
+    /**
+     * @param message The overflow's own message.
+     * @param run The run as it stood. Held, not copied.
+     * @param options The standard `cause`: the `ContextOverflow` the loop caught.
+     */
+    constructor(message: string, run: AgentLoopFailure, options?: ErrorOptions);
+}
+/**
+ * The run a failed `runAgentLoop` left behind, read off whatever it threw, or nothing.
+ *
+ * Two classes carry it — an overflow has to stay a `ContextOverflow` and so cannot also be an
+ * `AgentLoopError` — and a `catch` that only wants the transcript should not have to name both.
+ *
+ * @param error Whatever a `catch` around `runAgentLoop` bound. Anything the loop did not throw
+ * answers `undefined`.
+ */
+export declare const failedRun: (error: unknown) => AgentLoopFailure | undefined;