@cubicecho/agent-core 2.23.0 → 2.25.0

package/dist/tool-loading.js

@@ -1,6 +1,10 @@
+import { isRecord } from './guards.js';
+import { ARGUMENT_PREVIEW_CHARS } from './tool-calls.js';
+import { FUNCTION_TOOL, SchemaType } from './wire.js';
 /**
  * On-demand tool loading.
  *
+ * @remarks
  * A full tool definition is mostly JSON Schema, and it is sent on every request of every
  * iteration whether or not the model wants it — a couple of connected servers can cost more
  * tokens per request than the task's own prompt. So in on-demand mode the run starts with a
@@ -11,39 +15,48 @@
  * Names alone cost roughly a fortieth of what the schemas cost, so a run that needs no tools
  * pays almost nothing, and a run that needs three pays for three.
  */
-export const LOAD_TOOLS = "load_tools";
-/** Shallow freezing this one would leave `.function.description` — the part worth editing. */
+export const LOAD_TOOLS = 'load_tools';
+/**
+ * Shallow freezing this one would leave `.function.description` — the part worth editing.
+ *
+ * @param value - What to freeze, in place, with every object and array reachable from it. A
+ * primitive passes through. Nothing stops the walk on a value that holds itself.
+ * @returns `value` itself, not a copy.
+ */
 function deepFreeze(value) {
-    if (value && typeof value === "object")
-        for (const held of Object.values(value))
+    if (value && typeof value === 'object') {
+        for (const held of Object.values(value)) {
             deepFreeze(held);
+        }
+    }
     return Object.freeze(value);
 }
 /**
  * One object for the life of the process — the agent loop asks for it on every iteration.
  *
+ * @remarks
  * Frozen because it is shared: one mutable export reached by every consumer in the process
  * means a caller that edits the description in place has edited it for all of them, in a place
  * nobody would think to look for the change.
  */
 export const LOAD_TOOLS_DEFINITION = deepFreeze({
-    type: "function",
+    type: FUNCTION_TOOL,
     function: {
         name: LOAD_TOOLS,
-        description: "Load the full definitions of tools listed in the tool catalogue so you can call them. " +
-            "Pass the exact names you need, or a trailing wildcard like `server__group__*` for a " +
-            "whole group. The tools become callable on your next step — load them, then call them. " +
-            "Load only what the task actually needs.",
+        description: 'Load the full definitions of tools listed in the tool catalogue so you can call them. ' +
+            'Pass the exact names you need, or a trailing wildcard like `server__group__*` for a ' +
+            'whole group. The tools become callable on your next step — load them, then call them. ' +
+            'Load only what the task actually needs.',
         parameters: {
-            type: "object",
+            type: SchemaType.Object,
             properties: {
                 names: {
-                    type: "array",
-                    items: { type: "string" },
-                    description: "Tool names from the catalogue. Wildcards may end with `*`.",
+                    type: SchemaType.Array,
+                    items: { type: SchemaType.String },
+                    description: 'Tool names from the catalogue. Wildcards may end with `*`.',
                 },
             },
-            required: ["names"],
+            required: ['names'],
             additionalProperties: false,
         },
     },
@@ -51,26 +64,36 @@ export const LOAD_TOOLS_DEFINITION = deepFreeze({
 /**
  * The catalogue as a plain grouped listing of names, loaded ones marked if asked.
  *
+ * @param catalog - The connected servers. Ones with no tools are dropped.
+ * @param [loaded] - Names to mark `(loaded)` rather than remove. Absent marks nothing, which keeps the
+ * listing the same text for the whole run.
+ * @returns Each server's label on a line ending in a colon, its tool names indented beneath, one
+ * server straight after another. Empty where no server has a tool.
+ *
+ * @remarks
  * A server with no tools is dropped rather than titled: a pool hands one over whenever a
  * server is connected but has nothing to offer, and a label with nothing under it reads as a
  * listing that got cut off.
- *
- * @param catalog The connected servers. Ones with no tools are dropped.
- * @param loaded Names to mark `(loaded)` rather than remove. Absent marks nothing, which keeps the
- * listing the same text for the whole run.
  */
 export function catalogList(catalog, loaded) {
     return catalog
         .filter((server) => server.tools.length > 0)
         .map((server) => {
-        const names = server.tools.map((tool) => `  ${tool.name}${loaded?.has(tool.name) ? " (loaded)" : ""}`);
-        return `${server.label}:\n${names.join("\n")}`;
+        const names = server.tools.map((tool) => `  ${tool.name}${loaded?.has(tool.name) ? ' (loaded)' : ''}`);
+        return `${server.label}:\n${names.join('\n')}`;
     })
-        .join("\n");
+        .join('\n');
 }
 /**
  * The catalogue block appended to the system prompt. Names only — descriptions arrive on load.
  *
+ * @param catalog - The connected servers. A catalogue with no tools in it produces an empty string.
+ * @param [loaded] - Names to mark `(loaded)`, for a caller that rebuilds its prompt per load and does
+ * not mind the cache. Absent marks nothing.
+ * @returns The heading, the instructions and the listing, with no blank line before or after — the
+ * caller separates it from its own prompt. Empty where there is nothing to list.
+ *
+ * @remarks
  * `runAgentLoop` passes no `loaded`, so the block is the same text on every step. The system
  * prompt is the head of the request, and marking each load there threw away the prompt cache for
  * the whole transcript on every `load_tools` call. What is loaded is said where it does not move
@@ -81,56 +104,101 @@ export function catalogList(catalog, loaded) {
  * it was loaded, and the model loads again to get it back; hoisting them into a separate "already
  * loaded" section splits a server's tools apart, and the model picks a sibling from the longer
  * list instead.
- *
- * @param catalog The connected servers. A catalogue with no tools in it produces an empty string.
- * @param loaded Names to mark `(loaded)`, for a caller that rebuilds its prompt per load and does
- * not mind the cache. Absent marks nothing.
  */
 export function catalogPrompt(catalog, loaded) {
     const list = catalogList(catalog, loaded);
     // Not `catalog.length`: a catalogue of nothing but empty servers has no names to offer, and
     // the preamble below would then explain a mechanism against an empty list.
-    if (!list)
-        return "";
+    if (!list) {
+        return '';
+    }
     return [
-        "# Tool catalogue",
-        "",
-        "These tools exist but are not loaded. Call `load_tools` with the names you need, then call",
-        "them on the step after. Names are descriptive; load a tool to see its parameters. A tool",
-        "already in your tool list is loaded — call it directly, do not load it again. Do not load",
-        "tools the task does not need, and do not mention this mechanism in your answer.",
-        "",
+        '# Tool catalogue',
+        '',
+        'These tools exist but are not loaded. Call `load_tools` with the names you need, then call',
+        'them on the step after. Names are descriptive; load a tool to see its parameters. A tool',
+        'already in your tool list is loaded — call it directly, do not load it again. Do not load',
+        'tools the task does not need, and do not mention this mechanism in your answer.',
+        '',
         list,
-    ].join("\n");
+    ].join('\n');
 }
+/**
+ * Every tool in the catalogue as one list, server by server.
+ *
+ * @param catalog - The connected servers.
+ * @returns A new array in catalogue order. A name two servers offer is in it twice.
+ */
 const flatten = (catalog) => catalog.flatMap((server) => server.tools);
+/**
+ * The name a tool definition is called by, or `undefined` for one that is not a function.
+ *
+ * @param tool - The definition, as a request declares it.
+ * @returns The function's name as the definition spells it — an empty one comes back empty, not
+ * `undefined`.
+ *
+ * @remarks
+ * Undefined rather than empty, so a caller that skips such a tool and one that has to place it
+ * somewhere each say which they mean — a sort and a positional comparison want `?? ""`, a lookup
+ * by name wants the tool left out.
+ */
+export const toolName = (tool) => tool.type === FUNCTION_TOOL ? tool.function.name : undefined;
 /**
  * A tool array with newly loaded definitions appended, in the order they were loaded.
  *
+ * @param previous - What the last request declared, `load_tools` included. Not written to.
+ * @param matched - The definitions to add. Ones whose name is already declared, here or earlier in
+ * this list, are skipped rather than moved. One that is not a function has no name to be
+ * skipped by, and is appended.
+ * @returns A new array, `previous` first — a copy even where nothing was added.
+ *
+ * @remarks
  * Appended and never rebuilt from a set, so what a load adds is decided by the load and not by
  * the shape of whatever collection the definitions came out of. Where the appended array ends up
  * in the request is `orderTools`' business, which the loop applies after this.
- *
- * @param previous What the last request declared, `load_tools` included. Not written to.
- * @param matched The definitions to add. Ones whose name is already declared, here or earlier in
- * this list, are skipped rather than moved.
  */
 export function loadedTools(previous, matched) {
-    const nameOf = (tool) => tool.type === "function" ? tool.function.name : undefined;
-    const declared = new Set(previous.map(nameOf));
+    const declared = new Set(previous.map(toolName));
     const tools = [...previous];
     for (const tool of matched) {
-        const name = nameOf(tool);
-        if (name !== undefined && declared.has(name))
+        const name = toolName(tool);
+        if (name !== undefined && declared.has(name)) {
             continue;
+        }
         declared.add(name);
         tools.push(tool);
     }
     return tools;
 }
+/**
+ * Orders two names by code unit.
+ *
+ * @param a - The name on the left.
+ * @param b - The name on the right.
+ * @returns Negative where `a` sorts first, positive where `b` does, zero where they are the same.
+ *
+ * @remarks
+ * Rather than `localeCompare`, whose answer depends on the host's locale — which is the kind of
+ * instability `orderTools` exists to remove.
+ */
+function byCodeUnit(a, b) {
+    if (a < b) {
+        return -1;
+    }
+    if (a > b) {
+        return 1;
+    }
+    return 0;
+}
 /**
  * The tool array in a stable order, so the same set of tools renders the same way twice.
  *
+ * @param tools - The definitions to order. Not written to.
+ * @param [order] - `true` for name order, `false` to leave it alone, or a comparator over the names.
+ * A tool that is not a function orders as the empty name.
+ * @returns `tools` itself when it is already in that order, so the common case copies nothing.
+ *
+ * @remarks
  * A chat template renders the declared tools ahead of the system prompt, which makes the tool
  * array the first thing a prompt cache has to match — and an array assembled from a map, from
  * database rows, or from the order servers happened to connect in changes between processes and
@@ -142,25 +210,20 @@ export function loadedTools(previous, matched) {
  *
  * `false` is for a caller that means its order: the model reads the array top to bottom, and a
  * host may be putting what it wants reached for first at the front.
- *
- * @param tools The definitions to order. Not written to.
- * @param order `true` for name order, `false` to leave it alone, or a comparator over the names.
- * A tool that is not a function orders as the empty name.
- * @returns `tools` itself when it is already in that order, so the common case copies nothing.
  */
 export function orderTools(tools, order = true) {
-    if (order === false)
+    if (order === false) {
         return tools;
-    const nameOf = (tool) => tool.type === "function" ? tool.function.name : "";
-    // Code-unit order rather than `localeCompare`, whose answer depends on the host's locale —
-    // which is the kind of instability this exists to remove.
-    const compare = typeof order === "function" ? order : (a, b) => (a < b ? -1 : a > b ? 1 : 0);
+    }
+    const nameOf = (tool) => toolName(tool) ?? '';
+    const compare = typeof order === 'function' ? order : byCodeUnit;
     const sorted = [...tools].sort((a, b) => compare(nameOf(a), nameOf(b)));
     return sorted.some((tool, at) => tool !== tools[at]) ? sorted : tools;
 }
 /**
  * The most a single `load_tools` call may pull in.
  *
+ * @remarks
  * A wildcard like `gmail__*` matches 33 tools, and loading them all puts the model right back
  * in the position on-demand loading exists to avoid — a tool array too large to choose from.
  * Over-broad requests are refused with the matching names listed, so the next call can be
@@ -176,6 +239,7 @@ export const MAX_PER_LOAD = 12;
  * The most a conversation carries between turns. Bounds the tool array no matter how long the
  * conversation runs; past it, the earliest-declared names this turn did not use fall off first.
  *
+ * @remarks
  * Only a multi-turn caller needs this — a run that starts from nothing each time has nothing to
  * carry. See `carryOver`, which takes another number if this one is not yours.
  */
@@ -183,19 +247,21 @@ export const MAX_CARRIED = 16;
 /**
  * The tools to start the next turn with: last turn's where they were, then what this turn used.
  *
+ * @param previous - Last turn's names, in the order they were declared.
+ * @param used - What this turn called. Names not already carried are appended in the order given,
+ * so pass them in load order to keep them where the tool array had them.
+ * @param [max] - How many to carry. Past it, the earliest names not in
+ * `used` go first, then the earliest of all. At least one: a cap of zero is read as one, not as
+ * no cap and not as none.
+ * @returns The names to carry, as a new array no longer than the cap.
+ *
+ * @remarks
  * Nothing carried moves. A template renders the tool array near the head of the prompt, and
  * moving each used tool to the end — which this did until it was found in a local server's cache
  * log — reordered the array between turns and re-prefilled the whole transcript from the first
  * moved definition. Kept in place, the next turn's array is this one's with only the unused
  * loads gone, a prefix of it when every load was used. Past `max`, dropping a name from the
  * middle costs the cache from there, so it happens only when the cap forces it.
- *
- * @param previous Last turn's names, in the order they were declared.
- * @param used What this turn called. Names not already carried are appended in the order given,
- * so pass them in load order to keep them where the tool array had them.
- * @param max How many to carry, defaulting to `MAX_CARRIED`. Past it, the earliest names not in
- * `used` go first, then the earliest of all. At least one: a cap of zero is read as one, not as
- * no cap and not as none.
  */
 export function carryOver(previous, used, max = MAX_CARRIED) {
     const next = [...previous, ...[...used].filter((name) => !previous.includes(name))];
@@ -209,16 +275,19 @@ export function carryOver(previous, used, max = MAX_CARRIED) {
 /**
  * Resolves requested names against the catalogue, expanding trailing `*` wildcards.
  *
+ * @param requested - What the model asked for. A trailing `*` expands.
+ * @param catalog - The servers to resolve against.
+ * @param [maxPerLoad] - The most this call may load. It comes back on
+ * the resolution so `loadResult` reports the same number rather than a second opinion of it.
+ * @returns The names that resolved, each once; the ones nothing matched; the asks too broad for
+ * any call, with what they matched; and the ones that only did not fit this call.
+ *
+ * @remarks
  * Names are matched leniently. Catalogue entries are slug-qualified (`nas_fs__read_file`) and
  * models routinely ask for the bare tool name, so an exact miss falls back to a suffix match
  * on the `__` boundary — accepted only when it is unambiguous. Rejecting those outright just
  * buys a wasted round trip while the model guesses the prefix, and pushes it toward
  * shotgunning wildcards.
- *
- * @param requested What the model asked for. A trailing `*` expands.
- * @param catalog The servers to resolve against.
- * @param maxPerLoad The most this call may load, defaulting to `MAX_PER_LOAD`. It comes back on
- * the resolution so `loadResult` reports the same number rather than a second opinion of it.
  */
 export function expandNames(requested, catalog, maxPerLoad = MAX_PER_LOAD) {
     const all = flatten(catalog);
@@ -228,26 +297,29 @@ export function expandNames(requested, catalog, maxPerLoad = MAX_PER_LOAD) {
     const deferred = [];
     const known = new Set(all.map((tool) => tool.name));
     const resolve = (name) => {
-        if (name.endsWith("*")) {
+        if (name.endsWith('*')) {
             const stem = name.slice(0, -1);
             const direct = all.filter((tool) => tool.name.startsWith(stem));
-            if (direct.length)
+            if (direct.length) {
                 return direct.map((tool) => tool.name);
+            }
             return all.filter((tool) => tool.name.includes(`__${stem}`)).map((tool) => tool.name);
         }
-        if (known.has(name))
+        if (known.has(name)) {
             return [name];
+        }
         const suffix = all.filter((tool) => tool.name.endsWith(`__${name}`));
         return suffix.length === 1 ? [suffix[0].name] : [];
     };
     for (const raw of requested) {
         const name = raw.trim();
-        if (!name)
+        if (!name) {
             continue;
+        }
         // A bare `*` is not a guess at a name, it is a refusal to choose, and its empty stem
         // prefixes every tool in the catalogue. Answer it the way any other over-broad request is
         // answered: with the names, so the next call can pick from them.
-        if (name === "*") {
+        if (name === '*') {
             overBroad.push({ name, hits: all.map((tool) => tool.name) });
             continue;
         }
@@ -267,82 +339,105 @@ export function expandNames(requested, catalog, maxPerLoad = MAX_PER_LOAD) {
         // enough already — telling a model that asked for one exact tool that it matches one tool,
         // "more than the twelve one call may load", and to choose from a list holding just that
         // name, leaves it nothing to do but send the identical call again.
-        if (fresh.length > maxPerLoad)
+        if (fresh.length > maxPerLoad) {
             overBroad.push({ name, hits });
-        else if (matched.size + fresh.length > maxPerLoad)
+        }
+        else if (matched.size + fresh.length > maxPerLoad) {
             deferred.push(name);
-        else
-            for (const hit of hits)
+        }
+        else {
+            for (const hit of hits) {
                 matched.add(hit);
+            }
+        }
     }
     return { matched: [...matched], unknown, overBroad, deferred, maxPerLoad };
 }
+/**
+ * Each block's lines on their own, and a blank line between one block and the next.
+ *
+ * @param blocks - The blocks, each as its lines.
+ * @returns One text, empty where there are no blocks.
+ */
+const joinBlocks = (blocks) => blocks.map((block) => block.join('\n')).join('\n\n');
 /**
  * What `load_tools` reports back: the descriptions, now that they are worth their tokens.
  *
+ * @param expanded - What `expandNames` resolved: the matches, the misses, and the over-broad asks.
+ * @param catalog - The servers, read for the descriptions now worth their tokens.
+ * @param [loaded] - What was loaded before this call. Absent reports every match as newly loaded.
+ * @returns What the model reads, a blank line between each thing it is told: what was loaded with
+ * its descriptions, what already was, each over-broad ask with its matches, what did not fit this
+ * call, and what is not in the catalogue. `No tool names were given.` where there is none of them.
+ *
+ * @remarks
  * A name that was loaded before this call is reported as already loaded rather than loaded
  * again. The catalogue no longer marks what is loaded — see `catalogPrompt` — so this is where a
  * model that asks twice finds out it need not have, and is told to call the tool instead.
- *
- * @param expanded What `expandNames` resolved: the matches, the misses, and the over-broad asks.
- * @param catalog The servers, read for the descriptions now worth their tokens.
- * @param loaded What was loaded before this call. Absent reports every match as newly loaded.
  */
 export function loadResult({ matched, unknown, overBroad, deferred, maxPerLoad }, catalog, loaded) {
     const byName = new Map(flatten(catalog).map((tool) => [tool.name, tool.description]));
-    const lines = [];
+    // One entry per thing the model is told, each a blank line from the next.
+    const blocks = [];
     const fresh = matched.filter((name) => !loaded?.has(name));
     const again = matched.filter((name) => loaded?.has(name));
     if (fresh.length) {
-        lines.push(`Loaded ${fresh.length} tool(s); they are callable on your next step.`, "");
-        for (const name of fresh)
-            lines.push(`${name}: ${byName.get(name) ?? ""}`.trim());
+        blocks.push([
+            `Loaded ${fresh.length} tool(s); they are callable on your next step.`,
+            '',
+            ...fresh.map((name) => `${name}: ${byName.get(name) ?? ''}`.trim()),
+        ]);
     }
     if (again.length) {
-        if (lines.length)
-            lines.push("");
-        lines.push(`Already loaded and in your tool list: ${again.join(", ")}. Call them directly; do not load them again.`);
-    }
-    for (const { name, hits } of overBroad) {
-        if (lines.length)
-            lines.push("");
-        lines.push(`\`${name}\` matches ${hits.length} tools, more than the ${maxPerLoad} one call may load.`, "Name the ones you need from:", ...hits.map((hit) => `  ${hit}`));
+        blocks.push([
+            `Already loaded and in your tool list: ${again.join(', ')}. Call them directly; do not load them again.`,
+        ]);
     }
+    blocks.push(...overBroad.map(({ name, hits }) => [
+        `\`${name}\` matches ${hits.length} tools, more than the ${maxPerLoad} one call may load.`,
+        'Name the ones you need from:',
+        ...hits.map((hit) => `  ${hit}`),
+    ]));
     if (deferred.length) {
-        if (lines.length)
-            lines.push("");
-        lines.push(`This call is full at ${maxPerLoad} tools, so these were not loaded: ${deferred.join(", ")}.`, "Ask for them on your next step.");
+        blocks.push([
+            `This call is full at ${maxPerLoad} tools, so these were not loaded: ${deferred.join(', ')}.`,
+            'Ask for them on your next step.',
+        ]);
     }
     if (unknown.length) {
-        if (lines.length)
-            lines.push("");
-        lines.push(`Not in the catalogue: ${unknown.join(", ")}. Check the names and try again.`);
+        blocks.push([`Not in the catalogue: ${unknown.join(', ')}. Check the names and try again.`]);
     }
-    return lines.join("\n") || "No tool names were given.";
+    return joinBlocks(blocks) || 'No tool names were given.';
 }
 /**
  * Whether the catalogue holds a tool by this name.
  *
- * @param catalog The connected servers and the tools each one offers.
- * @param name An exact name. Nothing is prefixed, trimmed or fuzzily matched.
+ * @param catalog - The connected servers and the tools each one offers.
+ * @param name - An exact name. Nothing is prefixed, trimmed or fuzzily matched.
+ * @returns True where any server offers it, which no server of an empty catalogue does.
  */
 export const inCatalog = (catalog, name) => catalog.some((server) => server.tools.some((tool) => tool.name === name));
 /**
  * `load_tools` arguments, defensively — a model may send a bare string or a nested object.
  *
- * @param args The tool call's arguments, exactly as the model sent them.
+ * @param args - The tool call's arguments, exactly as the model sent them.
+ * @returns The names under `names`, or failing that `tools`, or `name`: a string as a list of one,
+ * an array less whatever in it is not a string, and anything else as none. Not trimmed.
  */
 export function requestedNames(args) {
     const value = args.names ?? args.tools ?? args.name;
-    if (typeof value === "string")
+    if (typeof value === 'string') {
         return [value];
-    if (Array.isArray(value))
-        return value.filter((item) => typeof item === "string");
+    }
+    if (Array.isArray(value)) {
+        return value.filter((item) => typeof item === 'string');
+    }
     return [];
 }
 /**
  * The one tool a proxied run reaches every catalogued tool through.
  *
+ * @remarks
  * 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
@@ -353,11 +448,12 @@ export function requestedNames(args) {
  * 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";
+export const CALL_TOOL = 'call_tool';
 /**
  * The whole tool array of a proxied run, `load_tools` then `call_tool`, frozen because it is
  * shared.
  *
+ * @remarks
  * 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:
@@ -367,44 +463,44 @@ export const CALL_TOOL = "call_tool";
  */
 export const PROXY_TOOLS = deepFreeze([
     {
-        type: "function",
+        type: FUNCTION_TOOL,
         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.",
+            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",
+                type: SchemaType.Object,
                 properties: {
                     names: {
-                        type: "array",
-                        items: { type: "string" },
-                        description: "Tool names from the catalogue. Wildcards may end with `*`.",
+                        type: SchemaType.Array,
+                        items: { type: SchemaType.String },
+                        description: 'Tool names from the catalogue. Wildcards may end with `*`.',
                     },
                 },
-                required: ["names"],
+                required: ['names'],
                 additionalProperties: false,
             },
         },
     },
     {
-        type: "function",
+        type: FUNCTION_TOOL,
         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.",
+            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",
+                type: SchemaType.Object,
                 properties: {
-                    name: { type: "string", description: "The tool's exact name from the catalogue." },
+                    name: { type: SchemaType.String, description: "The tool's exact name from the catalogue." },
                     arguments: {
-                        type: "object",
+                        type: SchemaType.Object,
                         description: "The tool's arguments, as its definition describes them.",
                         additionalProperties: true,
                     },
                 },
-                required: ["name", "arguments"],
+                required: ['name', 'arguments'],
             },
         },
     },
@@ -413,26 +509,29 @@ export const PROXY_TOOLS = deepFreeze([
  * The catalogue block for a proxied run's system prompt, worded for `call_tool` rather than for a
  * tool list.
  *
+ * @param catalog - The connected servers. A catalogue with no tools in it produces an empty string.
+ * @returns The heading, the instructions and the listing, with no blank line before or after.
+ *
+ * @remarks
  * `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 "";
+    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.",
-        "",
+        '# 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");
+    ].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`\./;
@@ -440,314 +539,129 @@ 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.
  *
+ * @param result - The tool message's text. A load that only pointed back or refused is not one.
+ * @returns True where the text opens as `proxyLoadResult` opens a result with a definition in it.
+ *
+ * @remarks
  * 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.
  *
+ * @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.
+ * @returns What the model reads, a blank line between each part: the count and one line of JSON
+ * per new definition, then what was already loaded, what has no definition, and the refusals.
+ * Never empty.
+ *
+ * @remarks
  * 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 blocks = [];
     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 fresh = definitions.flatMap((tool) => tool.type === FUNCTION_TOOL && !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 }));
+        blocks.push([`Loaded ${fresh.length} tool(s). Run them with \`${CALL_TOOL}\`.`]);
+        blocks.push(...fresh.map(({ name, description, parameters }) => [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.`);
+        blocks.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(", ")}.`);
+        blocks.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));
+    const hasMoreToSay = overBroad.length || deferred.length || unknown.length || !matched.length;
+    if (hasMoreToSay) {
+        blocks.push([loadResult({ ...resolved, matched: [] }, catalog)]);
     }
-    return lines.join("\n");
+    return joinBlocks(blocks);
 }
 /**
  * The tool a `call_tool` names and the arguments to run it with, or a throw the model can read.
  *
+ * @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.
+ * @returns The trimmed name, and the arguments as an object: the one the model passed, not a copy,
+ * or the one its JSON string parsed to.
+ *
+ * @remarks
  * `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)
+    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))
+    }
+    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") {
+    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)}`);
+            throw new Error(`${CALL_TOOL} arguments for ${name} are not valid JSON: ${text.slice(0, ARGUMENT_PREVIEW_CHARS)}`);
         }
     }
-    if (!input || typeof input !== "object" || Array.isArray(input))
+    if (!isRecord(input)) {
         throw new Error(`${CALL_TOOL} arguments for ${name} must be an object.`);
-    return { name, input: input };
+    }
+    return { name, input };
 }
 /**
  * A tool call as a watcher should see it: a `call_tool` as the tool it ran, anything else as it
  * is.
  *
+ * @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.
+ *
+ * @remarks
  * 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)
+    if (name !== CALL_TOOL) {
         return { name, input };
+    }
     try {
         const args = JSON.parse(input);
-        if (typeof args.name !== "string" || !args.name.trim())
+        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),
+            input: typeof inner === 'string' ? inner : JSON.stringify(inner),
         };
     }
     catch {
         return { name, input };
     }
 }
-/**
- * Where a request is cut for the preselector, in characters.
- *
- * A tool choice is made on what the work is, which is the top of a request rather than all of
- * it — and the whole of a long one is paid for again in the preselection call. `preselectInput`
- * takes another number for a caller whose requests are not shaped that way.
- */
-const PRESELECT_PROMPT_CHARS = 2000;
-/**
- * The system prompt a preselector is given, holding it to the cap its answer will be held to.
- *
- * On-demand loading otherwise costs a round trip every run: the model reads the catalogue,
- * calls `load_tools`, and only then can do the work. A small model reading the same catalogue
- * usually names the right tools outright, so the task model finds them already loaded and
- * starts working on its first step.
- *
- * A wrong guess is cheap — an unused definition is a few hundred tokens for one run — but a
- * broad guess is not, so the same cap applies here as to a `load_tools` call.
- *
- * @param maxPerLoad The most to ask for, defaulting to `MAX_PER_LOAD`. Give `preselection` the
- * same number: this one is what the preselector is told, and that one is what it is held to.
- */
-export const preselectSystem = (maxPerLoad = MAX_PER_LOAD) => "You choose tools. Below is a catalogue of tool names, then a request. Reply with a JSON " +
-    'object whose "tools" array holds the names the request is likely to need — exact names from ' +
-    `the catalogue, at most ${maxPerLoad}, and as few as could do the job. Reply with ` +
-    '`{"tools": []}` if the request can be answered without tools. Reply with the object alone — ' +
-    "no prose, no explanation.";
-/**
- * The shape a preselector's answer is held to where the server takes a schema: `{ tools: [...] }`.
- *
- * An object around the array rather than the array, because a structured answer's root has to be
- * an object — OpenAI's strict mode and every tool-schema normaliser insist.
- */
-export const PRESELECT_SCHEMA = {
-    type: "object",
-    properties: { tools: { type: "array", items: { type: "string" } } },
-    required: ["tools"],
-    additionalProperties: false,
-};
-/** The preselection system prompt at the default cap, for a caller that never changes it. */
-export const PRESELECT_SYSTEM = preselectSystem();
-/**
- * The user message for a preselection call: the catalogue, then the request.
- *
- * @param catalog The connected servers, rendered as the name-only listing.
- * @param prompt The request being planned for, truncated — choosing tools needs the shape of the
- * ask, not all of it.
- * @param maxPromptChars Where the request is cut, defaulting to 2000. A caller whose requests
- * carry the part that names the work at the end wants a larger one, and pays for it in the
- * preselector's prompt.
- */
-export const preselectInput = (catalog, prompt, maxPromptChars = PRESELECT_PROMPT_CHARS) => `# Tool catalogue\n\n${catalogList(catalog)}\n\n# Request\n\n${prompt.slice(0, maxPromptChars)}`;
-/**
- * Resolves a preselection against the catalogue: unknown names dropped, count capped.
- *
- * @param names What the preselector replied: `{ tools: [...] }` as `PRESELECT_SCHEMA` has it, or
- * the bare array an older prompt asked for. Unvalidated: anything else gives none, and entries
- * that are not strings are dropped.
- * @param catalog The servers to resolve against.
- * @param maxPerLoad The most to keep, defaulting to `MAX_PER_LOAD`. The same number
- * `preselectSystem` was given, or the model is being held to a cap it was never told about.
- */
-export function preselection(names, catalog, maxPerLoad = MAX_PER_LOAD) {
-    const list = names && typeof names === "object" && !Array.isArray(names)
-        ? names.tools
-        : names;
-    if (!Array.isArray(list))
-        return [];
-    const wanted = list.filter((name) => typeof name === "string");
-    return expandNames(wanted, catalog, maxPerLoad).matched.slice(0, maxPerLoad);
-}
-/**
- * Saturation and length normalisation for the BM25 score. Robertson's usual values.
- *
- * Nothing here is tuned for this corpus, because tuning them against a catalogue of forty short
- * documents would be fitting noise. `dropoff` and `minScore` are the knobs worth turning.
- */
-const BM25_K1 = 1.2;
-const BM25_B = 0.75;
-/**
- * The least a best match may score and still be acted on without a model.
- *
- * A BM25 score, so it is read against the shape of the corpus rather than as a percentage: a
- * query term carried by half the catalogue is worth about 0.7, and one carried by a single tool
- * about 3. One at this floor is therefore "something more distinctive than a word every other
- * tool uses", which is the weakest evidence worth skipping a round trip on.
- *
- * A term is distinctive only against other terms, so a catalogue of three or four tools rarely
- * clears it. That is the right answer rather than a gap: a catalogue that small is not costing
- * enough tokens to be worth choosing from in the first place.
- */
-export const KEYWORD_MIN_SCORE = 1;
-/**
- * How far the best unpicked tool must fall below the last picked one for the cut to count clean.
- *
- * Half. The cap is the only reason a hit is dropped, so a hit just underneath it scoring nearly
- * as much as one just above means the ranking chose arbitrarily, which is exactly the case a
- * model should be spent on.
- */
-export const KEYWORD_DROPOFF = 0.5;
-/**
- * English function words, dropped before matching.
- *
- * The inverse document frequency is supposed to make this unnecessary, and over a real corpus it
- * would: a word carried by every document is worth nothing. But a tool catalogue is twenty
- * one-line descriptions, and at that size "for" or "on" is rare by accident — it lands in one
- * description, scores as the most distinctive term in the query, and a request that says "for me"
- * is answered with whichever tool happened to use the word. Only closure-class words are here;
- * "list", "get", "run" and "show" are what tools are called and stay.
- */
-const NOISE = new Set(("about all also am an and any are as at be been being but by can could do does for from had " +
-    "has have how if in into is it its just me more most my no not of on or other our out over " +
-    "please should so some such than that the their them then there these they this to too up us " +
-    "very was we were what when where which who will with would you your").split(" "));
-/**
- * A text as the matcher reads it: lowercase words, `server__tool_name` and camelCase split apart.
- *
- * Plurals are folded, crudely, by dropping a trailing `s`: a request says "read the files" and
- * the tool is called `read_file`, and without this the two do not meet. Nothing else is stemmed —
- * a real stemmer is a table of English morphology, and this is matching identifiers.
- */
-const terms = (text) => text
-    .replace(/([a-z0-9])([A-Z])/g, "$1 $2")
-    .toLowerCase()
-    .split(/[^a-z0-9]+/)
-    .filter((word) => word.length > 1 && !NOISE.has(word))
-    .map((word) => word.length > 3 && word.endsWith("s") && !word.endsWith("ss") ? word.slice(0, -1) : word);
-/**
- * The tools a request's own words point at, ranked, and whether they point clearly enough.
- *
- * A preselection call costs a round trip to a model that is being asked to do term matching, and
- * on a local box that is seconds before the run has started. For a catalogue of a few dozen tools
- * the words usually decide it: a request that says "commit" and a tool called `git__commit` need
- * no reasoning to connect.
- *
- * BM25 rather than counting shared words, because the ranking has to survive the words every tool
- * uses. "list", "get" and "file" are in half the descriptions in a real catalogue, and a plain
- * overlap count hands the top of the ranking to whichever tool has the longest description. The
- * inverse document frequency makes a term worth what it distinguishes, and the length
- * normalisation stops a wordy description from outscoring the tool actually named.
- *
- * `confident` is what a caller acts on, and it is deliberately hard to earn: something more
- * distinctive than a word the whole catalogue shares has to have matched, and the tools left
- * unpicked have to score well below the ones picked. Anything else is ambiguous, and ambiguous is
- * what the model is for. Nothing matching is not confident either — the words cannot tell "this
- * request needs no tools" from "these words are not in the catalogue".
- *
- * @param catalog The servers to choose from. Each tool is matched on its name, its server's label
- * and its one-line description, which is everything the catalogue holds.
- * @param prompt The request being planned for. Only its head is read, as in `preselectInput`.
- * @param options The cap, the two confidence thresholds, and where the request is cut.
- */
-export function preselectByKeywords(catalog, prompt, { maxPerLoad = MAX_PER_LOAD, minScore = KEYWORD_MIN_SCORE, dropoff = KEYWORD_DROPOFF, maxPromptChars = PRESELECT_PROMPT_CHARS, } = {}) {
-    const empty = { names: [], confident: false, ranked: [] };
-    const docs = catalog.flatMap((server) => server.tools.map((tool) => ({
-        name: tool.name,
-        terms: terms(`${tool.name} ${server.label} ${tool.description}`),
-    })));
-    // A query term repeated in the request is not worth more than one said once: the request is
-    // prose about a task, not a document being matched against another document.
-    const query = new Set(terms(prompt.slice(0, maxPromptChars)));
-    if (!docs.length || !query.size)
-        return empty;
-    const length = docs.reduce((total, doc) => total + doc.terms.length, 0) / docs.length;
-    const documents = new Map();
-    for (const doc of docs)
-        for (const term of new Set(doc.terms))
-            documents.set(term, (documents.get(term) ?? 0) + 1);
-    const ranked = docs
-        .map((doc) => {
-        const counts = new Map();
-        for (const term of doc.terms)
-            counts.set(term, (counts.get(term) ?? 0) + 1);
-        let score = 0;
-        for (const term of query) {
-            const found = counts.get(term);
-            if (!found)
-                continue;
-            const held = documents.get(term) ?? 0;
-            const idf = Math.log(1 + (docs.length - held + 0.5) / (held + 0.5));
-            const norm = BM25_K1 * (1 - BM25_B + (BM25_B * doc.terms.length) / length);
-            score += (idf * found * (BM25_K1 + 1)) / (found + norm);
-        }
-        return { name: doc.name, score };
-    })
-        .filter((hit) => hit.score > 0)
-        // Ties break on the name, not on where the tool sat in the catalogue, so reconnecting a
-        // server in a different order does not change what a run opens with.
-        .sort((a, b) => b.score - a.score || a.name.localeCompare(b.name));
-    if (!ranked.length)
-        return empty;
-    const names = ranked.slice(0, maxPerLoad).map((hit) => hit.name);
-    const cut = ranked[names.length - 1].score;
-    const next = ranked[maxPerLoad]?.score ?? 0;
-    return { names, confident: ranked[0].score >= minScore && next <= dropoff * cut, ranked };
-}