@cubicecho/agent-core 1.3.0 → 2.0.1

package/README.md

@@ -27,10 +27,11 @@ only, Node >=22.
 | `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`. |
+| `retry` | What to do when a request is lost, refused or too big: `isTransient`, `backoffMs`, `ContextOverflow`, `EndpointSilent`, `requestTokens`. |
 | `config` | The structural interfaces every function here asks for. |
-| `run-turn` | `runTurn`: one turn with the retry loop around the negotiation around the stream. The whole loop, for a caller that wants it rather than its parts. |
+| `run-turn` | `runTurn`: one turn with the retry loop around the negotiation around the stream. The whole loop, for a caller that wants it rather than its parts. Sizes the request against an opt-in `contextLimit`. |
 | `reset` | `resetAll`: drops every cache and latch in one call, so a teardown cannot forget one. |
+| `tokens` | `estimateTokens`: characters over four, deliberately low, for everything here that has to guess at a window. |
 | `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. |
 
@@ -73,7 +74,29 @@ anything, and the re-send reads it — so a caller with its own retry budget pas
 `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.
+`requestTimeoutSeconds` of zero or absent, which waits forever — what a local model answering
+slowly needs.
+
+## Sizing a request before sending it
+
+`runTurn` will refuse a request that cannot fit rather than spending a round trip finding out:
+
+```ts
+import { contextLimitFor, runTurn } from "@cubicecho/agent-core";
+
+const turn = await runTurn(client, supports, build, {
+  maxRetries: 3,
+  // Opt-in: the number is the caller's to find. `contextLimitFor` asks the endpoint, and an
+  // operator's own setting overrides it — neither is network I/O a turn should be doing.
+  contextLimit: settings.contextLength || (await contextLimitFor(settings, model)),
+  onNotice: (message) => emit(runId, { kind: "notice", text: message }),
+});
+```
+
+The body is sized once, not per attempt: a downgraded request is strictly smaller than the one
+before it and the transcript does not change between retries. A `ContextOverflow` from this is
+neither a capability `negotiate` can answer nor something `isTransient` accepts, so it leaves
+both loops on the first attempt.
 
 ## The config seam
 
@@ -93,9 +116,8 @@ row has no `contextLength`; `min-agent` spells it `contextLimit` and carries no
 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.
+asks for the whole of `Endpoint`. `requestTimeoutSeconds` became optional in v2, so a consumer
+with no timeout to give now leaves it out rather than inventing a `0`.
 
 ## Where the merged behaviour came from
 

package/dist/client.d.ts

@@ -6,7 +6,7 @@ import type { Endpoint } from "./config.ts";
  * not — a caller must not let a local endpoint silently borrow the key meant for a paid one.
  */
 export declare const NO_KEY = "agent-core";
-/** Zero or less means no limit, which the SDK spells as `undefined`. */
+/** Zero, less, or absent means no limit, which the SDK spells as `undefined`. */
 export declare const timeoutMs: (config: Pick<Endpoint, "requestTimeoutSeconds">) => number | undefined;
 export declare function getClient(config: Endpoint): OpenAI;
 /** A model an endpoint offers, and what it says the model will read. Zero means it did not say. */

package/dist/client.js

@@ -5,8 +5,11 @@ import OpenAI from "openai";
  * not — a caller must not let a local endpoint silently borrow the key meant for a paid one.
  */
 export const NO_KEY = "agent-core";
-/** Zero or less means no limit, which the SDK spells as `undefined`. */
-export const timeoutMs = (config) => config.requestTimeoutSeconds > 0 ? config.requestTimeoutSeconds * 1000 : undefined;
+/** Zero, less, or absent means no limit, which the SDK spells as `undefined`. */
+export const timeoutMs = (config) => {
+    const seconds = config.requestTimeoutSeconds ?? 0;
+    return seconds > 0 ? seconds * 1000 : undefined;
+};
 /**
  * A client per endpoint, made once and kept.
  *

package/dist/config.d.ts

@@ -17,8 +17,15 @@ export interface Endpoint {
     baseUrl: string;
     /** Empty is normal — a local server ignores it. See `getClient` for what is sent instead. */
     apiKey: string;
-    /** Zero or less means no limit. */
-    requestTimeoutSeconds: number;
+    /**
+     * Zero, less, or absent means no limit — what a local model answering slowly needs.
+     *
+     * Optional because a consumer that has no timeout to give should not have to invent one. Two
+     * of the three servers this was extracted from carry no such field, and requiring it made
+     * them write `requestTimeoutSeconds: 0` to mean "I have no opinion", which is a made-up
+     * number standing in for an absent one.
+     */
+    requestTimeoutSeconds?: number;
 }
 /** What to ask the model for. */
 export interface ModelParams {

package/dist/events.d.ts

@@ -44,7 +44,15 @@ export interface RunEvent {
     runId: string;
     /** Per-run counter, from 1. Lets a client order and de-duplicate what it receives. */
     seq: number;
-    at: Date;
+    /**
+     * When it happened, as epoch milliseconds.
+     *
+     * A number rather than a `Date`: these events are read over a wire, where a `Date` is an ISO
+     * string by the time anyone sees it, and `emit` runs once per streamed token — so the object
+     * it does not allocate is one per token. It also spares the `getTime()` the sweep used to do
+     * to get this same number back out.
+     */
+    at: number;
     kind: RunEventKind;
     /** The delta, the arguments, the result, or the reason — whatever the kind carries. */
     text: string;
@@ -86,8 +94,14 @@ export declare function emit(runId: string, input: RunEventInput): RunEvent;
 export declare function watch(runId: string): AsyncGenerator<RunEvent>;
 /** The backlog alone, for a caller that wants a snapshot rather than a subscription. */
 export declare const history: (runId: string) => RunEvent[];
-/** Test seam: forget every run, so one test's events cannot be read by the next. */
-export declare const reset: () => void;
+/**
+ * Test seam: forget every run, so one test's events cannot be read by the next.
+ *
+ * Named for what it forgets rather than bare `reset`, which sat in a consumer's imports beside
+ * `resetAll`, `resetClients`, `resetCapabilities` and `resetHints` saying nothing about which
+ * of the five it was — `reset.ts` had to alias it on the way in to stay readable.
+ */
+export declare const resetEvents: () => void;
 /**
  * Consecutive tokens of one kind are one thing being said, not hundreds of things.
  *

package/dist/events.js

@@ -76,8 +76,10 @@ export function endRun(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);
+    // One clock read, used for both the event and the sweep's bookkeeping.
+    const at = Date.now();
     const event = {
-        at: new Date(),
+        at,
         text: "",
         name: "",
         step: "",
@@ -89,7 +91,7 @@ export function emit(runId, input) {
         seq: ++stream.seq,
     };
     stream.events.push(event);
-    stream.touched = event.at.getTime();
+    stream.touched = at;
     if (stream.events.length > MAX_EVENTS + TRIM_SLACK) {
         stream.events.splice(0, stream.events.length - MAX_EVENTS);
     }
@@ -116,17 +118,71 @@ export function emit(runId, input) {
  */
 export async function* watch(runId) {
     const stream = streamFor(runId);
-    const queue = [...stream.events];
+    // A cursor rather than `shift()`. Draining a backlog an event at a time off the front of an
+    // array is a copy of the whole array per event, which on the ten-thousand-delta run this bus
+    // is built for is the one quadratic left in the file. The prefix behind the cursor is dropped
+    // in one `slice` per `MAX_EVENTS` instead — the same amortised trade the bus itself makes.
+    let queue = [...stream.events];
+    let head = 0;
+    let dropped = 0;
     let wake = null;
     const listener = (event) => {
         queue.push(event);
+        // The bus caps its own backlog at `MAX_EVENTS`; without this the watcher downstream of it
+        // had no cap at all, so a client too slow to keep up held every delta a run ever emitted.
+        // The oldest go, which is what the backlog does, and the gap is reported once below.
+        //
+        // Dropped here means released here. Advancing the cursor alone left the dropped events in
+        // the slots behind it, to be freed by the compaction in the drain below — which a consumer
+        // that has stalled does not reach, and a stalled consumer is the whole reason for the cap.
+        // It read as capped and held every event anyway: 16MB where the cap promises a third of one.
+        const cut = queue.length - head - MAX_EVENTS;
+        if (cut > TRIM_SLACK) {
+            queue = queue.slice(head + cut);
+            head = 0;
+            dropped += cut;
+        }
         wake?.();
     };
     stream.listeners.add(listener);
     try {
         for (;;) {
-            while (queue.length > 0) {
-                const event = queue.shift();
+            while (head < queue.length) {
+                const event = queue[head++];
+                // What is behind the cursor is released rather than left there. Resetting only on catch-up
+                // was not enough: a watcher that keeps pace but never quite empties the queue never
+                // reaches that branch, and the array grows by a slot per event for the length of the run.
+                if (head === queue.length) {
+                    queue = [];
+                    head = 0;
+                }
+                else if (head > MAX_EVENTS) {
+                    queue = queue.slice(head);
+                    head = 0;
+                }
+                if (dropped > 0) {
+                    // Said once per gap rather than per event, and before the event that follows it, so a
+                    // client reading `seq` sees why the numbers jump instead of assuming it lost its place.
+                    //
+                    // One short of the event it precedes, which is the last seq that went missing. Sharing
+                    // a seq with the event behind it made the notice indistinguishable from a duplicate,
+                    // and de-duplicating on `seq` is the one thing the sequence is documented for — so a
+                    // client doing exactly that dropped either the gap notice or the event it explains.
+                    // Inside the gap there is nothing to collide with: those seqs reach no watcher.
+                    const gap = dropped;
+                    dropped = 0;
+                    yield {
+                        runId,
+                        seq: event.seq - 1,
+                        at: event.at,
+                        kind: "notice",
+                        text: `${gap} event(s) dropped: this watcher fell too far behind`,
+                        name: "",
+                        step: event.step,
+                        ok: null,
+                        usage: null,
+                    };
+                }
                 yield event;
                 // `done` is the last event a run will ever have, so the subscription completes rather
                 // than leaving the client holding an open stream that will never say anything again.
@@ -151,8 +207,14 @@ export async function* watch(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 = () => {
+/**
+ * Test seam: forget every run, so one test's events cannot be read by the next.
+ *
+ * Named for what it forgets rather than bare `reset`, which sat in a consumer's imports beside
+ * `resetAll`, `resetClients`, `resetCapabilities` and `resetHints` saying nothing about which
+ * of the five it was — `reset.ts` had to alias it on the way in to stay readable.
+ */
+export const resetEvents = () => {
     streams.clear();
     if (sweeping)
         clearTimeout(sweeping);
@@ -168,23 +230,37 @@ export const reset = () => {
  */
 export function fold(events) {
     const blocks = [];
+    // The text of the block still open, accumulated rather than re-concatenated. Rebuilding the
+    // block object per delta — a spread and a join of everything so far — is the same paragraph
+    // built ten thousand times to produce it once.
+    let parts = [];
+    const close = () => {
+        if (!parts.length)
+            return;
+        const last = blocks[blocks.length - 1];
+        if (parts.length > 1)
+            last.text = parts.join("");
+        parts = [];
+    };
     for (const event of events) {
         const last = blocks[blocks.length - 1];
         const mergeable = event.kind === "thinking" || event.kind === "output";
         if (last && mergeable && last.kind === event.kind && last.step === event.step) {
-            blocks[blocks.length - 1] = {
-                ...last,
-                seq: event.seq,
-                at: event.at,
-                text: last.text + event.text,
-            };
+            last.seq = event.seq;
+            last.at = event.at;
+            parts.push(event.text);
         }
         else {
-            // 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.
+            close();
+            // A copy, because the merged branch above writes into the block it returns 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 });
+            if (mergeable)
+                parts.push(event.text);
         }
     }
+    close();
     return blocks;
 }

package/dist/index.d.ts

@@ -14,7 +14,7 @@ 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, endRun, 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, resetEvents, 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 { type RunTurnOptions, runTurn } from "./run-turn.ts";

package/dist/index.js

@@ -12,7 +12,7 @@
 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, endRun, fold, history, reset, watch, } from "./events.js";
+export { emit, endRun, fold, history, resetEvents, 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 { runTurn } from "./run-turn.js";

package/dist/reset.d.ts

@@ -4,7 +4,7 @@
  * 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
+ * hints, and the event bus. `resetClients`, `resetCapabilities`, `resetHints` and `resetEvents` 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

package/dist/reset.js

@@ -1,6 +1,6 @@
 import { resetCapabilities } from "./capabilities.js";
 import { resetClients } from "./client.js";
-import { reset as resetEvents } from "./events.js";
+import { resetEvents } from "./events.js";
 import { resetHints } from "./side-task.js";
 /**
  * Forgets everything this package remembers between calls.
@@ -8,7 +8,7 @@ import { resetHints } from "./side-task.js";
  * 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
+ * hints, and the event bus. `resetClients`, `resetCapabilities`, `resetHints` and `resetEvents` 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

package/dist/retry.d.ts

@@ -23,17 +23,24 @@ export declare const compact: (tokens: number) => string;
 /**
  * What this request will cost the window, in tokens, near enough.
  *
- * 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, 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 this existed.
+ * See `estimateTokens` for why it is characters over four and which way it is wrong on purpose.
+ *
+ * Summed by walking the body rather than by serialising it. `JSON.stringify` on the messages
+ * built the entire transcript into a string on every call and threw it away having read nothing
+ * but its `.length` — against a transcript that grows by a turn each turn, and one the SDK is
+ * about to serialise again to send. What the walk misses is JSON's own punctuation and the keys,
+ * which `ENVELOPE` puts back approximately; the difference is a rounding error against an
+ * estimate that is already characters over four.
  */
 export declare const requestTokens: (body: OpenAI.ChatCompletionCreateParamsStreaming) => number;
 export declare const isOverflow: (detail: string) => boolean;
 /**
- * Below this, the window is nobody's business and is not asked for.
+ * The smallest window worth believing in, and the floor under both of its uses.
+ *
+ * `runTurn`'s `contextLimit` reads it as a sanity check on a number it was handed: below this,
+ * the limit is taken for a placeholder — an unset column, a listing that said nothing — rather
+ * than a window worth refusing a run over. `contextLimitFor` reads it as the point below which
+ * the window is nobody's business and is not asked for.
  *
  * Finding out what a model reads costs a listing against its endpoint, and a run whose whole
  * request is a few thousand tokens fits anything anyone serves — spending a round trip to

package/dist/retry.js

@@ -21,18 +21,78 @@ export class ContextOverflow extends Error {
 }
 /** 1234 → "1.2k". The numbers in an overflow message are large and nobody reads the units digit. */
 export const compact = (tokens) => tokens >= 1000 ? `${(tokens / 1000).toFixed(1)}k` : String(tokens);
+/** What `{"role":"","content":""},` costs around a message's own text, in characters. */
+const ENVELOPE = 25;
+/** The same for `{"id":"","type":"function","function":{"name":"","arguments":""}},` in a call. */
+const CALL_ENVELOPE = 62;
+/** The divisor behind `estimateTokens`, applied here to a character count rather than a string. */
+const CHARS_PER_TOKEN = 4;
+/** How many characters one message is worth, whichever of the shapes its content is in. */
+function messageChars(message) {
+    let chars = message.role.length + ENVELOPE;
+    const { content } = message;
+    if (typeof content === "string")
+        chars += content.length;
+    else if (Array.isArray(content))
+        for (const part of content) {
+            // Text and refusal parts carry their own strings; an image or an audio part carries a URL
+            // or a blob, and neither is priced by its length anyway.
+            if (part.type === "text")
+                chars += part.text.length;
+            else if (part.type === "refusal")
+                chars += part.refusal.length;
+        }
+    if ("name" in message && typeof message.name === "string")
+        chars += message.name.length;
+    if ("tool_call_id" in message && typeof message.tool_call_id === "string")
+        chars += message.tool_call_id.length;
+    if ("tool_calls" in message && Array.isArray(message.tool_calls))
+        for (const call of message.tool_calls) {
+            chars += CALL_ENVELOPE + call.id.length;
+            if (call.type === "function")
+                chars += call.function.name.length + call.function.arguments.length;
+        }
+    return chars;
+}
+/**
+ * The tools half, cached against the array.
+ *
+ * Tool definitions are stable objects handed out by a pool, and `sanitizeTools` already caches on
+ * that same identity — so the array a turn sends is the array the last turn sent unless something
+ * reconnected. Serialising two dozen JSON schemas to measure them, on every turn, to get the same
+ * number every time, was the more expensive half of this function.
+ */
+const toolTokens = new WeakMap();
+function toolsCost(tools) {
+    const hit = toolTokens.get(tools);
+    if (hit !== undefined)
+        return hit;
+    // Schemas are arbitrarily shaped, so this one really is a serialisation — but it happens once
+    // per tool array rather than once per turn.
+    const cost = estimateTokens(JSON.stringify(tools));
+    toolTokens.set(tools, cost);
+    return cost;
+}
 /**
  * What this request will cost the window, in tokens, near enough.
  *
- * 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, 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 this existed.
+ * See `estimateTokens` for why it is characters over four and which way it is wrong on purpose.
+ *
+ * Summed by walking the body rather than by serialising it. `JSON.stringify` on the messages
+ * built the entire transcript into a string on every call and threw it away having read nothing
+ * but its `.length` — against a transcript that grows by a turn each turn, and one the SDK is
+ * about to serialise again to send. What the walk misses is JSON's own punctuation and the keys,
+ * which `ENVELOPE` puts back approximately; the difference is a rounding error against an
+ * estimate that is already characters over four.
  */
-export const requestTokens = (body) => estimateTokens(JSON.stringify(body.messages)) +
-    (body.tools?.length ? estimateTokens(JSON.stringify(body.tools)) : 0);
+export const requestTokens = (body) => {
+    // Characters first and the division once at the end, rather than a rounded count per message:
+    // `Math.ceil` on every one of a few hundred messages is a few hundred tokens of pure rounding.
+    let chars = 0;
+    for (const message of body.messages)
+        chars += messageChars(message);
+    return Math.ceil(chars / CHARS_PER_TOKEN) + (body.tools?.length ? toolsCost(body.tools) : 0);
+};
 /**
  * Servers refuse an over-long request in their own words; these are the ones worth reading as
  * that rather than as a broken request. Matched loosely — every one of them is some
@@ -58,7 +118,12 @@ 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.
+ * The smallest window worth believing in, and the floor under both of its uses.
+ *
+ * `runTurn`'s `contextLimit` reads it as a sanity check on a number it was handed: below this,
+ * the limit is taken for a placeholder — an unset column, a listing that said nothing — rather
+ * than a window worth refusing a run over. `contextLimitFor` reads it as the point below which
+ * the window is nobody's business and is not asked for.
  *
  * Finding out what a model reads costs a listing against its endpoint, and a run whose whole
  * request is a few thousand tokens fits anything anyone serves — spending a round trip to

package/dist/run-turn.d.ts

@@ -28,6 +28,18 @@ export interface RunTurnOptions extends Omit<StreamTurnOptions, "produced"> {
      * see an unexplained pause. Carries both the capability notices and the retry notices.
      */
     onNotice?: (message: string) => void;
+    /**
+     * What the model will read, in tokens. Zero — the default — sends whatever it is given.
+     *
+     * With a limit, the request is sized before it is sent and a `ContextOverflow` is raised here
+     * rather than by the endpoint one round trip later. It is opt-in because the number is the
+     * caller's to find: `contextLimitFor` asks the endpoint, an operator's own setting overrides
+     * it, and neither is something a turn should be doing network I/O to discover. A limit below
+     * `SMALLEST_LIKELY_WINDOW` is not believed — a model with a window that small is rare enough
+     * that the number is far more likely a caller threading a placeholder through, and refusing a
+     * run over one would be the guard failing exactly the callers it was meant to help.
+     */
+    contextLimit?: number;
 }
 /**
  * `request` is a callback rather than a body because the body has to be rebuilt from whatever
@@ -35,4 +47,4 @@ export interface RunTurnOptions extends Omit<StreamTurnOptions, "produced"> {
  * has to apply to the schemas that were just sanitised. It is handed the same `Capabilities`
  * object throughout, and a caller that reads those from its own closure can ignore the argument.
  */
-export declare function runTurn(client: OpenAI, supports: Capabilities, request: (supports: Capabilities) => OpenAI.ChatCompletionCreateParamsStreaming, { maxRetries, onNotice, ...stream }?: RunTurnOptions): Promise<Turn>;
+export declare function runTurn(client: OpenAI, supports: Capabilities, request: (supports: Capabilities) => OpenAI.ChatCompletionCreateParamsStreaming, { maxRetries, onNotice, contextLimit, ...stream }?: RunTurnOptions): Promise<Turn>;

package/dist/run-turn.js

@@ -1,6 +1,6 @@
 import { negotiate } from "./capabilities.js";
 import { errorMessage } from "./errors.js";
-import { backoffMs, isTransient, sleep } from "./retry.js";
+import { backoffMs, ContextOverflow, compact, isTransient, requestTokens, SMALLEST_LIKELY_WINDOW, sleep, } from "./retry.js";
 import { streamTurn } from "./stream.js";
 /**
  * `request` is a callback rather than a body because the body has to be rebuilt from whatever
@@ -8,11 +8,30 @@ import { streamTurn } from "./stream.js";
  * has to apply to the schemas that were just sanitised. It is handed the same `Capabilities`
  * object throughout, and a caller that reads those from its own closure can ignore the argument.
  */
-export async function runTurn(client, supports, request, { maxRetries = 0, onNotice, ...stream } = {}) {
+export async function runTurn(client, supports, request, { maxRetries = 0, onNotice, contextLimit = 0, ...stream } = {}) {
+    // Sized once rather than per build. `request` is called again for every downgrade and every
+    // retry, but a downgraded body is strictly smaller than the one before it and the transcript
+    // does not change between attempts — so the first body is the one worth measuring, and
+    // measuring the rest would only spend the walk again to reach the same answer.
+    let sized = false;
+    const measured = (capabilities) => {
+        const body = request(capabilities);
+        if (!sized && contextLimit >= SMALLEST_LIKELY_WINDOW) {
+            sized = true;
+            const needed = requestTokens(body);
+            // Not retried, and deliberately not a capability: `isTransient` refuses it and none of the
+            // words below are ones `negotiate` reads as a refusal it can answer, so this leaves both
+            // loops on the first attempt instead of being sent again to be refused again.
+            if (needed > contextLimit) {
+                throw new ContextOverflow(`the request is about ${compact(needed)} tokens, over this model's ${compact(contextLimit)}`);
+            }
+        }
+        return body;
+    };
     for (let attempt = 0;; attempt++) {
         const produced = { any: false };
         try {
-            return await negotiate(supports, (capabilities, box) => streamTurn(client, request(capabilities), { ...stream, produced: box }), { produced, onNotice });
+            return await negotiate(supports, (capabilities, box) => streamTurn(client, measured(capabilities), { ...stream, produced: box }), { produced, onNotice });
         }
         catch (error) {
             // The abort is read before the classification, not after. A run stopped by its operator

package/dist/schema-compat.d.ts

@@ -5,7 +5,7 @@ export declare const sanitizeTools: (tools: OpenAI.ChatCompletionTool[]) => Open
  * `pattern` and most `format` values, both of which only ever narrowed a string the tool
  * re-validates anyway.
  */
-export declare function relaxTools(tools: OpenAI.ChatCompletionTool[]): OpenAI.ChatCompletionTool[];
+export declare const relaxTools: (tools: OpenAI.ChatCompletionTool[]) => OpenAI.ChatCompletionTool[];
 /**
  * Does this failure look like the server could not build a grammar from our tool schemas?
  *

package/dist/schema-compat.js

@@ -190,64 +190,83 @@ function sanitizeParameters(parameters) {
     pruneRequired(out);
     return out;
 }
-const mapTools = (tools, fn) => tools.map((tool) => tool.type === "function"
-    ? { ...tool, function: { ...tool.function, parameters: fn(tool.function.parameters) } }
-    : tool);
+/** Rewrites one tool's parameters, leaving a non-function tool alone. */
+const mapTool = (tool, fn) => tool.type === "function"
+    ? {
+        ...tool,
+        function: { ...tool.function, parameters: fn(tool.function.parameters) },
+    }
+    : tool;
 /**
- * Cached against the tool object rather than recomputed.
+ * Both rewrites are cached against the tool object rather than recomputed.
  *
  * The agent loop rebuilds its tool array on every iteration of every step, and normalising a
  * couple of dozen MCP schemas is the only walk in a run that is neither a request nor a query.
  * The pool hands out the same definition objects for the life of a connection, so identity is
  * exactly the right key: a reconnect makes new ones and they are normalised again.
+ *
+ * Two maps rather than one, because the two answer different questions about the same tool and a
+ * relaxed schema is reached by way of a sanitised one. `relaxed` is the load-bearing half: an
+ * endpoint that has refused a grammar once has `strictSchemas` off for the life of the process
+ * (see `capabilities.ts`), so from that point every request takes this path and only this path.
+ * Caching the call that happens once per connection and not the one that happens on every request
+ * had it exactly the wrong way round.
+ *
+ * The contract both rely on is that a tool definition is not mutated in place. Nothing can evict
+ * an entry here — a caller that edits `tool.function.parameters` after the fact keeps the schema
+ * it had at first sight. Build a new definition object instead.
  */
 const sanitized = new WeakMap();
-export const sanitizeTools = (tools) => tools.map((tool) => {
-    const hit = sanitized.get(tool);
+const relaxed = new WeakMap();
+/** Looks one up, computing and remembering it on a miss. */
+const through = (cache, tools, fn) => tools.map((tool) => {
+    const hit = cache.get(tool);
     if (hit)
         return hit;
-    const [clean] = mapTools([tool], sanitizeParameters);
-    sanitized.set(tool, clean);
-    return clean;
+    const built = mapTool(tool, fn);
+    cache.set(tool, built);
+    return built;
 });
+export const sanitizeTools = (tools) => through(sanitized, tools, sanitizeParameters);
+/**
+ * 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.
+ *
+ * At module scope rather than inside `relaxTools`, so the closure is made once rather than per
+ * call — which, on the path this is on, is per request.
+ */
+const strip = (node) => {
+    if (Array.isArray(node))
+        return node.map(strip);
+    if (!isObject(node))
+        return node;
+    const out = {};
+    for (const [key, value] of Object.entries(node)) {
+        if (key === "pattern" || key === "format")
+            continue;
+        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;
+};
 /**
  * The retry shape: llama.cpp's converter rejects regex escape classes (`\d`, `\w`, `\s`) in
  * `pattern` and most `format` values, both of which only ever narrowed a string the 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);
-        if (!isObject(node))
-            return node;
-        const out = {};
-        for (const [key, value] of Object.entries(node)) {
-            if (key === "pattern" || key === "format")
-                continue;
-            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;
-    };
-    return mapTools(tools, (parameters) => {
-        const stripped = strip(parameters);
-        return isObject(stripped) ? stripped : EMPTY_OBJECT();
-    });
-}
+export const relaxTools = (tools) => through(relaxed, tools, (parameters) => {
+    const stripped = strip(parameters);
+    return isObject(stripped) ? stripped : EMPTY_OBJECT();
+});
 /**
  * Qwen chat templates raise this when the transcript has no user turn. Some servers wrap it
  * in the same "unable to generate parser" wording as a real schema failure, and stripping

package/dist/side-task.d.ts

@@ -5,14 +5,22 @@ export interface SideTaskOptions {
     maxTokens?: number;
     temperature?: number;
     signal?: AbortSignal;
+    /**
+     * Told what was given up on, the same way `runTurn` and `negotiate` tell a caller.
+     *
+     * There is no default, and nothing is printed without one. A library that writes to the
+     * console decides for its consumer where operator text goes — which a server embedding this
+     * cannot then route to its own logger, attach to the run it belongs to, or silence in tests.
+     */
+    onNotice?: (message: string) => void;
 }
 /** Runs a side task and returns the reply text, thinking stripped. Throws like any request. */
-export declare function ask(config: Endpoint, model: string, system: string, user: string, { maxTokens, temperature, signal }?: SideTaskOptions): Promise<string>;
+export declare function ask(config: Endpoint, model: string, system: string, user: string, { maxTokens, temperature, signal, onNotice }?: SideTaskOptions): Promise<string>;
 /**
  * A side task is never worth failing the work it supports. Callers that can carry on without
  * an answer use this and get `undefined` instead of an exception.
  */
-export declare function tryAsk<T>(label: string, run: () => Promise<T>): Promise<T | undefined>;
+export declare function tryAsk<T>(label: string, run: () => Promise<T>, { onNotice }?: Pick<SideTaskOptions, "onNotice">): Promise<T | undefined>;
 /**
  * Models are asked for JSON and often answer with prose around it, or a fenced block. Pull out
  * the first array or object rather than failing the task over a wrapper.

package/dist/side-task.js

@@ -63,7 +63,7 @@ function rejectedTheRequest(error) {
  */
 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 } = {}) {
+export async function ask(config, model, system, user, { maxTokens = 512, temperature = 0.3, signal, onNotice } = {}) {
     const send = (hints) => getClient(config).chat.completions.create({
         model,
         max_tokens: maxTokens,
@@ -83,7 +83,7 @@ export async function ask(config, model, system, user, { maxTokens = 512, temper
     catch (error) {
         if (!hints || !rejectedTheRequest(error))
             throw error;
-        console.warn("[side-task] server rejected the no-thinking hints; retrying without them");
+        onNotice?.("server rejected the no-thinking hints; retrying without them");
         noHints.add(key);
         response = await send(false);
     }
@@ -100,7 +100,7 @@ export async function ask(config, model, system, user, { maxTokens = 512, temper
  * A side task is never worth failing the work it supports. Callers that can carry on without
  * an answer use this and get `undefined` instead of an exception.
  */
-export async function tryAsk(label, run) {
+export async function tryAsk(label, run, { onNotice } = {}) {
     try {
         return await run();
     }
@@ -109,7 +109,7 @@ export async function tryAsk(label, run) {
         // indistinguishable and left the cancellation with nowhere to go.
         if (error instanceof OpenAI.APIUserAbortError)
             throw error;
-        console.warn(`[side-task] ${label}:`, errorMessage(error));
+        onNotice?.(`${label}: ${errorMessage(error)}`);
         return undefined;
     }
 }

package/dist/tokens.d.ts

@@ -8,7 +8,9 @@
  * 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.
+ * Its own module because it is the one number several of these agree on, and the module that
+ * owns it should not be one that also does something. It was extracted from `side-task` to
+ * break a cycle with `retry`; `side-task` no longer reads it, but `retry` and any consumer
+ * sizing its own prompt still do, and a leaf with no imports is the right home for it.
  */
 export declare const estimateTokens: (text: string) => number;

package/dist/tokens.js

@@ -8,7 +8,9 @@
  * 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.
+ * Its own module because it is the one number several of these agree on, and the module that
+ * owns it should not be one that also does something. It was extracted from `side-task` to
+ * break a cycle with `retry`; `side-task` no longer reads it, but `retry` and any consumer
+ * sizing its own prompt still do, and a leaf with no imports is the right home for it.
  */
 export const estimateTokens = (text) => Math.ceil(text.length / 4);

package/dist/tool-loading.d.ts

@@ -14,7 +14,13 @@ import type { CatalogServer } from "./catalog.ts";
  * pays almost nothing, and a run that needs three pays for three.
  */
 export declare const LOAD_TOOLS = "load_tools";
-/** One object for the life of the process — the agent loop asks for it on every iteration. */
+/**
+ * One object for the life of the process — the agent loop asks for it on every iteration.
+ *
+ * Frozen because it is shared: one mutable export reached by every consumer in the process
+ * means a caller that edits the description in place has edited it for all of them, in a place
+ * nobody would think to look for the change.
+ */
 export declare const LOAD_TOOLS_DEFINITION: OpenAI.ChatCompletionTool;
 /**
  * The catalogue as a plain grouped listing of names, loaded ones marked.

package/dist/tool-loading.js

@@ -12,8 +12,21 @@
  * pays almost nothing, and a run that needs three pays for three.
  */
 export const LOAD_TOOLS = "load_tools";
-/** One object for the life of the process — the agent loop asks for it on every iteration. */
-export const LOAD_TOOLS_DEFINITION = {
+/** Shallow freezing this one would leave `.function.description` — the part worth editing. */
+function deepFreeze(value) {
+    if (value && typeof value === "object")
+        for (const held of Object.values(value))
+            deepFreeze(held);
+    return Object.freeze(value);
+}
+/**
+ * One object for the life of the process — the agent loop asks for it on every iteration.
+ *
+ * Frozen because it is shared: one mutable export reached by every consumer in the process
+ * means a caller that edits the description in place has edited it for all of them, in a place
+ * nobody would think to look for the change.
+ */
+export const LOAD_TOOLS_DEFINITION = deepFreeze({
     type: "function",
     function: {
         name: LOAD_TOOLS,
@@ -34,7 +47,7 @@ export const LOAD_TOOLS_DEFINITION = {
             additionalProperties: false,
         },
     },
-};
+});
 /**
  * The catalogue as a plain grouped listing of names, loaded ones marked.
  *

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cubicecho/agent-core",
-  "version": "1.3.0",
+  "version": "2.0.1",
   "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",
@@ -46,7 +46,9 @@
     "test": "vitest run",
     "test:watch": "vitest",
     "lint": "biome check .",
-    "format": "biome check --write ."
+    "format": "biome check --write .",
+    "bench": "vitest bench --run",
+    "coverage": "vitest run --coverage"
   },
   "peerDependencies": {
     "openai": ">=6"
@@ -56,6 +58,7 @@
     "@semantic-release/changelog": "^7.0.0",
     "@semantic-release/git": "^11.0.1",
     "@types/node": "^26.4.0",
+    "@vitest/coverage-v8": "^4.1.11",
     "openai": "^7.8.0",
     "semantic-release": "^25.0.9",
     "typescript": "^7.0.2",