@cubicecho/agent-core 2.8.0 → 2.8.1

package/README.md

@@ -307,7 +307,10 @@ Found calls are run as `call_recovered_0` onward, the text is what is left, `onT
 result see the turn that way, and a notice says so, since the real fix is the server's parser.
 
 With `toolDiscovery: "ondemand"` and a catalogue, the request declares `load_tools` and what has
-been loaded, and the catalogue rides on the system prompt marked with what is. A model that calls
+been loaded, appended in the order it was loaded, and the catalogue rides on the system prompt
+unmarked, the same text on every step. Marking loads there rewrote the head of the prompt and lost
+the prompt cache for the whole transcript on each one; a model that loads a tool twice is told in
+the `load_tools` result that it already has it. A model that calls
 a catalogued tool without loading it first is right about what it wants, and gets it loaded and
 run. A preselection shapes the first step alone: those tools, no catalogue, no `load_tools` —
 a model with the menu still in front of it shops, reloading what it has or picking a sibling —

package/dist/agent-loop.d.ts

@@ -192,9 +192,10 @@ export interface AgentLoopResult {
  * whatever `runTurn` throws — `ContextOverflow` among them, however it was found out.
  *
  * On-demand loading is handled here, `load_tools` and all: the catalogue rides on the system
- * prompt and marks what is loaded, a catalogued tool called without being loaded is loaded and
- * run rather than refused, and a preselection shapes the first step. A turn cut off at
- * `maxTokens` is said so as a notice, because it otherwise reads exactly like a finished one.
+ * prompt unchanged from step to step, loaded tools are appended to the tool array in load order,
+ * a catalogued tool called without being loaded is loaded and run rather than refused, and a
+ * preselection shapes the first step. A turn cut off at `maxTokens` is said so as a notice,
+ * because it otherwise reads exactly like a finished one.
  *
  * @param options The config, transcript, tools and dispatcher, plus the optional hooks, events
  * and cancellation. See `AgentLoopOptions`.

package/dist/agent-loop.js

@@ -6,7 +6,7 @@ import { runTurn } from "./run-turn.js";
 import { relaxTools, sanitizeTools } from "./schema-compat.js";
 import { askJson, tryAsk } from "./side-task.js";
 import { parseToolArguments, recoverToolCalls } from "./tool-calls.js";
-import { catalogPrompt, expandNames, inCatalog, LOAD_TOOLS, LOAD_TOOLS_DEFINITION, loadResult, MAX_PER_LOAD, PRESELECT_SCHEMA, preselectInput, preselection, preselectSystem, requestedNames, } from "./tool-loading.js";
+import { catalogPrompt, expandNames, inCatalog, LOAD_TOOLS, LOAD_TOOLS_DEFINITION, loadedTools, loadResult, MAX_PER_LOAD, PRESELECT_SCHEMA, preselectInput, preselection, preselectSystem, requestedNames, } from "./tool-loading.js";
 /**
  * The loop above a turn: send, run the tools the model asked for, send again, until it stops
  * asking.
@@ -130,9 +130,10 @@ const accumulate = (total, turn) => {
  * whatever `runTurn` throws — `ContextOverflow` among them, however it was found out.
  *
  * On-demand loading is handled here, `load_tools` and all: the catalogue rides on the system
- * prompt and marks what is loaded, a catalogued tool called without being loaded is loaded and
- * run rather than refused, and a preselection shapes the first step. A turn cut off at
- * `maxTokens` is said so as a notice, because it otherwise reads exactly like a finished one.
+ * prompt unchanged from step to step, loaded tools are appended to the tool array in load order,
+ * a catalogued tool called without being loaded is loaded and run rather than refused, and a
+ * preselection shapes the first step. A turn cut off at `maxTokens` is said so as a notice,
+ * because it otherwise reads exactly like a finished one.
  *
  * @param options The config, transcript, tools and dispatcher, plus the optional hooks, events
  * and cancellation. See `AgentLoopOptions`.
@@ -150,7 +151,15 @@ export async function runAgentLoop(options) {
     for (const name of preselected)
         loaded.add(name);
     const used = new Set();
-    const byName = (names) => tools.filter((tool) => tool.type === "function" && names.has(tool.function.name));
+    const definitions = new Map();
+    for (const tool of tools) {
+        if (tool.type === "function" && !definitions.has(tool.function.name)) {
+            definitions.set(tool.function.name, tool);
+        }
+    }
+    // In the order the names are given, not the order of `tools`: `loaded` is a set, which iterates
+    // in the order things were added, so a load appends and never reshuffles what went before.
+    const byName = (names) => [...names].flatMap((name) => definitions.get(name) ?? []);
     let messages = [...options.messages];
     // Held by reference rather than by index, so a `beforeStep` that folds the head into a summary
     // moves the question without losing it — and one that summarises the question away takes the
@@ -176,9 +185,12 @@ export async function runAgentLoop(options) {
         const declared = routed
             ? byName(new Set(preselected))
             : onDemand
-                ? [LOAD_TOOLS_DEFINITION, ...byName(loaded)]
+                ? loadedTools([LOAD_TOOLS_DEFINITION], byName(loaded))
                 : tools;
-        const prompt = onDemand && !routed ? `${system}\n\n${catalogPrompt(catalog, loaded)}`.trim() : system;
+        // Unmarked, so the system prompt is the same text on every step and a load does not throw
+        // away the cache for the whole transcript. What is loaded is said in `declared` and in the
+        // `load_tools` result instead. The preselected first step is the one exception, by design.
+        const prompt = onDemand && !routed ? `${system}\n\n${catalogPrompt(catalog)}`.trim() : system;
         const request = [
             ...(prompt ? [{ role: "system", content: prompt }] : []),
             ...withContext(messages, question ? messages.indexOf(question) : -1, gathered.context, hooks?.preface),
@@ -293,9 +305,9 @@ export async function runAgentLoop(options) {
                     throw unreadable;
                 if (onDemand && name === LOAD_TOOLS) {
                     const resolved = expandNames(requestedNames(args), catalog);
+                    content = loadResult(resolved, catalog, loaded);
                     for (const hit of resolved.matched)
                         loaded.add(hit);
-                    content = loadResult(resolved, catalog);
                     ok = resolved.matched.length > 0;
                 }
                 else {

package/dist/index.d.ts

@@ -28,4 +28,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, LOAD_TOOLS, LOAD_TOOLS_DEFINITION, loadResult, MAX_CARRIED, MAX_PER_LOAD, PRESELECT_SCHEMA, PRESELECT_SYSTEM, preselectInput, preselection, preselectSystem, requestedNames, } from "./tool-loading.ts";
+export { carryOver, catalogList, catalogPrompt, expandNames, inCatalog, LOAD_TOOLS, LOAD_TOOLS_DEFINITION, loadedTools, loadResult, MAX_CARRIED, MAX_PER_LOAD, PRESELECT_SCHEMA, PRESELECT_SYSTEM, preselectInput, preselection, preselectSystem, requestedNames, } from "./tool-loading.ts";

package/dist/index.js

@@ -26,4 +26,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, LOAD_TOOLS, LOAD_TOOLS_DEFINITION, loadResult, MAX_CARRIED, MAX_PER_LOAD, PRESELECT_SCHEMA, PRESELECT_SYSTEM, preselectInput, preselection, preselectSystem, requestedNames, } from "./tool-loading.js";
+export { carryOver, catalogList, catalogPrompt, expandNames, inCatalog, LOAD_TOOLS, LOAD_TOOLS_DEFINITION, loadedTools, loadResult, MAX_CARRIED, MAX_PER_LOAD, PRESELECT_SCHEMA, PRESELECT_SYSTEM, preselectInput, preselection, preselectSystem, requestedNames, } from "./tool-loading.js";

package/dist/tool-loading.d.ts

@@ -23,28 +23,49 @@ export declare const LOAD_TOOLS = "load_tools";
  */
 export declare const LOAD_TOOLS_DEFINITION: OpenAI.ChatCompletionTool;
 /**
- * The catalogue as a plain grouped listing of names, loaded ones marked.
+ * The catalogue as a plain grouped listing of names, loaded ones marked if asked.
  *
  * 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 already loaded, marked in the listing rather than removed from it.
+ * @param loaded Names to mark `(loaded)` rather than remove. Absent marks nothing, which keeps the
+ * listing the same text for the whole run.
  */
 export declare function catalogList(catalog: CatalogServer[], loaded?: ReadonlySet<string>): string;
 /**
  * The catalogue block appended to the system prompt. Names only — descriptions arrive on load.
  *
- * Loaded tools stay in the list, marked. Removing them reads as the tool having vanished the
- * moment 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.
+ * `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
+ * the prefix instead: in the tool array, appended in load order (`loadedTools`), and in the
+ * `load_tools` result, which answers a repeat load with "already loaded" (`loadResult`).
+ *
+ * Loaded tools are never removed from the list. That reads as the tool having vanished the moment
+ * 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 already loaded, marked in the listing.
+ * @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 declare function catalogPrompt(catalog: CatalogServer[], loaded?: ReadonlySet<string>): string;
+/**
+ * A tool array with newly loaded definitions appended, in the order they were loaded.
+ *
+ * Never re-sorted and never rebuilt from a set. A template renders the tool array into the
+ * prompt near its head, and a load that moved an earlier definition moved everything after it,
+ * so the cache was lost from there on every load; appended, the definitions already sent stay
+ * a prefix of the new array.
+ *
+ * @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 declare function loadedTools(previous: readonly OpenAI.ChatCompletionTool[], matched: readonly OpenAI.ChatCompletionTool[]): OpenAI.ChatCompletionTool[];
 /**
  * The most a single `load_tools` call may pull in.
  *
@@ -103,10 +124,15 @@ export declare function expandNames(requested: string[], catalog: CatalogServer[
 /**
  * What `load_tools` reports back: the descriptions, now that they are worth their tokens.
  *
+ * 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 declare function loadResult({ matched, unknown, overBroad, deferred, maxPerLoad }: ReturnType<typeof expandNames>, catalog: CatalogServer[]): string;
+export declare function loadResult({ matched, unknown, overBroad, deferred, maxPerLoad }: ReturnType<typeof expandNames>, catalog: CatalogServer[], loaded?: ReadonlySet<string>): string;
 /**
  * Whether the catalogue holds a tool by this name.
  *

package/dist/tool-loading.js

@@ -49,14 +49,15 @@ export const LOAD_TOOLS_DEFINITION = deepFreeze({
     },
 });
 /**
- * The catalogue as a plain grouped listing of names, loaded ones marked.
+ * The catalogue as a plain grouped listing of names, loaded ones marked if asked.
  *
  * 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 already loaded, marked in the listing rather than removed from it.
+ * @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
@@ -70,13 +71,20 @@ export function catalogList(catalog, loaded) {
 /**
  * The catalogue block appended to the system prompt. Names only — descriptions arrive on load.
  *
- * Loaded tools stay in the list, marked. Removing them reads as the tool having vanished the
- * moment 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.
+ * `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
+ * the prefix instead: in the tool array, appended in load order (`loadedTools`), and in the
+ * `load_tools` result, which answers a repeat load with "already loaded" (`loadResult`).
+ *
+ * Loaded tools are never removed from the list. That reads as the tool having vanished the moment
+ * 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 already loaded, marked in the listing.
+ * @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);
@@ -88,14 +96,39 @@ export function catalogPrompt(catalog, loaded) {
         "# 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 name",
-        "marked `(loaded)` is already in your tool list — 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.",
+        "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");
 }
 const flatten = (catalog) => catalog.flatMap((server) => server.tools);
+/**
+ * A tool array with newly loaded definitions appended, in the order they were loaded.
+ *
+ * Never re-sorted and never rebuilt from a set. A template renders the tool array into the
+ * prompt near its head, and a load that moved an earlier definition moved everything after it,
+ * so the cache was lost from there on every load; appended, the definitions already sent stay
+ * a prefix of the new array.
+ *
+ * @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 tools = [...previous];
+    for (const tool of matched) {
+        const name = nameOf(tool);
+        if (name !== undefined && declared.has(name))
+            continue;
+        declared.add(name);
+        tools.push(tool);
+    }
+    return tools;
+}
 /**
  * The most a single `load_tools` call may pull in.
  *
@@ -201,17 +234,29 @@ export function expandNames(requested, catalog, maxPerLoad = MAX_PER_LOAD) {
 /**
  * What `load_tools` reports back: the descriptions, now that they are worth their tokens.
  *
+ * 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) {
+export function loadResult({ matched, unknown, overBroad, deferred, maxPerLoad }, catalog, loaded) {
     const byName = new Map(flatten(catalog).map((tool) => [tool.name, tool.description]));
     const lines = [];
-    if (matched.length) {
-        lines.push(`Loaded ${matched.length} tool(s); they are callable on your next step.`, "");
-        for (const name of matched)
+    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());
     }
+    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("");

package/llms.txt

@@ -231,12 +231,13 @@ Reading what a model meant by a tool call when it did not write one cleanly.
 ### tool-loading
 
 - `carryOver` — The tools to start the next turn with: recently used, newest last, capped.
-- `catalogList` — The catalogue as a plain grouped listing of names, loaded ones marked.
+- `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.
 - `inCatalog` — Whether the catalogue holds a tool by this name.
 - `LOAD_TOOLS` — On-demand tool loading.
 - `LOAD_TOOLS_DEFINITION` — One object for the life of the process — the agent loop asks for it on every iteration.
+- `loadedTools` — A tool array with newly loaded definitions appended, in the order they were loaded.
 - `loadResult` — What `load_tools` reports back: the descriptions, now that they are worth their tokens.
 - `MAX_CARRIED` — The most a conversation carries between turns.
 - `MAX_PER_LOAD` — The most a single `load_tools` call may pull in.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cubicecho/agent-core",
-  "version": "2.8.0",
+  "version": "2.8.1",
   "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",