@cubicecho/agent-core 4.16.0 → 4.17.0

package/README.md

@@ -470,6 +470,7 @@ const { turn, messages, usage, loaded } = await runAgentLoop({
   messages: history,              // ending in the question; not written to
   tools,                          // every tool the run may reach
   catalog,                        // the same, name-only, for on-demand and proxied loading
+  hostTools,                      // the host's own, declared in every mode and never catalogued
   serverInstructions: true,       // the catalogue's `instructions` after `system`; off by default
   preselected,                    // from `preselect`, if a small model chose
   dispatch: ({ name, args }, signal) => pool.call(name, args, signal),
@@ -688,6 +689,27 @@ a `tool-call` and a `tool-result` event, told to `onToolCall` and `onToolResult`
 id is numbered by where the call lands in the transcript, so two questions do not share one. A name
 with no definition in `tools`, or outside the catalogue, is left out, and none left is no exchange.
 
+A host with tools of its own — a question for a person, a resource read — passes them as
+`hostTools`, and they are declared on every step in every mode: after `PROXY_TOOLS` proxied, after
+`load_tools` and ahead of anything loaded on demand, after `tools` in eager mode, and after the
+shortlist on a preselected first step. They reach `dispatch` like any other call and are kept out
+of discovery: taken out of `catalog`, `loaded` and `preselected` before the run starts, never
+counted as a load, and a `call_tool` naming one is refused with a pointer to call it directly.
+Proxied and eager, the array is one set for the whole run, so the cache holds whatever `toolOrder`
+does with it; on demand, `toolOrder: false` keeps them in the prefix every load appends after.
+
+```ts
+await runAgentLoop({
+  config: { ...config, toolDiscovery: "proxy" },
+  messages: history,
+  tools: pool.tools(),
+  catalog: pool.catalog(),
+  hostTools: [ASK_PERSON_DEFINITION], // declared beside load_tools and call_tool, on every step
+  dispatch: (call, signal) =>
+    call.name === ASK_PERSON ? ask(call.args) : pool.call(call.name, call.args, signal),
+});
+```
+
 ### What the servers said on the way
 
 A server can log while a call runs — a warning that the cache was stale, an error it recovered

package/dist/run/agent-loop.d.ts

@@ -152,6 +152,23 @@ export interface AgentLoopOptions {
      * loaded so far, by name; proxied mode declares none, and answers a load with them instead.
      */
     tools?: OpenAI.ChatCompletionTool[];
+    /**
+     * The host's own tools — a question for a person, a resource read — declared on every step in
+     * every discovery mode and dispatched like any other call, but never catalogued, loaded, or
+     * reached through `call_tool`.
+     *
+     * @remarks
+     * Each sits after the loop's own definitions: after `PROXY_TOOLS` proxied, after `load_tools`
+     * and ahead of anything loaded on demand, after `tools` in eager mode, and after the shortlist
+     * on a preselected first step; `toolOrder` then orders the array as it always does. Proxied and
+     * eager, the array is one set for the whole run, so the cache holds in either order; on demand,
+     * `toolOrder: false` keeps them in the prefix every load appends after.
+     *
+     * A name of one is taken out of `catalog`, `loaded` and `preselected` before the run starts, is
+     * never counted as a load, and is declared once where `tools` or the loop has it too. A
+     * `call_tool` naming one is refused with a pointer to call it directly.
+     */
+    hostTools?: OpenAI.ChatCompletionTool[];
     /**
      * The same tools as a name-only catalogue. On-demand and proxied modes need it, and are eager
      * without it.
@@ -595,6 +612,8 @@ export interface AgentLoopResult {
  * tool array to go into, so it is written into the transcript as a `load_tools` exchange after
  * the question. `call_tool` is honoured on demand too, unless the host has a tool of that name —
  * a session switched out of proxied mode still has it in its history, and the model copies it.
+ * The host's own `hostTools` are declared beside whatever the mode sends, in every mode, and are
+ * never catalogued.
  *
  * Neither side task is run unless asked for. `preselect` has the loop make the preselection and
  * `compact` has it fold the transcript, each by the task `config.tasks` carries for it and on

package/dist/run/agent-loop.js

@@ -112,6 +112,8 @@ function cacheDiagnosis(previous, next, usage) {
  * tool array to go into, so it is written into the transcript as a `load_tools` exchange after
  * the question. `call_tool` is honoured on demand too, unless the host has a tool of that name —
  * a session switched out of proxied mode still has it in its history, and the model copies it.
+ * The host's own `hostTools` are declared beside whatever the mode sends, in every mode, and are
+ * never catalogued.
  *
  * Neither side task is run unless asked for. `preselect` has the loop make the preselection and
  * `compact` has it fold the transcript, each by the task `config.tasks` carries for it and on
@@ -133,9 +135,10 @@ export async function runAgentLoop(options) {
         }),
     };
     let result;
+    const apart = hostToolsApart(options);
     try {
-        pin = await pinSession(options);
-        result = await runSteps(options, standing, pin);
+        pin = await pinSession(apart);
+        result = await runSteps(apart, standing, pin);
     }
     catch (error) {
         // Wrapped rather than annotated: an abort's reason is one object shared by every run under
@@ -399,6 +402,43 @@ function recorder(heard) {
     };
     return { recorded, onEvent };
 }
+/**
+ * The names of the host's own tools.
+ *
+ * @param [tools] - The host's definitions. One that is not a function has no name, and is left out.
+ * @returns A new set, empty where there are none.
+ */
+const hostToolNames = (tools = []) => new Set(tools.flatMap((tool) => toolName(tool) ?? []));
+/**
+ * The run's options with the host's own tools kept out of discovery: off the catalogue, and out of
+ * what was carried and what was picked.
+ *
+ * @param options - What `runAgentLoop` was given. Not written to.
+ * @returns `options` itself where there are no host tools, and otherwise a copy with `catalog`,
+ * `loaded` and `preselected` filtered, a server that offers none of them kept as it was.
+ *
+ * @remarks
+ * Done once, here, so that preselection, `load_tools`, `call_tool` and the catalogue prompt all
+ * read one catalogue, and a host tool is never loadable however a name of one reaches the loop.
+ */
+function hostToolsApart(options) {
+    const own = hostToolNames(options.hostTools);
+    if (own.size === 0) {
+        return options;
+    }
+    const isCatalogued = (name) => own.has(name) === false;
+    const { catalog, loaded, preselected } = options;
+    const apart = (server) => server.tools.every((entry) => isCatalogued(entry.name))
+        ? server
+        : { ...server, tools: server.tools.filter((entry) => isCatalogued(entry.name)) };
+    return {
+        ...options,
+        ...(catalog ? { catalog: catalog.map(apart) } : {}),
+        ...(loaded ? { loaded: [...loaded].filter(isCatalogued) } : {}),
+        // Undefined stays undefined: an empty shortlist is a host saying it has already decided.
+        ...(preselected ? { preselected: preselected.filter(isCatalogued) } : {}),
+    };
+}
 /** What opens the notice naming the loop's own picks, ahead of the names. */
 export const PRESELECTED_NOTICE = 'tools picked before the run: ';
 /**
@@ -570,11 +610,17 @@ async function runSteps(options, standing, pin) {
     const summarise = ownSummariser(options, notice);
     const used = new Set();
     const definitions = definitionsByName(tools);
+    // Each once, by name, so one given twice is declared once.
+    const hostTools = loadedTools([], options.hostTools ?? []);
+    const hostNames = hostToolNames(hostTools);
+    // After the head the mode declares, which a host tool of the same name does not displace.
+    const withHost = (head) => (hostTools.length ? loadedTools(head, hostTools) : head);
     // Looked through unless the host has a tool by that name, which is then the host's to answer.
-    const proxies = onDemand && !definitions.has(CALL_TOOL);
+    const proxies = onDemand && !definitions.has(CALL_TOOL) && !hostNames.has(CALL_TOOL);
     // What a call the model wrote as text may name: the host's tools, and the loop's own on demand.
     const recoverable = [
         ...tools.map(toolName).filter((name) => name !== undefined),
+        ...hostNames,
         ...(onDemand ? [LOAD_TOOLS, ...(proxies ? [CALL_TOOL] : [])] : []),
     ];
     // In the order the names are given, not the order of `tools`: `loaded` is a set, which iterates
@@ -626,6 +672,7 @@ async function runSteps(options, standing, pin) {
         proxied,
         proxies,
         definitions,
+        hostNames,
         loaded,
         loads,
         used,
@@ -691,15 +738,15 @@ async function runSteps(options, standing, pin) {
         // Ordered here rather than left to `buildBody`, so `names` below is what the request actually
         // declared — a diagnosis reading an order the server never saw calls an untouched tool array
         // `tools-changed`.
-        let offered = tools;
+        let offered = withHost(tools);
         if (routed) {
-            offered = byName(new Set(preselected));
+            offered = withHost(byName(new Set(preselected)));
         }
         else if (proxied) {
-            offered = [...PROXY_TOOLS];
+            offered = withHost([...PROXY_TOOLS]);
         }
         else if (onDemand) {
-            offered = loadedTools([LOAD_TOOLS_DEFINITION], byName(loaded));
+            offered = loadedTools(withHost([LOAD_TOOLS_DEFINITION]), byName(loaded));
         }
         const declared = orderTools(offered, toolOrder);
         // Unmarked, so the system prompt is the same text on every step and a load does not throw
@@ -783,7 +830,7 @@ async function runSteps(options, standing, pin) {
         if (turn.finishReason === FinishReason.Length) {
             notice(`the model stopped at maxTokens (${config.maxTokens}); this turn is cut short`);
         }
-        const canRecover = recover && (tools.length > 0 || onDemand);
+        const canRecover = recover && (tools.length > 0 || hostTools.length > 0 || onDemand);
         const { calls, content } = turnCalls(turn, canRecover ? recoverable : undefined, notice);
         const shown = { ...turn, content, toolCalls: calls };
         onTurn?.(shown, step);

package/dist/run/run-calls.d.ts

@@ -86,6 +86,8 @@ export interface Calling {
     /** Whether a `call_tool` is looked through, which it is unless the host has a tool by that name. */
     proxies: boolean;
     definitions: ReadonlyMap<string, OpenAI.ChatCompletionTool>;
+    /** The host's own tools by name: declared on every step, and never reached through `call_tool`. */
+    hostNames: ReadonlySet<string>;
     loaded: Set<string>;
     loads: {
         toolsLoaded: number;

package/dist/run/run-calls.js

@@ -256,7 +256,12 @@ function prepare(run, entry) {
     // nothing a load could not, and the refusal is the call's answer.
     let inner = args ?? {};
     let refused;
-    if (proxy && args) {
+    if (proxy && args && run.hostNames.has(name)) {
+        // Declared already, so the model is pointed at the call it can make rather than told the
+        // tool does not exist.
+        refused = { error: new Error(`${name} is not in the catalogue; call it directly, not through ${CALL_TOOL}.`) };
+    }
+    else if (proxy && args) {
         try {
             inner = proxiedCall(args, catalog).input;
         }

package/package.json

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