@cubicecho/agent-core 1.0.0 → 1.2.0

package/README.md

@@ -4,7 +4,17 @@ The endpoint-agnostic half of an OpenAI-compatible agent loop.
 
 Extracted from three servers that had each written it separately — `kanban_server`,
 `task_server` and `min-agent` — after the copies drifted far enough that a fix in one was a bug
-still live in another. See [`standards/extraction-backlog.md`](../standards/extraction-backlog.md).
+still live in another.
+
+## Install
+
+```sh
+npm install @cubicecho/agent-core openai
+```
+
+`openai` is a peer dependency (`>=6`) so the client this hands back is the same one your code
+already imports — one SDK version in the tree, one `instanceof` that means what it says. ESM
+only, Node >=22.
 
 ## What is here
 
@@ -12,15 +22,58 @@ still live in another. See [`standards/extraction-backlog.md`](../standards/extr
 | --- | --- |
 | `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. |
+| `stream` | Reads one streamed turn back into a message: token callbacks, tool-call reassembly, and the idle watchdog that turns a silent endpoint into `EndpointSilent`. |
+| `capabilities` | What an endpoint turned out not to support, per endpoint, and the loop that answers it when it says so. `capabilitiesFor`, `negotiate`. |
 | `side-task` | One-shot calls that support a run without being one — small prompt, short answer, no tools, never worth failing the run over. |
 | `events` | The in-memory bus a watcher reads while a run happens. |
 | `client` | A pooled `OpenAI` client per endpoint, plus the context-window listing and its cache. |
 | `retry` | What to do when a request is lost, refused or too big: `isTransient`, `backoffMs`, `ContextOverflow`, `EndpointSilent`. |
 | `config` | The structural interfaces every function here asks for. |
+| `reset` | `resetAll`: drops every cache and latch in one call, so a teardown cannot forget one. |
+| `errors` | `errorMessage`: a caught `unknown` turned into something a run row can hold. |
+| `catalog` | `CatalogServer`: the name-only shape `tool-loading` reads a connected server as. |
 
 What is **not** here is the work: orchestration, prompts, and whatever the run is about. That
 is the caller's, and it is the part that actually differs between one server and the next.
 
+## A turn
+
+`negotiate` wrapping `streamTurn` is the whole of one turn against an endpoint: the request is
+re-sent for as long as the answer is this server refusing something the request can do without,
+and nothing is re-sent once it has started answering.
+
+```ts
+import {
+  capabilitiesFor, getClient, negotiate, relaxTools, sanitizeTools, streamTurn, timeoutMs,
+} from "@cubicecho/agent-core";
+
+const declared = sanitizeTools(tools);
+const supports = capabilitiesFor(config.baseUrl);
+
+const turn = await negotiate(supports, (supports, produced) =>
+  streamTurn(
+    getClient(config),
+    {
+      model, messages, stream: true,
+      // Rebuilt per attempt: what the endpoint has refused is latched off by the line above.
+      ...(supports.usageInStream ? { stream_options: { include_usage: true } } : {}),
+      tools: supports.strictSchemas ? declared : relaxTools(declared),
+    },
+    { produced, signal, idleMs: timeoutMs(config), onOutput: (text) => emit(runId, { kind: "output", text }) },
+  ),
+);
+```
+
+`send` takes a callback rather than a body because the body has to be rebuilt from the latched
+flags. `produced` is one box per attempt — `streamTurn` sets it as soon as the server says
+anything, and the re-send reads it — so a caller with its own retry budget passes one in
+(`{ produced }`) and reads it afterwards to decide whether the failure is worth another attempt.
+
+`idleMs` is silence, not a deadline: the timer is rearmed on every chunk, so a model that is
+still talking is never cut off however long it takes, and one that has stopped answering raises
+`EndpointSilent` rather than hanging the run. `timeoutMs(config)` returns `undefined` for a
+`requestTimeoutSeconds` of zero, which waits forever — what a local model answering slowly needs.
+
 ## The config seam
 
 Nothing here imports a config type from a consumer, and no function asks for a whole
@@ -35,9 +88,13 @@ const client = getClient(settings satisfies Endpoint);
 ```
 
 This matters because the three consumers do not agree on the fields. `task_server`'s settings
-row has no `contextLength`; `min-agent` spells it `contextLimit` and has no timeout or retry
-budget at all. A single god interface would have forced two of them to grow columns they have
-no use for.
+row has no `contextLength`; `min-agent` spells it `contextLimit` and carries no retry budget.
+A single god interface would have forced two of them to grow columns they have no use for.
+
+The seam is not finished. `timeoutMs` narrows to the one field it reads, but `getClient` still
+asks for the whole of `Endpoint`, and `requestTimeoutSeconds` on it is required — so a consumer
+that has no timeout to give must invent one (`0` means "no limit"). Making it optional is a
+breaking change and is waiting for the next major.
 
 ## Where the merged behaviour came from
 

package/dist/capabilities.d.ts

@@ -0,0 +1,68 @@
+import type { Produced } from "./stream.ts";
+/**
+ * What an endpoint turned out not to support, and answering it when it says so.
+ *
+ * This package knew *how* to answer a refusal — `isGrammarError`, `relaxTools`, `sanitizeTools`
+ * — but not that it had already answered one, so each consumer kept its own memory of what an
+ * endpoint could not do and wrote the negotiation around it separately. Both of those are facts
+ * about the server on the other end rather than about this process, which is what makes them
+ * this package's to hold.
+ */
+/** What one endpoint turned out not to support. Both start optimistic and only ever latch off. */
+export interface Capabilities {
+    /**
+     * llama.cpp-backed servers compile every tool schema into one grammar and reject keywords
+     * their converter cannot express — one bad shape from one MCP server fails the whole request.
+     * Once we have seen that, the advisory keywords stay off rather than costing every later run
+     * a failed call first. See `relaxTools`.
+     */
+    strictSchemas: boolean;
+    /**
+     * `stream_options` is how a streamed request asks for its token counts, and a server that has
+     * not heard of it rejects the whole request rather than the option. Dropped for good once that
+     * happens: the counts are worth one failed call to find out about, not one per run.
+     */
+    usageInStream: boolean;
+}
+/**
+ * What this endpoint is known not to support. The same object every time, so what `negotiate`
+ * latches off stays off.
+ */
+export declare function capabilitiesFor(baseUrl: string): Capabilities;
+/** Forgets every endpoint's capabilities. For tests, and for a settings change under test. */
+export declare function resetCapabilities(): void;
+export interface NegotiateOptions {
+    /**
+     * The flag `send` will be given, for a caller that has to read it after `negotiate` returns.
+     *
+     * An outer retry loop needs it: nothing is retried once the server has started answering, and
+     * by the time a rejected promise is in hand the turn is over. Callers without one can leave
+     * this out and take the flag from `send`'s second argument, which is the same object.
+     */
+    produced?: Produced;
+    /** Told what was given up on, for a watcher who would otherwise see an unexplained pause. */
+    onNotice?: (message: string) => void;
+}
+/**
+ * Sends a request, re-sending it each time the answer is this endpoint refusing something the
+ * request can do without. Returns once the endpoint has answered, or throws if the refusal is
+ * not one of ours.
+ *
+ * A loop rather than one retry. A server that has heard of neither `stream_options` nor a
+ * grammar keyword complains about them one at a time, and answering only the first leaves the
+ * second to fail the request — so the first run against such an endpoint is spent discovering
+ * what the second one starts knowing. It terminates in at most one pass per capability, since
+ * each pass either latches one off for good or rethrows.
+ *
+ * `send` is a thunk rather than a request body because the body has to be rebuilt from the
+ * latched flags: `relaxTools` applies to the tools that were just sanitised, and
+ * `stream_options` is present or absent rather than adjusted. It is generic over what it
+ * resolves, so a caller whose request resolves a stream object before any chunk is read is the
+ * same shape as one that resolves a finished turn.
+ *
+ * It is handed the `produced` flag rather than being expected to close over one. There is only
+ * ever one flag in a turn — the same box `streamTurn` sets and the re-send below reads — and a
+ * caller that passed it to only one of the two got a turn that had already streamed tokens sent
+ * again, silently, with the watcher seeing every one of them twice.
+ */
+export declare function negotiate<T>(supports: Capabilities, send: (supports: Capabilities, produced: Produced) => Promise<T>, { produced, onNotice }?: NegotiateOptions): Promise<T>;

package/dist/capabilities.js

@@ -0,0 +1,77 @@
+import { errorMessage } from "./errors.js";
+import { isGrammarError } from "./schema-compat.js";
+/**
+ * What each endpoint cannot do, remembered for the life of the process.
+ *
+ * Keyed by base URL, because these are facts about the server on the other end and not about
+ * this one. A llama.cpp box that cannot compile a grammar and a cloud API that can are both
+ * reachable from one settings row over its lifetime — an operator retargets it from Ollama this
+ * afternoon to OpenAI this evening — and the first one's refusal must not quietly strip
+ * pattern/format from the second one's requests, or silently cost it its token counts, for the
+ * rest of the process. Bounded by the number of endpoints ever configured, which is a settings
+ * row's worth.
+ */
+const capabilities = new Map();
+/**
+ * What this endpoint is known not to support. The same object every time, so what `negotiate`
+ * latches off stays off.
+ */
+export function capabilitiesFor(baseUrl) {
+    let known = capabilities.get(baseUrl);
+    if (!known) {
+        known = { strictSchemas: true, usageInStream: true };
+        capabilities.set(baseUrl, known);
+    }
+    return known;
+}
+/** Forgets every endpoint's capabilities. For tests, and for a settings change under test. */
+export function resetCapabilities() {
+    capabilities.clear();
+}
+/** `stream_options` is named in the refusal by every server that has not heard of it. */
+const REJECTS_USAGE = /stream_options/i;
+/**
+ * Sends a request, re-sending it each time the answer is this endpoint refusing something the
+ * request can do without. Returns once the endpoint has answered, or throws if the refusal is
+ * not one of ours.
+ *
+ * A loop rather than one retry. A server that has heard of neither `stream_options` nor a
+ * grammar keyword complains about them one at a time, and answering only the first leaves the
+ * second to fail the request — so the first run against such an endpoint is spent discovering
+ * what the second one starts knowing. It terminates in at most one pass per capability, since
+ * each pass either latches one off for good or rethrows.
+ *
+ * `send` is a thunk rather than a request body because the body has to be rebuilt from the
+ * latched flags: `relaxTools` applies to the tools that were just sanitised, and
+ * `stream_options` is present or absent rather than adjusted. It is generic over what it
+ * resolves, so a caller whose request resolves a stream object before any chunk is read is the
+ * same shape as one that resolves a finished turn.
+ *
+ * It is handed the `produced` flag rather than being expected to close over one. There is only
+ * ever one flag in a turn — the same box `streamTurn` sets and the re-send below reads — and a
+ * caller that passed it to only one of the two got a turn that had already streamed tokens sent
+ * again, silently, with the watcher seeing every one of them twice.
+ */
+export async function negotiate(supports, send, { produced = { any: false }, onNotice } = {}) {
+    for (;;) {
+        try {
+            return await send(supports, produced);
+        }
+        catch (error) {
+            if (produced.any)
+                throw error;
+            const detail = errorMessage(error);
+            if (supports.strictSchemas && isGrammarError(detail)) {
+                supports.strictSchemas = false;
+                onNotice?.("server could not build a grammar; retrying without pattern/format");
+            }
+            else if (supports.usageInStream && REJECTS_USAGE.test(detail)) {
+                supports.usageInStream = false;
+                onNotice?.("server rejected stream_options; token counts unavailable");
+            }
+            else {
+                throw error;
+            }
+        }
+    }
+}

package/dist/client.d.ts

@@ -24,8 +24,10 @@ export declare function listModels(config: Endpoint): Promise<ModelInfo[]>;
  * happily load a 256k model at `-c 16384` and go on listing it as 256k — and a run refused on
  * the honest-looking number is a run that fails at the endpoint instead.
  *
- * Otherwise the listing is asked, once per endpoint. A server that will not list models still
- * has to be able to run a turn: a failure here is an unknown window, not a failed run.
+ * Otherwise the endpoint's listing is asked — once, and again whenever it does not name this
+ * model, since a model can arrive after the first listing was taken. A server that will not
+ * list models still has to be able to run a turn: a failure here is an unknown window, not a
+ * failed run.
  */
 export declare function contextLimitFor(config: Endpoint & {
     model: string;

package/dist/client.js

@@ -63,8 +63,8 @@ function contextLengthOf(model) {
  *
  * Keyed the same way the clients are, because two endpoints are two different sets of models
  * and one of them having answered says nothing about the other. It is only ever a cache of
- * something asked for anyway: nothing here refreshes it, and a listing that fails leaves
- * whatever was there rather than emptying it.
+ * something asked for anyway, and a listing that fails leaves whatever was there rather than
+ * emptying it.
  */
 const listings = new Map();
 const endpointKey = (config) => JSON.stringify([config.baseUrl, config.apiKey || NO_KEY]);
@@ -85,15 +85,28 @@ export async function listModels(config) {
  * happily load a 256k model at `-c 16384` and go on listing it as 256k — and a run refused on
  * the honest-looking number is a run that fails at the endpoint instead.
  *
- * Otherwise the listing is asked, once per endpoint. A server that will not list models still
- * has to be able to run a turn: a failure here is an unknown window, not a failed run.
+ * Otherwise the endpoint's listing is asked — once, and again whenever it does not name this
+ * model, since a model can arrive after the first listing was taken. A server that will not
+ * list models still has to be able to run a turn: a failure here is an unknown window, not a
+ * failed run.
  */
 export async function contextLimitFor(config, declared = 0) {
     if (declared > 0)
         return declared;
-    // A failure is not remembered: an endpoint that was down when the last run started is not an
-    // endpoint with no models, and the one listing this costs is nothing beside the run itself.
-    if (!listings.has(endpointKey(config))) {
+    const key = endpointKey(config);
+    // The listing is asked for again when it does not name this model, rather than only when
+    // there is no listing at all. Models arrive after a process starts — an `ollama pull` on a
+    // box that has been up a week, a worker added to a router, a name the operator has only just
+    // typed into settings — and a cache keyed on "we have asked once" answers zero for every one
+    // of them until a restart. Zero means "nobody knows", so what the operator loses is the
+    // context meter and, in a consumer that compacts on it, compaction: the session then runs at
+    // the window instead of under it and fails against the endpoint's own refusal.
+    //
+    // The cost of asking again is one listing per call while the model really is absent, which
+    // is exactly the case where the cached answer would have been wrong.
+    if (!listings.get(key)?.some((model) => model.id === config.model)) {
+        // A failure is not remembered: an endpoint that was down when the last run started is not
+        // an endpoint with no models, and a window nobody could ask about is not a failed run.
         try {
             await listModels(config);
         }
@@ -101,7 +114,7 @@ export async function contextLimitFor(config, declared = 0) {
             return 0;
         }
     }
-    const listed = listings.get(endpointKey(config)) ?? [];
+    const listed = listings.get(key) ?? [];
     return listed.find((model) => model.id === config.model)?.contextLength ?? 0;
 }
 /** Forgets every cached client and listing. For tests, and for a settings change under test. */

package/dist/events.d.ts

@@ -61,8 +61,20 @@ export interface RunEvent {
     /** Running totals on `usage`, otherwise null. */
     usage: RunUsage | null;
 }
-/** What `emit` is given: the run and the sequence are the bus's to assign. */
-export type RunEventInput = Pick<RunEvent, "kind"> & Partial<Omit<RunEvent, "kind">>;
+/**
+ * What `emit` is given: the run and the sequence are the bus's to assign.
+ *
+ * Named exclusions rather than a blanket `Partial`, which permitted both and let the spread in
+ * `emit` overwrite them — a caller could file an event under another run and hand every watcher
+ * a duplicate `seq`, which is the one thing the sequence is for.
+ */
+export type RunEventInput = Pick<RunEvent, "kind"> & Partial<Omit<RunEvent, "kind" | "runId" | "seq">>;
+/**
+ * Forgets a run that will not be emitting `done` — one whose process is tearing down, or whose
+ * loop threw where it could not be caught. The sweep gets there on its own; this is for a
+ * caller that already knows.
+ */
+export declare function endRun(runId: string): void;
 /** Records one event and hands it to everyone watching that run. Never throws at the caller. */
 export declare function emit(runId: string, input: RunEventInput): RunEvent;
 /**

package/dist/events.js

@@ -27,16 +27,56 @@ const streamFor = (runId) => {
     const existing = streams.get(runId);
     if (existing)
         return existing;
-    const stream = { events: [], listeners: new Set(), seq: 0 };
+    const stream = {
+        events: [],
+        listeners: new Set(),
+        seq: 0,
+        touched: Date.now(),
+        ended: false,
+    };
     streams.set(runId, stream);
     return stream;
 };
+/**
+ * Drops the streams nobody is reading and nothing is writing to.
+ *
+ * Cleanup used to hang entirely off `done`, which assumed every run reaches it. A run killed by
+ * an uncaught throw, a signal, or a caller that simply forgets pinned its backlog for the life
+ * of the process — and in a long-lived server that map only ever grew. The `done` timer had the
+ * same shape of hole from the other end: if a watcher was still attached when it fired it
+ * deleted nothing and nothing rescheduled it, so any client slow enough to still be reading a
+ * minute after the end leaked the stream permanently.
+ *
+ * One timer for the whole map, rescheduled only while there is something in it to expire.
+ */
+let sweeping = null;
+function sweep() {
+    sweeping = null;
+    const deadline = Date.now() - RETAIN_MS;
+    for (const [runId, stream] of streams) {
+        if (stream.listeners.size === 0 && stream.touched <= deadline)
+            streams.delete(runId);
+    }
+    scheduleSweep();
+}
+function scheduleSweep() {
+    if (sweeping || streams.size === 0)
+        return;
+    sweeping = setTimeout(sweep, RETAIN_MS);
+    sweeping.unref?.();
+}
+/**
+ * Forgets a run that will not be emitting `done` — one whose process is tearing down, or whose
+ * loop threw where it could not be caught. The sweep gets there on its own; this is for a
+ * caller that already knows.
+ */
+export function endRun(runId) {
+    streams.delete(runId);
+}
 /** Records one event and hands it to everyone watching that run. Never throws at the caller. */
 export function emit(runId, input) {
     const stream = streamFor(runId);
     const event = {
-        runId,
-        seq: ++stream.seq,
         at: new Date(),
         text: "",
         name: "",
@@ -44,20 +84,27 @@ export function emit(runId, input) {
         ok: null,
         usage: null,
         ...input,
+        // After the spread, not before: these are the bus's and a caller does not get a say.
+        runId,
+        seq: ++stream.seq,
     };
     stream.events.push(event);
+    stream.touched = event.at.getTime();
     if (stream.events.length > MAX_EVENTS + TRIM_SLACK) {
         stream.events.splice(0, stream.events.length - MAX_EVENTS);
     }
-    for (const listener of stream.listeners)
-        listener(event);
-    if (event.kind === "done") {
-        // Kept for a moment so a watcher that arrives just after the end still sees how it went,
-        // then dropped: a finished run's record is the row, not this.
-        setTimeout(() => {
-            if (streams.get(runId) === stream && stream.listeners.size === 0)
-                streams.delete(runId);
-        }, RETAIN_MS).unref?.();
+    // Kept for a moment so a watcher that arrives just after the end still sees how it went,
+    // then dropped: a finished run's record is the row, not this.
+    if (event.kind === "done")
+        stream.ended = true;
+    scheduleSweep();
+    for (const listener of stream.listeners) {
+        // The guarantee above is the point of this: a listener that throws must not take out the
+        // emitter, the listeners after it, or the bookkeeping already done above.
+        try {
+            listener(event);
+        }
+        catch { }
     }
     return event;
 }
@@ -95,15 +142,22 @@ export async function* watch(runId) {
     finally {
         stream.listeners.delete(listener);
         // A watcher can name a run that has not started, or will never start. Nothing was recorded
-        // under it, so nothing is left behind either.
-        if (stream.listeners.size === 0 && stream.events.length === 0)
+        // under it, so nothing is left behind either — and a run that has ended has nothing more to
+        // say to anyone, so the last watcher leaving takes the backlog with it.
+        if (stream.listeners.size === 0 && (stream.ended || stream.events.length === 0)) {
             streams.delete(runId);
+        }
     }
 }
 /** The backlog alone, for a caller that wants a snapshot rather than a subscription. */
 export const history = (runId) => [...(streams.get(runId)?.events ?? [])];
 /** Test seam: forget every run, so one test's events cannot be read by the next. */
-export const reset = () => streams.clear();
+export const reset = () => {
+    streams.clear();
+    if (sweeping)
+        clearTimeout(sweeping);
+    sweeping = null;
+};
 /**
  * Consecutive tokens of one kind are one thing being said, not hundreds of things.
  *
@@ -126,7 +180,10 @@ export function fold(events) {
             };
         }
         else {
-            blocks.push(event);
+            // A copy, because the merged branch above makes one and the caller cannot tell which
+            // branch its events took. Pushing the stored object let `fold(history(id))[0].text = ...`
+            // rewrite the bus, and every watcher after it read the rewrite.
+            blocks.push({ ...event });
         }
     }
     return blocks;

package/dist/index.d.ts

@@ -3,17 +3,22 @@
  *
  * What is here is everything that does not know what the agent is *for*: making a tool schema
  * a strict server will accept, getting tool definitions in front of a model without paying for
- * all of them, one-shot calls that support a run, the event bus a watcher reads, a pooled
- * client, and the rules about retrying. What is not here is the work — orchestration, prompts,
- * and whatever the run is about — because that is the caller's, and it is the part that differs
- * between one server and the next.
+ * all of them, reading one streamed turn back into a message, answering an endpoint that
+ * refuses one of those, one-shot calls that support a run, the event bus a watcher reads, a
+ * pooled client, and the rules about retrying. What is not here is the work — orchestration,
+ * prompts, and whatever the run is about — because that is the caller's, and it is the part
+ * that differs between one server and the next.
  */
+export { type Capabilities, capabilitiesFor, type NegotiateOptions, negotiate, resetCapabilities, } from "./capabilities.ts";
 export type { CatalogServer } from "./catalog.ts";
 export { contextLimitFor, getClient, listModels, type ModelInfo, NO_KEY, resetClients, timeoutMs, } from "./client.ts";
 export type { AgentConfig, Endpoint, ModelParams, RetryPolicy, ToolPolicy, } from "./config.ts";
 export { errorMessage } from "./errors.ts";
-export { emit, fold, history, type RunEvent, type RunEventInput, type RunEventKind, type RunUsage, reset, watch, } from "./events.ts";
+export { emit, endRun, fold, history, type RunEvent, type RunEventInput, type RunEventKind, type RunUsage, reset, watch, } from "./events.ts";
+export { resetAll } from "./reset.ts";
 export { backoffMs, ContextOverflow, compact, EndpointSilent, isOverflow, isTransient, requestTokens, SMALLEST_LIKELY_WINDOW, sleep, } from "./retry.ts";
 export { isGrammarError, relaxTools, sanitizeTools } from "./schema-compat.ts";
-export { ask, clean, estimateTokens, listLines, parseJson, type SideTaskOptions, tryAsk, } from "./side-task.ts";
+export { ask, clean, listLines, parseJson, resetHints, type SideTaskOptions, tryAsk, } from "./side-task.ts";
+export { type Produced, type StreamTurnOptions, streamTurn, type Turn, type TurnUsage, } from "./stream.ts";
+export { estimateTokens } from "./tokens.ts";
 export { carryOver, catalogList, catalogPrompt, expandNames, inCatalog, LOAD_TOOLS, LOAD_TOOLS_DEFINITION, loadResult, MAX_CARRIED, MAX_PER_LOAD, PRESELECT_SYSTEM, preselectInput, preselection, requestedNames, } from "./tool-loading.ts";

package/dist/index.js

@@ -3,15 +3,20 @@
  *
  * What is here is everything that does not know what the agent is *for*: making a tool schema
  * a strict server will accept, getting tool definitions in front of a model without paying for
- * all of them, one-shot calls that support a run, the event bus a watcher reads, a pooled
- * client, and the rules about retrying. What is not here is the work — orchestration, prompts,
- * and whatever the run is about — because that is the caller's, and it is the part that differs
- * between one server and the next.
+ * all of them, reading one streamed turn back into a message, answering an endpoint that
+ * refuses one of those, one-shot calls that support a run, the event bus a watcher reads, a
+ * pooled client, and the rules about retrying. What is not here is the work — orchestration,
+ * prompts, and whatever the run is about — because that is the caller's, and it is the part
+ * that differs between one server and the next.
  */
+export { capabilitiesFor, negotiate, resetCapabilities, } from "./capabilities.js";
 export { contextLimitFor, getClient, listModels, NO_KEY, resetClients, timeoutMs, } from "./client.js";
 export { errorMessage } from "./errors.js";
-export { emit, fold, history, reset, watch, } from "./events.js";
+export { emit, endRun, fold, history, reset, watch, } from "./events.js";
+export { resetAll } from "./reset.js";
 export { backoffMs, ContextOverflow, compact, EndpointSilent, isOverflow, isTransient, requestTokens, SMALLEST_LIKELY_WINDOW, sleep, } from "./retry.js";
 export { isGrammarError, relaxTools, sanitizeTools } from "./schema-compat.js";
-export { ask, clean, estimateTokens, listLines, parseJson, tryAsk, } from "./side-task.js";
+export { ask, clean, listLines, parseJson, resetHints, tryAsk, } from "./side-task.js";
+export { streamTurn, } from "./stream.js";
+export { estimateTokens } from "./tokens.js";
 export { carryOver, catalogList, catalogPrompt, expandNames, inCatalog, LOAD_TOOLS, LOAD_TOOLS_DEFINITION, loadResult, MAX_CARRIED, MAX_PER_LOAD, PRESELECT_SYSTEM, preselectInput, preselection, requestedNames, } from "./tool-loading.js";

package/dist/reset.d.ts

@@ -0,0 +1,20 @@
+/**
+ * Forgets everything this package remembers between calls.
+ *
+ * Four modules here keep state for the life of the process, each for a good reason and each
+ * with its own seam: the pooled clients and their model listings, the endpoints that turned
+ * out not to take `stream_options` or a grammar, the models that refused the no-thinking
+ * hints, and the event bus. `resetClients`, `resetCapabilities`, `resetHints` and `reset` stay
+ * exported, because a test that means to clear one thing should say so.
+ *
+ * This is for the other case, which is every teardown. What all four hold is *latched
+ * refusals* — a fact one test taught the process about an endpoint, still true as far as the
+ * next test can tell. Miss one and the suite becomes order-dependent in the way that passes
+ * locally and fails in CI on a different shard: the test that latched it still passes, and the
+ * one that reads the latch fails only when it happens to run second. `tests/side-task-hints.test.ts`
+ * was written that way and only passed because every case had been handed a hostname of its own.
+ *
+ * It is also the seam that does not need finding again. A fifth module with a cache is a fifth
+ * line here, rather than an edit to the teardown of three consumers who will not all notice.
+ */
+export declare function resetAll(): void;

package/dist/reset.js

@@ -0,0 +1,29 @@
+import { resetCapabilities } from "./capabilities.js";
+import { resetClients } from "./client.js";
+import { reset as resetEvents } from "./events.js";
+import { resetHints } from "./side-task.js";
+/**
+ * Forgets everything this package remembers between calls.
+ *
+ * Four modules here keep state for the life of the process, each for a good reason and each
+ * with its own seam: the pooled clients and their model listings, the endpoints that turned
+ * out not to take `stream_options` or a grammar, the models that refused the no-thinking
+ * hints, and the event bus. `resetClients`, `resetCapabilities`, `resetHints` and `reset` stay
+ * exported, because a test that means to clear one thing should say so.
+ *
+ * This is for the other case, which is every teardown. What all four hold is *latched
+ * refusals* — a fact one test taught the process about an endpoint, still true as far as the
+ * next test can tell. Miss one and the suite becomes order-dependent in the way that passes
+ * locally and fails in CI on a different shard: the test that latched it still passes, and the
+ * one that reads the latch fails only when it happens to run second. `tests/side-task-hints.test.ts`
+ * was written that way and only passed because every case had been handed a hostname of its own.
+ *
+ * It is also the seam that does not need finding again. A fifth module with a cache is a fifth
+ * line here, rather than an edit to the teardown of three consumers who will not all notice.
+ */
+export function resetAll() {
+    resetClients();
+    resetCapabilities();
+    resetHints();
+    resetEvents();
+}

package/dist/retry.js

@@ -1,5 +1,5 @@
 import OpenAI from "openai";
-import { estimateTokens } from "./side-task.js";
+import { estimateTokens } from "./tokens.js";
 /**
  * Everything about a request failing that is not about what the request said.
  *
@@ -44,7 +44,19 @@ const OVERFLOW = [
     /too (long|large) for/i,
     /reduce the length/i,
 ];
-export const isOverflow = (detail) => OVERFLOW.some((pattern) => pattern.test(detail)) && /token|context/i.test(detail);
+/**
+ * A rate limit says the same words and means the opposite thing.
+ *
+ * OpenAI refuses a request over the per-minute token budget with "Request too large for gpt-4o
+ * ... on tokens per min (TPM)", which is "too large for" beside "tokens" — both halves of the
+ * test below. That is a 429, which `isTransient` accepts and which succeeds on the next attempt;
+ * reading it as an overflow turned it into a `ContextOverflow`, whose whole purpose is that
+ * nothing retries it. The two classifiers in this file disagreed about one error.
+ */
+const RATE_LIMITED = /per (min|hour|day)|rate.?limit|\b[tr]pm\b|quota/i;
+export const isOverflow = (detail) => !RATE_LIMITED.test(detail) &&
+    OVERFLOW.some((pattern) => pattern.test(detail)) &&
+    /token|context/i.test(detail);
 /**
  * Below this, the window is nobody's business and is not asked for.
  *

package/dist/schema-compat.js

@@ -97,16 +97,97 @@ function collapseNullableUnion(node) {
 }
 /** Combinators at the top level of a parameters schema; strict backends reject them outright. */
 const TOP_LEVEL_COMBINATORS = ["allOf", "anyOf", "oneOf", "enum", "not"];
+/** `#/definitions/Args` or `#/$defs/Args` — a pointer into this schema's own definitions. */
+const LOCAL_POINTER = /^#\/(definitions|\$defs)\/([^/]+)$/;
+/**
+ * Replaces a root-level `$ref` with what it points at.
+ *
+ * Dropping the siblings of a `$ref` is right at a nested position and wrong at this one: the
+ * siblings here are the `definitions` the pointer needs, so the reference is left dangling and
+ * `properties` is then backfilled empty below. The tool goes out advertising no arguments at
+ * all — which the model cannot detect and the server has no reason to refuse. A schema
+ * generator emits this shape whenever the argument object is a named type.
+ */
+function inlineRootRef(parameters) {
+    const defs = {};
+    for (const key of ["definitions", "$defs"])
+        if (isObject(parameters[key]))
+            defs[key] = parameters[key];
+    const seen = new Set();
+    let node = parameters;
+    while (typeof node.$ref === "string") {
+        const pointer = node.$ref;
+        const target = LOCAL_POINTER.exec(pointer);
+        // A pointer at another document, or one that comes back to itself, has nothing here to
+        // resolve against. An object with no properties is at least honest about taking none.
+        if (!target || seen.has(pointer))
+            return EMPTY_OBJECT();
+        seen.add(pointer);
+        const pool = defs[target[1]];
+        const resolved = isObject(pool) ? pool[target[2]] : undefined;
+        if (!isObject(resolved))
+            return EMPTY_OBJECT();
+        node = resolved;
+    }
+    // The definitions travel with it: whatever the target refers to still lives in them.
+    return node === parameters ? parameters : { ...node, ...defs };
+}
+/**
+ * Folds a root `allOf` into the root itself.
+ *
+ * It is the other way a generated schema spells "the arguments are this named type", and
+ * deleting it outright below threw the arguments away while leaving the `required` that named
+ * them. Branches that are references are not something to guess at — those fall through to
+ * `pruneRequired`, which at least keeps the result self-consistent.
+ */
+function mergeRootAllOf(out) {
+    const branches = out.allOf;
+    if (!Array.isArray(branches))
+        return;
+    const properties = isObject(out.properties) ? { ...out.properties } : {};
+    const required = new Set(Array.isArray(out.required) ? out.required.filter((name) => typeof name === "string") : []);
+    for (const branch of branches) {
+        if (!isObject(branch) || "$ref" in branch)
+            continue;
+        if (isObject(branch.properties))
+            Object.assign(properties, branch.properties);
+        if (Array.isArray(branch.required))
+            for (const name of branch.required)
+                if (typeof name === "string")
+                    required.add(name);
+    }
+    if (!Object.keys(properties).length)
+        return;
+    out.properties = properties;
+    if (required.size)
+        out.required = [...required];
+}
+/**
+ * A required argument that is not in `properties` is one no caller can supply and no strict
+ * validator will accept. Anything the rewrites above removed, `required` may still name.
+ */
+function pruneRequired(out) {
+    if (!Array.isArray(out.required))
+        return;
+    const properties = isObject(out.properties) ? out.properties : {};
+    const kept = out.required.filter((name) => typeof name === "string" && name in properties);
+    if (kept.length)
+        out.required = kept;
+    else
+        delete out.required;
+}
 function sanitizeParameters(parameters) {
     if (!isObject(parameters))
         return EMPTY_OBJECT();
-    const out = normalize(parameters);
+    const out = normalize(inlineRootRef(parameters));
+    mergeRootAllOf(out);
     for (const key of TOP_LEVEL_COMBINATORS)
         delete out[key];
     if (out.type !== "object")
         out.type = "object";
     if (!isObject(out.properties))
         out.properties = {};
+    pruneRequired(out);
     return out;
 }
 const mapTools = (tools, fn) => tools.map((tool) => tool.type === "function"
@@ -135,6 +216,14 @@ export const sanitizeTools = (tools) => tools.map((tool) => {
  * re-validates anyway.
  */
 export function relaxTools(tools) {
+    /**
+     * Walked as a schema rather than as arbitrary JSON, because `pattern` and `format` are
+     * keyword names and perfectly ordinary argument names at once. Matching on the key alone
+     * deleted a *property* called `format` along with the keyword, leaving the parent's
+     * `required` naming an argument that no longer existed — which every strict validator
+     * rejects, so the retry produced the failure it was reaching for. The same distinction keeps
+     * the walk out of `default`, `enum` and `const`, whose contents are data, not schema.
+     */
     const strip = (node) => {
         if (Array.isArray(node))
             return node.map(strip);
@@ -144,7 +233,13 @@ export function relaxTools(tools) {
         for (const [key, value] of Object.entries(node)) {
             if (key === "pattern" || key === "format")
                 continue;
-            out[key] = strip(value);
+            if (SCHEMA_KEYS.has(key))
+                out[key] = Array.isArray(value) ? value.map(strip) : strip(value);
+            else if (SCHEMA_MAPS.has(key) && isObject(value))
+                // The keys here are argument names; only the values are schemas.
+                out[key] = Object.fromEntries(Object.entries(value).map(([name, sub]) => [name, strip(sub)]));
+            else
+                out[key] = value;
         }
         return out;
     };

package/dist/side-task.d.ts

@@ -1,4 +1,6 @@
 import type { Endpoint } from "./config.ts";
+/** Test seam, alongside `resetClients` and `reset`: forget which models refused the hints. */
+export declare const resetHints: () => void;
 export interface SideTaskOptions {
     maxTokens?: number;
     temperature?: number;
@@ -24,14 +26,3 @@ export declare const clean: (line: string) => string;
  * squinted at is worse than one fewer suggestion.
  */
 export declare const listLines: (text: string, max: number, maxChars: number) => string[];
-/**
- * Rough token count. Characters over four, because there is no tokenizer here and there is not
- * going to be one: a server that will not say how big its window is will not lend us its
- * vocabulary either.
- *
- * The estimate runs low on tool schemas — JSON packs more tokens into a character than prose
- * does — and that is the side to be wrong on wherever it guards a window, since the cost of
- * guessing high is a run refused that would have worked, and the cost of guessing low is the
- * endpoint's own refusal, which is where we were before the guard existed.
- */
-export declare const estimateTokens: (text: string) => number;

package/dist/side-task.js

@@ -1,5 +1,7 @@
 import OpenAI from "openai";
 import { getClient } from "./client.js";
+import { errorMessage } from "./errors.js";
+import { isTransient } from "./retry.js";
 /**
  * One-shot calls that support a run without being one: picking tools, naming a session,
  * summarising a transcript, proposing follow-ups. They share a shape — small prompt, short
@@ -17,30 +19,49 @@ const NO_THINKING = {
     chat_template_kwargs: { enable_thinking: false },
 };
 /**
- * The endpoints that turned out not to take the hints, by base URL.
+ * The models that turned out not to take the hints, by endpoint and model.
  *
  * Keyed rather than global for the reason the client cache is keyed: a refusal is a fact about
- * the server on the other end, not about this process. A llama.cpp box and a cloud API are both
+ * what is on the other end, not about this process. A llama.cpp box and a cloud API are both
  * reachable from one consumer over its lifetime, and the first one's refusal must not stop the
  * second from ever being asked.
+ *
+ * The model belongs in the key for the same reason. One base URL is routinely many models —
+ * OpenRouter, LiteLLM, vLLM serving several at once — and whether `reasoning_effort` is
+ * understood is a property of the model behind the route, not of the route. Keyed on the host
+ * alone, the first model to refuse spoke for every model on it.
  */
 const noHints = new Set();
+const hintKey = (baseUrl, model) => JSON.stringify([baseUrl, model]);
+/** Test seam, alongside `resetClients` and `reset`: forget which models refused the hints. */
+export const resetHints = () => noHints.clear();
 /**
  * Whether a failure is the server complaining about the request, rather than failing to answer.
  *
  * The retry below used to catch everything, so an aborted first call — or a connection that
  * never landed — latched the hints off for the life of the process and every later side task
- * paid for it by burning a whole budget on deliberation. Only a 4xx says the fields were the
- * problem; a timeout, a refused connection or a 500 say nothing about them at all.
+ * paid for it by burning a whole budget on deliberation. Narrowing that to any 4xx was still
+ * too wide: 401, 404 and 429 are all 4xx and none of them is about the fields. A 429 was the
+ * worst of them, because the retry then re-sent the whole request immediately — doubling the
+ * rate against a server that had just asked for less of it — and `isTransient` accepts exactly
+ * that status, so the two halves of this package disagreed about one error.
+ *
+ * 400 and 422 are what a server says when it read the body and disliked it. Everything else
+ * is left to the caller's own retry.
  */
 function rejectedTheRequest(error) {
-    if (!(error instanceof OpenAI.APIError))
+    if (!(error instanceof OpenAI.APIError) || isTransient(error))
         return false;
-    const status = error.status ?? 0;
-    return status >= 400 && status < 500;
+    return error.status === 400 || error.status === 422;
 }
-/** Reasoning models that ignore the hints still fence their scratchpad; drop it. */
-const stripThinking = (text) => text.replace(/<think>[\s\S]*?<\/think>/gi, "");
+/**
+ * Reasoning models that ignore the hints still fence their scratchpad; drop it.
+ *
+ * Including the fence that never closes. A side task answers under a small `max_tokens`, so a
+ * model that spends it deliberating is cut off mid-scratchpad and the closing tag never
+ * arrives — and the whole deliberation was then returned to the caller as the answer.
+ */
+const stripThinking = (text) => text.replace(/<think>[\s\S]*?<\/think>/gi, "").replace(/<think>[\s\S]*$/i, "");
 /** Runs a side task and returns the reply text, thinking stripped. Throws like any request. */
 export async function ask(config, model, system, user, { maxTokens = 512, temperature = 0.3, signal } = {}) {
     const send = (hints) => getClient(config).chat.completions.create({
@@ -53,7 +74,8 @@ export async function ask(config, model, system, user, { maxTokens = 512, temper
         ],
         ...(hints ? NO_THINKING : {}),
     }, { signal });
-    const hints = !noHints.has(config.baseUrl);
+    const key = hintKey(config.baseUrl, model);
+    const hints = !noHints.has(key);
     let response;
     try {
         response = await send(hints);
@@ -62,10 +84,17 @@ export async function ask(config, model, system, user, { maxTokens = 512, temper
         if (!hints || !rejectedTheRequest(error))
             throw error;
         console.warn("[side-task] server rejected the no-thinking hints; retrying without them");
-        noHints.add(config.baseUrl);
+        noHints.add(key);
         response = await send(false);
     }
-    return stripThinking(response.choices[0]?.message?.content ?? "").trim();
+    const message = response.choices[0]?.message;
+    const answer = stripThinking(message?.content ?? "").trim();
+    // Nothing but scratchpad. Some servers put the deliberation in its own field and leave the
+    // content genuinely empty, in which case there is no answer to find anywhere else.
+    if (answer)
+        return answer;
+    const reasoning = message?.reasoning_content;
+    return typeof reasoning === "string" ? stripThinking(reasoning).trim() : "";
 }
 /**
  * A side task is never worth failing the work it supports. Callers that can carry on without
@@ -76,7 +105,11 @@ export async function tryAsk(label, run) {
         return await run();
     }
     catch (error) {
-        console.warn(`[side-task] ${label}:`, error.message);
+        // A cancelled run is not a failed side task. Swallowing the abort made the two
+        // indistinguishable and left the cancellation with nowhere to go.
+        if (error instanceof OpenAI.APIUserAbortError)
+            throw error;
+        console.warn(`[side-task] ${label}:`, errorMessage(error));
         return undefined;
     }
 }
@@ -116,14 +149,3 @@ export const listLines = (text, max, maxChars) => text
     .map(clean)
     .filter((line) => line.length > 0 && line.length <= maxChars)
     .slice(0, max);
-/**
- * Rough token count. Characters over four, because there is no tokenizer here and there is not
- * going to be one: a server that will not say how big its window is will not lend us its
- * vocabulary either.
- *
- * The estimate runs low on tool schemas — JSON packs more tokens into a character than prose
- * does — and that is the side to be wrong on wherever it guards a window, since the cost of
- * guessing high is a run refused that would have worked, and the cost of guessing low is the
- * endpoint's own refusal, which is where we were before the guard existed.
- */
-export const estimateTokens = (text) => Math.ceil(text.length / 4);

package/dist/stream.d.ts

@@ -0,0 +1,63 @@
+import type OpenAI from "openai";
+/**
+ * Reading one streamed turn back into a message.
+ *
+ * The rest of a request is the caller's — which model, which tools, which transcript — but the
+ * reading of the answer is the same everywhere, and it is fiddly in ways the API does not
+ * advertise: tool calls arrive in pieces, an aborted stream ends rather than throws, reasoning
+ * has two spellings and is in no published type, and an endpoint that stops answering mid-stream
+ * hangs the turn until somebody presses stop. `EndpointSilent` and `timeoutMs` were exported for
+ * this loop long before the loop itself was.
+ */
+/** What a turn cost. Zero throughout means the server did not say. */
+export interface TurnUsage {
+    prompt: number;
+    completion: number;
+    total: number;
+}
+/** One streamed turn, put back together into the shape a loop and a transcript work with. */
+export interface Turn {
+    content: string;
+    toolCalls: OpenAI.ChatCompletionMessageToolCall[];
+    usage: TurnUsage;
+}
+/**
+ * Whether the server has started answering.
+ *
+ * A box rather than a return value because it has to be readable *while* the request is in
+ * flight: the rules in `retry.ts` are built on the premise that a stream which has already
+ * emitted tokens must never be replayed, and by the time a rejected promise is in hand the turn
+ * is over. There is one of these per attempt, shared by everything that has a say in whether
+ * the attempt is repeated. See `negotiate`.
+ */
+export interface Produced {
+    any: boolean;
+}
+export interface StreamTurnOptions {
+    signal?: AbortSignal;
+    /**
+     * Silence allowed before the request is given up on. Zero or undefined waits forever, which
+     * is what `timeoutMs` means by a timeout of zero and what a local model answering slowly
+     * needs.
+     */
+    idleMs?: number;
+    /** Set as soon as the server has said anything, so a failed call knows if it can be retried. */
+    produced?: Produced;
+    /** The model's scratchpad, as it arrives. */
+    onThinking?: (delta: string) => void;
+    /** The model's answer, as it arrives. */
+    onOutput?: (delta: string) => void;
+}
+/**
+ * Runs one turn as a stream, reporting tokens as they arrive and assembling them back into a
+ * message.
+ *
+ * Streaming buys no speed — nothing waits on the reply but the loop itself. It is what makes a
+ * run watchable: a run that stalls, loops, or reaches for the wrong tool says so while it is
+ * happening instead of only in the row it leaves behind.
+ *
+ * Two token callbacks rather than an event input, because a turn does not know which step of
+ * which run it is: `step` is the caller's flow concept, and wrapping these into an `emit` is one
+ * line at the call site.
+ */
+export declare function streamTurn(client: OpenAI, body: OpenAI.ChatCompletionCreateParamsStreaming, { signal, idleMs, produced, onThinking, onOutput }?: StreamTurnOptions): Promise<Turn>;

package/dist/stream.js

@@ -0,0 +1,104 @@
+import { EndpointSilent } from "./retry.js";
+/**
+ * Runs one turn as a stream, reporting tokens as they arrive and assembling them back into a
+ * message.
+ *
+ * Streaming buys no speed — nothing waits on the reply but the loop itself. It is what makes a
+ * run watchable: a run that stalls, loops, or reaches for the wrong tool says so while it is
+ * happening instead of only in the row it leaves behind.
+ *
+ * Two token callbacks rather than an event input, because a turn does not know which step of
+ * which run it is: `step` is the caller's flow concept, and wrapping these into an `emit` is one
+ * line at the call site.
+ */
+export async function streamTurn(client, body, { signal, idleMs, produced, onThinking, onOutput } = {}) {
+    // Silence, not duration: the timer is rearmed on every chunk, so a model that is still
+    // talking is never cut off however long it takes, and one that has stopped talking does not
+    // hang the run until someone notices. A request that never answers at all is the same case
+    // with no chunks in it, which is why the first arming happens before the request is sent.
+    const watchdog = new AbortController();
+    const linked = signal ? AbortSignal.any([signal, watchdog.signal]) : watchdog.signal;
+    let idle;
+    const rearm = () => {
+        if (!idleMs)
+            return;
+        clearTimeout(idle);
+        idle = setTimeout(() => watchdog.abort(), idleMs);
+    };
+    try {
+        rearm();
+        return await collect();
+    }
+    catch (error) {
+        // The caller's own stop has to stay distinguishable from ours: one is a run that was called
+        // off, the other is an endpoint that stopped answering and may be worth retrying. Getting
+        // this backwards records a stopped run as an endpoint fault, which nobody notices until
+        // they read the row and disbelieve it.
+        if (watchdog.signal.aborted && !signal?.aborted) {
+            throw new EndpointSilent(`the model endpoint sent nothing for ${(idleMs ?? 0) / 1000}s`);
+        }
+        throw error;
+    }
+    finally {
+        clearTimeout(idle);
+    }
+    async function collect() {
+        const stream = await client.chat.completions.create(body, { signal: linked });
+        const content = [];
+        const calls = new Map();
+        const usage = { prompt: 0, completion: 0, total: 0 };
+        for await (const chunk of stream) {
+            if (produced)
+                produced.any = true;
+            rearm();
+            // Assigned rather than accumulated. `stream_options.include_usage` sends one final chunk
+            // and the two agree there, but a server that reports cumulatively per chunk makes a sum
+            // of sums out of an accumulator — and a token count wrong by a factor of the chunk count
+            // is not a number anyone would attribute to the stream reader.
+            if (chunk.usage) {
+                usage.prompt = chunk.usage.prompt_tokens ?? 0;
+                usage.completion = chunk.usage.completion_tokens ?? 0;
+                usage.total = chunk.usage.total_tokens ?? 0;
+            }
+            const delta = chunk.choices[0]?.delta;
+            if (!delta)
+                continue;
+            const thinking = delta.reasoning_content || delta.reasoning || "";
+            if (thinking)
+                onThinking?.(thinking);
+            if (delta.content) {
+                content.push(delta.content);
+                onOutput?.(delta.content);
+            }
+            // Tool calls arrive in pieces, keyed by position: the id in one chunk, the name in
+            // another, the arguments spread across the next several.
+            for (const part of delta.tool_calls ?? []) {
+                const call = calls.get(part.index) ?? { id: "", name: "", arguments: "" };
+                if (part.id)
+                    call.id = part.id;
+                if (part.function?.name)
+                    call.name += part.function.name;
+                if (part.function?.arguments)
+                    call.arguments += part.function.arguments;
+                calls.set(part.index, call);
+            }
+        }
+        // An aborted stream ends its iteration rather than throwing, so without this a turn cut off
+        // halfway — by the watchdog or by someone stopping the run — comes back looking like a
+        // complete one, and a truncated answer is recorded as the output. Nothing about the API
+        // says you have to know this.
+        linked.throwIfAborted();
+        return {
+            content: content.join(""),
+            toolCalls: [...calls.entries()]
+                .sort(([a], [b]) => a - b)
+                .map(([index, call]) => ({
+                // A server that streams a call without an id still needs one for the result to answer.
+                id: call.id || `call_${index}`,
+                type: "function",
+                function: { name: call.name, arguments: call.arguments },
+            })),
+            usage,
+        };
+    }
+}

package/dist/tokens.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Rough token count. Characters over four, because there is no tokenizer here and there is not
+ * going to be one: a server that will not say how big its window is will not lend us its
+ * vocabulary either.
+ *
+ * The estimate runs low on tool schemas — JSON packs more tokens into a character than prose
+ * does — and that is the side to be wrong on wherever it guards a window, since the cost of
+ * guessing high is a run refused that would have worked, and the cost of guessing low is the
+ * endpoint's own refusal, which is where we were before the guard existed.
+ *
+ * Its own module because both `retry` and `side-task` need it and they now need each other:
+ * leaving it in `side-task` made the pair a cycle.
+ */
+export declare const estimateTokens: (text: string) => number;

package/dist/tokens.js

@@ -0,0 +1,14 @@
+/**
+ * Rough token count. Characters over four, because there is no tokenizer here and there is not
+ * going to be one: a server that will not say how big its window is will not lend us its
+ * vocabulary either.
+ *
+ * The estimate runs low on tool schemas — JSON packs more tokens into a character than prose
+ * does — and that is the side to be wrong on wherever it guards a window, since the cost of
+ * guessing high is a run refused that would have worked, and the cost of guessing low is the
+ * endpoint's own refusal, which is where we were before the guard existed.
+ *
+ * Its own module because both `retry` and `side-task` need it and they now need each other:
+ * leaving it in `side-task` made the pair a cycle.
+ */
+export const estimateTokens = (text) => Math.ceil(text.length / 4);

package/dist/tool-loading.d.ts

@@ -16,7 +16,13 @@ import type { CatalogServer } from "./catalog.ts";
 export declare const LOAD_TOOLS = "load_tools";
 /** One object for the life of the process — the agent loop asks for it on every iteration. */
 export declare const LOAD_TOOLS_DEFINITION: OpenAI.ChatCompletionTool;
-/** The catalogue as a plain grouped listing of names, loaded ones marked. */
+/**
+ * The catalogue as a plain grouped listing of names, loaded ones marked.
+ *
+ * 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.
+ */
 export declare function catalogList(catalog: CatalogServer[], loaded?: ReadonlySet<string>): string;
 /**
  * The catalogue block appended to the system prompt. Names only — descriptions arrive on load.

package/dist/tool-loading.js

@@ -35,9 +35,16 @@ export const LOAD_TOOLS_DEFINITION = {
         },
     },
 };
-/** The catalogue as a plain grouped listing of names, loaded ones marked. */
+/**
+ * The catalogue as a plain grouped listing of names, loaded ones marked.
+ *
+ * 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.
+ */
 export function catalogList(catalog, loaded) {
     return catalog
+        .filter((server) => server.tools.length > 0)
         .map((server) => {
         const names = server.tools.map((tool) => `  ${tool.name}${loaded?.has(tool.name) ? " (loaded)" : ""}`);
         return `${server.label}:\n${names.join("\n")}`;
@@ -53,7 +60,10 @@ export function catalogList(catalog, loaded) {
  * the longer list instead.
  */
 export function catalogPrompt(catalog, loaded) {
-    if (!catalog.length)
+    const list = catalogList(catalog, loaded);
+    // Not `catalog.length`: a catalogue of nothing but empty servers has no names to offer, and
+    // the preamble below would then explain a mechanism against an empty list.
+    if (!list)
         return "";
     return [
         "# Tool catalogue",
@@ -63,7 +73,7 @@ export function catalogPrompt(catalog, loaded) {
         "marked `(loaded)` is already in your tool list — call it directly, do not load it again. Do",
         "not load tools the task does not need, and do not mention this mechanism in your answer.",
         "",
-        catalogList(catalog, loaded),
+        list,
     ].join("\n");
 }
 const flatten = (catalog) => catalog.flatMap((server) => server.tools);
@@ -118,10 +128,24 @@ export function expandNames(requested, catalog) {
         const name = raw.trim();
         if (!name)
             continue;
+        // A bare `*` is not a guess at a name, it is a refusal to choose, and its empty stem
+        // prefixes every tool in the catalogue. Answer it the way any other over-broad request is
+        // answered: with the names, so the next call can pick from them.
+        if (name === "*") {
+            overBroad.push({ name, hits: all.map((tool) => tool.name) });
+            continue;
+        }
         const hits = resolve(name);
-        if (!hits.length)
+        if (!hits.length) {
             unknown.push(name);
-        else if (hits.length > MAX_PER_LOAD)
+            continue;
+        }
+        // The cap is what one call may load, not what one name may match: three wildcards of a
+        // dozen each cleared a per-name check and still put thirty-six definitions in front of a
+        // model that is meant to be choosing from twelve. Already-matched names are free, so a
+        // name that only repeats an earlier one never spends budget.
+        const fresh = hits.filter((hit) => !matched.has(hit));
+        if (matched.size + fresh.length > MAX_PER_LOAD)
             overBroad.push({ name, hits });
         else
             for (const hit of hits)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cubicecho/agent-core",
-  "version": "1.0.0",
+  "version": "1.2.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",
@@ -42,7 +42,7 @@
   "scripts": {
     "build": "tsc -p tsconfig.build.json",
     "prepare": "npm run build",
-    "typecheck": "tsc --noEmit",
+    "typecheck": "tsc -p tsconfig.tests.json",
     "test": "vitest run",
     "test:watch": "vitest",
     "lint": "biome check .",