@cubicecho/agent-core 2.15.0 → 2.17.0

package/README.md

@@ -21,7 +21,7 @@ only, Node >=22.
 | Module | What it does |
 | --- | --- |
 | `schema-compat` | Makes an MCP tool schema something a strict or grammar-constrained server will accept. `sanitizeTools`, `relaxTools`, `isGrammarError`. |
-| `tool-loading` | On-demand tool discovery: a name-only catalogue plus a `load_tools` meta-tool, so a run pays for the schemas it asks for instead of all of them. |
+| `tool-loading` | On-demand tool discovery: a name-only catalogue plus a `load_tools` meta-tool, so a run pays for the schemas it asks for instead of all of them. Plus `preselectByKeywords`, which picks from it without a model. |
 | `stream` | Reads one streamed turn back into a message: token callbacks, tool-call reassembly, fenced reasoning taken out of the answer, and the idle watchdog that turns a silent endpoint into `EndpointSilent`. |
 | `capabilities` | What an endpoint turned out not to support — and, under it, what one model on that endpoint did not — plus the loop that answers either when it says so. `capabilitiesFor`, `modelCapabilitiesFor`, `negotiate`. |
 | `thinking` | Tells a scratchpad fenced inside `content` from the answer: `FenceSplitter` for a stream, `stripThinking` for a whole reply, and the fence tables both read. |
@@ -132,28 +132,49 @@ again, with the setting still reading `high` and nothing anywhere saying it had
 So they hang off the endpoint under the name the endpoint knows the model by. Pass `model` and
 the same loop answers both levels; leave it out and nothing changes.
 
-A refusal of the *value* is not one of these, however alike the two read: an effort off a list
-this package does not know, a `max_tokens` larger than the model's ceiling, a temperature out of
-range. Dropping the field answers those too — at the model's own default, latched for the rest of
-the process, with the settings row still reading what was typed and nothing saying it had stopped
-meaning it. They are passed to the caller instead, where whoever typed the number can see it.
+A refusal of the *value* is not one of these, however alike the two read: a `max_tokens` larger
+than the model's ceiling, a temperature out of range. Dropping the field answers those too — at
+the model's own default, latched for the rest of the process, with the settings row still reading
+what was typed and nothing saying it had stopped meaning it. They are passed to the caller
+instead, where whoever typed the number can see it.
+
+The effort is the exception, because there the model has said what it *would* take:
+`Unsupported value: 'reasoning_effort' does not support 'none' with this model. Supported values
+are: 'minimal', 'low', 'medium', and 'high'.` `negotiate` latches the rung that was refused and
+re-sends at the cheapest one above it, which is a request rather than a failure. Where the refusal
+lists nothing it walks `EFFORT_LADDER` — `none`, `minimal`, `low`, `medium`, `high` — a rung per
+refusal. Both latch per `(endpoint, model)` and ride in the snapshot, so a restart does not walk
+the ladder again.
+
+Only ever upward, and only from a value on the ladder. Answering a refused `xhigh` with `high`
+would quietly reason less than whoever typed it asked for; stepping up from `none` only costs
+tokens, and says so in a notice. When the ladder runs out, or the value is not on it, the refusal
+goes to the caller as it did before.
+
+`effortFor(model, asked)` is what a body builder calls to get the value to send — `buildBody` and
+the side tasks both do — and it answers the empty string for a model that takes no effort at all,
+for `"off"` and for an absent setting.
 
 ```ts
-const turn = await negotiate(supports, (supports, produced, model) =>
-  streamTurn(
-    getClient(config),
-    {
-      model: name, messages, stream: true,
-      // Each rebuilt per attempt from what this model has already refused.
-      ...(model?.reasoningEffort ? { reasoning_effort: effort } : {}),
-      ...(model?.legacyTokenLimit === false
-        ? { max_completion_tokens: limit }
-        : { max_tokens: limit }),
-      ...(model?.chosenTemperature ? { temperature } : {}),
-      tools: supports.strictSchemas ? declared : relaxTools(declared),
-    },
-    { produced, signal },
-  ),
+const turn = await negotiate(
+  supports,
+  (supports, produced, model) => {
+    // Each rebuilt per attempt from what this model has already refused.
+    const asked = effortFor(model, effort);
+    return streamTurn(
+      getClient(config),
+      {
+        model: name, messages, stream: true,
+        ...(asked ? { reasoning_effort: asked } : {}),
+        ...(model?.legacyTokenLimit === false
+          ? { max_completion_tokens: limit }
+          : { max_tokens: limit }),
+        ...(model?.chosenTemperature ? { temperature } : {}),
+        tools: supports.strictSchemas ? declared : relaxTools(declared),
+      },
+      { produced, signal },
+    );
+  },
   { model: name },
 );
 ```
@@ -420,6 +441,33 @@ run. A preselection shapes the first step alone: those tools, no catalogue, no `
 a model with the menu still in front of it shops, reloading what it has or picking a sibling —
 and everything is back from the second step on.
 
+That preselection costs a round trip to a model, which on a local box is a few seconds before the
+run has started, spent on a model doing term matching. `preselect(..., { keywords: true })` does
+the matching directly and spends the model only on what the words cannot settle:
+
+```ts
+const preselected = await preselect(config, config.toolSelectModel, catalog, prompt, {
+  keywords: true, // or { minScore, dropoff } to move the bar
+  onNotice,
+});
+```
+
+`preselectByKeywords` is the matcher on its own, ranking every tool against the request by BM25
+over its name, its server's label and its one-line description. BM25 rather than counting shared
+words, because a catalogue is full of words every tool uses — "list", "get", "file" — and an
+overlap count hands the top of the ranking to whichever tool has the longest description. English
+function words are dropped outright: the inverse document frequency is meant to handle them, and
+over a real corpus it would, but twenty one-line descriptions are few enough that "for" lands in
+one of them and scores as the most distinctive word in the request.
+
+What a caller acts on is `confident`, which is deliberately hard to earn: something more
+distinctive than a word the catalogue shares has to have matched, and the tools the cap left out
+have to score well below the ones it kept — a hit just under the line scoring nearly as much as
+one just over it means the ranking chose arbitrarily, which is the case a model is worth spending
+on. Matching nothing is not confident either, since the words cannot tell a request that needs no
+tools from one whose words are not in the catalogue. An empty `toolSelectModel` still means no
+preselection at all, words included.
+
 A turn cut off at `maxTokens` is said so as a notice, and with `maxContinuations` above zero it is
 continued first. `continueTurn` is the same thing for a caller with its own loop:
 

package/dist/agent-loop.d.ts

@@ -5,7 +5,7 @@ import type { Endpoint, ModelParams, RetryPolicy, ToolPolicy } from "./config.ts
 import { type RunEventInput, type RunMetrics } from "./events.ts";
 import { type HookContext, type HookEvent, type HookNote, type HookRunner } from "./hooks.ts";
 import type { Turn, TurnUsage } from "./stream.ts";
-import { type ToolOrder } from "./tool-loading.ts";
+import { type KeywordPreselectOptions, type ToolOrder } from "./tool-loading.ts";
 /**
  * The one place a streamed request's body is decided from a config and what the endpoint and
  * the model have refused.
@@ -18,7 +18,8 @@ import { type ToolOrder } from "./tool-loading.ts";
  * one has to read the same — which is the test one of the three copies had inverted.
  *
  * @param config What to ask for. `maxTokens` of zero or less sends no ceiling; `reasoningEffort`
- * absent or `"off"` sends no effort.
+ * absent or `"off"` sends no effort, and one the model has refused by value is stepped up to the
+ * cheapest it takes by `effortFor`.
  * @param supports What the endpoint has refused, as `negotiate` hands it to `send`.
  * @param refused What the model has refused, as `negotiate` hands it over. Absent is a model
  * that has refused nothing.
@@ -71,19 +72,30 @@ export declare function resolveApiKey(own: {
  * a failed one costs nothing — it is reported through `onNotice` and answered with an empty list,
  * since a side task is never worth failing the run. A stop still throws.
  *
+ * With `keywords`, the request's own words are matched against the catalogue first and the model
+ * is spent only on what they cannot settle, which on a local box is the difference between a run
+ * starting now and starting in a few seconds. The words have to be clear about it; see
+ * `preselectByKeywords` for what that means.
+ *
  * @param config The endpoint the preselector is reached through.
  * @param model The preselector. An empty name picks nothing, which is what `toolSelectModel`
  * means by empty.
  * @param catalog The servers to choose from.
  * @param prompt The request being planned for. Only its head is read; see `preselectInput`.
- * @param options Cancellation, notices, the reply ceiling (256) and the cap the choice is held to
- * (`MAX_PER_LOAD`).
+ * @param options Cancellation, notices, the reply ceiling (256), the cap the choice is held to
+ * (`MAX_PER_LOAD`), and whether to try the words first.
  */
-export declare function preselect(config: Endpoint, model: string, catalog: CatalogServer[], prompt: string, { signal, onNotice, maxTokens, maxPerLoad, }?: {
+export declare function preselect(config: Endpoint, model: string, catalog: CatalogServer[], prompt: string, { signal, onNotice, maxTokens, maxPerLoad, keywords, }?: {
     signal?: AbortSignal;
     onNotice?: (message: string) => void;
     maxTokens?: number;
     maxPerLoad?: number;
+    /**
+     * Try `preselectByKeywords` first and spend the model only on what it cannot settle. `true`
+     * takes its defaults; an object tunes the thresholds. An empty `model` still means no
+     * preselection at all, words included — that is what `toolSelectModel: ""` asks for.
+     */
+    keywords?: boolean | KeywordPreselectOptions;
 }): Promise<string[]>;
 /** One call the model made, as `dispatch` is handed it. */
 export interface ToolCallRequest {

package/dist/agent-loop.js

@@ -1,5 +1,5 @@
 import { charsPerTokenFor } from "./calibration.js";
-import { capabilitiesFor } from "./capabilities.js";
+import { capabilitiesFor, effortFor, } from "./capabilities.js";
 import { firstTokenMs, getClient, NO_KEY, timeoutMs } from "./client.js";
 import { continueTurn } from "./continuation.js";
 import { errorMessage } from "./errors.js";
@@ -10,7 +10,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, loadedTools, loadResult, MAX_PER_LOAD, orderTools, PRESELECT_SCHEMA, preselectInput, preselection, preselectSystem, requestedNames, } from "./tool-loading.js";
+import { catalogPrompt, expandNames, inCatalog, LOAD_TOOLS, LOAD_TOOLS_DEFINITION, loadedTools, loadResult, MAX_PER_LOAD, orderTools, PRESELECT_SCHEMA, preselectByKeywords, 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.
@@ -35,7 +35,8 @@ const RESERVED = new Set(["model", "messages", "stream", "tools"]);
  * one has to read the same — which is the test one of the three copies had inverted.
  *
  * @param config What to ask for. `maxTokens` of zero or less sends no ceiling; `reasoningEffort`
- * absent or `"off"` sends no effort.
+ * absent or `"off"` sends no effort, and one the model has refused by value is stepped up to the
+ * cheapest it takes by `effortFor`.
  * @param supports What the endpoint has refused, as `negotiate` hands it to `send`.
  * @param refused What the model has refused, as `negotiate` hands it over. Absent is a model
  * that has refused nothing.
@@ -51,7 +52,7 @@ export function buildBody(config, supports, refused, messages, tools = [], order
     const declared = supports.strictSchemas
         ? sanitizeTools(sorted)
         : relaxTools(sanitizeTools(sorted));
-    const effort = config.reasoningEffort;
+    const effort = effortFor(refused, config.reasoningEffort);
     const extra = Object.entries(config.extraBody ?? {}).filter(([field]) => !RESERVED.has(field) && !refused?.refusedFields.has(field));
     return {
         ...(config.maxTokens > 0
@@ -60,9 +61,7 @@ export function buildBody(config, supports, refused, messages, tools = [], order
                 : { max_tokens: config.maxTokens }
             : {}),
         ...(refused?.chosenTemperature === false ? {} : { temperature: config.temperature }),
-        ...(effort && effort !== "off" && refused?.reasoningEffort !== false
-            ? { reasoning_effort: effort }
-            : {}),
+        ...(effort ? { reasoning_effort: effort } : {}),
         ...(supports.usageInStream ? { stream_options: { include_usage: true } } : {}),
         ...Object.fromEntries(extra),
         model: config.model,
@@ -115,17 +114,32 @@ export function resolveApiKey(own, inherited, env = process.env) {
  * a failed one costs nothing — it is reported through `onNotice` and answered with an empty list,
  * since a side task is never worth failing the run. A stop still throws.
  *
+ * With `keywords`, the request's own words are matched against the catalogue first and the model
+ * is spent only on what they cannot settle, which on a local box is the difference between a run
+ * starting now and starting in a few seconds. The words have to be clear about it; see
+ * `preselectByKeywords` for what that means.
+ *
  * @param config The endpoint the preselector is reached through.
  * @param model The preselector. An empty name picks nothing, which is what `toolSelectModel`
  * means by empty.
  * @param catalog The servers to choose from.
  * @param prompt The request being planned for. Only its head is read; see `preselectInput`.
- * @param options Cancellation, notices, the reply ceiling (256) and the cap the choice is held to
- * (`MAX_PER_LOAD`).
+ * @param options Cancellation, notices, the reply ceiling (256), the cap the choice is held to
+ * (`MAX_PER_LOAD`), and whether to try the words first.
  */
-export async function preselect(config, model, catalog, prompt, { signal, onNotice, maxTokens = 256, maxPerLoad = MAX_PER_LOAD, } = {}) {
+export async function preselect(config, model, catalog, prompt, { signal, onNotice, maxTokens = 256, maxPerLoad = MAX_PER_LOAD, keywords, } = {}) {
     if (!model || !catalog.some((server) => server.tools.length > 0))
         return [];
+    if (keywords) {
+        const guess = preselectByKeywords(catalog, prompt, {
+            maxPerLoad,
+            ...(keywords === true ? {} : keywords),
+        });
+        if (guess.confident) {
+            onNotice?.(`chose ${guess.names.length} tool${guess.names.length === 1 ? "" : "s"} by name`);
+            return guess.names;
+        }
+    }
     const reply = await tryAsk("preselect", () => askJson(config, model, preselectSystem(maxPerLoad), preselectInput(catalog, prompt), PRESELECT_SCHEMA, { name: "preselection", maxTokens, signal, onNotice }), { onNotice });
     return preselection(reply, catalog, maxPerLoad);
 }

package/dist/capabilities.d.ts

@@ -93,6 +93,22 @@ export interface ModelCapabilities {
      * endpoint's because one key reaches models that differ here, the way they differ on effort.
      */
     structuredOutput: boolean;
+    /**
+     * Efforts this model refused by value rather than by field — a request that named `none` on a
+     * model whose list starts at `minimal`. Only ever grows, which is this set's way of latching.
+     *
+     * Separate from `reasoningEffort` because the two refusals mean opposite things: that one says
+     * the model cannot reason and the field must go, this one says it reasons and was handed an
+     * effort off a list this package does not know. Dropping the field there would run at the
+     * model's own default, which is neither what the caller asked for nor something it can see.
+     */
+    refusedEfforts: Set<string>;
+    /**
+     * The efforts a refusal published as this model's, in ladder order, filtered to the ones
+     * `EFFORT_LADDER` can place. Absent until a refusal lists them, and a model that lists nothing
+     * is walked up the ladder a rung per refusal instead.
+     */
+    supportedEfforts?: string[];
     /**
      * Continues a trailing assistant message rather than answering afresh, which `continueTurn`
      * relies on. llama.cpp renders one as a prefill and picks up mid-word; hosted OpenAI takes the
@@ -170,6 +186,30 @@ export declare function resetCapabilities(endpoint?: {
  * @returns How many endpoints were forgotten.
  */
 export declare function expireCapabilities(maxAgeMs: number, now?: number): number;
+/**
+ * The efforts this package can place, cheapest first. A substitution only ever walks *up* it.
+ *
+ * Not a list of what any model takes — `medium` is refused by a model whose list is
+ * `minimal, low, high`, and `xhigh` is real and deliberately absent. It is the order the values
+ * OpenAI has shipped stand in, which is all a step needs to know. A value not on it cannot be
+ * placed, and an unplaceable value is left alone rather than guessed at: stepping down from a
+ * refused `xhigh` to `high` would quietly answer a question with less deliberation than whoever
+ * typed it asked for, where stepping up from `none` to `minimal` only costs tokens and says so.
+ */
+export declare const EFFORT_LADDER: readonly ["none", "minimal", "low", "medium", "high"];
+/**
+ * What to actually put in `reasoning_effort` for a model that has refused the value asked for.
+ *
+ * The caller's own value, until this model has said that value is not one of its own; then the
+ * cheapest it will take that is at least as much deliberation. A model that takes no effort at
+ * all, and an absent or `"off"` setting, both answer the empty string, which is the body
+ * builders' signal to send no field.
+ *
+ * @param refused What the model has refused, as `negotiate` hands it over. Absent is a model that
+ * has refused nothing.
+ * @param asked What the config asks for. `"off"` and absent mean no effort.
+ */
+export declare function effortFor(refused: ModelCapabilities | undefined, asked: string | undefined): string;
 /** What `negotiate` takes besides the request. All optional. */
 export interface NegotiateOptions {
     /**

package/dist/capabilities.js

@@ -56,6 +56,7 @@ export function modelCapabilitiesFor(supports, model) {
             chosenTemperature: true,
             refusedFields: new Set(),
             structuredOutput: true,
+            refusedEfforts: new Set(),
             assistantPrefill: true,
         };
         supports.models.set(model, known);
@@ -154,7 +155,8 @@ const rejectsResponseFormat = (detail) => /response_format|json_schema/i.test(de
  * perfectly well; it was handed an effort off a list this package does not know. Dropping the
  * field succeeds, at the model's own default effort, which is neither what the caller asked for
  * nor something it can see — and the drop latches, so every later turn on that model reasons at
- * the default with the setting still reading what the operator typed.
+ * the default with the setting still reading what the operator typed. `stepEffort` answers this
+ * one instead, by naming an effort the model does take.
  */
 const REFUSED_VALUE = /unsupported value|invalid value|supported values/i;
 /**
@@ -165,6 +167,127 @@ const REFUSED_VALUE = /unsupported value|invalid value|supported values/i;
  * latching.
  */
 const rejectsEffort = (detail) => /reasoning_effort/i.test(detail) && !REFUSED_VALUE.test(detail);
+/**
+ * The efforts this package can place, cheapest first. A substitution only ever walks *up* it.
+ *
+ * Not a list of what any model takes — `medium` is refused by a model whose list is
+ * `minimal, low, high`, and `xhigh` is real and deliberately absent. It is the order the values
+ * OpenAI has shipped stand in, which is all a step needs to know. A value not on it cannot be
+ * placed, and an unplaceable value is left alone rather than guessed at: stepping down from a
+ * refused `xhigh` to `high` would quietly answer a question with less deliberation than whoever
+ * typed it asked for, where stepping up from `none` to `minimal` only costs tokens and says so.
+ */
+export const EFFORT_LADDER = ["none", "minimal", "low", "medium", "high"];
+const rankOf = (effort) => EFFORT_LADDER.indexOf(effort.toLowerCase());
+/**
+ * The efforts a refusal lists as this model's: `Supported values are: 'minimal', 'low', 'medium',
+ * and 'high'.` Quoted or bare, separated by commas and a trailing `and` or `or`.
+ */
+function listedEfforts(detail) {
+    const listed = detail.match(/supported values(?:\s+\w+)?\s*(?:are|is|include)?\s*:?\s*([^\n.]+)/i)?.[1];
+    if (!listed)
+        return undefined;
+    const values = listed
+        .split(/,|\band\b|\bor\b/)
+        .map((value) => value
+        .trim()
+        .replace(/^['"`]+|['"`]+$/g, "")
+        .toLowerCase())
+        .filter((value) => rankOf(value) >= 0);
+    return values.length ? values : undefined;
+}
+/**
+ * Which effort a refusal says was refused, in the two shapes the wording takes: the field quoted
+ * then `does not support 'none'`, and `reasoning_effort: none`.
+ *
+ * Read rather than remembered, because `negotiate` builds no request and so does not know what
+ * went out — and a proxy that rewrites the value before passing it on is refusing the one it sent
+ * rather than the one it was given. A refusal that names no value steps nothing: guessing which
+ * rung was refused is how a ladder walks past the value that would have worked.
+ *
+ * @param detail The refusal.
+ * @param supported What the same refusal listed, which the value cannot be one of.
+ */
+function refusedEffortValue(detail, supported = []) {
+    const found = detail.match(/reasoning_effort['"`]?\s*(?:does not support|is not supported with|:)\s*['"`]?([\w-]+)/i)?.[1];
+    const value = found?.toLowerCase();
+    return value && !supported.includes(value) ? value : undefined;
+}
+/**
+ * The cheapest effort above this one that the model has not refused, or `undefined` when the
+ * ladder is out of rungs.
+ *
+ * Above, never below: see `EFFORT_LADDER`. Where a refusal published a list that is the whole of
+ * what is tried, so the step lands in one request; where it published none the ladder is walked a
+ * rung at a time, each refusal latching the rung it named.
+ */
+function nextEffort(refused, asked) {
+    const rank = rankOf(asked);
+    if (rank < 0)
+        return undefined;
+    let best;
+    for (const value of refused.supportedEfforts ?? EFFORT_LADDER) {
+        const at = rankOf(value);
+        if (at <= rank || refused.refusedEfforts.has(value))
+            continue;
+        if (best === undefined || at < rankOf(best))
+            best = value;
+    }
+    return best;
+}
+/**
+ * What to actually put in `reasoning_effort` for a model that has refused the value asked for.
+ *
+ * The caller's own value, until this model has said that value is not one of its own; then the
+ * cheapest it will take that is at least as much deliberation. A model that takes no effort at
+ * all, and an absent or `"off"` setting, both answer the empty string, which is the body
+ * builders' signal to send no field.
+ *
+ * @param refused What the model has refused, as `negotiate` hands it over. Absent is a model that
+ * has refused nothing.
+ * @param asked What the config asks for. `"off"` and absent mean no effort.
+ */
+export function effortFor(refused, asked) {
+    if (!asked || asked === "off")
+        return "";
+    if (!refused)
+        return asked;
+    if (!refused.reasoningEffort)
+        return "";
+    const known = refused.supportedEfforts;
+    const listed = known ? known.includes(asked.toLowerCase()) : true;
+    if (listed && !refused.refusedEfforts.has(asked.toLowerCase()))
+        return asked;
+    return nextEffort(refused, asked) ?? asked;
+}
+/**
+ * How to answer a refused effort *value*, or `undefined` when there is nothing new to learn or
+ * nowhere left to go — in which case the refusal is the caller's, as it was before this existed.
+ *
+ * Pure, so `negotiate` can work out whether this refusal is one of its own before deciding to
+ * answer it, and latch only in the branch it takes.
+ */
+function planEffortStep(detail, refused) {
+    if (!refused.reasoningEffort)
+        return undefined;
+    if (!/reasoning_effort/i.test(detail) || !REFUSED_VALUE.test(detail))
+        return undefined;
+    const supported = listedEfforts(detail);
+    const value = refusedEffortValue(detail, supported);
+    if (value === undefined)
+        return undefined;
+    // Something has to be new, or a server that answers every request by naming an effort nobody
+    // sent would have `negotiate` re-send for as long as it kept saying it.
+    const fresh = supported?.join() !== refused.supportedEfforts?.join();
+    if (refused.refusedEfforts.has(value) && !fresh)
+        return undefined;
+    const next = nextEffort({
+        ...refused,
+        refusedEfforts: new Set(refused.refusedEfforts).add(value),
+        supportedEfforts: supported ?? refused.supportedEfforts,
+    }, value);
+    return next === undefined ? undefined : { value, next, ...(supported ? { supported } : {}) };
+}
 /**
  * Read only alongside the name it is asking for: `'max_tokens' is not supported with this model.
  * Use 'max_completion_tokens' instead.`
@@ -280,6 +403,7 @@ export async function negotiate(supports, send, { produced = { any: false }, onN
             if (produced.any)
                 throw error;
             const detail = errorMessage(error);
+            const stepped = named && planEffortStep(detail, named.refused);
             if (supports.strictSchemas && isGrammarError(detail)) {
                 supports.strictSchemas = false;
                 onNotice?.("server could not build a grammar; retrying without pattern/format");
@@ -292,6 +416,12 @@ export async function negotiate(supports, send, { produced = { any: false }, onN
                 named.refused.reasoningEffort = false;
                 onNotice?.(`${named.name} does not take a reasoning effort; retrying without one`);
             }
+            else if (named && stepped) {
+                named.refused.refusedEfforts.add(stepped.value);
+                if (stepped.supported)
+                    named.refused.supportedEfforts = stepped.supported;
+                onNotice?.(`${named.name} does not reason at ${stepped.value}; retrying at ${stepped.next}`);
+            }
             else if (named?.refused.legacyTokenLimit && wantsCompletionLimit(detail)) {
                 named.refused.legacyTokenLimit = false;
                 onNotice?.(`${named.name} wants max_completion_tokens; retrying with the limit spelled that way`);

package/dist/index.d.ts

@@ -11,7 +11,7 @@
  */
 export { type AgentLoopHooks, type AgentLoopOptions, type AgentLoopResult, buildBody, preselect, preview, resolveApiKey, runAgentLoop, type ToolCallOutcome, type ToolCallRequest, } from "./agent-loop.ts";
 export { calibrate, charsPerTokenFor, resetCalibration } from "./calibration.ts";
-export { type Capabilities, capabilitiesFor, expireCapabilities, type ModelCapabilities, modelCapabilitiesFor, type NegotiateOptions, negotiate, resetCapabilities, } from "./capabilities.ts";
+export { type Capabilities, capabilitiesFor, EFFORT_LADDER, effortFor, expireCapabilities, type ModelCapabilities, modelCapabilitiesFor, type NegotiateOptions, negotiate, resetCapabilities, } from "./capabilities.ts";
 export type { CatalogServer } from "./catalog.ts";
 export { type ClientPoolOptions, configureClients, contextLimitFor, endpointId, endpointKey, FIRST_TOKEN_FACTOR, firstTokenMs, getClient, listModels, type ModelInfo, NO_KEY, resetClients, servedWindow, timeoutMs, } from "./client.ts";
 export { applyCompaction, COMPACT_AT, type CompactionOptions, type CompactionPlan, type CompactionRecord, type CompactionRunOptions, compactTranscript, KEEP_RATIO, type PruneOptions, planCompaction, pruneToolResults, requestIndex, runCompaction, SUMMARY_LEAD, SUMMARY_PROMPT, summariser, summaryInput, } from "./compaction.ts";
@@ -30,4 +30,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, loadedTools, loadResult, MAX_CARRIED, MAX_PER_LOAD, orderTools, PRESELECT_SCHEMA, PRESELECT_SYSTEM, preselectInput, preselection, preselectSystem, requestedNames, type ToolOrder, } from "./tool-loading.ts";
+export { carryOver, catalogList, catalogPrompt, expandNames, inCatalog, KEYWORD_DROPOFF, KEYWORD_MIN_SCORE, type KeywordPreselection, type KeywordPreselectOptions, LOAD_TOOLS, LOAD_TOOLS_DEFINITION, loadedTools, loadResult, MAX_CARRIED, MAX_PER_LOAD, orderTools, PRESELECT_SCHEMA, PRESELECT_SYSTEM, preselectByKeywords, preselectInput, preselection, preselectSystem, requestedNames, type ToolMatch, type ToolOrder, } from "./tool-loading.ts";

package/dist/index.js

@@ -11,7 +11,7 @@
  */
 export { buildBody, preselect, preview, resolveApiKey, runAgentLoop, } from "./agent-loop.js";
 export { calibrate, charsPerTokenFor, resetCalibration } from "./calibration.js";
-export { capabilitiesFor, expireCapabilities, modelCapabilitiesFor, negotiate, resetCapabilities, } from "./capabilities.js";
+export { capabilitiesFor, EFFORT_LADDER, effortFor, expireCapabilities, modelCapabilitiesFor, negotiate, resetCapabilities, } from "./capabilities.js";
 export { configureClients, contextLimitFor, endpointId, endpointKey, FIRST_TOKEN_FACTOR, firstTokenMs, getClient, listModels, NO_KEY, resetClients, servedWindow, timeoutMs, } from "./client.js";
 export { applyCompaction, COMPACT_AT, compactTranscript, KEEP_RATIO, planCompaction, pruneToolResults, requestIndex, runCompaction, SUMMARY_LEAD, SUMMARY_PROMPT, summariser, summaryInput, } from "./compaction.js";
 export { continueTurn, isContinuable, } from "./continuation.js";
@@ -28,4 +28,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, loadedTools, loadResult, MAX_CARRIED, MAX_PER_LOAD, orderTools, PRESELECT_SCHEMA, PRESELECT_SYSTEM, preselectInput, preselection, preselectSystem, requestedNames, } from "./tool-loading.js";
+export { carryOver, catalogList, catalogPrompt, expandNames, inCatalog, KEYWORD_DROPOFF, KEYWORD_MIN_SCORE, LOAD_TOOLS, LOAD_TOOLS_DEFINITION, loadedTools, loadResult, MAX_CARRIED, MAX_PER_LOAD, orderTools, PRESELECT_SCHEMA, PRESELECT_SYSTEM, preselectByKeywords, preselectInput, preselection, preselectSystem, requestedNames, } from "./tool-loading.js";

package/dist/side-task.js

@@ -1,5 +1,5 @@
 import OpenAI from "openai";
-import { capabilitiesFor, modelCapabilitiesFor, negotiate, } from "./capabilities.js";
+import { capabilitiesFor, effortFor, modelCapabilitiesFor, negotiate, } from "./capabilities.js";
 import { endpointId, getClient } from "./client.js";
 import { errorMessage } from "./errors.js";
 import { isTransient } from "./retry.js";
@@ -85,7 +85,11 @@ async function complete(config, model, system, user, { maxTokens = 512, temperat
     // Whether the last request carried an effort, which `negotiate` decides and not this function.
     let sentEffort = false;
     const send = (hints, effort, supports, refused) => {
-        sentEffort = effort && refused?.reasoningEffort !== false;
+        // `none` is what a side task wants and not always what the model offers: OpenAI's reasoning
+        // models refuse it by value and list `minimal` as their floor. `effortFor` answers with the
+        // cheapest rung this one takes, which `negotiate` has been stepping up as it was refused.
+        const asked = effort ? effortFor(refused, "none") : "";
+        sentEffort = asked !== "";
         return getClient(config).chat.completions.create({
             model,
             // The reasoning models want the ceiling spelled the other way, and they are exactly the
@@ -103,7 +107,7 @@ async function complete(config, model, system, user, { maxTokens = 512, temperat
             ...(hints ? NO_THINKING : {}),
             // Not gated on `hints`: a model that refuses `chat_template_kwargs` may still read the
             // effort, and the two latches would otherwise contradict each other.
-            ...(sentEffort ? { reasoning_effort: "none" } : {}),
+            ...(sentEffort ? { reasoning_effort: asked } : {}),
             ...(format && refused ? format(supports, refused) : {}),
         }, { signal });
     };

package/dist/snapshot.d.ts

@@ -22,6 +22,14 @@ export interface ModelSnapshot {
     assistantPrefill: boolean;
     /** Takes the no-thinking hints `ask` sends. */
     thinkingHints: boolean;
+    /**
+     * Efforts refused by value rather than by field, so a restart does not spend a request per rung
+     * walking the ladder again. Absent in a snapshot taken before they were latched, which reads as
+     * none refused.
+     */
+    refusedEfforts?: string[];
+    /** The efforts a refusal published as this model's, in ladder order. Absent is none published. */
+    supportedEfforts?: string[];
 }
 /** What one endpoint refused, and under it what each of its models did. */
 export interface EndpointSnapshot {

package/dist/snapshot.js

@@ -18,6 +18,7 @@ const optimisticModel = () => ({
     structuredOutput: true,
     assistantPrefill: true,
     thinkingHints: true,
+    refusedEfforts: [],
 });
 const refusedAnything = (model) => !model.reasoningEffort ||
     !model.legacyTokenLimit ||
@@ -25,7 +26,8 @@ const refusedAnything = (model) => !model.reasoningEffort ||
     !model.thinkingHints ||
     !model.structuredOutput ||
     !model.assistantPrefill ||
-    model.refusedFields.length > 0;
+    model.refusedFields.length > 0 ||
+    (model.refusedEfforts?.length ?? 0) > 0;
 /**
  * Every refusal this process has latched, as a JSON-safe blob to store and hand back on boot.
  *
@@ -59,6 +61,10 @@ export function exportCapabilities() {
                 refusedFields: [...refused.refusedFields].sort(),
                 structuredOutput: refused.structuredOutput,
                 assistantPrefill: refused.assistantPrefill,
+                refusedEfforts: [...refused.refusedEfforts].sort(),
+                // Only alongside a refusal, since on its own a published list latches nothing: the model
+                // named it while refusing a rung, and that rung is in `refusedEfforts`.
+                ...(refused.supportedEfforts ? { supportedEfforts: [...refused.supportedEfforts] } : {}),
             };
             if (refusedAnything(model))
                 models[name] = model;
@@ -128,6 +134,19 @@ export function importCapabilities(snapshot) {
                 refused.structuredOutput = false;
             if (model.assistantPrefill === false)
                 refused.assistantPrefill = false;
+            if (Array.isArray(model.refusedEfforts)) {
+                for (const effort of model.refusedEfforts) {
+                    if (typeof effort === "string")
+                        refused.refusedEfforts.add(effort);
+                }
+            }
+            // Replaced rather than merged: two lists of what one model takes are two readings of the
+            // same fact, and the stored one is at least as recent as an empty absent.
+            if (Array.isArray(model.supportedEfforts)) {
+                const listed = model.supportedEfforts.filter((value) => typeof value === "string");
+                if (listed.length)
+                    refused.supportedEfforts = listed;
+            }
             if (Array.isArray(model.refusedFields)) {
                 for (const field of model.refusedFields) {
                     if (typeof field === "string")

package/dist/tool-loading.d.ts

@@ -229,3 +229,76 @@ export declare const preselectInput: (catalog: CatalogServer[], prompt: string,
  * `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;

package/dist/tool-loading.js

@@ -394,3 +394,128 @@ export function preselection(names, catalog, maxPerLoad = MAX_PER_LOAD) {
     const wanted = list.filter((name) => typeof name === "string");
     return expandNames(wanted, catalog, maxPerLoad).matched.slice(0, maxPerLoad);
 }
+/**
+ * Saturation and length normalisation for the BM25 score. Robertson's usual values.
+ *
+ * Nothing here is tuned for this corpus, because tuning them against a catalogue of forty short
+ * documents would be fitting noise. `dropoff` and `minScore` are the knobs worth turning.
+ */
+const BM25_K1 = 1.2;
+const BM25_B = 0.75;
+/**
+ * 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 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 const KEYWORD_DROPOFF = 0.5;
+/**
+ * English function words, dropped before matching.
+ *
+ * The inverse document frequency is supposed to make this unnecessary, and over a real corpus it
+ * would: a word carried by every document is worth nothing. But a tool catalogue is twenty
+ * one-line descriptions, and at that size "for" or "on" is rare by accident — it lands in one
+ * description, scores as the most distinctive term in the query, and a request that says "for me"
+ * is answered with whichever tool happened to use the word. Only closure-class words are here;
+ * "list", "get", "run" and "show" are what tools are called and stay.
+ */
+const NOISE = new Set(("about all also am an and any are as at be been being but by can could do does for from had " +
+    "has have how if in into is it its just me more most my no not of on or other our out over " +
+    "please should so some such than that the their them then there these they this to too up us " +
+    "very was we were what when where which who will with would you your").split(" "));
+/**
+ * A text as the matcher reads it: lowercase words, `server__tool_name` and camelCase split apart.
+ *
+ * Plurals are folded, crudely, by dropping a trailing `s`: a request says "read the files" and
+ * the tool is called `read_file`, and without this the two do not meet. Nothing else is stemmed —
+ * a real stemmer is a table of English morphology, and this is matching identifiers.
+ */
+const terms = (text) => text
+    .replace(/([a-z0-9])([A-Z])/g, "$1 $2")
+    .toLowerCase()
+    .split(/[^a-z0-9]+/)
+    .filter((word) => word.length > 1 && !NOISE.has(word))
+    .map((word) => word.length > 3 && word.endsWith("s") && !word.endsWith("ss") ? word.slice(0, -1) : word);
+/**
+ * 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 function preselectByKeywords(catalog, prompt, { maxPerLoad = MAX_PER_LOAD, minScore = KEYWORD_MIN_SCORE, dropoff = KEYWORD_DROPOFF, maxPromptChars = PRESELECT_PROMPT_CHARS, } = {}) {
+    const empty = { names: [], confident: false, ranked: [] };
+    const docs = catalog.flatMap((server) => server.tools.map((tool) => ({
+        name: tool.name,
+        terms: terms(`${tool.name} ${server.label} ${tool.description}`),
+    })));
+    // A query term repeated in the request is not worth more than one said once: the request is
+    // prose about a task, not a document being matched against another document.
+    const query = new Set(terms(prompt.slice(0, maxPromptChars)));
+    if (!docs.length || !query.size)
+        return empty;
+    const length = docs.reduce((total, doc) => total + doc.terms.length, 0) / docs.length;
+    const documents = new Map();
+    for (const doc of docs)
+        for (const term of new Set(doc.terms))
+            documents.set(term, (documents.get(term) ?? 0) + 1);
+    const ranked = docs
+        .map((doc) => {
+        const counts = new Map();
+        for (const term of doc.terms)
+            counts.set(term, (counts.get(term) ?? 0) + 1);
+        let score = 0;
+        for (const term of query) {
+            const found = counts.get(term);
+            if (!found)
+                continue;
+            const held = documents.get(term) ?? 0;
+            const idf = Math.log(1 + (docs.length - held + 0.5) / (held + 0.5));
+            const norm = BM25_K1 * (1 - BM25_B + (BM25_B * doc.terms.length) / length);
+            score += (idf * found * (BM25_K1 + 1)) / (found + norm);
+        }
+        return { name: doc.name, score };
+    })
+        .filter((hit) => hit.score > 0)
+        // Ties break on the name, not on where the tool sat in the catalogue, so reconnecting a
+        // server in a different order does not change what a run opens with.
+        .sort((a, b) => b.score - a.score || a.name.localeCompare(b.name));
+    if (!ranked.length)
+        return empty;
+    const names = ranked.slice(0, maxPerLoad).map((hit) => hit.name);
+    const cut = ranked[names.length - 1].score;
+    const next = ranked[maxPerLoad]?.score ?? 0;
+    return { names, confident: ranked[0].score >= minScore && next <= dropoff * cut, ranked };
+}

package/llms.txt

@@ -38,6 +38,8 @@ What an endpoint turned out not to support, and answering it when it says so.
 
 - `Capabilities` (type) — What one endpoint turned out not to support.
 - `capabilitiesFor` — What this endpoint is known not to support.
+- `EFFORT_LADDER` — The efforts this package can place, cheapest first.
+- `effortFor` — What to actually put in `reasoning_effort` for a model that has refused the value asked for.
 - `expireCapabilities` — Forgets every endpoint whose entry is older than this, so the next request finds out again.
 - `ModelCapabilities` (type) — What one model on that endpoint turned out not to support.
 - `modelCapabilitiesFor` — What this model on this endpoint is known not to support.
@@ -275,6 +277,10 @@ Reading what a model meant by a tool call when it did not write one cleanly.
 - `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.
+- `KEYWORD_DROPOFF` — How far the best unpicked tool must fall below the last picked one for the cut to count clean.
+- `KEYWORD_MIN_SCORE` — The least a best match may score and still be acted on without a model.
+- `KeywordPreselection` (type) — What `preselectByKeywords` found.
+- `KeywordPreselectOptions` (type) — What `preselectByKeywords` takes besides the catalogue and the request.
 - `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.
@@ -284,8 +290,10 @@ Reading what a model meant by a tool call when it did not write one cleanly.
 - `orderTools` — The tool array in a stable order, so the same set of tools renders the same way twice.
 - `PRESELECT_SCHEMA` — The shape a preselector's answer is held to where the server takes a schema: `{ tools: [...] }`.
 - `PRESELECT_SYSTEM` — The preselection system prompt at the default cap, for a caller that never changes it.
+- `preselectByKeywords` — The tools a request's own words point at, ranked, and whether they point clearly enough.
 - `preselectInput` — The user message for a preselection call: the catalogue, then the request.
 - `preselection` — Resolves a preselection against the catalogue: unknown names dropped, count capped.
 - `preselectSystem` — The system prompt a preselector is given, holding it to the cap its answer will be held to.
 - `requestedNames` — `load_tools` arguments, defensively — a model may send a bare string or a nested object.
+- `ToolMatch` (type) — One tool's score against a request.
 - `ToolOrder` (type) — How a tool array is ordered before it is sent: `true` by name, `false` as the caller built it, or a comparator over the two names.

package/package.json

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