@cubicecho/agent-core 2.8.0 → 2.9.0

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 —
@@ -501,6 +504,18 @@ Either one given something that is not a number above zero keeps what was there,
 `configureEvents` does, so a `0` threaded through for "no opinion" does not switch recall off.
 `resetHooks` (and `resetAll`) puts the default back.
 
+The preface said above the blocks moves the same way. `HOOK_PREFACE` names no host, so a host that
+wants its own name says so once with `configureHooks({ preface })`, and a `preface` passed to
+`withContext` (or on `runAgentLoop`'s `hooks`) wins over it for one request. An empty string is a
+preface of nothing — the blocks lead the question on their own, with no blank line above them —
+and anything that is not a string keeps what was there:
+
+```ts
+configureHooks({ preface: "Added by my-host's hooks — background, not the user's words:" });
+const request = withContext(messages, messages.length - 1, gathered.context); // says it
+withContext(messages, messages.length - 1, gathered.context, ""); // says nothing
+```
+
 Neither function rejects. A hook failing is an outcome, and a runner that throws outright is
 noted once for its event and costs only that event's context. `notify` takes no signal: a reader
 who leaves once the turn is answered has not asked for it not to be remembered.

package/dist/agent-loop.d.ts

@@ -105,7 +105,7 @@ export interface AgentLoopHooks {
     events?: readonly HookEvent[];
     /** The shared context budget. Absent is `configureHooks`'s. */
     maxTokens?: number;
-    /** Said above the context blocks. Absent is `HOOK_PREFACE`. */
+    /** Said above the context blocks. Absent is `configureHooks`'s; empty is none. */
     preface?: string;
     /** Hears each note, from before the request and from `afterTurn`. */
     onNote?: (note: HookNote) => void;
@@ -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/hooks.d.ts

@@ -129,6 +129,12 @@ export interface Gathered {
  * `configureHooks` moves it for a process, and `gather` and `assembleContext` for one request.
  */
 export declare const HOOK_CONTEXT_TOKENS = 2000;
+/**
+ * Said once, above the blocks, so the model reads them as background rather than instructions.
+ * Names no host; `configureHooks` sets another for a process that wants to, and `withContext`
+ * for one request.
+ */
+export declare const HOOK_PREFACE: string;
 /** What hooks are held to across a process. Every field optional; see `configureHooks`. */
 export interface HookOptions {
     /**
@@ -136,31 +142,34 @@ export interface HookOptions {
      * held to its own `maxTokens` inside it.
      */
     contextTokens?: number;
+    /**
+     * Said above the context blocks, when a call does not give its own. Empty says nothing, and the
+     * blocks lead the question on their own.
+     */
+    preface?: string;
 }
 /**
  * Changes what hooks are held to, for a process whose windows are not the size these defaults
- * were chosen for.
+ * were chosen for, or whose host wants its own name above the context.
  *
- * Module-level for the same reason `configureEvents` is: a budget is a deployment's setting, said
- * once at startup. A caller that sizes it per model or per agent — a 128k window can afford more
- * recall than an 8k one — passes `maxTokens` to `gather` instead, which wins over this.
+ * Module-level for the same reason `configureEvents` is: a budget and a preface are a deployment's
+ * settings, said once at startup. A caller that sizes the budget per model or per agent — a 128k
+ * window can afford more recall than an 8k one — passes `maxTokens` to `gather` instead, and a
+ * `preface` passed to `withContext` or `runAgentLoop`'s hooks wins over this one the same way.
  *
- * @param options The limits to change. A field left out — or given anything that is not a number
- * above zero — keeps what it has, so a half-built config narrows nothing. `Infinity` is a number
- * above zero, and lifts the shared budget entirely.
+ * @param options The settings to change. A field left out keeps what it has, and so does one given
+ * the wrong kind of value — `contextTokens` anything but a number above zero, `preface` anything
+ * but a string — so a half-built config narrows nothing. `Infinity` is a number above zero, and
+ * lifts the shared budget entirely. An empty `preface` is a string, and turns the preface off.
  * @returns Everything in force afterwards, including what this call did not change.
  */
 export declare function configureHooks(options?: HookOptions): Required<HookOptions>;
 /**
- * Test seam: puts `configureHooks` back to the defaults, so one test's budget is not the next's.
+ * Test seam: puts `configureHooks` back to the defaults, so one test's budget or preface is not the
+ * next's.
  * `resetAll` calls it.
  */
 export declare const resetHooks: () => void;
-/**
- * Said once, above the blocks, so the model reads them as background rather than instructions.
- * Names no host; `withContext` takes another for one that wants to.
- */
-export declare const HOOK_PREFACE: string;
 /**
  * Builds the context a set of outcomes adds and the notes that go with it.
  *
@@ -192,7 +201,8 @@ export declare function assembleContext(outcomes: readonly HookOutcome[], maxTok
  * session once a compaction has folded the head into a summary. Anything but a user message there
  * leaves the request as it was.
  * @param context What `assembleContext` built. Empty returns `history` itself.
- * @param preface Said above the blocks. Defaults to `HOOK_PREFACE`.
+ * @param preface Said above the blocks. Absent is what `configureHooks` last set — `HOOK_PREFACE`
+ * unless something moved it. Empty says nothing, rather than leaving a blank line where it was.
  * @returns `history` when there was nothing to add or nowhere to add it, otherwise a new array.
  */
 export declare function withContext(history: OpenAI.ChatCompletionMessageParam[], index: number, context: string, preface?: string): OpenAI.ChatCompletionMessageParam[];

package/dist/hooks.js

@@ -23,49 +23,58 @@ export const INJECT_EVENTS = new Set(["sessionStart", "beforeTurn"]);
  * `configureHooks` moves it for a process, and `gather` and `assembleContext` for one request.
  */
 export const HOOK_CONTEXT_TOKENS = 2000;
-/** The numbers this module was written with. */
-const HOOK_DEFAULTS = { contextTokens: HOOK_CONTEXT_TOKENS };
+/**
+ * Said once, above the blocks, so the model reads them as background rather than instructions.
+ * Names no host; `configureHooks` sets another for a process that wants to, and `withContext`
+ * for one request.
+ */
+export const HOOK_PREFACE = "The <context> blocks below were added for this message by the host's hooks. They are " +
+    "background the user did not write and may not be relevant. The user's message follows them.";
+/** The settings this module was written with. */
+const HOOK_DEFAULTS = {
+    contextTokens: HOOK_CONTEXT_TOKENS,
+    preface: HOOK_PREFACE,
+};
 /** What is in force now. Read where it is used, so a change applies from the next request. */
-let hookLimits = { ...HOOK_DEFAULTS };
+let hookSettings = { ...HOOK_DEFAULTS };
 /**
  * Changes what hooks are held to, for a process whose windows are not the size these defaults
- * were chosen for.
+ * were chosen for, or whose host wants its own name above the context.
  *
- * Module-level for the same reason `configureEvents` is: a budget is a deployment's setting, said
- * once at startup. A caller that sizes it per model or per agent — a 128k window can afford more
- * recall than an 8k one — passes `maxTokens` to `gather` instead, which wins over this.
+ * Module-level for the same reason `configureEvents` is: a budget and a preface are a deployment's
+ * settings, said once at startup. A caller that sizes the budget per model or per agent — a 128k
+ * window can afford more recall than an 8k one — passes `maxTokens` to `gather` instead, and a
+ * `preface` passed to `withContext` or `runAgentLoop`'s hooks wins over this one the same way.
  *
- * @param options The limits to change. A field left out — or given anything that is not a number
- * above zero — keeps what it has, so a half-built config narrows nothing. `Infinity` is a number
- * above zero, and lifts the shared budget entirely.
+ * @param options The settings to change. A field left out keeps what it has, and so does one given
+ * the wrong kind of value — `contextTokens` anything but a number above zero, `preface` anything
+ * but a string — so a half-built config narrows nothing. `Infinity` is a number above zero, and
+ * lifts the shared budget entirely. An empty `preface` is a string, and turns the preface off.
  * @returns Everything in force afterwards, including what this call did not change.
  */
 export function configureHooks(options = {}) {
-    for (const [name, value] of Object.entries(options)) {
-        if (typeof value === "number" && value > 0)
-            hookLimits[name] = value;
+    const { contextTokens, preface } = options;
+    if (typeof contextTokens === "number" && contextTokens > 0) {
+        hookSettings.contextTokens = contextTokens;
     }
-    return { ...hookLimits };
+    if (typeof preface === "string")
+        hookSettings.preface = preface;
+    return { ...hookSettings };
 }
 /**
- * Test seam: puts `configureHooks` back to the defaults, so one test's budget is not the next's.
+ * Test seam: puts `configureHooks` back to the defaults, so one test's budget or preface is not the
+ * next's.
  * `resetAll` calls it.
  */
 export const resetHooks = () => {
-    hookLimits = { ...HOOK_DEFAULTS };
+    hookSettings = { ...HOOK_DEFAULTS };
 };
 /**
  * The budget a call is held to: its own when it gave a usable one, the process's otherwise. The
  * same rule `configureHooks` applies, so a `0` threaded through for "no opinion" does not quietly
  * turn every hook's context off.
  */
-const budget = (given) => typeof given === "number" && given > 0 ? given : hookLimits.contextTokens;
-/**
- * Said once, above the blocks, so the model reads them as background rather than instructions.
- * Names no host; `withContext` takes another for one that wants to.
- */
-export const HOOK_PREFACE = "The <context> blocks below were added for this message by the host's hooks. They are " +
-    "background the user did not write and may not be relevant. The user's message follows them.";
+const budget = (given) => typeof given === "number" && given > 0 ? given : hookSettings.contextTokens;
 const attribute = (text) => text.replaceAll("&", "&amp;").replaceAll('"', "&quot;").replaceAll("<", "&lt;");
 /**
  * Builds the context a set of outcomes adds and the notes that go with it.
@@ -124,14 +133,15 @@ export function assembleContext(outcomes, maxTokens) {
  * session once a compaction has folded the head into a summary. Anything but a user message there
  * leaves the request as it was.
  * @param context What `assembleContext` built. Empty returns `history` itself.
- * @param preface Said above the blocks. Defaults to `HOOK_PREFACE`.
+ * @param preface Said above the blocks. Absent is what `configureHooks` last set — `HOOK_PREFACE`
+ * unless something moved it. Empty says nothing, rather than leaving a blank line where it was.
  * @returns `history` when there was nothing to add or nowhere to add it, otherwise a new array.
  */
-export function withContext(history, index, context, preface = HOOK_PREFACE) {
+export function withContext(history, index, context, preface = hookSettings.preface) {
     const message = history[index];
     if (!context || message?.role !== "user")
         return history;
-    const lead = `${preface}\n\n${context}\n\n`;
+    const lead = preface ? `${preface}\n\n${context}\n\n` : `${context}\n\n`;
     const content = typeof message.content === "string"
         ? `${lead}${message.content}`
         : [{ type: "text", text: lead }, ...message.content];

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

@@ -4,9 +4,9 @@
  * Five modules here keep state for the life of the process, each for a good reason and each
  * with its own seam: the pooled clients and their model listings, the endpoints that turned
  * out not to take `stream_options` or a grammar, the models that refused the no-thinking
- * hints, the event bus, and the hooks' configured budget. `resetClients`, `resetCapabilities`,
- * `resetHints`, `resetEvents` and `resetHooks` stay exported, because a test that means to clear
- * one thing should say so.
+ * hints, the event bus, and the hooks' configured budget and preface. `resetClients`,
+ * `resetCapabilities`, `resetHints`, `resetEvents` and `resetHooks` stay exported, because a
+ * test that means to clear one thing should say so.
  *
  * This is for the other case, which is every teardown. What they hold is *latched
  * refusals* — a fact one test taught the process about an endpoint, still true as far as the

package/dist/reset.js

@@ -9,9 +9,9 @@ import { resetHints } from "./side-task.js";
  * Five modules here keep state for the life of the process, each for a good reason and each
  * with its own seam: the pooled clients and their model listings, the endpoints that turned
  * out not to take `stream_options` or a grammar, the models that refused the no-thinking
- * hints, the event bus, and the hooks' configured budget. `resetClients`, `resetCapabilities`,
- * `resetHints`, `resetEvents` and `resetHooks` stay exported, because a test that means to clear
- * one thing should say so.
+ * hints, the event bus, and the hooks' configured budget and preface. `resetClients`,
+ * `resetCapabilities`, `resetHints`, `resetEvents` and `resetHooks` stay exported, because a
+ * test that means to clear one thing should say so.
  *
  * This is for the other case, which is every teardown. What they hold is *latched
  * refusals* — a fact one test taught the process about an endpoint, still true as far as the

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

@@ -108,7 +108,7 @@ What a run is doing, while it is doing it.
 Lifecycle hooks, from the host's side: what a session looks like to them, where their context lands in a request, and what is said about each one.
 
 - `assembleContext` — Builds the context a set of outcomes adds and the notes that go with it.
-- `configureHooks` — Changes what hooks are held to, for a process whose windows are not the size these defaults were chosen for.
+- `configureHooks` — Changes what hooks are held to, for a process whose windows are not the size these defaults were chosen for, or whose host wants its own name above the context.
 - `Gathered` (type) — The context a set of outcomes adds to a request, and a note for each hook worth mentioning.
 - `gather` — Runs the hooks ahead of a request and builds what they add to it.
 - `HOOK_CONTEXT_TOKENS` — The most context all of a request's hooks add between them by default, in estimated tokens.
@@ -123,7 +123,7 @@ Lifecycle hooks, from the host's side: what a session looks like to them, where
 - `HookRunner` (type) — Runs one event's hooks.
 - `INJECT_EVENTS` — The events whose hooks run before a request, and so the only ones whose output can reach it.
 - `notify` — Runs the hooks for an event that reads what happened and adds nothing to a request.
-- `resetHooks` — Test seam: puts `configureHooks` back to the defaults, so one test's budget is not the next's.
+- `resetHooks` — Test seam: puts `configureHooks` back to the defaults, so one test's budget or preface is not the next's.
 - `turnIndex` — Which turn of a session begins at a point, from 0: the user messages ahead of it.
 - `turnMessages` — A stretch of a transcript as a hook reads it: what the user and the assistant said, and nothing else.
 - `UNTRUSTED_PREFACE` — One sentence for a system prompt, saying what an `untrusted` block is.
@@ -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.9.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",