@cubicecho/agent-core 2.13.0 → 2.15.0

package/README.md

@@ -29,7 +29,7 @@ only, Node >=22.
 | `hooks` | The host's side of lifecycle hooks: `gather` before a request and `notify` after, the shared context budget, `withContext` to put what they add on the turn's question, `untrusted` to fence text nobody vouched for, and `turnMessages` to hand them a transcript. Running a hook is a runner the caller passes. |
 | `events` | The in-memory bus a watcher reads while a run happens: `emit`, `watch`, `history`, `fold`, and `runMetrics` for what a run cost. A watcher's backlog is capped and reports its own gaps. |
 | `client` | A pooled `OpenAI` client per endpoint, plus the context window: the served one where a local server says, the listed one otherwise, and their caches. |
-| `retry` | What to do when a request is lost, refused or too big: `isTransient`, `isModelLoading`, `backoffMs`, `ContextOverflow`, `EndpointSilent`, `requestTokens`. |
+| `retry` | What to do when a request is lost, refused or too big: `isTransient`, `isModelLoading`, `backoffMs`, `ContextOverflow`, `EndpointSilent`, `requestTokens`, `contextTokens`. |
 | `calibration` | How many characters a token is worth on one model, learned from the prompt counts its endpoint reports: `charsPerTokenFor`, `calibrate`. |
 | `continuation` | `continueTurn`: carries on an answer the token ceiling cut off, by prefilling it as a trailing assistant message. |
 | `config` | The structural interfaces every function here asks for. |
@@ -314,6 +314,35 @@ for up to `loadingTimeoutMs` (two minutes by default, zero to turn it off) witho
 `maxRetries`, with one notice at the start. `runAgentLoop` reads it as `loadingTimeoutSeconds` off
 the config. A 503 that says nothing about loading stays on the ordinary backoff.
 
+### What is filling the window
+
+A total tells an operator a run is close to the edge and nothing about what to do next, so
+`contextTokens` cuts the same body four ways, along the four levers there are: `system` is the
+system and developer messages, which means shortening the prompt; `tools` is the declared schemas,
+which means loading them on demand instead of declaring them whole; `toolResults` is exactly the
+`tool` messages, which is precisely what `pruneToolResults` shrinks; and `history` is everything
+else, which is what compaction folds, the arguments of the calls in it included.
+
+```ts
+const { system, tools, history, toolResults, total } = contextTokens(body, {
+  charsPerToken: charsPerTokenFor(supports, config.model),
+  // Optional: what the endpoint said the prompt cost, once a turn has come back.
+  promptTokens: turn.usage?.prompt_tokens,
+});
+```
+
+The parts are shares of one total rather than four separate estimates, because a readout whose
+parts do not add up to the number beside them is one nobody trusts; the largest part absorbs the
+rounding, so they sum exactly. Nothing in the round trip reports anything finer than a prompt
+count — a completion says how many tokens it read and not a word about where they came from — so
+the proportions are a guess whatever the total is, and `contextChars` is there for a caller that
+wants the exact characters underneath them.
+
+Given a `promptTokens` the total is what was charged and every part is a share of it. Without one
+the total is `requestTokens`, and the tool block is counted the way `requestTokens` and
+`TurnMetrics.toolSchemaTokens` count it rather than shared out, so the breakdown and the metrics
+line cannot disagree about the same tool list.
+
 ## The loop
 
 `runAgentLoop` is the part of an agent that three servers had each written, and that had drifted
@@ -341,10 +370,17 @@ const { turn, messages, usage, loaded } = await runAgentLoop({
 
 Each step is one `runTurn` with the body from `buildBody`, so everything `negotiate` answers is
 answered here too, and a request that is too big throws `ContextOverflow` whichever side found
-out. Between steps the loop runs the calls: sequentially by default, or together with
-`parallel: true`, which also makes an identical call — the same name and arguments, byte for byte
-— once for the run. A call that threw is forgotten rather than cached, so asking again is a real
-retry. What a tool throws is what the model reads, and so are arguments that did not parse.
+out. Between steps the loop runs the calls: sequentially by default, or together with `parallel: true`.
+Either way an identical call — the same name and arguments, byte for byte — is made once and its
+answer handed to the repeat, and two still in flight share the request. A call that threw is
+forgotten rather than cached, so asking again is a real retry. What a tool throws is what the model
+reads, and so are arguments that did not parse.
+
+The scope is the step, not the run: between steps other tools have run, and the file the model read
+may be the file it has since written. `dedupeToolCalls: false` dispatches everything, and a
+predicate is asked per call — which is how `send_email` opts out, since twice is two emails and
+nothing in an OpenAI tool definition says which tools those are. A pool that reads the MCP
+`readOnlyHint` and `idempotentHint` annotations can answer it; this package cannot.
 
 Arguments go through `parseToolArguments`, which is lenient where the model's meaning is plain:
 JSON held in a string is opened, and the almost-JSON local models write — single quotes, Python's
@@ -353,7 +389,7 @@ string. What still is not an object throws a `ToolArgumentsError` whose `kind` i
 the turn stopped at the ceiling, with a message telling the model so, and `malformed` otherwise.
 The repaired JSON is what the transcript keeps, and an unreadable call is replayed as `{}`, because
 a server that parses replayed arguments refuses the originals on every later request. `dispatch`
-is still handed the model's own text as `raw`, and the parallel dedupe compares repaired arguments,
+is still handed the model's own text as `raw`, and the dedupe compares repaired arguments,
 so `{'a': 1}` and `{"a": 1}` are one call.
 
 A server whose tool-call parser was written for another template streams the model's call as
@@ -799,7 +835,35 @@ A snapshot names endpoints by `endpointId`, a SHA-256 digest of the URL and key,
 written to a settings row or a file without a credential going with it. Importing merges and only
 latches off, the same as a refusal does. A snapshot of another `version` is ignored. How old is too
 old is left to the consumer, who can read `savedAt` first: a server upgraded between boots may
-accept what it used to refuse, and nothing latched ever unlatches without a reset.
+accept what it used to refuse, and nothing latched ever unlatches on its own.
+
+It unlatches when you say so. A server upgraded behind the same URL — a newer llama.cpp that
+compiles the grammar, a proxy that has learned `stream_options` — keeps being sent the downgraded
+request until something forgets what it refused, and `resetCapabilities` takes the endpoint to
+forget:
+
+```ts
+resetCapabilities({ baseUrl: row.baseUrl, apiKey: row.apiKey });  // this one changed
+expireCapabilities(6 * 60 * 60_000);                              // anything half a day old
+```
+
+`resetCapabilities` with no argument still clears every endpoint, which is what `resetAll` and a
+test mean by it; with one it clears that endpoint alone, so an upgraded local box does not cost the
+cloud endpoint beside it its latches, and returns whether there was anything to forget. Call it
+where the host already knows something changed: a settings row saved, a health check reading a new
+build string, an operator pressing a button.
+
+`expireCapabilities(maxAgeMs)` covers the case where nobody knows, dropping every endpoint older
+than that and returning how many. An expiry does not probe anything — it stops suppressing, so the
+next request carries the field again and a server that still refuses it refuses it once, which
+`negotiate` answers as it always did. At an age measured in hours that is a few extra round trips a
+day against a downgrade that would otherwise last as long as the process. Nothing calls it on a
+timer; when to sweep is yours, the same way how stale a snapshot is too stale is.
+
+An endpoint's age is when it was first met, not when a flag latched, and `exportCapabilities`
+carries it in the snapshot so an imported latch keeps its real age instead of being born again on
+every boot. Importing takes the older of the two ages, and a snapshot written before this field
+existed reads as met now.
 
 ## Where the merged behaviour came from
 

package/dist/agent-loop.d.ts

@@ -152,12 +152,26 @@ export interface AgentLoopOptions {
     /** Runs one tool call and returns what the model reads. What it throws, the model reads too. */
     dispatch: (call: ToolCallRequest, signal?: AbortSignal) => Promise<string>;
     /**
-     * Runs a step's calls together rather than one after another, and makes an identical call —
-     * the same name and arguments, word for word — once for the run, handing a repeat the first
-     * answer. A call that threw is not an answer and is made again. Results still go into the
-     * transcript in the order the model asked.
+     * Runs a step's calls together rather than one after another. Results still go into the
+     * transcript in the order the model asked. See `dedupeToolCalls`, which applies either way.
      */
     parallel?: boolean;
+    /**
+     * Answers an identical repeat of a call — the same name and the same arguments, word for word —
+     * within one step from the first one, rather than dispatching it again.
+     *
+     * On by default, and on whether or not the calls run in `parallel`: a model that asks the same
+     * question twice in one reply gets one answer, and two that are still in flight share the
+     * request. A call that threw is not an answer and is made again. The scope is the step and not
+     * the run, because between steps other tools have run and the file the model read may be the
+     * file it has since written.
+     *
+     * `false` dispatches every call. A predicate is asked per call and is how a tool that does
+     * something rather than reads something opts out — `send_email` twice is two emails, and this
+     * package cannot tell which tools those are. A pool that reads the MCP `readOnlyHint` and
+     * `idempotentHint` annotations can answer it; nothing in an OpenAI tool definition can.
+     */
+    dedupeToolCalls?: boolean | ((call: ToolCallRequest) => boolean);
     /** Hooks gathered onto the question before the first request, and told the reply after. */
     hooks?: AgentLoopHooks;
     /**

package/dist/agent-loop.js

@@ -202,7 +202,8 @@ function cacheDiagnosis(previous, messages, tools, usage) {
  */
 export async function runAgentLoop(options) {
     const { config, system = "", tools = [], catalog = [], dispatch, hooks, signal } = options;
-    const { onTurn, beforeStep, parallel = false, recoverToolCalls: recover = true, maxContinuations = 0, toolOrder = true, } = options;
+    const { onTurn, beforeStep, parallel = false, recoverToolCalls: recover = true, maxContinuations = 0, toolOrder = true, dedupeToolCalls = true, } = options;
+    const dedupable = typeof dedupeToolCalls === "function" ? dedupeToolCalls : () => dedupeToolCalls;
     const started = Date.now();
     // What the loop emitted, less the token deltas, for `runMetrics` at the end. Stamped here rather
     // than by the bus, which the loop does not know about.
@@ -259,7 +260,6 @@ export async function runAgentLoop(options) {
         : { context: "", notes: [] };
     const usage = { prompt: 0, completion: 0, total: 0, cached: 0 };
     const toolCalls = [];
-    const answered = new Map();
     const loads = { toolsLoaded: 0, redundantLoads: 0, unknownToolNames: 0 };
     let previous;
     for (let step = 0; step < config.maxToolIterations; step++) {
@@ -411,6 +411,9 @@ export async function runAgentLoop(options) {
                 },
             };
         }
+        // Per step, not per run: the answer to a call made two steps ago was true before the tools in
+        // between ran, and the file the model read may be the file it has since written.
+        const answered = new Map();
         const run = async ({ call, args, error: unreadable, normal }) => {
             const { name, arguments: raw } = call.function;
             onEvent({ kind: "tool-call", name, text: preview(raw) });
@@ -436,7 +439,7 @@ export async function runAgentLoop(options) {
                         loaded.add(name);
                     used.add(name);
                     const request = { id: call.id, name, args, raw };
-                    content = parallel
+                    content = dedupable(request)
                         ? await once(answered, `${name}\0${normal}`, () => dispatch(request, signal))
                         : await dispatch(request, signal);
                 }
@@ -470,8 +473,8 @@ export async function runAgentLoop(options) {
 }
 /**
  * Makes a call at most once per key, sharing the in-flight promise so two identical calls in one
- * step make one request between them. A call that rejected is forgotten, so asking again is a
- * real retry rather than a replayed failure.
+ * step make one request between them whether they run together or one after the other. A call
+ * that rejected is forgotten, so asking again is a real retry rather than a replayed failure.
  */
 async function once(answered, key, make) {
     const previous = answered.get(key);

package/dist/capabilities.d.ts

@@ -35,6 +35,17 @@ export interface Capabilities {
      * stopped. Empty until `modelCapabilitiesFor` is asked about a model.
      */
     models: Map<string, ModelCapabilities>;
+    /**
+     * When this entry was opened, as epoch milliseconds: first contact with the endpoint in this
+     * process, or the age an imported snapshot gave it. What `expireCapabilities` measures.
+     *
+     * Not when a flag latched. A flag that latches at all almost always does so on the first
+     * request or two, and an entry that latched nothing has nothing to expire, so the difference
+     * costs at most one retried field somewhat earlier than it was due — which is the direction to
+     * be wrong in. Stamping each latch instead would mean stamping it in four modules and
+     * remembering to in the fifth.
+     */
+    since: number;
 }
 /**
  * What one model on that endpoint turned out not to support. All start optimistic and only ever
@@ -124,8 +135,41 @@ export declare const knownCapabilities: () => ReadonlyMap<string, Capabilities>;
  * `importCapabilities` reaches an endpoint it has only a digest for.
  */
 export declare function capabilitiesById(id: string): Capabilities;
-/** Forgets every endpoint's capabilities. For tests, and for a settings change under test. */
-export declare function resetCapabilities(): void;
+/**
+ * Forgets what one endpoint refused, or every endpoint's when told none.
+ *
+ * A latch never unlatches on its own, so a server upgraded behind the same URL — a newer
+ * llama.cpp that compiles the grammar, a proxy that has learned `stream_options` — keeps being
+ * sent the downgraded request for the life of the process. This is the seam for a consumer that
+ * *knows* it changed: a settings row saved, a health check that reads a new build string, an
+ * operator pressing a button. See `expireCapabilities` for the case where nobody knows.
+ *
+ * @param endpoint Whose to forget, by the same identity `capabilitiesFor` takes. Absent clears
+ * every endpoint, which is what tests and `resetAll` mean by it.
+ * @returns Whether there was anything to forget.
+ */
+export declare function resetCapabilities(endpoint?: {
+    baseUrl: string;
+    apiKey?: string;
+}): boolean;
+/**
+ * Forgets every endpoint whose entry is older than this, so the next request finds out again.
+ *
+ * The other half of the problem `resetCapabilities` solves: a server upgraded behind the same URL
+ * with nobody to notice. What an expiry costs is one round trip per endpoint and model — the next
+ * request carries the field again, and a server that still refuses it refuses it once and
+ * `negotiate` re-sends — so at an age measured in hours it is a few requests a day against a
+ * downgrade that would otherwise last as long as the process. That is the trade `exportCapabilities`
+ * exists to avoid paying *per restart*; paying it per day is a different bargain.
+ *
+ * Nothing calls this on a timer. When to sweep is the consumer's, the same way how stale a
+ * snapshot is too stale is, and a sweep costs a walk of one settings row's worth of entries.
+ *
+ * @param maxAgeMs How old an entry may be. Zero or less expires everything.
+ * @param now The clock, for tests.
+ * @returns How many endpoints were forgotten.
+ */
+export declare function expireCapabilities(maxAgeMs: number, now?: number): number;
 /** What `negotiate` takes besides the request. All optional. */
 export interface NegotiateOptions {
     /**

package/dist/capabilities.js

@@ -71,14 +71,58 @@ export const knownCapabilities = () => capabilities;
 export function capabilitiesById(id) {
     let known = capabilities.get(id);
     if (!known) {
-        known = { strictSchemas: true, usageInStream: true, models: new Map() };
+        known = { strictSchemas: true, usageInStream: true, models: new Map(), since: Date.now() };
         capabilities.set(id, known);
     }
     return known;
 }
-/** Forgets every endpoint's capabilities. For tests, and for a settings change under test. */
-export function resetCapabilities() {
-    capabilities.clear();
+/**
+ * Forgets what one endpoint refused, or every endpoint's when told none.
+ *
+ * A latch never unlatches on its own, so a server upgraded behind the same URL — a newer
+ * llama.cpp that compiles the grammar, a proxy that has learned `stream_options` — keeps being
+ * sent the downgraded request for the life of the process. This is the seam for a consumer that
+ * *knows* it changed: a settings row saved, a health check that reads a new build string, an
+ * operator pressing a button. See `expireCapabilities` for the case where nobody knows.
+ *
+ * @param endpoint Whose to forget, by the same identity `capabilitiesFor` takes. Absent clears
+ * every endpoint, which is what tests and `resetAll` mean by it.
+ * @returns Whether there was anything to forget.
+ */
+export function resetCapabilities(endpoint) {
+    if (!endpoint) {
+        const held = capabilities.size > 0;
+        capabilities.clear();
+        return held;
+    }
+    return capabilities.delete(endpointId(endpoint));
+}
+/**
+ * Forgets every endpoint whose entry is older than this, so the next request finds out again.
+ *
+ * The other half of the problem `resetCapabilities` solves: a server upgraded behind the same URL
+ * with nobody to notice. What an expiry costs is one round trip per endpoint and model — the next
+ * request carries the field again, and a server that still refuses it refuses it once and
+ * `negotiate` re-sends — so at an age measured in hours it is a few requests a day against a
+ * downgrade that would otherwise last as long as the process. That is the trade `exportCapabilities`
+ * exists to avoid paying *per restart*; paying it per day is a different bargain.
+ *
+ * Nothing calls this on a timer. When to sweep is the consumer's, the same way how stale a
+ * snapshot is too stale is, and a sweep costs a walk of one settings row's worth of entries.
+ *
+ * @param maxAgeMs How old an entry may be. Zero or less expires everything.
+ * @param now The clock, for tests.
+ * @returns How many endpoints were forgotten.
+ */
+export function expireCapabilities(maxAgeMs, now = Date.now()) {
+    let dropped = 0;
+    for (const [id, known] of capabilities) {
+        if (now - known.since < maxAgeMs)
+            continue;
+        capabilities.delete(id);
+        dropped++;
+    }
+    return dropped;
 }
 /**
  * Every latching flag in play on one attempt, endpoint and model together, in a stable order.

package/dist/index.d.ts

@@ -11,7 +11,7 @@
  */
 export { type AgentLoopHooks, type AgentLoopOptions, type AgentLoopResult, buildBody, preselect, preview, resolveApiKey, runAgentLoop, type ToolCallOutcome, type ToolCallRequest, } from "./agent-loop.ts";
 export { calibrate, charsPerTokenFor, resetCalibration } from "./calibration.ts";
-export { type Capabilities, capabilitiesFor, type ModelCapabilities, modelCapabilitiesFor, type NegotiateOptions, negotiate, resetCapabilities, } from "./capabilities.ts";
+export { type Capabilities, capabilitiesFor, expireCapabilities, type ModelCapabilities, modelCapabilitiesFor, type NegotiateOptions, negotiate, resetCapabilities, } from "./capabilities.ts";
 export type { CatalogServer } from "./catalog.ts";
 export { type ClientPoolOptions, configureClients, contextLimitFor, endpointId, endpointKey, FIRST_TOKEN_FACTOR, firstTokenMs, getClient, listModels, type ModelInfo, NO_KEY, resetClients, servedWindow, timeoutMs, } from "./client.ts";
 export { applyCompaction, COMPACT_AT, type CompactionOptions, type CompactionPlan, type CompactionRecord, type CompactionRunOptions, compactTranscript, KEEP_RATIO, type PruneOptions, planCompaction, pruneToolResults, requestIndex, runCompaction, SUMMARY_LEAD, SUMMARY_PROMPT, summariser, summaryInput, } from "./compaction.ts";
@@ -21,7 +21,7 @@ export { errorMessage } from "./errors.ts";
 export { configureEvents, type EventBusOptions, emit, endRun, fold, history, type RunEvent, type RunEventInput, type RunEventKind, type RunMetrics, type RunMetricsOptions, type RunUsage, resetEvents, runMetrics, type TurnReport, watch, } from "./events.ts";
 export { assembleContext, configureHooks, consult, type Gathered, gather, HOOK_CONTEXT_TOKENS, HOOK_EVENTS, HOOK_PREFACE, type HookContext, type HookEvent, type HookMessage, type HookNote, type HookOptions, type HookOutcome, type HookRunner, INJECT_EVENTS, notify, resetHooks, turnIndex, turnMessages, UNTRUSTED_PREFACE, untrusted, withContext, } from "./hooks.ts";
 export { resetAll } from "./reset.ts";
-export { backoffMs, CHARS_PER_TOKEN, ContextOverflow, compact, EndpointSilent, isModelLoading, isOverflow, isTransient, LOADING_POLL_MS, LOADING_TIMEOUT_MS, messageTokens, requestChars, requestTokens, SMALLEST_LIKELY_WINDOW, sleep, type TokenEstimateOptions, toolsChars, } from "./retry.ts";
+export { backoffMs, CHARS_PER_TOKEN, type ContextBreakdown, type ContextBreakdownOptions, ContextOverflow, compact, contextChars, contextTokens, EndpointSilent, isModelLoading, isOverflow, isTransient, LOADING_POLL_MS, LOADING_TIMEOUT_MS, messageTokens, requestChars, requestTokens, SMALLEST_LIKELY_WINDOW, sleep, type TokenEstimateOptions, toolsChars, } from "./retry.ts";
 export { type RunTurnOptions, runTurn } from "./run-turn.ts";
 export { isGrammarError, relaxTools, sanitizeTools } from "./schema-compat.ts";
 export { type AskJsonOptions, ask, askJson, clean, listLines, parseJson, resetHints, type SideTaskInput, type SideTaskOptions, tryAsk, } from "./side-task.ts";

package/dist/index.js

@@ -11,7 +11,7 @@
  */
 export { buildBody, preselect, preview, resolveApiKey, runAgentLoop, } from "./agent-loop.js";
 export { calibrate, charsPerTokenFor, resetCalibration } from "./calibration.js";
-export { capabilitiesFor, modelCapabilitiesFor, negotiate, resetCapabilities, } from "./capabilities.js";
+export { capabilitiesFor, expireCapabilities, modelCapabilitiesFor, negotiate, resetCapabilities, } from "./capabilities.js";
 export { configureClients, contextLimitFor, endpointId, endpointKey, FIRST_TOKEN_FACTOR, firstTokenMs, getClient, listModels, NO_KEY, resetClients, servedWindow, timeoutMs, } from "./client.js";
 export { applyCompaction, COMPACT_AT, compactTranscript, KEEP_RATIO, planCompaction, pruneToolResults, requestIndex, runCompaction, SUMMARY_LEAD, SUMMARY_PROMPT, summariser, summaryInput, } from "./compaction.js";
 export { continueTurn, isContinuable, } from "./continuation.js";
@@ -19,7 +19,7 @@ export { errorMessage } from "./errors.js";
 export { configureEvents, emit, endRun, fold, history, resetEvents, runMetrics, watch, } from "./events.js";
 export { assembleContext, configureHooks, consult, gather, HOOK_CONTEXT_TOKENS, HOOK_EVENTS, HOOK_PREFACE, INJECT_EVENTS, notify, resetHooks, turnIndex, turnMessages, UNTRUSTED_PREFACE, untrusted, withContext, } from "./hooks.js";
 export { resetAll } from "./reset.js";
-export { backoffMs, CHARS_PER_TOKEN, ContextOverflow, compact, EndpointSilent, isModelLoading, isOverflow, isTransient, LOADING_POLL_MS, LOADING_TIMEOUT_MS, messageTokens, requestChars, requestTokens, SMALLEST_LIKELY_WINDOW, sleep, toolsChars, } from "./retry.js";
+export { backoffMs, CHARS_PER_TOKEN, ContextOverflow, compact, contextChars, contextTokens, EndpointSilent, isModelLoading, isOverflow, isTransient, LOADING_POLL_MS, LOADING_TIMEOUT_MS, messageTokens, requestChars, requestTokens, SMALLEST_LIKELY_WINDOW, sleep, toolsChars, } from "./retry.js";
 export { runTurn } from "./run-turn.js";
 export { isGrammarError, relaxTools, sanitizeTools } from "./schema-compat.js";
 export { ask, askJson, clean, listLines, parseJson, resetHints, tryAsk, } from "./side-task.js";

package/dist/retry.d.ts

@@ -79,6 +79,66 @@ export declare function requestChars(body: OpenAI.ChatCompletionCreateParamsStre
  * @param options The divisor, `CHARS_PER_TOKEN` when none is given.
  */
 export declare const requestTokens: (body: OpenAI.ChatCompletionCreateParamsStreaming, { charsPerToken }?: TokenEstimateOptions) => number;
+/**
+ * What a request is made of, by the part of it a consumer can actually do something about.
+ *
+ * The question an operator asks is not how big the request is — the total already answers that —
+ * but what is filling the window, and the only useful answer names a lever: a system prompt to
+ * shorten, a tool list to load on demand instead of declaring whole, a transcript to compact,
+ * results to prune. So the cut follows the levers rather than the roles: `toolResults` is exactly
+ * what `pruneToolResults` can shrink, and `history` is everything `planCompaction` folds, the
+ * arguments of the calls in it included.
+ */
+export interface ContextBreakdown {
+    /** Every system and developer message, wherever it sits in the transcript. */
+    system: number;
+    /** The declared tool schemas, which a chat template renders ahead of the system prompt. */
+    tools: number;
+    /** What was said: the user and assistant messages, and the calls the assistant asked for. */
+    history: number;
+    /** What the tools handed back — the `tool` messages, and nothing else. */
+    toolResults: number;
+    /** The four above, summed. */
+    total: number;
+}
+/**
+ * What each part of a request is worth in characters, by the same walk `requestTokens` divides.
+ *
+ * Exact and additive: the parts sum to `total`, which is `requestChars` plus `toolsChars`. The
+ * conversion to tokens is `contextTokens`' business, because that is where an estimate and a
+ * reported count have to be told apart.
+ *
+ * @param body The request as it will be sent, tools included.
+ */
+export declare function contextChars(body: OpenAI.ChatCompletionCreateParamsStreaming): ContextBreakdown;
+/** What `contextTokens` takes besides the request. */
+export interface ContextBreakdownOptions extends TokenEstimateOptions {
+    /**
+     * The prompt count the endpoint reported for this request, if it has answered. Given one, the
+     * parts are shares of it and the breakdown sums to what was actually charged rather than to an
+     * estimate; left out, they are shares of `requestTokens`.
+     */
+    promptTokens?: number;
+}
+/**
+ * What each part of a request costs the window, in tokens, adding up to the whole.
+ *
+ * Shares rather than four independent estimates, because a readout whose parts do not add up to
+ * the total beside them is a readout nobody trusts. Nothing in the round trip reports anything
+ * finer than a prompt count — a completion says how many tokens it read and not a word about
+ * where they came from — so the proportions are an estimate whatever the total is.
+ *
+ * Without a reported count the total is `requestTokens`, and the tools are counted the way it and
+ * `TurnMetrics.toolSchemaTokens` count them rather than shared out, so the two agree by
+ * construction and an operator does not read one number for the tool block in the metrics and a
+ * different one here. With a reported count every part is a share of it, the tools included:
+ * that number is the server's, and the point of using it is that the parts sum to what was
+ * charged.
+ *
+ * @param body The request as it will be sent, tools included.
+ * @param options The divisor, and the reported prompt count when there is one.
+ */
+export declare function contextTokens(body: OpenAI.ChatCompletionCreateParamsStreaming, { charsPerToken, promptTokens }?: ContextBreakdownOptions): ContextBreakdown;
 /**
  * One message's estimated tokens, by the same count `requestTokens` sums for a whole request.
  *

package/dist/retry.js

@@ -183,6 +183,89 @@ export const requestTokens = (body, { charsPerToken } = {}) => {
     const per = divisor(charsPerToken);
     return Math.ceil(requestChars(body) / per) + Math.ceil(toolsChars(body.tools ?? []) / per);
 };
+/** The parts, in the order a readout reads them. */
+const PARTS = ["system", "tools", "history", "toolResults"];
+/**
+ * What each part of a request is worth in characters, by the same walk `requestTokens` divides.
+ *
+ * Exact and additive: the parts sum to `total`, which is `requestChars` plus `toolsChars`. The
+ * conversion to tokens is `contextTokens`' business, because that is where an estimate and a
+ * reported count have to be told apart.
+ *
+ * @param body The request as it will be sent, tools included.
+ */
+export function contextChars(body) {
+    const out = {
+        system: 0,
+        tools: toolsChars(body.tools ?? []),
+        history: 0,
+        toolResults: 0,
+        total: 0,
+    };
+    for (const message of body.messages) {
+        const chars = messageChars(message);
+        // Every system message and not just the leading one: a host that appends guidance, or a
+        // hook that injects a preface, has put more of the window there and wants to be told so.
+        if (message.role === "system" || message.role === "developer")
+            out.system += chars;
+        else if (message.role === "tool")
+            out.toolResults += chars;
+        else
+            out.history += chars;
+    }
+    out.total = out.system + out.tools + out.history + out.toolResults;
+    return out;
+}
+/**
+ * Shares `total` out over these parts by their character counts, the largest absorbing the
+ * rounding so they add up to it exactly rather than to within a few tokens of it.
+ */
+function share(chars, over, total) {
+    const out = { system: 0, tools: 0, history: 0, toolResults: 0, total };
+    const measured = over.reduce((sum, part) => sum + chars[part], 0);
+    if (measured <= 0 || total <= 0)
+        return out;
+    const absorber = over.reduce((a, b) => (chars[b] > chars[a] ? b : a));
+    let assigned = 0;
+    for (const part of over) {
+        if (part === absorber)
+            continue;
+        out[part] = Math.round((chars[part] / measured) * total);
+        assigned += out[part];
+    }
+    out[absorber] = Math.max(0, total - assigned);
+    return out;
+}
+/**
+ * What each part of a request costs the window, in tokens, adding up to the whole.
+ *
+ * Shares rather than four independent estimates, because a readout whose parts do not add up to
+ * the total beside them is a readout nobody trusts. Nothing in the round trip reports anything
+ * finer than a prompt count — a completion says how many tokens it read and not a word about
+ * where they came from — so the proportions are an estimate whatever the total is.
+ *
+ * Without a reported count the total is `requestTokens`, and the tools are counted the way it and
+ * `TurnMetrics.toolSchemaTokens` count them rather than shared out, so the two agree by
+ * construction and an operator does not read one number for the tool block in the metrics and a
+ * different one here. With a reported count every part is a share of it, the tools included:
+ * that number is the server's, and the point of using it is that the parts sum to what was
+ * charged.
+ *
+ * @param body The request as it will be sent, tools included.
+ * @param options The divisor, and the reported prompt count when there is one.
+ */
+export function contextTokens(body, { charsPerToken, promptTokens } = {}) {
+    const chars = contextChars(body);
+    if (promptTokens !== undefined && promptTokens > 0)
+        return share(chars, PARTS, promptTokens);
+    const per = divisor(charsPerToken);
+    const tools = Math.ceil(chars.tools / per);
+    const rest = Math.ceil((chars.total - chars.tools) / per);
+    const out = share(chars, ["system", "history", "toolResults"], rest);
+    out.tools = tools;
+    out.total = rest + tools;
+    return out;
+}
 /**
  * One message's estimated tokens, by the same count `requestTokens` sums for a whole request.
  *

package/dist/snapshot.d.ts

@@ -28,6 +28,13 @@ export interface EndpointSnapshot {
     strictSchemas: boolean;
     usageInStream: boolean;
     models: Record<string, ModelSnapshot>;
+    /**
+     * When this endpoint was first met, as epoch milliseconds, so `expireCapabilities` measures a
+     * latch from when it was learned rather than from the boot that imported it. Absent in a snapshot
+     * taken before it was written, which reads as met now — the behaviour of every release until this
+     * one, and the reason no version bump is owed.
+     */
+    since?: number;
 }
 /** Every latched refusal in the process, JSON-safe. See `exportCapabilities`. */
 export interface CapabilitySnapshot {
@@ -43,7 +50,8 @@ export interface CapabilitySnapshot {
  * Covers what `negotiate` latches on endpoints and models and the models `ask` found refusing the
  * no-thinking hints. Only what was actually refused is in it, so a snapshot of a process that met
  * no refusals has no endpoints. Endpoints are named by digest rather than URL and key, since the
- * blob is meant to be written somewhere and a key must not be written with it.
+ * blob is meant to be written somewhere and a key must not be written with it. Each carries the
+ * `since` it was learned at, so importing it does not make an old latch young again.
  */
 export declare function exportCapabilities(): CapabilitySnapshot;
 /**
@@ -53,7 +61,8 @@ export declare function exportCapabilities(): CapabilitySnapshot;
  * off whatever the snapshot says, and one the snapshot has off is turned off. A snapshot of another
  * version, or anything that is not one, is ignored — a stale shape costs the refused requests it
  * would have saved, which is what a restart cost before. How old is too old is the consumer's call,
- * made on `savedAt` before importing, since a server behind a URL can be upgraded between boots.
+ * made on `savedAt` before importing, or afterwards per endpoint with `expireCapabilities`, since a
+ * server behind a URL can be upgraded between boots.
  *
  * @param snapshot What `exportCapabilities` returned, as stored. Read defensively: a field of the
  * wrong type is skipped rather than trusted.

package/dist/snapshot.js

@@ -32,13 +32,21 @@ const refusedAnything = (model) => !model.reasoningEffort ||
  * Covers what `negotiate` latches on endpoints and models and the models `ask` found refusing the
  * no-thinking hints. Only what was actually refused is in it, so a snapshot of a process that met
  * no refusals has no endpoints. Endpoints are named by digest rather than URL and key, since the
- * blob is meant to be written somewhere and a key must not be written with it.
+ * blob is meant to be written somewhere and a key must not be written with it. Each carries the
+ * `since` it was learned at, so importing it does not make an old latch young again.
  */
 export function exportCapabilities() {
     const endpoints = {};
     const entry = (id) => {
-        endpoints[id] ??= { strictSchemas: true, usageInStream: true, models: {} };
-        return endpoints[id];
+        const held = endpoints[id];
+        if (held)
+            return held;
+        const fresh = { strictSchemas: true, usageInStream: true, models: {} };
+        const since = knownCapabilities().get(id)?.since;
+        if (since !== undefined)
+            fresh.since = since;
+        endpoints[id] = fresh;
+        return fresh;
     };
     for (const [id, supports] of knownCapabilities()) {
         const models = {};
@@ -79,7 +87,8 @@ const isRecord = (value) => typeof value === "object" && value !== null && !Arra
  * off whatever the snapshot says, and one the snapshot has off is turned off. A snapshot of another
  * version, or anything that is not one, is ignored — a stale shape costs the refused requests it
  * would have saved, which is what a restart cost before. How old is too old is the consumer's call,
- * made on `savedAt` before importing, since a server behind a URL can be upgraded between boots.
+ * made on `savedAt` before importing, or afterwards per endpoint with `expireCapabilities`, since a
+ * server behind a URL can be upgraded between boots.
  *
  * @param snapshot What `exportCapabilities` returned, as stored. Read defensively: a field of the
  * wrong type is skipped rather than trusted.
@@ -98,6 +107,11 @@ export function importCapabilities(snapshot) {
             supports.strictSchemas = false;
         if (endpoint.usageInStream === false)
             supports.usageInStream = false;
+        // Older of the two, so a snapshot ages an entry and never rejuvenates one: importing must not
+        // be a way to keep a latch from ever reaching `expireCapabilities`.
+        if (typeof endpoint.since === "number" && endpoint.since < supports.since) {
+            supports.since = endpoint.since;
+        }
         if (!isRecord(endpoint.models))
             continue;
         for (const [name, model] of Object.entries(endpoint.models)) {

package/llms.txt

@@ -38,11 +38,12 @@ What an endpoint turned out not to support, and answering it when it says so.
 
 - `Capabilities` (type) — What one endpoint turned out not to support.
 - `capabilitiesFor` — What this endpoint is known not to support.
+- `expireCapabilities` — Forgets every endpoint whose entry is older than this, so the next request finds out again.
 - `ModelCapabilities` (type) — What one model on that endpoint turned out not to support.
 - `modelCapabilitiesFor` — What this model on this endpoint is known not to support.
 - `NegotiateOptions` (type) — What `negotiate` takes besides the request.
 - `negotiate` — Sends a request, re-sending it each time the answer is this endpoint refusing something the request can do without.
-- `resetCapabilities` — Forgets every endpoint's capabilities.
+- `resetCapabilities` — Forgets what one endpoint refused, or every endpoint's when told none.
 
 ### catalog
 
@@ -170,8 +171,12 @@ Everything about a request failing that is not about what the request said.
 
 - `backoffMs` — Exponential, with jitter so several tasks failing at once do not return in lockstep.
 - `CHARS_PER_TOKEN` — The divisor behind `estimateTokens`, applied here to a character count rather than a string.
+- `ContextBreakdown` (type) — What a request is made of, by the part of it a consumer can actually do something about.
+- `ContextBreakdownOptions` (type) — What `contextTokens` takes besides the request.
 - `ContextOverflow` — The request was bigger than the model will read.
 - `compact` — 1234 → "1.2k".
+- `contextChars` — What each part of a request is worth in characters, by the same walk `requestTokens` divides.
+- `contextTokens` — What each part of a request costs the window, in tokens, adding up to the whole.
 - `EndpointSilent` — The endpoint stopped answering mid-request.
 - `isModelLoading` — Whether a failure is a local server still loading the model, rather than one failing to serve.
 - `isOverflow` — Whether a refusal means the request was too big, rather than merely refused.

package/package.json

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