@cubicecho/agent-core 2.24.0 → 2.25.0

package/dist/index.js

@@ -9,27 +9,32 @@
  * prompts, and whatever the run is about — because that is the caller's, and it is the part
  * that differs between one server and the next.
  */
-export { buildBody, preselect, preview, resolveApiKey, runAgentLoop, taskCall, } from "./agent-loop.js";
-export { calibrate, charsPerTokenFor, resetCalibration } from "./calibration.js";
-export { capabilitiesFor, EFFORT_LADDER, effortFor, expireCapabilities, modelCapabilitiesFor, negotiate, resetCapabilities, } from "./capabilities.js";
-export { configureClients, contextLimitFor, endpointId, endpointKey, FIRST_TOKEN_FACTOR, firstTokenMs, getClient, listModels, NO_KEY, resetClients, servedWindow, timeoutMs, } from "./client.js";
-export { applyCompaction, COMPACT_AT, compactTranscript, KEEP_RATIO, planCompaction, pruneToolResults, requestIndex, runCompaction, SUMMARY_LEAD, SUMMARY_PROMPT, summariser, summaryInput, } from "./compaction.js";
-export { continueTurn, isContinuable, } from "./continuation.js";
-export { AgentLoopError, AgentLoopOverflow, errorMessage, failedRun, ToolIterationLimit, } from "./errors.js";
-export { configureEvents, emit, endRun, fold, history, resetEvents, runMetrics, watch, } from "./events.js";
-export { HOOK_EVENTS, INJECT_EVENTS } from "./hook-events.js";
-export { assembleContext, configureHooks, consult, gather, HOOK_CONTEXT_TOKENS, HOOK_PREFACE, notify, resetHooks, turnIndex, turnMessages, UNTRUSTED_PREFACE, untrusted, withContext, } from "./hooks.js";
-export { estimateFrom, rebaseLedger, recordRequest, tokensBetween, } from "./ledger.js";
-export { resetAll } from "./reset.js";
-export { backoffMs, 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 { createRuntime, defaultRuntime } from "./runtime.js";
-export { isGrammarError, relaxSchema, relaxTools, sanitizeSchema, sanitizeTools, } from "./schema-compat.js";
-export { ask, askJson, clean, listLines, parseJson, resetHints, tryAsk, } from "./side-task.js";
-export { CAPABILITY_SNAPSHOT_VERSION, exportCapabilities, importCapabilities, } from "./snapshot.js";
-export { AGENT_SPEC, AGENT_SPEC_VERSION, AGENT_TASKS, exportSpec, parseSpec, RESOLVED_DEFAULTS, resolveAgentSpec, SPEC_EVENTS, } from "./spec.js";
-export { streamTurn, } from "./stream.js";
-export { ALL_FENCES, DEFAULT_FENCES, FenceSplitter, stripThinking, THINK_FENCE, } from "./thinking.js";
-export { CHARS_PER_TOKEN, estimateTokens } from "./tokens.js";
-export { parseToolArguments, recoverToolCalls, ToolArgumentsError, } from "./tool-calls.js";
-export { CALL_TOOL, carryOver, catalogList, catalogPrompt, expandNames, holdsDefinitions, inCatalog, KEYWORD_DROPOFF, KEYWORD_MIN_SCORE, LOAD_TOOLS, LOAD_TOOLS_DEFINITION, loadedTools, loadResult, MAX_CARRIED, MAX_PER_LOAD, orderTools, PRESELECT_SCHEMA, PRESELECT_SYSTEM, PROXY_TOOLS, preselectByKeywords, preselectInput, preselection, preselectSystem, proxiedCall, proxyCatalogPrompt, proxyLoadResult, requestedNames, shownCall, } from "./tool-loading.js";
+export { PRESELECT_APPEND, PRESELECT_EXCLUSIVE, runAgentLoop, } from './agent-loop.js';
+export { calibrate, charsPerTokenFor, resetCalibration } from './calibration.js';
+export { capabilitiesFor, EFFORT_LADDER, EFFORT_NONE, EFFORT_OFF, effortFor, expireCapabilities, modelCapabilitiesFor, negotiate, resetCapabilities, } from './capabilities.js';
+export { configureClients, contextLimitFor, endpointId, endpointKey, FIRST_TOKEN_FACTOR, firstTokenMs, getClient, listModels, NO_KEY, resetClients, resolveApiKey, 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 { ToolDiscovery, } from './config.js';
+export { continueTurn, isContinuable, } from './continuation.js';
+export { AgentLoopError, AgentLoopOverflow, errorMessage, failedRun, ToolIterationLimit, } from './errors.js';
+export { configureEvents, emit, endRun, fold, history, RunEventKind, RunOutcome, resetEvents, runMetrics, watch, } from './events.js';
+export { HOOK_EVENTS, HookEvent, INJECT_EVENTS } from './hook-events.js';
+export { assembleContext, configureHooks, consult, gather, HOOK_CONTEXT_TOKENS, HOOK_PREFACE, notify, resetHooks, turnIndex, turnMessages, UNTRUSTED_PREFACE, untrusted, withContext, } from './hooks.js';
+export { estimateFrom, rebaseLedger, recordRequest, tokensBetween, } from './ledger.js';
+export { KEYWORD_DROPOFF, KEYWORD_MIN_SCORE, PRESELECT_SCHEMA, PRESELECT_SYSTEM, preselect, preselectByKeywords, preselectInput, preselection, preselectSystem, } from './preselect.js';
+export { buildBody } from './request-body.js';
+export { resetAll } from './reset.js';
+export { backoffMs, ContextOverflow, EndpointSilent, isModelLoading, isOverflow, isTransient, LOADING_POLL_MS, LOADING_TIMEOUT_MS, SMALLEST_LIKELY_WINDOW, sleep, } from './retry.js';
+export { preview } from './run-calls.js';
+export { runTurn } from './run-turn.js';
+export { createRuntime, defaultRuntime } from './runtime.js';
+export { isGrammarError, relaxSchema, relaxTools, sanitizeSchema, sanitizeTools, } from './schema-compat.js';
+export { ask, askJson, clean, listLines, parseJson, resetHints, taskCall, tryAsk, } from './side-task.js';
+export { CAPABILITY_SNAPSHOT_VERSION, exportCapabilities, importCapabilities, } from './snapshot.js';
+export { AGENT_SPEC, AGENT_SPEC_VERSION, AGENT_TASKS, exportSpec, parseSpec, REF_FILE, REF_URL, RESOLVED_DEFAULTS, resolveAgentSpec, SPEC_EVENTS, } from './spec.js';
+export { CacheBreakReason, streamTurn, } from './stream.js';
+export { ALL_FENCES, DEFAULT_FENCES, FenceSplitter, SPLIT_OUTPUT, SPLIT_REASONING, stripThinking, THINK_FENCE, } from './thinking.js';
+export { CHARS_PER_TOKEN, compact, contextChars, contextTokens, estimateTokens, messageTokens, requestChars, requestTokens, toolsChars, } from './tokens.js';
+export { ARGUMENTS_MALFORMED, ARGUMENTS_TRUNCATED, parseToolArguments, recoverToolCalls, ToolArgumentsError, } from './tool-calls.js';
+export { CALL_TOOL, carryOver, catalogList, catalogPrompt, expandNames, holdsDefinitions, inCatalog, LOAD_TOOLS, LOAD_TOOLS_DEFINITION, loadedTools, loadResult, MAX_CARRIED, MAX_PER_LOAD, orderTools, PROXY_TOOLS, proxiedCall, proxyCatalogPrompt, proxyLoadResult, requestedNames, shownCall, } from './tool-loading.js';
+export { FinishReason, FUNCTION_TOOL, JSON_SCHEMA_FORMAT, PartType, Role, SchemaType } from './wire.js';

package/dist/ledger.d.ts

@@ -1,5 +1,6 @@
-import type OpenAI from "openai";
-import { type TokenEstimateOptions } from "./retry.ts";
+import type OpenAI from 'openai';
+import type { TurnUsage } from './stream.ts';
+import { type TokenEstimateOptions } from './tokens.ts';
 /**
  * What stretches of a transcript cost, read off the prompt counts the server already reported.
  *
@@ -17,6 +18,7 @@ type Message = OpenAI.ChatCompletionMessageParam;
 /**
  * One request's reported prompt, and how far into the transcript that request reached.
  *
+ * @remarks
  * Three numbers and nothing else, so it serialises as it is: a host that stores a row per message
  * keeps `prompt` and `epoch` in two columns on the row `through` names, and one that stores a
  * session keeps the array beside it.
@@ -39,12 +41,15 @@ export interface LedgerEntry {
 }
 /** A transcript's entries in the order their requests were sent, which is also by `through`. */
 export type TokenLedger = LedgerEntry[];
-/** What `recordRequest` needs to know of one request. */
-export interface LedgerRequest {
+/** The part of a request that decides whether the next one only appended to it. */
+export interface RequestShape {
     /** The messages as they were sent, a system prompt and any context a hook added included. */
     messages: Message[];
     /** The names of the tools declared, in the order they were sent. Absent is none. */
     tools?: readonly string[];
+}
+/** What `recordRequest` needs to know of one request. */
+export interface LedgerRequest extends RequestShape {
     /** The prompt tokens the endpoint reported. Zero or less is no report, and records nothing. */
     prompt: number;
     /** The index, in the host's transcript, of the last message the request carried. */
@@ -53,48 +58,79 @@ export interface LedgerRequest {
 /** What `tokensBetween` and `estimateFrom` take besides the ledger and the transcript. */
 export interface LedgerEstimateOptions extends TokenEstimateOptions {
     /**
-     * One unmeasured message's tokens. `messageTokens` by default, divided by `charsPerToken` — the
-     * calibrated estimate, given `charsPerTokenFor` the model.
+     * One unmeasured message's tokens.
+     *
+     * @defaultValue `messageTokens` divided by `charsPerToken` — the calibrated estimate, given
+     * `charsPerTokenFor` the model.
      */
     estimate?: (message: Message) => number;
 }
+/**
+ * Where a request stopped matching the one before it, earliest in the rendered prompt first — the
+ * tool block, then the system prompt, then the history — or `none-known` where it only appended.
+ *
+ * @param previous - The request before, as it was sent.
+ * @param next - The request being explained.
+ * @returns The first of the three that differs, so a request that changed its tools and its history
+ * is reported as `tools-changed` alone.
+ *
+ * @remarks
+ * Beside `recordRequest` because it is the same comparison asked for a different reason: that one
+ * wants to know whether two prompts subtract, and this one why a cache that should have held
+ * did not.
+ */
+export declare function breakReason(previous: RequestShape, next: RequestShape): NonNullable<TurnUsage['cacheBreakReason']>;
 /**
  * The ledger with one more request on it, in the epoch the request before it says it belongs to.
  *
+ * @param ledger - The ledger so far. Not written to; handed back as it is when nothing is recorded.
+ * @param previous - The request the ledger's last entry was recorded from — not merely the last one
+ * sent, so that a request which reported nothing is skipped over rather than compared against.
+ * `undefined` where that is not known, which starts a new epoch.
+ * @param next - The request just answered.
+ * @returns `ledger` itself when nothing was recorded, otherwise a new array with the entry at its
+ * end. The first entry of an empty ledger is epoch 0.
+ *
+ * @remarks
  * The epoch carries on only where the new request declared the same tools in the same order and
  * sent every earlier message unchanged — the case in which the two prompts subtract. Anything else
  * starts a new one: a fold, a prune, a system prompt that moved, and a tool array that grew, whose
  * schema would otherwise be counted as the cost of the messages beside it. A request that reported
  * no prompt records nothing, and neither does one that reaches no further than the last entry in
  * the same epoch, so a retry or a continuation leaves the first reading standing.
- *
- * @param ledger The ledger so far. Not written to; handed back as it is when nothing is recorded.
- * @param previous The request the ledger's last entry was recorded from — not merely the last one
- * sent, so that a request which reported nothing is skipped over rather than compared against.
- * `undefined` where that is not known, which starts a new epoch.
- * @param next The request just answered.
  */
 export declare function recordRequest(ledger: TokenLedger, previous: LedgerRequest | undefined, next: LedgerRequest): TokenLedger;
 /**
  * The ledger for a transcript that has been rewritten, keeping the boundaries the rewrite left
  * standing.
  *
+ * @param ledger - The ledger for `before`. Not written to.
+ * @param before - The transcript the ledger's indexes are in.
+ * @param after - The transcript that replaces it. One that only appended to `before`, or is the same
+ * array, hands the ledger back as it is.
+ * @returns `ledger` itself where nothing was rewritten, otherwise a new array. The entries it keeps
+ * from the head are the same objects; the ones from the tail are copies.
+ *
+ * @remarks
  * A difference inside an epoch stays true after the epoch ends, since the prefix the two requests
  * shared cancels whatever became of it. So the entries that fall in the part of the transcript
  * still at its head keep their place, the ones in the part still at its tail move with it, and
  * only the ones in between — the messages a fold removed or a prune stubbed — are dropped. The
  * tail's entries move to a later epoch as well, so no difference is read across the rewrite.
- *
- * @param ledger The ledger for `before`. Not written to.
- * @param before The transcript the ledger's indexes are in.
- * @param after The transcript that replaces it. One that only appended to `before`, or is the same
- * array, hands the ledger back as it is.
  */
 export declare function rebaseLedger(ledger: TokenLedger, before: readonly Message[], after: readonly Message[]): TokenLedger;
 /**
  * What the messages from `from` up to, not including, `to` cost the window, measured where the
  * ledger can say and estimated where it cannot.
  *
+ * @param ledger - The ledger kept for `messages`.
+ * @param from - The first message counted. Below zero counts from the start.
+ * @param to - The first message not counted, as `slice` takes it. Past the end counts to the end.
+ * @param messages - The transcript the ledger's indexes are in.
+ * @param [options] - The estimate for what is not measured: a divisor, or a function of the caller's.
+ * @returns Whole tokens, rounded once over the stretch rather than per message.
+ *
+ * @remarks
  * Between two boundaries recorded in one epoch it is a subtraction and exact. A boundary falls
  * after a question and after each step's tool results, never after an assistant message, so a
  * stretch that starts or ends inside a group is given that group's measured total divided by
@@ -105,28 +141,24 @@ export declare function rebaseLedger(ledger: TokenLedger, before: readonly Messa
  * A difference of zero or less is not trusted and is estimated instead. That is how a server
  * reporting `prompt_tokens` net of its cache would show up, though one whose net counts still
  * happened to rise would not be caught by it.
- *
- * @param ledger The ledger kept for `messages`.
- * @param from The first message counted. Below zero counts from the start.
- * @param to The first message not counted, as `slice` takes it. Past the end counts to the end.
- * @param messages The transcript the ledger's indexes are in.
- * @param options The estimate for what is not measured: a divisor, or a function of the caller's.
- * @returns Whole tokens, rounded once over the stretch rather than per message.
  */
 export declare function tokensBetween(ledger: TokenLedger, from: number, to: number, messages: readonly Message[], options?: LedgerEstimateOptions): number;
 /**
  * A per-message cost for `planCompaction`'s `estimate`: the measured share where the ledger covers
  * the message, the calibrated estimate where it does not.
  *
+ * @param ledger - The ledger kept for `messages`.
+ * @param messages - The transcript the plan will be made for. The function it returns knows a
+ * message by identity, so it has to be asked about these objects and not copies of them; one it
+ * does not know is estimated.
+ * @param [options] - The estimate for what is not measured: a divisor, or a function of the caller's.
+ * @returns A function giving one message's tokens, unrounded where it was measured. It holds what
+ * the ledger said when this was called, and does not see entries recorded since.
+ *
+ * @remarks
  * The planner asks about one message at a time, and nothing reports anything that fine, so a
  * measured message is given its group's total by character share. The shares are not rounded,
  * which is what makes a whole group of them add back up to the difference the server reported.
- *
- * @param ledger The ledger kept for `messages`.
- * @param messages The transcript the plan will be made for. The function it returns knows a
- * message by identity, so it has to be asked about these objects and not copies of them; one it
- * does not know is estimated.
- * @param options The estimate for what is not measured: a divisor, or a function of the caller's.
  */
 export declare function estimateFrom(ledger: TokenLedger, messages: readonly Message[], options?: LedgerEstimateOptions): (message: Message) => number;
 export {};

package/dist/ledger.js

@@ -1,88 +1,181 @@
-import { messageChars, messageTokens } from "./retry.js";
-/** Whether two messages say the same thing, by identity first since most of a transcript is. */
+import { CacheBreakReason } from './stream.js';
+import { messageChars, messageTokens } from './tokens.js';
+import { Role } from './wire.js';
+/**
+ * Whether two messages say the same thing, by identity first since most of a transcript is.
+ *
+ * @param a - One message.
+ * @param b - The other. The order makes no difference.
+ * @returns `true` for the same object, or two that serialise to the same JSON — so the same fields
+ * written in another key order are not the same.
+ */
 const sameMessage = (a, b) => a === b || JSON.stringify(a) === JSON.stringify(b);
-/** Whether a request sent everything the one before it did, in the same place, and then more. */
-const appended = (previous, next) => {
+/**
+ * Whether two requests declared the same tools in the same order.
+ *
+ * @param previous - The request before. Absent `tools` reads as none.
+ * @param next - The request after, read the same way.
+ * @returns `true` when the names match one for one. Only names are compared, so a schema that
+ * changed under the same name is not seen.
+ */
+const sameTools = (previous, next) => {
     const before = previous.tools ?? [];
     const now = next.tools ?? [];
-    return (before.length === now.length &&
-        before.every((name, at) => name === now[at]) &&
-        previous.messages.length <= next.messages.length &&
-        previous.messages.every((message, at) => sameMessage(message, next.messages[at])));
+    return before.length === now.length && before.every((name, at) => name === now[at]);
+};
+/**
+ * Whether a request sent every message the one before it did, in the same place.
+ *
+ * @param previous - The earlier request's messages.
+ * @param next - The later one's, which may run on past them.
+ * @returns `true` when `previous` is a prefix of `next` by `sameMessage` — the two being equal
+ * included, and an empty `previous` always.
+ */
+const keptMessages = (previous, next) => previous.length <= next.length && previous.every((message, at) => sameMessage(message, next[at]));
+/**
+ * Whether a request sent everything the one before it did, in the same place, and then more.
+ *
+ * @param previous - The request before.
+ * @param next - The request after.
+ * @returns `true` when the tools are the same and the earlier messages a prefix of the later —
+ * which a request that added nothing also is.
+ */
+const appended = (previous, next) => sameTools(previous, next) && keptMessages(previous.messages, next.messages);
+/**
+ * The system messages a request opens with, which a template renders ahead of the history.
+ *
+ * @param messages - The request's messages. Not written to.
+ * @returns A new array of the messages ahead of the first that is not `system`: empty when the
+ * request does not open with one, and all of them when it holds nothing else. A `developer` message
+ * ends the run.
+ */
+const leadingSystem = (messages) => {
+    const end = messages.findIndex((message) => message.role !== Role.System);
+    return messages.slice(0, end === -1 ? messages.length : end);
 };
+/**
+ * Where a request stopped matching the one before it, earliest in the rendered prompt first — the
+ * tool block, then the system prompt, then the history — or `none-known` where it only appended.
+ *
+ * @param previous - The request before, as it was sent.
+ * @param next - The request being explained.
+ * @returns The first of the three that differs, so a request that changed its tools and its history
+ * is reported as `tools-changed` alone.
+ *
+ * @remarks
+ * Beside `recordRequest` because it is the same comparison asked for a different reason: that one
+ * wants to know whether two prompts subtract, and this one why a cache that should have held
+ * did not.
+ */
+export function breakReason(previous, next) {
+    if (!sameTools(previous, next)) {
+        return CacheBreakReason.ToolsChanged;
+    }
+    const before = leadingSystem(previous.messages);
+    const now = leadingSystem(next.messages);
+    const systemKept = before.length === now.length && keptMessages(before, now);
+    if (!systemKept) {
+        return CacheBreakReason.SystemChanged;
+    }
+    if (!keptMessages(previous.messages, next.messages)) {
+        return CacheBreakReason.HistoryRewritten;
+    }
+    return CacheBreakReason.NoneKnown;
+}
 /**
  * The ledger with one more request on it, in the epoch the request before it says it belongs to.
  *
+ * @param ledger - The ledger so far. Not written to; handed back as it is when nothing is recorded.
+ * @param previous - The request the ledger's last entry was recorded from — not merely the last one
+ * sent, so that a request which reported nothing is skipped over rather than compared against.
+ * `undefined` where that is not known, which starts a new epoch.
+ * @param next - The request just answered.
+ * @returns `ledger` itself when nothing was recorded, otherwise a new array with the entry at its
+ * end. The first entry of an empty ledger is epoch 0.
+ *
+ * @remarks
  * The epoch carries on only where the new request declared the same tools in the same order and
  * sent every earlier message unchanged — the case in which the two prompts subtract. Anything else
  * starts a new one: a fold, a prune, a system prompt that moved, and a tool array that grew, whose
  * schema would otherwise be counted as the cost of the messages beside it. A request that reported
  * no prompt records nothing, and neither does one that reaches no further than the last entry in
  * the same epoch, so a retry or a continuation leaves the first reading standing.
- *
- * @param ledger The ledger so far. Not written to; handed back as it is when nothing is recorded.
- * @param previous The request the ledger's last entry was recorded from — not merely the last one
- * sent, so that a request which reported nothing is skipped over rather than compared against.
- * `undefined` where that is not known, which starts a new epoch.
- * @param next The request just answered.
  */
 export function recordRequest(ledger, previous, next) {
-    if (!(next.prompt > 0))
+    if (!(next.prompt > 0)) {
         return ledger;
+    }
     const last = ledger.at(-1);
     if (last && previous && appended(previous, next)) {
-        if (next.through <= last.through)
+        if (next.through <= last.through) {
             return ledger;
+        }
         return [...ledger, { through: next.through, prompt: next.prompt, epoch: last.epoch }];
     }
-    return [
-        ...ledger,
-        { through: next.through, prompt: next.prompt, epoch: last ? last.epoch + 1 : 0 },
-    ];
+    return [...ledger, { through: next.through, prompt: next.prompt, epoch: last ? last.epoch + 1 : 0 }];
 }
 /**
  * The ledger for a transcript that has been rewritten, keeping the boundaries the rewrite left
  * standing.
  *
+ * @param ledger - The ledger for `before`. Not written to.
+ * @param before - The transcript the ledger's indexes are in.
+ * @param after - The transcript that replaces it. One that only appended to `before`, or is the same
+ * array, hands the ledger back as it is.
+ * @returns `ledger` itself where nothing was rewritten, otherwise a new array. The entries it keeps
+ * from the head are the same objects; the ones from the tail are copies.
+ *
+ * @remarks
  * A difference inside an epoch stays true after the epoch ends, since the prefix the two requests
  * shared cancels whatever became of it. So the entries that fall in the part of the transcript
  * still at its head keep their place, the ones in the part still at its tail move with it, and
  * only the ones in between — the messages a fold removed or a prune stubbed — are dropped. The
  * tail's entries move to a later epoch as well, so no difference is read across the rewrite.
- *
- * @param ledger The ledger for `before`. Not written to.
- * @param before The transcript the ledger's indexes are in.
- * @param after The transcript that replaces it. One that only appended to `before`, or is the same
- * array, hands the ledger back as it is.
  */
 export function rebaseLedger(ledger, before, after) {
-    if (before === after)
+    if (before === after) {
         return ledger;
+    }
     const shortest = Math.min(before.length, after.length);
     let head = 0;
-    while (head < shortest && sameMessage(before[head], after[head]))
+    while (head < shortest && sameMessage(before[head], after[head])) {
         head++;
-    if (head === before.length)
+    }
+    if (head === before.length) {
         return ledger;
+    }
     let tail = 0;
-    while (tail < shortest - head &&
-        sameMessage(before[before.length - 1 - tail], after[after.length - 1 - tail]))
+    while (tail < shortest - head && sameMessage(before[before.length - 1 - tail], after[after.length - 1 - tail])) {
         tail++;
+    }
     // The boundary just ahead of a kept tail stands too: what follows it is all still there. With
     // no tail kept there is nothing left for it to be the start of.
     const start = tail > 0 ? before.length - tail - 1 : before.length;
     const shift = after.length - before.length;
-    return ledger.flatMap((entry) => entry.through < head
-        ? [entry]
-        : entry.through >= start
-            ? [{ ...entry, through: entry.through + shift, epoch: entry.epoch + 1 }]
-            : []);
+    const rebased = [];
+    for (const entry of ledger) {
+        if (entry.through < head) {
+            rebased.push(entry);
+        }
+        else if (entry.through >= start) {
+            rebased.push({ ...entry, through: entry.through + shift, epoch: entry.epoch + 1 });
+        }
+    }
+    return rebased;
 }
 /**
- * Each measured message's share of its group's cost, by index. A group is the messages between two
- * neighbouring entries of one epoch, and is left out — for the estimate to answer — where the
- * difference is not above zero, where the entries are out of order, or where the transcript does
- * not reach its end.
+ * Each measured message's share of its group's cost, by index.
+ *
+ * @param ledger - The entries, in the order their requests were sent.
+ * @param messages - The transcript the ledger's indexes are in. Each measured message is read for
+ * its characters.
+ * @returns Tokens by message index, unrounded, so a group's shares add back up to its difference.
+ * A message no group covers has no entry.
+ *
+ * @remarks
+ * A group is the messages between two neighbouring entries of one epoch, and is left out — for the
+ * estimate to answer — where the difference is not above zero, where the entries are out of order,
+ * or where the transcript does not reach its end.
  */
 function shares(ledger, messages) {
     const out = new Map();
@@ -93,10 +186,12 @@ function shares(ledger, messages) {
         const tokens = to.prompt - from.prompt;
         const start = from.through + 1;
         const end = to.through + 1;
-        if (from.epoch !== to.epoch || !(tokens > 0))
+        if (from.epoch !== to.epoch || !(tokens > 0)) {
             continue;
-        if (start < floor || end <= start || end > messages.length)
+        }
+        if (start < floor || end <= start || end > messages.length) {
             continue;
+        }
         floor = end;
         const chars = [];
         let total = 0;
@@ -110,12 +205,27 @@ function shares(ledger, messages) {
     }
     return out;
 }
-/** The estimate for a message nothing measured, as the options ask for it. */
+/**
+ * The estimate for a message nothing measured, as the options ask for it.
+ *
+ * @param options - `estimate` is handed back as it is, and `charsPerToken` is then not read.
+ * Without one, `charsPerToken` is the divisor.
+ * @returns A function giving one message's tokens: the caller's own, or `messageTokens` at that
+ * divisor.
+ */
 const fallback = ({ charsPerToken, estimate }) => estimate ?? ((message) => messageTokens(message, { charsPerToken }));
 /**
  * What the messages from `from` up to, not including, `to` cost the window, measured where the
  * ledger can say and estimated where it cannot.
  *
+ * @param ledger - The ledger kept for `messages`.
+ * @param from - The first message counted. Below zero counts from the start.
+ * @param to - The first message not counted, as `slice` takes it. Past the end counts to the end.
+ * @param messages - The transcript the ledger's indexes are in.
+ * @param [options] - The estimate for what is not measured: a divisor, or a function of the caller's.
+ * @returns Whole tokens, rounded once over the stretch rather than per message.
+ *
+ * @remarks
  * Between two boundaries recorded in one epoch it is a subtraction and exact. A boundary falls
  * after a question and after each step's tool results, never after an assistant message, so a
  * stretch that starts or ends inside a group is given that group's measured total divided by
@@ -126,13 +236,6 @@ const fallback = ({ charsPerToken, estimate }) => estimate ?? ((message) => mess
  * A difference of zero or less is not trusted and is estimated instead. That is how a server
  * reporting `prompt_tokens` net of its cache would show up, though one whose net counts still
  * happened to rise would not be caught by it.
- *
- * @param ledger The ledger kept for `messages`.
- * @param from The first message counted. Below zero counts from the start.
- * @param to The first message not counted, as `slice` takes it. Past the end counts to the end.
- * @param messages The transcript the ledger's indexes are in.
- * @param options The estimate for what is not measured: a divisor, or a function of the caller's.
- * @returns Whole tokens, rounded once over the stretch rather than per message.
  */
 export function tokensBetween(ledger, from, to, messages, options = {}) {
     const measured = shares(ledger, messages);
@@ -147,20 +250,24 @@ export function tokensBetween(ledger, from, to, messages, options = {}) {
  * A per-message cost for `planCompaction`'s `estimate`: the measured share where the ledger covers
  * the message, the calibrated estimate where it does not.
  *
+ * @param ledger - The ledger kept for `messages`.
+ * @param messages - The transcript the plan will be made for. The function it returns knows a
+ * message by identity, so it has to be asked about these objects and not copies of them; one it
+ * does not know is estimated.
+ * @param [options] - The estimate for what is not measured: a divisor, or a function of the caller's.
+ * @returns A function giving one message's tokens, unrounded where it was measured. It holds what
+ * the ledger said when this was called, and does not see entries recorded since.
+ *
+ * @remarks
  * The planner asks about one message at a time, and nothing reports anything that fine, so a
  * measured message is given its group's total by character share. The shares are not rounded,
  * which is what makes a whole group of them add back up to the difference the server reported.
- *
- * @param ledger The ledger kept for `messages`.
- * @param messages The transcript the plan will be made for. The function it returns knows a
- * message by identity, so it has to be asked about these objects and not copies of them; one it
- * does not know is estimated.
- * @param options The estimate for what is not measured: a divisor, or a function of the caller's.
  */
 export function estimateFrom(ledger, messages, options = {}) {
     const estimate = fallback(options);
     const measured = new Map();
-    for (const [at, tokens] of shares(ledger, messages))
+    for (const [at, tokens] of shares(ledger, messages)) {
         measured.set(messages[at], tokens);
+    }
     return (message) => measured.get(message) ?? estimate(message);
 }

package/dist/platform.d.ts

@@ -0,0 +1,13 @@
+/**
+ * The platform's own numbers and words, each under a name.
+ *
+ * A leaf with no imports. Settings are in seconds because that is what a person types, timers are
+ * in milliseconds because that is what the platform takes, and each module that crossed between
+ * the two had written the thousand out.
+ */
+/** How many milliseconds a second is. */
+export declare const MS_PER_SECOND = 1000;
+/** How many milliseconds a minute is. */
+export declare const MS_PER_MINUTE: number;
+/** The event an `AbortSignal` fires when it aborts. */
+export declare const ABORT_EVENT = "abort";

package/dist/platform.js

@@ -0,0 +1,13 @@
+/**
+ * The platform's own numbers and words, each under a name.
+ *
+ * A leaf with no imports. Settings are in seconds because that is what a person types, timers are
+ * in milliseconds because that is what the platform takes, and each module that crossed between
+ * the two had written the thousand out.
+ */
+/** How many milliseconds a second is. */
+export const MS_PER_SECOND = 1000;
+/** How many milliseconds a minute is. */
+export const MS_PER_MINUTE = 60 * MS_PER_SECOND;
+/** The event an `AbortSignal` fires when it aborts. */
+export const ABORT_EVENT = 'abort';