@cubicecho/agent-core 2.18.1 → 2.20.0

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

@@ -15,14 +15,17 @@ The loop above a turn: send, run the tools the model asked for, send again, unti
 
 - `AgentLoopHooks` (type) — The hooks a loop runs around one question.
 - `AgentLoopOptions` (type) — What `runAgentLoop` takes.
+- `AgentLoopRequest` (type) — One step's request as `onRequest` is handed it: what the model is about to read.
 - `AgentLoopResult` (type) — What a finished loop hands back.
 - `buildBody` — The one place a streamed request's body is decided from a config and what the endpoint and the model have refused.
 - `preselect` — The tools a request is likely to need, picked by a small model before the run starts, or none.
 - `preview` — A long tool argument or result cut to what a watcher needs, with the full length said.
 - `resolveApiKey` — The key to send, where an endpoint may inherit one from the settings it overrides.
 - `runAgentLoop` — Runs a question to its answer: one `runTurn` per step, the tools it asks for between them, until a turn asks for none.
+- `StepWindow` (type) — How full the window is as a step is about to be sent, as `beforeStep` is told it.
 - `ToolCallOutcome` (type) — What one tool call did, in the order the model asked.
-- `ToolCallRequest` (type) — One call the model made, as `dispatch` is handed it.
+- `ToolCallRequest` (type) — One call the model made, as `dispatch` and `onToolCall` are handed it.
+- `ToolCallResult` (type) — One call's whole answer, as `onToolResult` is handed it.
 
 ### calibration
 
@@ -163,6 +166,19 @@ Lifecycle hooks, from the host's side: what a session looks like to them, where
 - `untrusted` — Fences text nobody trusted — a fetched page, an email, a submitted card, a tool result — so the model can see where it starts and ends and read it as data rather than as instructions.
 - `withContext` — The request, with the hooks' context added to this turn's question.
 
+### ledger
+
+What stretches of a transcript cost, read off the prompt counts the server already reported.
+
+- `estimateFrom` — A per-message cost for `planCompaction`'s `estimate`: the measured share where the ledger covers the message, the calibrated estimate where it does not.
+- `LedgerEntry` (type) — One request's reported prompt, and how far into the transcript that request reached.
+- `LedgerEstimateOptions` (type) — What `tokensBetween` and `estimateFrom` take besides the ledger and the transcript.
+- `LedgerRequest` (type) — What `recordRequest` needs to know of one request.
+- `rebaseLedger` — The ledger for a transcript that has been rewritten, keeping the boundaries the rewrite left standing.
+- `recordRequest` — The ledger with one more request on it, in the epoch the request before it says it belongs to.
+- `TokenLedger` (type) — A transcript's entries in the order their requests were sent, which is also by `through`.
+- `tokensBetween` — What the messages from `from` up to, not including, `to` cost the window, measured where the ledger can say and estimated where it cannot.
+
 ### reset
 
 - `resetAll` — Forgets everything this package remembers between calls.
@@ -300,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.
@@ -318,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.18.1",
+  "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",