@cubicecho/agent-core 2.19.0 → 2.20.0

package/README.md

@@ -23,7 +23,7 @@ only, Node >=22.
 | Module | What it does |
 | --- | --- |
 | `schema-compat` | Makes an MCP tool schema something a strict or grammar-constrained server will accept. `sanitizeTools`, `relaxTools`, `isGrammarError`. |
-| `tool-loading` | On-demand tool discovery: a name-only catalogue plus a `load_tools` meta-tool, so a run pays for the schemas it asks for instead of all of them. Plus `preselectByKeywords`, which picks from it without a model. |
+| `tool-loading` | On-demand tool discovery: a name-only catalogue plus a `load_tools` meta-tool, so a run pays for the schemas it asks for instead of all of them. Plus `preselectByKeywords`, which picks from it without a model, and the proxied form of the same thing — `PROXY_TOOLS`, `proxyLoadResult`, `proxiedCall` — for a server whose prompt cache a growing tool array throws away. |
 | `stream` | Reads one streamed turn back into a message: token callbacks, tool-call reassembly, fenced reasoning taken out of the answer, and the idle watchdog that turns a silent endpoint into `EndpointSilent`. |
 | `capabilities` | What an endpoint turned out not to support — and, under it, what one model on that endpoint did not — plus the loop that answers either when it says so. `capabilitiesFor`, `modelCapabilitiesFor`, `negotiate`. |
 | `thinking` | Tells a scratchpad fenced inside `content` from the answer: `FenceSplitter` for a stream, `stripThinking` for a whole reply, and the fence tables both read. |
@@ -385,10 +385,10 @@ import { runAgentLoop, emit } from "@cubicecho/agent-core";
 
 const { turn, messages, usage, loaded } = await runAgentLoop({
   config,                         // Endpoint & ModelParams & { maxToolIterations, toolDiscovery?, maxRetries?, loadingTimeoutSeconds?, contextLength? }
-  system,                         // sent as the first message; on-demand mode appends the catalogue
+  system,                         // sent as the first message; on-demand and proxied modes append the catalogue
   messages: history,              // ending in the question; not written to
   tools,                          // every tool the run may reach
-  catalog,                        // the same, name-only, for on-demand loading
+  catalog,                        // the same, name-only, for on-demand and proxied loading
   preselected,                    // from `preselect`, if a small model chose
   dispatch: ({ name, args }, signal) => pool.call(name, args, signal),
   hooks: { run, context: { session: { id } } },
@@ -483,6 +483,53 @@ tool array stays a strict prefix of the new one. With name order, the default, a
 is sorted in and moves every definition after it — the first step still matches the second, but
 the last turn's cache holds only as far as the first new name.
 
+`toolDiscovery: "proxy"` is the same catalogue behind a tool array that never changes. A chat
+template renders the tool array in the system turn, so on a server that caches by prefix —
+llama.cpp, and anything built on it — a `load_tools` that appends a definition changes the head of
+the prompt and the whole transcript is prefilled again, on the very step that was meant to save
+tokens. Proxied, every step declares `PROXY_TOOLS` and nothing else: `load_tools`, and `call_tool`,
+which takes `{ name, arguments }`. A load answers with each new tool's name, description and
+parameters as a line of JSON, since no request will ever declare them, and with a pointer back for
+one whose definition is already in the conversation. A `call_tool` is refused for a name outside
+the catalogue, takes `arguments` as an object or as JSON in a string, and reaches `dispatch` as the
+tool it names — the inner name and arguments, under the call's own id — so a dispatcher, a watcher
+and `used` see the same thing in every mode. The transcript keeps the `call_tool` the model wrote.
+
+```ts
+const { messages, used } = await runAgentLoop({
+  config: { ...config, toolDiscovery: "proxy" },
+  messages: history,
+  tools,                          // never declared; a load answers with them
+  catalog,
+  preselected,                    // written into the transcript, not into the tool array
+  dispatch: ({ name, args }, signal) => pool.call(name, args, signal),
+});
+```
+
+A preselection has no tool array to go into there, and no step of its own. It is written into the
+transcript after the question as a `load_tools` call the model did not make, and the result that
+call would have had:
+
+```ts
+{ role: "assistant", content: null, tool_calls: [{ id: "preselect-3", type: "function",
+    function: { name: "load_tools", arguments: '{"names":["files__read_file"]}' } }] },
+{ role: "tool", tool_call_id: "preselect-3", content: "Loaded 1 tool(s). Run them with `call_tool`.\n\n{...}" },
+```
+
+The pair is in the `messages` the loop hands back, to be stored like any other, and is reported as
+a `tool-call` and a `tool-result` event, told to `onToolCall` and `onToolResult`, and counted in
+`toolCalls` and in the `load_tools` metrics. The
+id is numbered by where the call lands in the transcript, so two questions do not share one. A name
+with no definition in `tools`, or outside the catalogue, is left out, and none left is no exchange.
+
+What is loaded there is what the history holds, so `loaded` comes back empty and the `loaded`
+option is not read: there is nothing to carry, and a definition a compaction folded away has to be
+loadable again. For the same reason a `beforeStep` that returns a different array makes the loop
+forget what it loaded, which costs a definition sent twice at worst. `call_tool` is honoured in
+`ondemand` mode as well — a session switched out of proxied mode still has it in its history, and
+a model copies what it has seen work — unless the host has a tool of that name, which is then the
+host's. Eager mode does not know it.
+
 That preselection costs a round trip to a model, which on a local box is a few seconds before the
 run has started, spent on a model doing term matching. `preselect(..., { keywords: true })` does
 the matching directly and spends the model only on what the words cannot settle:
@@ -663,7 +710,9 @@ Two ways to make a transcript smaller, cheap first.
 `pruneToolResults(messages, { keepLast: 5, maxChars: 256 })` replaces every tool result but the
 latest five with a stub — `[result cleared, 10,412 chars]`. A 40k-character `read_file` is 10k
 tokens on every turn after it, and by then the model has usually taken what it wanted; the stub
-keeps the call answered and says how much was there.
+keeps the call answered and says how much was there. A proxied `load_tools` result that carries
+definitions is never cleared, however old: it is the only copy of the schema the model has, and
+`holdsDefinitions` is the test for a host with a prune of its own.
 
 `planCompaction(messages, { limit, used })` says where to fold the oldest stretch into a summary,
 once `used` (the last turn's prompt tokens, or the estimate) is past three quarters of the window.

package/dist/agent-loop.d.ts

@@ -98,7 +98,12 @@ export declare function preselect(config: Endpoint, model: string, catalog: Cata
      */
     keywords?: boolean | KeywordPreselectOptions;
 }): Promise<string[]>;
-/** One call the model made, as `dispatch` and `onToolCall` are handed it. */
+/**
+ * One call the model made, as `dispatch` and `onToolCall` are handed it.
+ *
+ * A `call_tool` arrives as the tool it names — that tool's name and arguments, under the
+ * `call_tool`'s id — so a dispatcher is the same in every discovery mode.
+ */
 export interface ToolCallRequest {
     id: string;
     name: string;
@@ -107,7 +112,10 @@ export interface ToolCallRequest {
      * read, which only `onToolCall` is ever handed.
      */
     args: Record<string, unknown>;
-    /** The arguments as the model wrote them, before any repair. */
+    /**
+     * The arguments as the model wrote them, before any repair. Through `call_tool`, the inner
+     * arguments as JSON text.
+     */
     raw: string;
 }
 /** What one tool call did, in the order the model asked. */
@@ -119,6 +127,7 @@ export interface ToolCallOutcome {
      * sets it; optional so an outcome built before it existed still compiles.
      */
     id?: string;
+    /** The tool that was called. For a `call_tool`, the tool it named. */
     name: string;
     /** False when the arguments did not parse, the tool threw, or `load_tools` loaded nothing. */
     ok: boolean;
@@ -192,20 +201,27 @@ export interface AgentLoopOptions {
      * The endpoint, what to ask the model for, and how long it may keep calling tools.
      * `toolDiscovery` absent is eager, `maxRetries` absent is none, and `contextLength` is handed
      * to `runTurn` as `contextLimit`, which sizes each request against the window before sending.
+     * `"proxy"` is on-demand loading behind a tool array that never changes; see `PROXY_TOOLS`.
      */
     config: Endpoint & ModelParams & Pick<ToolPolicy, "maxToolIterations"> & Partial<Pick<ToolPolicy, "toolDiscovery">> & Partial<RetryPolicy> & {
         contextLength?: number;
     };
-    /** The standing instruction, sent as the first message. On-demand mode appends the catalogue. */
+    /**
+     * The standing instruction, sent as the first message. On-demand and proxied modes append the
+     * catalogue, each in its own wording.
+     */
     system?: string;
     /** The transcript so far, ending in the question. Not written to; see the result's `messages`. */
     messages: OpenAI.ChatCompletionMessageParam[];
     /**
      * Every tool this run may reach. Eager mode sends all of them; on-demand mode sends the ones
-     * loaded so far, by name.
+     * loaded so far, by name; proxied mode declares none, and answers a load with them instead.
      */
     tools?: OpenAI.ChatCompletionTool[];
-    /** The same tools as a name-only catalogue. On-demand mode needs it, and is eager without it. */
+    /**
+     * The same tools as a name-only catalogue. On-demand and proxied modes need it, and are eager
+     * without it.
+     */
     catalog?: CatalogServer[];
     /**
      * How the declared tools are ordered before each request. By name unless told otherwise, so a
@@ -218,6 +234,13 @@ export interface AgentLoopOptions {
      * `load_tools` — because a model with the menu still in front of it shops: it reloads what it
      * has or picks a sibling. Everything comes back on the step after. `preselectRouting` trades
      * that for a first step shaped like the rest.
+     *
+     * Proxied, the tool array is fixed and there is no such step. The shortlist is written into the
+     * transcript instead, after the question, as a `load_tools` call the model did not make and the
+     * result that call would have had — an assistant message and a tool message, handed back in
+     * `messages` like any other, reported as a `tool-call` and a `tool-result` event and told to
+     * `onToolCall` and `onToolResult`. Names with no definition in `tools`, or outside the
+     * catalogue, are left out, and none left is no exchange.
      */
     preselected?: readonly string[];
     /**
@@ -233,11 +256,14 @@ export interface AgentLoopOptions {
      * Appended is before `toolOrder` has its say: sorted, a preselected tool lands at its name's
      * place and moves every definition after it, so only `toolOrder: false` keeps a carried array
      * a strict prefix. Either way the first step's system prompt is the second's, and so is its
-     * tool array until something else is loaded. Nothing to do without a preselection, or in eager
-     * mode.
+     * tool array until something else is loaded. Nothing to do without a preselection, in eager
+     * mode, or proxied, where no step is routed either way.
      */
     preselectRouting?: "exclusive" | "append";
-    /** Tools already loaded, carried from an earlier question. See `carryOver`. */
+    /**
+     * Tools already loaded, carried from an earlier question. See `carryOver`. Not read in proxied
+     * mode, where a tool is loaded only while its definition is in the history.
+     */
     loaded?: Iterable<string>;
     /** Runs one tool call and returns what the model reads. What it throws, the model reads too. */
     dispatch: (call: ToolCallRequest, signal?: AbortSignal) => Promise<string>;
@@ -343,11 +369,18 @@ export interface AgentLoopResult {
     messages: OpenAI.ChatCompletionMessageParam[];
     /** Summed over every turn of the run. */
     usage: TurnUsage;
-    /** Every call, `load_tools` included, in the order they were made, each under its call id. */
+    /**
+     * Every call, `load_tools` included, in the order they were made, each under its call id — a
+     * proxied preselection's among them, first.
+     */
     toolCalls: ToolCallOutcome[];
-    /** What is loaded at the end, for `carryOver`. Empty in eager mode. */
+    /**
+     * What is loaded at the end, for `carryOver`. Empty in eager mode, and in proxied mode: a
+     * definition loaded there is already in the history, and one a compaction folded away has to be
+     * loadable again rather than answered "already loaded".
+     */
     loaded: string[];
-    /** The tools the model actually called, `load_tools` excluded. */
+    /** The tools the model actually called, `load_tools` excluded and `call_tool` looked through. */
     used: string[];
     /** The hooks' notes from before the first request. */
     notes: HookNote[];
@@ -407,6 +440,13 @@ export interface AgentLoopResult {
  * 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`.
  */

package/dist/agent-loop.js

@@ -11,7 +11,7 @@ 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.
@@ -220,6 +220,13 @@ 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`.
  */
@@ -254,11 +261,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,6 +278,8 @@ 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) ?? []);
@@ -291,35 +305,71 @@ export async function runAgentLoop(options) {
     // 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);
+        messages.push({
+            role: "assistant",
+            content: null,
+            tool_calls: [{ id, type: "function", function: { name: LOAD_TOOLS, arguments: args } }],
+        }, { role: "tool", tool_call_id: id, content });
+    }
     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 +452,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;
@@ -463,7 +513,7 @@ export async function runAgentLoop(options) {
                 messages,
                 usage,
                 toolCalls,
-                loaded: [...loaded],
+                loaded: proxied ? [] : [...loaded],
                 used: [...used],
                 notes: gathered.notes,
                 context: gathered.context,
@@ -482,10 +532,29 @@ export async function runAgentLoop(options) {
         // 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;
+            const proxy = proxies && call.function.name === CALL_TOOL;
+            // 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 { name, input: raw } = proxy
+                ? shownCall(CALL_TOOL, args ? normal : call.function.arguments)
+                : { name: call.function.name, input: call.function.arguments };
+            // 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 +562,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);
                 }
             }

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/index.d.ts

@@ -32,4 +32,4 @@ export { type Produced, type StreamTurnOptions, streamTurn, type Turn, type Turn
 export { ALL_FENCES, DEFAULT_FENCES, type Fence, FenceSplitter, type FenceSplitterOptions, type Split, stripThinking, THINK_FENCE, } from "./thinking.ts";
 export { estimateTokens } from "./tokens.ts";
 export { parseToolArguments, recoverToolCalls, ToolArgumentsError, type ToolCall, } from "./tool-calls.ts";
-export { carryOver, catalogList, catalogPrompt, expandNames, inCatalog, KEYWORD_DROPOFF, KEYWORD_MIN_SCORE, type KeywordPreselection, type KeywordPreselectOptions, LOAD_TOOLS, LOAD_TOOLS_DEFINITION, loadedTools, loadResult, MAX_CARRIED, MAX_PER_LOAD, orderTools, PRESELECT_SCHEMA, PRESELECT_SYSTEM, preselectByKeywords, preselectInput, preselection, preselectSystem, requestedNames, type ToolMatch, type ToolOrder, } from "./tool-loading.ts";
+export { CALL_TOOL, carryOver, catalogList, catalogPrompt, expandNames, holdsDefinitions, inCatalog, KEYWORD_DROPOFF, KEYWORD_MIN_SCORE, type KeywordPreselection, type KeywordPreselectOptions, LOAD_TOOLS, LOAD_TOOLS_DEFINITION, loadedTools, loadResult, MAX_CARRIED, MAX_PER_LOAD, orderTools, PRESELECT_SCHEMA, PRESELECT_SYSTEM, PROXY_TOOLS, preselectByKeywords, preselectInput, preselection, preselectSystem, proxiedCall, proxyCatalogPrompt, proxyLoadResult, requestedNames, shownCall, type ToolMatch, type ToolOrder, } from "./tool-loading.ts";

package/dist/index.js

@@ -30,4 +30,4 @@ export { streamTurn, } from "./stream.js";
 export { ALL_FENCES, DEFAULT_FENCES, FenceSplitter, stripThinking, THINK_FENCE, } from "./thinking.js";
 export { estimateTokens } from "./tokens.js";
 export { parseToolArguments, recoverToolCalls, ToolArgumentsError, } from "./tool-calls.js";
-export { carryOver, catalogList, catalogPrompt, expandNames, inCatalog, KEYWORD_DROPOFF, KEYWORD_MIN_SCORE, LOAD_TOOLS, LOAD_TOOLS_DEFINITION, loadedTools, loadResult, MAX_CARRIED, MAX_PER_LOAD, orderTools, PRESELECT_SCHEMA, PRESELECT_SYSTEM, preselectByKeywords, preselectInput, preselection, preselectSystem, requestedNames, } from "./tool-loading.js";
+export { CALL_TOOL, carryOver, catalogList, catalogPrompt, expandNames, holdsDefinitions, inCatalog, KEYWORD_DROPOFF, KEYWORD_MIN_SCORE, LOAD_TOOLS, LOAD_TOOLS_DEFINITION, loadedTools, loadResult, MAX_CARRIED, MAX_PER_LOAD, orderTools, PRESELECT_SCHEMA, PRESELECT_SYSTEM, PROXY_TOOLS, preselectByKeywords, preselectInput, preselection, preselectSystem, proxiedCall, proxyCatalogPrompt, proxyLoadResult, requestedNames, shownCall, } from "./tool-loading.js";

package/dist/spec.d.ts

@@ -105,7 +105,11 @@ export interface PromptPart {
 }
 /** How tools reach the model, and which servers this agent may reach at all. */
 export interface ToolsSpec {
-    discovery?: "eager" | "ondemand";
+    /**
+     * How tool definitions reach the model: all of them on every request, a name-only catalogue
+     * the model loads from, or that catalogue behind a fixed `load_tools` and `call_tool`.
+     */
+    discovery?: "eager" | "ondemand" | "proxy";
     /** The hard stop on a tool loop. At least one. */
     maxIterations?: number;
     /**

package/dist/spec.js

@@ -206,10 +206,12 @@ function parseTools(report, value) {
         return void report.drop("tools", "must be an object");
     let discovery;
     if (!absent(value.discovery)) {
-        if (value.discovery === "eager" || value.discovery === "ondemand")
+        if (value.discovery === "eager" ||
+            value.discovery === "ondemand" ||
+            value.discovery === "proxy")
             discovery = value.discovery;
         else
-            report.drop("tools.discovery", 'must be "eager" or "ondemand"');
+            report.drop("tools.discovery", 'must be "eager", "ondemand" or "proxy"');
     }
     let servers;
     if (!absent(value.servers)) {

package/dist/tool-loading.d.ts

@@ -180,6 +180,104 @@ export declare const inCatalog: (catalog: CatalogServer[], name: string) => bool
  * @param args The tool call's arguments, exactly as the model sent them.
  */
 export declare function requestedNames(args: Record<string, unknown>): string[];
+/**
+ * The one tool a proxied run reaches every catalogued tool through.
+ *
+ * Proxied discovery is on-demand loading with a tool array that never changes. On-demand mode
+ * declares each tool as it is loaded, and a chat template renders the tool array in the system
+ * turn, ahead of the whole conversation — so appending one definition there moves every token
+ * after it, and on a model llama.cpp can only rewind to a saved checkpoint a single load
+ * re-prefills the transcript from the first token. Proxied, the array is `load_tools` and
+ * `call_tool` for the life of the session: a load answers with the definitions as its result, at
+ * the end of the history where the cache already stops, and the model runs a loaded tool through
+ * this one. The price is a level of indirection the model has to get right, which a small model
+ * does less reliably than a native call.
+ */
+export declare const CALL_TOOL = "call_tool";
+/**
+ * The whole tool array of a proxied run, `load_tools` then `call_tool`, frozen because it is
+ * shared.
+ *
+ * The load keeps `LOAD_TOOLS` as its name, so `requestedNames` and `expandNames` read its
+ * arguments as they do on demand; only what it promises differs, which is why it is not
+ * `LOAD_TOOLS_DEFINITION`. `call_tool`'s `arguments` says `additionalProperties: true` and has to:
+ * `sanitizeTools` gives an object with no properties an empty property list, a grammar-constrained
+ * server compiles that to `{}`, and without the keyword the model is left no way to pass an
+ * argument at all.
+ */
+export declare const PROXY_TOOLS: readonly OpenAI.ChatCompletionTool[];
+/**
+ * The catalogue block for a proxied run's system prompt, worded for `call_tool` rather than for a
+ * tool list.
+ *
+ * `catalogPrompt` tells the model a loaded tool is in its tool list, which proxied is never true —
+ * a model told so looks for it there and calls it natively. The listing itself is the same, and
+ * like that one it is never marked, so the head of the prompt is one text for the whole session.
+ *
+ * @param catalog The connected servers. A catalogue with no tools in it produces an empty string.
+ */
+export declare function proxyCatalogPrompt(catalog: CatalogServer[]): string;
+/**
+ * Whether a tool result is a proxied load carrying definitions, which is the only copy of them
+ * the model has.
+ *
+ * On demand the definitions are in the tool array and a load's result only repeats their
+ * descriptions, so clearing it loses nothing. Proxied, the result is the schema, and
+ * `pruneToolResults` asks this before it stubs one. Told by how `proxyLoadResult` opens, the way
+ * a summary is told by `SUMMARY_LEAD`, because a `tool` message carries no tool name of its own.
+ *
+ * @param result The tool message's text. A load that only pointed back or refused is not one.
+ */
+export declare const holdsDefinitions: (result: string) => boolean;
+/**
+ * What a proxied `load_tools` answers: each new tool's whole definition as a line of JSON, since
+ * the result is the only place the model will ever see it.
+ *
+ * A name loaded before this call is answered with a pointer back rather than its definition a
+ * second time, and one the catalogue lists but `definitions` does not hold is said to have none,
+ * so the model is not left waiting on a schema that is not coming. The refusals — too broad, over
+ * the per-call cap, not in the catalogue, nothing asked for — are `loadResult`'s, worded the same
+ * in both modes.
+ *
+ * @param resolved What the call asked for, from `expandNames`.
+ * @param catalog The servers, read for the refusals' wording.
+ * @param definitions The definitions of `resolved.matched`, as many as the host has. Ones that
+ * are not functions are skipped.
+ * @param loaded What was loaded before this call. Absent reports every match as newly loaded.
+ */
+export declare function proxyLoadResult(resolved: ReturnType<typeof expandNames>, catalog: CatalogServer[], definitions: readonly OpenAI.ChatCompletionTool[], loaded?: ReadonlySet<string>): string;
+/**
+ * The tool a `call_tool` names and the arguments to run it with, or a throw the model can read.
+ *
+ * `arguments` arrives as an object when the model follows the schema and as a JSON string when it
+ * copies the shape of a native call instead; both are taken, since the intent is the same. A name
+ * outside the catalogue is refused here rather than handed to a dispatcher, which is what keeps
+ * `call_tool` from reaching anything the catalogue does not offer.
+ *
+ * @param args The `call_tool` call's own arguments, parsed. An absent `arguments` is no arguments.
+ * @param catalog What may be called. The name is trimmed and then matched exactly.
+ */
+export declare function proxiedCall(args: Record<string, unknown>, catalog: CatalogServer[]): {
+    name: string;
+    input: Record<string, unknown>;
+};
+/**
+ * A tool call as a watcher should see it: a `call_tool` as the tool it ran, anything else as it
+ * is.
+ *
+ * The transcript keeps the `call_tool` the model wrote, since the next request has to repeat it
+ * word for word to stay in the cache; only the display looks through it. Anything that does not
+ * parse as a proxied call is left as it came.
+ *
+ * @param name The name the model called.
+ * @param input The call's arguments as JSON text.
+ * @returns The inner name and its arguments as JSON text — the string itself where the model
+ * passed `arguments` as one.
+ */
+export declare function shownCall(name: string, input: string): {
+    name: string;
+    input: string;
+};
 /**
  * The system prompt a preselector is given, holding it to the cap its answer will be held to.
  *

package/dist/tool-loading.js

@@ -340,6 +340,221 @@ export function requestedNames(args) {
         return value.filter((item) => typeof item === "string");
     return [];
 }
+/**
+ * The one tool a proxied run reaches every catalogued tool through.
+ *
+ * Proxied discovery is on-demand loading with a tool array that never changes. On-demand mode
+ * declares each tool as it is loaded, and a chat template renders the tool array in the system
+ * turn, ahead of the whole conversation — so appending one definition there moves every token
+ * after it, and on a model llama.cpp can only rewind to a saved checkpoint a single load
+ * re-prefills the transcript from the first token. Proxied, the array is `load_tools` and
+ * `call_tool` for the life of the session: a load answers with the definitions as its result, at
+ * the end of the history where the cache already stops, and the model runs a loaded tool through
+ * this one. The price is a level of indirection the model has to get right, which a small model
+ * does less reliably than a native call.
+ */
+export const CALL_TOOL = "call_tool";
+/**
+ * The whole tool array of a proxied run, `load_tools` then `call_tool`, frozen because it is
+ * shared.
+ *
+ * The load keeps `LOAD_TOOLS` as its name, so `requestedNames` and `expandNames` read its
+ * arguments as they do on demand; only what it promises differs, which is why it is not
+ * `LOAD_TOOLS_DEFINITION`. `call_tool`'s `arguments` says `additionalProperties: true` and has to:
+ * `sanitizeTools` gives an object with no properties an empty property list, a grammar-constrained
+ * server compiles that to `{}`, and without the keyword the model is left no way to pass an
+ * argument at all.
+ */
+export const PROXY_TOOLS = deepFreeze([
+    {
+        type: "function",
+        function: {
+            name: LOAD_TOOLS,
+            description: "Get the full definitions of tools listed in the tool catalogue: what each does and the " +
+                "arguments it takes. Pass the exact names you need, or a trailing wildcard like " +
+                "`server__group__*` for a whole group. Then run them with `call_tool`. Load only what " +
+                "the task actually needs.",
+            parameters: {
+                type: "object",
+                properties: {
+                    names: {
+                        type: "array",
+                        items: { type: "string" },
+                        description: "Tool names from the catalogue. Wildcards may end with `*`.",
+                    },
+                },
+                required: ["names"],
+                additionalProperties: false,
+            },
+        },
+    },
+    {
+        type: "function",
+        function: {
+            name: CALL_TOOL,
+            description: "Run a tool from the catalogue. Load it with `load_tools` first to learn its arguments, " +
+                "then pass its exact name and an arguments object matching its parameters.",
+            parameters: {
+                type: "object",
+                properties: {
+                    name: { type: "string", description: "The tool's exact name from the catalogue." },
+                    arguments: {
+                        type: "object",
+                        description: "The tool's arguments, as its definition describes them.",
+                        additionalProperties: true,
+                    },
+                },
+                required: ["name", "arguments"],
+            },
+        },
+    },
+]);
+/**
+ * The catalogue block for a proxied run's system prompt, worded for `call_tool` rather than for a
+ * tool list.
+ *
+ * `catalogPrompt` tells the model a loaded tool is in its tool list, which proxied is never true —
+ * a model told so looks for it there and calls it natively. The listing itself is the same, and
+ * like that one it is never marked, so the head of the prompt is one text for the whole session.
+ *
+ * @param catalog The connected servers. A catalogue with no tools in it produces an empty string.
+ */
+export function proxyCatalogPrompt(catalog) {
+    const list = catalogList(catalog);
+    if (!list)
+        return "";
+    return [
+        "# Tool catalogue",
+        "",
+        "These tools exist. Call `load_tools` with the names you need to get their definitions, then",
+        "run them with `call_tool`. Names are descriptive; load a tool to see its parameters. A tool",
+        "whose definition is already in this conversation does not need loading again. Do not load",
+        "tools the task does not need, and do not mention this mechanism in your answer.",
+        "",
+        list,
+    ].join("\n");
+}
+/** How a proxied load result that carries definitions opens, with the count left open. */
+const PROXY_LOADED = /^Loaded \d+ tool\(s\)\. Run them with `call_tool`\./;
+/**
+ * Whether a tool result is a proxied load carrying definitions, which is the only copy of them
+ * the model has.
+ *
+ * On demand the definitions are in the tool array and a load's result only repeats their
+ * descriptions, so clearing it loses nothing. Proxied, the result is the schema, and
+ * `pruneToolResults` asks this before it stubs one. Told by how `proxyLoadResult` opens, the way
+ * a summary is told by `SUMMARY_LEAD`, because a `tool` message carries no tool name of its own.
+ *
+ * @param result The tool message's text. A load that only pointed back or refused is not one.
+ */
+export const holdsDefinitions = (result) => PROXY_LOADED.test(result);
+/**
+ * What a proxied `load_tools` answers: each new tool's whole definition as a line of JSON, since
+ * the result is the only place the model will ever see it.
+ *
+ * A name loaded before this call is answered with a pointer back rather than its definition a
+ * second time, and one the catalogue lists but `definitions` does not hold is said to have none,
+ * so the model is not left waiting on a schema that is not coming. The refusals — too broad, over
+ * the per-call cap, not in the catalogue, nothing asked for — are `loadResult`'s, worded the same
+ * in both modes.
+ *
+ * @param resolved What the call asked for, from `expandNames`.
+ * @param catalog The servers, read for the refusals' wording.
+ * @param definitions The definitions of `resolved.matched`, as many as the host has. Ones that
+ * are not functions are skipped.
+ * @param loaded What was loaded before this call. Absent reports every match as newly loaded.
+ */
+export function proxyLoadResult(resolved, catalog, definitions, loaded) {
+    const lines = [];
+    const again = resolved.matched.filter((name) => loaded?.has(name));
+    const fresh = definitions.flatMap((tool) => tool.type === "function" && !loaded?.has(tool.function.name) ? [tool.function] : []);
+    const defined = new Set(fresh.map((tool) => tool.name));
+    const missing = resolved.matched.filter((name) => !loaded?.has(name) && !defined.has(name));
+    if (fresh.length) {
+        lines.push(`Loaded ${fresh.length} tool(s). Run them with \`${CALL_TOOL}\`.`);
+        for (const { name, description, parameters } of fresh)
+            lines.push("", JSON.stringify({ name, description, parameters }));
+    }
+    if (again.length) {
+        if (lines.length)
+            lines.push("");
+        lines.push(`Already loaded earlier in this conversation: ${again.join(", ")}. Run them with ` +
+            `\`${CALL_TOOL}\`; do not load them again.`);
+    }
+    if (missing.length) {
+        if (lines.length)
+            lines.push("");
+        lines.push(`No definition is available for: ${missing.join(", ")}.`);
+    }
+    const { overBroad, deferred, unknown, matched } = resolved;
+    if (overBroad.length || deferred.length || unknown.length || !matched.length) {
+        if (lines.length)
+            lines.push("");
+        lines.push(loadResult({ ...resolved, matched: [] }, catalog));
+    }
+    return lines.join("\n");
+}
+/**
+ * The tool a `call_tool` names and the arguments to run it with, or a throw the model can read.
+ *
+ * `arguments` arrives as an object when the model follows the schema and as a JSON string when it
+ * copies the shape of a native call instead; both are taken, since the intent is the same. A name
+ * outside the catalogue is refused here rather than handed to a dispatcher, which is what keeps
+ * `call_tool` from reaching anything the catalogue does not offer.
+ *
+ * @param args The `call_tool` call's own arguments, parsed. An absent `arguments` is no arguments.
+ * @param catalog What may be called. The name is trimmed and then matched exactly.
+ */
+export function proxiedCall(args, catalog) {
+    const name = typeof args.name === "string" ? args.name.trim() : "";
+    if (!name)
+        throw new Error(`${CALL_TOOL} needs a name; pass one from the tool catalogue.`);
+    if (!inCatalog(catalog, name))
+        throw new Error(`Not in the catalogue: ${name}. Check the name and try again.`);
+    let input = args.arguments ?? {};
+    if (typeof input === "string") {
+        const text = input;
+        try {
+            input = text.trim() ? JSON.parse(text) : {};
+        }
+        catch {
+            throw new Error(`${CALL_TOOL} arguments for ${name} are not valid JSON: ${text.slice(0, 200)}`);
+        }
+    }
+    if (!input || typeof input !== "object" || Array.isArray(input))
+        throw new Error(`${CALL_TOOL} arguments for ${name} must be an object.`);
+    return { name, input: input };
+}
+/**
+ * A tool call as a watcher should see it: a `call_tool` as the tool it ran, anything else as it
+ * is.
+ *
+ * The transcript keeps the `call_tool` the model wrote, since the next request has to repeat it
+ * word for word to stay in the cache; only the display looks through it. Anything that does not
+ * parse as a proxied call is left as it came.
+ *
+ * @param name The name the model called.
+ * @param input The call's arguments as JSON text.
+ * @returns The inner name and its arguments as JSON text — the string itself where the model
+ * passed `arguments` as one.
+ */
+export function shownCall(name, input) {
+    if (name !== CALL_TOOL)
+        return { name, input };
+    try {
+        const args = JSON.parse(input);
+        if (typeof args.name !== "string" || !args.name.trim())
+            return { name, input };
+        const inner = args.arguments ?? {};
+        return {
+            name: args.name.trim(),
+            input: typeof inner === "string" ? inner : JSON.stringify(inner),
+        };
+    }
+    catch {
+        return { name, input };
+    }
+}
 /**
  * Where a request is cut for the preselector, in characters.
  *

package/llms.txt

@@ -316,10 +316,12 @@ Reading what a model meant by a tool call when it did not write one cleanly.
 
 ### tool-loading
 
+- `CALL_TOOL` — The one tool a proxied run reaches every catalogued tool through.
 - `carryOver` — The tools to start the next turn with: last turn's where they were, then what this turn used.
 - `catalogList` — The catalogue as a plain grouped listing of names, loaded ones marked if asked.
 - `catalogPrompt` — The catalogue block appended to the system prompt.
 - `expandNames` — Resolves requested names against the catalogue, expanding trailing `*` wildcards.
+- `holdsDefinitions` — Whether a tool result is a proxied load carrying definitions, which is the only copy of them the model has.
 - `inCatalog` — Whether the catalogue holds a tool by this name.
 - `KEYWORD_DROPOFF` — How far the best unpicked tool must fall below the last picked one for the cut to count clean.
 - `KEYWORD_MIN_SCORE` — The least a best match may score and still be acted on without a model.
@@ -334,10 +336,15 @@ Reading what a model meant by a tool call when it did not write one cleanly.
 - `orderTools` — The tool array in a stable order, so the same set of tools renders the same way twice.
 - `PRESELECT_SCHEMA` — The shape a preselector's answer is held to where the server takes a schema: `{ tools: [...] }`.
 - `PRESELECT_SYSTEM` — The preselection system prompt at the default cap, for a caller that never changes it.
+- `PROXY_TOOLS` — The whole tool array of a proxied run, `load_tools` then `call_tool`, frozen because it is shared.
 - `preselectByKeywords` — The tools a request's own words point at, ranked, and whether they point clearly enough.
 - `preselectInput` — The user message for a preselection call: the catalogue, then the request.
 - `preselection` — Resolves a preselection against the catalogue: unknown names dropped, count capped.
 - `preselectSystem` — The system prompt a preselector is given, holding it to the cap its answer will be held to.
+- `proxiedCall` — The tool a `call_tool` names and the arguments to run it with, or a throw the model can read.
+- `proxyCatalogPrompt` — The catalogue block for a proxied run's system prompt, worded for `call_tool` rather than for a tool list.
+- `proxyLoadResult` — What a proxied `load_tools` answers: each new tool's whole definition as a line of JSON, since the result is the only place the model will ever see it.
 - `requestedNames` — `load_tools` arguments, defensively — a model may send a bare string or a nested object.
+- `shownCall` — A tool call as a watcher should see it: a `call_tool` as the tool it ran, anything else as it is.
 - `ToolMatch` (type) — One tool's score against a request.
 - `ToolOrder` (type) — How a tool array is ordered before it is sent: `true` by name, `false` as the caller built it, or a comparator over the two names.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cubicecho/agent-core",
-  "version": "2.19.0",
+  "version": "2.20.0",
   "description": "The endpoint-agnostic half of an OpenAI-compatible agent loop: tool-schema compatibility, on-demand tool loading, one-shot side tasks, run events, and a pooled client.",
   "keywords": [
     "openai",