@cubicecho/agent-core 2.12.0 → 2.14.0

package/dist/compaction.js

@@ -37,6 +37,25 @@ const messageText = (message) => {
     return `${textOf(message.content)} ${calls}`.trim();
 };
 const isSummary = (message) => message.role === "system" && textOf(message.content).startsWith(SUMMARY_LEAD);
+/** The summary as it sits in a transcript, which is the one shape `isSummary` recognises again. */
+const summaryMessage = (summary) => ({
+    role: "system",
+    content: `${SUMMARY_LEAD}${summary.trim()}`,
+});
+/**
+ * The leading system messages a fold never touches, and the summary an earlier one left among
+ * them. What a caller who keeps its system prompt out of the array knows already, and passes.
+ */
+const systemHead = (messages) => {
+    let from = 0;
+    let previous;
+    while (from < messages.length && messages[from].role === "system") {
+        if (isSummary(messages[from]))
+            previous = textOf(messages[from].content).slice(SUMMARY_LEAD.length);
+        from++;
+    }
+    return { from, previous };
+};
 /**
  * The transcript with every tool result but the latest few replaced by a one-line stub.
  *
@@ -80,22 +99,24 @@ export function pruneToolResults(messages, { keepLast = 5, maxChars = 256 } = {}
  * than summarised as if it were conversation. No plan comes back when the window is not full
  * enough, or when the only legal cut folds too little to pay for the summary.
  *
+ * Both of those are recovered by reading the transcript, which is what a host whose array holds
+ * everything it sends has to do. A host that keeps its fold as a record beside an append-only
+ * transcript — its system prompt a separate argument, no summary message in the array at all —
+ * knows them exactly, and passes `from` and `previous` instead of hoping the scan agrees.
+ *
  * @param messages The transcript, system prompts included if the caller keeps them in it.
- * @param options The window, what is in use, and the ratios. See `CompactionOptions`.
+ * @param options The window, what is in use, the ratios, and where the last fold ended. See
+ * `CompactionOptions`.
  */
-export function planCompaction(messages, { limit, used, compactAt = COMPACT_AT, keepRatio = KEEP_RATIO, charsPerToken, estimate = (message) => messageTokens(message, { charsPerToken }), }) {
+export function planCompaction(messages, { limit, used, compactAt = COMPACT_AT, keepRatio = KEEP_RATIO, charsPerToken, estimate = (message) => messageTokens(message, { charsPerToken }), from: givenFrom, previous: givenPrevious, }) {
     if (!(limit > 0))
         return undefined;
     const cost = used ?? messages.reduce((total, message) => total + estimate(message), 0);
     if (cost < limit * compactAt)
         return undefined;
-    let from = 0;
-    let previous;
-    while (from < messages.length && messages[from].role === "system") {
-        if (isSummary(messages[from]))
-            previous = textOf(messages[from].content).slice(SUMMARY_LEAD.length);
-        from++;
-    }
+    const head = systemHead(messages);
+    const from = Math.min(Math.max(givenFrom ?? head.from, 0), messages.length);
+    const previous = givenPrevious ?? head.previous;
     const budget = limit * keepRatio;
     let kept = 0;
     let cut = messages.length;
@@ -139,31 +160,21 @@ export function summaryInput(plan) {
  */
 export const summariser = (config, model, { system = SUMMARY_PROMPT, maxTokens = 1024, ...options } = {}) => (text) => ask(config, model, system, text, { maxTokens, ...options });
 /**
- * The transcript with the plan's stretch replaced by one system message holding its summary.
+ * The hooks and the summariser for a plan, as a record to store rather than a transcript to send.
  *
- * `beforeCompact` is told what is being folded while the summary is written, beside it rather
- * than ahead of it — a memory server filing it is not a rescue worth making the run wait for, and
- * `notify` never rejects. A host that wants its hooks able to stop a compaction sets
- * `honourVeto`, and then they run first and the summary waits on them: any `ok` outcome carrying
- * `veto` leaves the transcript as it was, and each vetoing hook is noted by name. A `forced`
- * compaction ignores a veto and runs the hooks beside the summary as before, because a run already
- * past its window has no better option — a veto there only trades the summary for a
- * `ContextOverflow`. An empty summary folds nothing either. Rewrites the prefix; see the module
- * comment on when to run it.
+ * What `compactTranscript` does before it rewrites anything, which is all a host needs when the
+ * fold lives on the session row and the messages stay where they are. Nothing here is persisted or
+ * logged — that is the host's, and so is deciding what to do with a fold that did not happen.
  *
- * @param messages The transcript the plan was made for. Not written to.
+ * @param messages The transcript the plan was made for. Read only, and only for the hooks.
  * @param plan What `planCompaction` returned for it.
  * @param summarise Writes the summary from `summaryInput`'s text. See `summariser`. Not called
  * when a hook vetoes.
- * @param options Hooks to tell. `context` is extended with `compacting` and `range`, whose
- * indexes are the plan's. `honourVeto` waits for the hooks and lets one stop the compaction; off
- * by default, which adds no latency. `forced` says the window is already exceeded — the caller
- * caught a `ContextOverflow`, or is compacting to make a refused request fit — and overrides
- * `honourVeto`.
- * @returns `messages` itself when nothing was folded — a veto or an empty summary — otherwise a
- * new array.
+ * @param options Hooks to tell and whether the window is already past. See `CompactionRunOptions`.
+ * @returns `undefined` when nothing was folded — a hook vetoed, or the summary came back empty —
+ * so the caller stores nothing and the transcript is still whole.
  */
-export async function compactTranscript(messages, plan, summarise, { hooks, forced = false, } = {}) {
+export async function runCompaction(messages, plan, summarise, { hooks, forced = false } = {}) {
     const context = hooks && {
         ...hooks.context,
         compacting: turnMessages(hooks.context.session.id, messages, plan.from, plan.cut),
@@ -173,7 +184,7 @@ export async function compactTranscript(messages, plan, summarise, { hooks, forc
     if (hooks && context && hooks.honourVeto && !forced) {
         const { vetoed } = await consult(hooks.run, "beforeCompact", context, hooks.onNote);
         if (vetoed)
-            return messages;
+            return undefined;
         summary = await summarise(summaryInput(plan));
     }
     else {
@@ -183,10 +194,85 @@ export async function compactTranscript(messages, plan, summarise, { hooks, forc
         ]);
     }
     if (!summary.trim())
+        return undefined;
+    return { summary: summary.trim(), through: plan.cut, at: new Date().toISOString() };
+}
+/**
+ * The transcript as the server should see it: the folded head replaced by its summary.
+ *
+ * The inverse of storing a `CompactionRecord`, and the shape `planCompaction` expects to meet
+ * again — the same `SUMMARY_LEAD`, in a `system` message at the same place — so the next fold
+ * continues these notes rather than summarising them a second time. Any earlier summary message in
+ * the kept head is dropped, since the record's already contains it.
+ *
+ * @param messages The stored transcript, whole. Not written to.
+ * @param record The fold, or `undefined` for a session that has not been compacted, which hands
+ * back `messages` itself.
+ * @param options `from` is the first message the fold was allowed to take — the plan's, for a host
+ * that keeps its system prompts in the array; everything before it is kept ahead of the summary.
+ * Absent, the leading `system` messages are found by scanning, and zero of them is the ordinary
+ * case for a host whose system prompt is a separate argument.
+ */
+export function applyCompaction(messages, record, { from } = {}) {
+    if (!record?.summary.trim())
         return messages;
+    const head = Math.min(Math.max(from ?? systemHead(messages).from, 0), record.through);
     return [
-        ...messages.slice(0, plan.from).filter((message) => !isSummary(message)),
-        { role: "system", content: `${SUMMARY_LEAD}${summary.trim()}` },
-        ...messages.slice(plan.cut),
+        ...messages.slice(0, head).filter((message) => !isSummary(message)),
+        summaryMessage(record.summary),
+        ...messages.slice(record.through),
     ];
 }
+/**
+ * Where a stored index sits in the request `applyCompaction` builds, once a fold has shifted
+ * everything after it.
+ *
+ * A transcript that stays append-only and a request that does not are two numberings of the same
+ * conversation, and anything that names a position — `withContext`'s index, a range handed to a
+ * hook — has to say which it is in. An index inside the folded stretch answers with the summary
+ * message that now stands for it.
+ *
+ * @param index The position in the stored transcript.
+ * @param record The fold in force, or `undefined` for a session that has none, which hands the
+ * index straight back.
+ * @param head How many messages the request keeps ahead of the summary — the leading system
+ * prompts, when the host keeps them in the array. Zero, the default, is the stored-fold case,
+ * where the summary is the request's first message.
+ */
+export const requestIndex = (index, record, head = 0) => {
+    if (!record)
+        return index;
+    return index < record.through ? head : index - record.through + head + 1;
+};
+/**
+ * The transcript with the plan's stretch replaced by one system message holding its summary.
+ *
+ * `beforeCompact` is told what is being folded while the summary is written, beside it rather
+ * than ahead of it — a memory server filing it is not a rescue worth making the run wait for, and
+ * `notify` never rejects. A host that wants its hooks able to stop a compaction sets
+ * `honourVeto`, and then they run first and the summary waits on them: any `ok` outcome carrying
+ * `veto` leaves the transcript as it was, and each vetoing hook is noted by name. A `forced`
+ * compaction ignores a veto and runs the hooks beside the summary as before, because a run already
+ * past its window has no better option — a veto there only trades the summary for a
+ * `ContextOverflow`. An empty summary folds nothing either. Rewrites the prefix; see the module
+ * comment on when to run it.
+ *
+ * `runCompaction` and `applyCompaction` are its two halves, and it is nothing but the two in
+ * order, so a host that stores the fold instead of the array gets the same summary at the same
+ * cut rather than a second implementation that drifts from this one.
+ *
+ * @param messages The transcript the plan was made for. Not written to.
+ * @param plan What `planCompaction` returned for it.
+ * @param summarise Writes the summary from `summaryInput`'s text. See `summariser`. Not called
+ * when a hook vetoes.
+ * @param options Hooks to tell and whether the window is already past. See
+ * `CompactionRunOptions`.
+ * @returns `messages` itself when nothing was folded — a veto or an empty summary — otherwise a
+ * new array.
+ */
+export async function compactTranscript(messages, plan, summarise, options = {}) {
+    const record = await runCompaction(messages, plan, summarise, options);
+    if (!record)
+        return messages;
+    return applyCompaction(messages, record, { from: plan.from });
+}

package/dist/hooks.d.ts

@@ -256,26 +256,44 @@ export declare function untrusted(text: string, { source }?: {
  * two identical "ok"s one memory. The same message sent twice, after its turn and again when it
  * is compacted, is one.
  *
+ * That position is the array's, which is the host's only while the two agree. Once a compaction
+ * has folded the head of a request into one summary message, the same message sits at a lower
+ * index there than it does in a transcript the host kept whole — so the same turn, sent after it
+ * and again when it is compacted, would arrive under two uuids and be remembered twice. `offset`
+ * is what puts the numbering back on the host's own indexes; passing the stored transcript rather
+ * than the request avoids the question entirely.
+ *
  * @param sessionId Prefixes every uuid, so two sessions never share one.
  * @param messages The transcript, in whatever shape the host stores it, so long as each message
  * has an OpenAI-style `role` and `content`.
  * @param from The first index, inclusive. Below zero reads from the start.
  * @param to The end, exclusive. Absent, or past the end, reads to the end.
+ * @param options `offset` is what the array's first message is numbered as in the uuids — the
+ * stored index of `messages[0]`, when `messages` is a request a fold has shifted. Zero by default,
+ * which numbers by position as before. `from` and `to` stay array indexes either way.
  */
 export declare function turnMessages(sessionId: string, messages: readonly {
     role: string;
     content?: unknown;
-}[], from: number, to?: number): HookMessage[];
+}[], from: number, to?: number, { offset }?: {
+    offset?: number;
+}): HookMessage[];
 /**
  * Which turn of a session begins at a point, from 0: the user messages ahead of it.
  *
+ * Counted over what it is given, which is the session only while nothing has been folded away — a
+ * compacted request has lost the questions the summary now stands for, and turn eleven counting
+ * itself as turn two is the kind of thing a hook writes into a memory. Count over the stored
+ * transcript, or add what the fold took as `offset`.
+ *
  * @param messages The transcript.
  * @param before Where the turn begins. Absent is the end, which is the index of a turn whose
  * question has not been appended yet.
+ * @param offset Turns already folded away and so not in `messages`. Zero by default.
  */
 export declare const turnIndex: (messages: readonly {
     role: string;
-}[], before?: number) => number;
+}[], before?: number, offset?: number) => number;
 /**
  * Runs the hooks ahead of a request and builds what they add to it.
  *

package/dist/hooks.js

@@ -204,13 +204,23 @@ const textOf = (content) => {
  * two identical "ok"s one memory. The same message sent twice, after its turn and again when it
  * is compacted, is one.
  *
+ * That position is the array's, which is the host's only while the two agree. Once a compaction
+ * has folded the head of a request into one summary message, the same message sits at a lower
+ * index there than it does in a transcript the host kept whole — so the same turn, sent after it
+ * and again when it is compacted, would arrive under two uuids and be remembered twice. `offset`
+ * is what puts the numbering back on the host's own indexes; passing the stored transcript rather
+ * than the request avoids the question entirely.
+ *
  * @param sessionId Prefixes every uuid, so two sessions never share one.
  * @param messages The transcript, in whatever shape the host stores it, so long as each message
  * has an OpenAI-style `role` and `content`.
  * @param from The first index, inclusive. Below zero reads from the start.
  * @param to The end, exclusive. Absent, or past the end, reads to the end.
+ * @param options `offset` is what the array's first message is numbered as in the uuids — the
+ * stored index of `messages[0]`, when `messages` is a request a fold has shifted. Zero by default,
+ * which numbers by position as before. `from` and `to` stay array indexes either way.
  */
-export function turnMessages(sessionId, messages, from, to) {
+export function turnMessages(sessionId, messages, from, to, { offset = 0 } = {}) {
     const end = Math.min(to ?? messages.length, messages.length);
     const out = [];
     for (let at = Math.max(0, from); at < end; at++) {
@@ -221,18 +231,28 @@ export function turnMessages(sessionId, messages, from, to) {
         if (!text)
             continue;
         const digest = createHash("sha256").update(`${message.role}\0${text}`).digest("hex");
-        out.push({ speaker: message.role, text, uuid: `${sessionId}:${at}:${digest.slice(0, 12)}` });
+        out.push({
+            speaker: message.role,
+            text,
+            uuid: `${sessionId}:${at + offset}:${digest.slice(0, 12)}`,
+        });
     }
     return out;
 }
 /**
  * Which turn of a session begins at a point, from 0: the user messages ahead of it.
  *
+ * Counted over what it is given, which is the session only while nothing has been folded away — a
+ * compacted request has lost the questions the summary now stands for, and turn eleven counting
+ * itself as turn two is the kind of thing a hook writes into a memory. Count over the stored
+ * transcript, or add what the fold took as `offset`.
+ *
  * @param messages The transcript.
  * @param before Where the turn begins. Absent is the end, which is the index of a turn whose
  * question has not been appended yet.
+ * @param offset Turns already folded away and so not in `messages`. Zero by default.
  */
-export const turnIndex = (messages, before = messages.length) => messages.slice(0, before).filter((message) => message.role === "user").length;
+export const turnIndex = (messages, before = messages.length, offset = 0) => offset + messages.slice(0, before).filter((message) => message.role === "user").length;
 /** A runner that rejected, as the one outcome its event can still be noted by. */
 const rejected = (event, error) => ({
     serverId: "",

package/dist/index.d.ts

@@ -11,17 +11,17 @@
  */
 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 { COMPACT_AT, type CompactionOptions, type CompactionPlan, compactTranscript, KEEP_RATIO, type PruneOptions, planCompaction, pruneToolResults, SUMMARY_LEAD, SUMMARY_PROMPT, summariser, summaryInput, } from "./compaction.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";
 export type { AgentConfig, Endpoint, ModelParams, RetryPolicy, ToolPolicy, } from "./config.ts";
 export { type ContinueTurnOptions, continueTurn, isContinuable, } from "./continuation.ts";
 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";
@@ -30,4 +30,4 @@ export { type Produced, type StreamTurnOptions, streamTurn, type Turn, type Turn
 export { ALL_FENCES, DEFAULT_FENCES, type Fence, FenceSplitter, type FenceSplitterOptions, type Split, stripThinking, THINK_FENCE, } from "./thinking.ts";
 export { estimateTokens } from "./tokens.ts";
 export { parseToolArguments, recoverToolCalls, ToolArgumentsError, type ToolCall, } from "./tool-calls.ts";
-export { carryOver, catalogList, catalogPrompt, expandNames, inCatalog, LOAD_TOOLS, LOAD_TOOLS_DEFINITION, loadedTools, loadResult, MAX_CARRIED, MAX_PER_LOAD, PRESELECT_SCHEMA, PRESELECT_SYSTEM, preselectInput, preselection, preselectSystem, requestedNames, } from "./tool-loading.ts";
+export { carryOver, catalogList, catalogPrompt, expandNames, inCatalog, LOAD_TOOLS, LOAD_TOOLS_DEFINITION, loadedTools, loadResult, MAX_CARRIED, MAX_PER_LOAD, orderTools, PRESELECT_SCHEMA, PRESELECT_SYSTEM, preselectInput, preselection, preselectSystem, requestedNames, type ToolOrder, } from "./tool-loading.ts";

package/dist/index.js

@@ -11,15 +11,15 @@
  */
 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 { COMPACT_AT, compactTranscript, KEEP_RATIO, planCompaction, pruneToolResults, SUMMARY_LEAD, SUMMARY_PROMPT, summariser, summaryInput, } from "./compaction.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";
 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";
@@ -28,4 +28,4 @@ export { streamTurn, } from "./stream.js";
 export { ALL_FENCES, DEFAULT_FENCES, FenceSplitter, stripThinking, THINK_FENCE, } from "./thinking.js";
 export { estimateTokens } from "./tokens.js";
 export { parseToolArguments, recoverToolCalls, ToolArgumentsError, } from "./tool-calls.js";
-export { carryOver, catalogList, catalogPrompt, expandNames, inCatalog, LOAD_TOOLS, LOAD_TOOLS_DEFINITION, loadedTools, loadResult, MAX_CARRIED, MAX_PER_LOAD, PRESELECT_SCHEMA, PRESELECT_SYSTEM, preselectInput, preselection, preselectSystem, requestedNames, } from "./tool-loading.js";
+export { carryOver, catalogList, catalogPrompt, expandNames, inCatalog, LOAD_TOOLS, LOAD_TOOLS_DEFINITION, loadedTools, loadResult, MAX_CARRIED, MAX_PER_LOAD, orderTools, PRESELECT_SCHEMA, PRESELECT_SYSTEM, preselectInput, preselection, preselectSystem, requestedNames, } from "./tool-loading.js";

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)) {