@cubicecho/agent-core 2.19.0 → 2.21.0

package/dist/errors.js

@@ -1,3 +1,4 @@
+import { ContextOverflow } from "./retry.js";
 /**
  * What went wrong, as a string.
  *
@@ -8,3 +9,79 @@
  * @param error Whatever a `catch` bound. Anything that is not an `Error` is stringified.
  */
 export const errorMessage = (error) => error instanceof Error ? error.message : String(error);
+/**
+ * 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 class AgentLoopError extends Error {
+    name = "AgentLoopError";
+    messages;
+    usage;
+    toolCalls;
+    loaded;
+    used;
+    /**
+     * @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, run, options) {
+        super(message, options);
+        this.messages = run.messages;
+        this.usage = run.usage;
+        this.toolCalls = run.toolCalls;
+        this.loaded = run.loaded;
+        this.used = run.used;
+    }
+}
+/**
+ * `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 class ToolIterationLimit extends AgentLoopError {
+    name = "ToolIterationLimit";
+}
+/**
+ * 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 class AgentLoopOverflow extends ContextOverflow {
+    messages;
+    usage;
+    toolCalls;
+    loaded;
+    used;
+    /**
+     * @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, run, options) {
+        super(message, options);
+        this.messages = run.messages;
+        this.usage = run.usage;
+        this.toolCalls = run.toolCalls;
+        this.loaded = run.loaded;
+        this.used = run.used;
+    }
+}
+/**
+ * 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 const failedRun = (error) => error instanceof AgentLoopError || error instanceof AgentLoopOverflow ? error : undefined;

package/dist/index.d.ts

@@ -17,7 +17,7 @@ export { type ClientPoolOptions, configureClients, contextLimitFor, endpointId,
 export { applyCompaction, COMPACT_AT, type CompactionOptions, type CompactionPlan, type CompactionRecord, type CompactionRunOptions, compactTranscript, KEEP_RATIO, type PruneOptions, planCompaction, pruneToolResults, requestIndex, runCompaction, SUMMARY_LEAD, SUMMARY_PROMPT, summariser, summaryInput, } from "./compaction.ts";
 export type { AgentConfig, Endpoint, ModelParams, RetryPolicy, ToolPolicy, } from "./config.ts";
 export { type ContinueTurnOptions, continueTurn, isContinuable, } from "./continuation.ts";
-export { errorMessage } from "./errors.ts";
+export { AgentLoopError, type AgentLoopFailure, AgentLoopOverflow, errorMessage, failedRun, ToolIterationLimit, } from "./errors.ts";
 export { configureEvents, type EventBusOptions, emit, endRun, fold, history, type RunEvent, type RunEventInput, type RunEventKind, type RunMetrics, type RunMetricsOptions, type RunUsage, resetEvents, runMetrics, type TurnReport, watch, } from "./events.ts";
 export { assembleContext, configureHooks, consult, type Gathered, gather, HOOK_CONTEXT_TOKENS, HOOK_EVENTS, HOOK_PREFACE, type HookContext, type HookEvent, type HookMessage, type HookNote, type HookOptions, type HookOutcome, type HookRunner, INJECT_EVENTS, notify, resetHooks, turnIndex, turnMessages, UNTRUSTED_PREFACE, untrusted, withContext, } from "./hooks.ts";
 export { estimateFrom, type LedgerEntry, type LedgerEstimateOptions, type LedgerRequest, rebaseLedger, recordRequest, type TokenLedger, tokensBetween, } from "./ledger.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

@@ -15,7 +15,7 @@ export { capabilitiesFor, EFFORT_LADDER, effortFor, expireCapabilities, modelCap
 export { configureClients, contextLimitFor, endpointId, endpointKey, FIRST_TOKEN_FACTOR, firstTokenMs, getClient, listModels, NO_KEY, resetClients, servedWindow, timeoutMs, } from "./client.js";
 export { applyCompaction, COMPACT_AT, compactTranscript, KEEP_RATIO, planCompaction, pruneToolResults, requestIndex, runCompaction, SUMMARY_LEAD, SUMMARY_PROMPT, summariser, summaryInput, } from "./compaction.js";
 export { continueTurn, isContinuable, } from "./continuation.js";
-export { errorMessage } from "./errors.js";
+export { AgentLoopError, AgentLoopOverflow, errorMessage, failedRun, ToolIterationLimit, } from "./errors.js";
 export { configureEvents, emit, endRun, fold, history, resetEvents, runMetrics, watch, } from "./events.js";
 export { assembleContext, configureHooks, consult, gather, HOOK_CONTEXT_TOKENS, HOOK_EVENTS, HOOK_PREFACE, INJECT_EVENTS, notify, resetHooks, turnIndex, turnMessages, UNTRUSTED_PREFACE, untrusted, withContext, } from "./hooks.js";
 export { estimateFrom, rebaseLedger, recordRequest, tokensBetween, } from "./ledger.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

@@ -115,7 +115,12 @@ Picking up an answer the token ceiling cut off, instead of keeping half of it.
 
 ### errors
 
+- `AgentLoopError` — What `runAgentLoop` throws, carrying the run as it stood and what was caught as `cause`.
+- `AgentLoopFailure` (type) — A run as it stood when `runAgentLoop` gave up on it.
+- `AgentLoopOverflow` — A `ContextOverflow` out of `runAgentLoop`, carrying the run as it stood.
 - `errorMessage` — What went wrong, as a string.
+- `failedRun` — The run a failed `runAgentLoop` left behind, read off whatever it threw, or nothing.
+- `ToolIterationLimit` — `maxToolIterations` was spent with the model still asking for tools.
 
 ### events
 
@@ -316,10 +321,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 +341,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.21.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",