@cubicecho/agent-core 2.23.0 → 2.25.0

package/dist/tool-loading.d.ts

@@ -1,8 +1,9 @@
-import type OpenAI from "openai";
-import type { CatalogServer } from "./catalog.ts";
+import type OpenAI from 'openai';
+import type { CatalogServer } from './catalog.ts';
 /**
  * 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
@@ -17,6 +18,7 @@ export declare const LOAD_TOOLS = "load_tools";
 /**
  * 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.
@@ -25,18 +27,28 @@ export declare const LOAD_TOOLS_DEFINITION: OpenAI.ChatCompletionTool;
 /**
  * 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 declare function catalogList(catalog: CatalogServer[], loaded?: ReadonlySet<string>): string;
 /**
  * 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
@@ -47,22 +59,34 @@ export declare function catalogList(catalog: CatalogServer[], loaded?: ReadonlyS
  * 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 declare function catalogPrompt(catalog: CatalogServer[], loaded?: ReadonlySet<string>): string;
+/**
+ * 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 declare const toolName: (tool: OpenAI.ChatCompletionTool) => string | 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 declare function loadedTools(previous: readonly OpenAI.ChatCompletionTool[], matched: readonly OpenAI.ChatCompletionTool[]): OpenAI.ChatCompletionTool[];
 /**
@@ -73,6 +97,12 @@ export type ToolOrder = boolean | ((a: string, b: string) => number);
 /**
  * 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
@@ -84,16 +114,12 @@ export type ToolOrder = boolean | ((a: string, b: string) => number);
  *
  * `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 declare function orderTools(tools: OpenAI.ChatCompletionTool[], order?: ToolOrder): OpenAI.ChatCompletionTool[];
 /**
  * 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
@@ -109,6 +135,7 @@ export declare 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.
  */
@@ -116,34 +143,39 @@ export declare 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 declare function carryOver(previous: readonly string[], used: ReadonlySet<string>, max?: number): string[];
 /**
  * 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 declare function expandNames(requested: string[], catalog: CatalogServer[], maxPerLoad?: number): {
     matched: string[];
@@ -158,31 +190,39 @@ export declare function expandNames(requested: string[], catalog: CatalogServer[
 /**
  * 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 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.
  *
- * @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 declare const inCatalog: (catalog: CatalogServer[], name: string) => boolean;
 /**
  * `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 declare function requestedNames(args: Record<string, unknown>): string[];
 /**
  * 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
@@ -198,6 +238,7 @@ export declare 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:
@@ -210,52 +251,63 @@ export declare const PROXY_TOOLS: readonly OpenAI.ChatCompletionTool[];
  * 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 declare function proxyCatalogPrompt(catalog: CatalogServer[]): string;
 /**
  * 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 declare const holdsDefinitions: (result: string) => boolean;
 /**
  * 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 declare function proxyLoadResult(resolved: ReturnType<typeof expandNames>, catalog: CatalogServer[], definitions: readonly OpenAI.ChatCompletionTool[], loaded?: ReadonlySet<string>): string;
 /**
  * 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 declare function proxiedCall(args: Record<string, unknown>, catalog: CatalogServer[]): {
     name: string;
@@ -265,147 +317,17 @@ export declare function proxiedCall(args: Record<string, unknown>, catalog: Cata
  * 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 declare function shownCall(name: string, input: string): {
     name: string;
     input: string;
 };
-/**
- * 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 declare const preselectSystem: (maxPerLoad?: number) => string;
-/**
- * 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 declare const PRESELECT_SCHEMA: {
-    type: string;
-    properties: {
-        tools: {
-            type: string;
-            items: {
-                type: string;
-            };
-        };
-    };
-    required: string[];
-    additionalProperties: boolean;
-};
-/** The preselection system prompt at the default cap, for a caller that never changes it. */
-export declare const PRESELECT_SYSTEM: string;
-/**
- * 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 declare const preselectInput: (catalog: CatalogServer[], prompt: string, maxPromptChars?: number) => string;
-/**
- * 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 declare function preselection(names: unknown, catalog: CatalogServer[], maxPerLoad?: number): string[];
-/**
- * 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 declare 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 declare const KEYWORD_DROPOFF = 0.5;
-/** One tool's score against a request. */
-export interface ToolMatch {
-    name: string;
-    /** Its BM25 score. Zero-scoring tools are not ranked at all. */
-    score: number;
-}
-/** What `preselectByKeywords` found. */
-export interface KeywordPreselection {
-    /** The names, best first, capped at `maxPerLoad`. */
-    names: string[];
-    /** Whether the match is clear enough to run on without asking a model. */
-    confident: boolean;
-    /** Every tool that scored at all, best first — for a caller measuring its own threshold. */
-    ranked: ToolMatch[];
-}
-/** What `preselectByKeywords` takes besides the catalogue and the request. */
-export interface KeywordPreselectOptions {
-    /** The most to pick, defaulting to `MAX_PER_LOAD`. The same cap the model is held to. */
-    maxPerLoad?: number;
-    /** The floor under a confident best match, defaulting to `KEYWORD_MIN_SCORE`. */
-    minScore?: number;
-    /** The gap a confident cut needs, defaulting to `KEYWORD_DROPOFF`. */
-    dropoff?: number;
-    /** Where the request is cut, defaulting to 2000 — the same head `preselectInput` reads. */
-    maxPromptChars?: number;
-}
-/**
- * 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 declare function preselectByKeywords(catalog: CatalogServer[], prompt: string, { maxPerLoad, minScore, dropoff, maxPromptChars, }?: KeywordPreselectOptions): KeywordPreselection;