@cubicecho/agent-core 2.18.1 → 2.19.0

package/dist/agent-loop.js

@@ -1,11 +1,12 @@
 import { charsPerTokenFor } from "./calibration.js";
-import { capabilitiesFor, effortFor, } from "./capabilities.js";
+import { capabilitiesFor, effortFor, modelCapabilitiesFor, } from "./capabilities.js";
 import { firstTokenMs, getClient, NO_KEY, timeoutMs } from "./client.js";
 import { continueTurn } from "./continuation.js";
 import { errorMessage } from "./errors.js";
 import { runMetrics } from "./events.js";
-import { gather, notify, turnIndex, turnMessages, withContext, } from "./hooks.js";
-import { toolsChars } from "./retry.js";
+import { configureHooks, gather, notify, turnIndex, turnMessages, withContext, } from "./hooks.js";
+import { rebaseLedger, recordRequest } from "./ledger.js";
+import { contextTokens, toolsChars } from "./retry.js";
 import { runTurn } from "./run-turn.js";
 import { relaxTools, sanitizeTools } from "./schema-compat.js";
 import { askJson, tryAsk } from "./side-task.js";
@@ -206,17 +207,25 @@ function cacheDiagnosis(previous, messages, tools, usage) {
  * prompt unchanged from step to step, a load adds to the tool array — which every request sends
  * in the stable order `toolOrder` asks for — and
  * a catalogued tool called without being loaded is loaded and run rather than refused, and a
- * preselection shapes the first step. A turn cut off at `maxTokens` is said so as a notice,
- * because it otherwise reads exactly like a finished one — or, given `maxContinuations`, is
+ * preselection shapes the first step unless `preselectRouting` says to append it. A turn cut off
+ * at `maxTokens` is said so as a notice, because it otherwise reads exactly like a finished one — or, given `maxContinuations`, is
  * continued first. Every turn ends in a `usage` event carrying the turn's own report, with the
- * cache compared against the request before it; see `TurnUsage` and `runMetrics`.
+ * cache compared against the request before it and the request broken down by what filled it; see
+ * `TurnUsage` and `runMetrics`.
+ *
+ * Each step's reported prompt goes on a token ledger, in the same epoch as the step before where
+ * the request only appended to it and in a new one where it did not — a `beforeStep` that rewrote
+ * the transcript, a tool array a load grew — so that what the messages between two steps cost can
+ * be read back as a subtraction. The prompt recorded is the first request's, before any
+ * continuation, and a step that reported none, or reported a cache count above its prompt, is not
+ * recorded. The ledger comes back in the result and on every `usage` event; see `tokensBetween`.
  *
  * @param options The config, transcript, tools and dispatcher, plus the optional hooks, events
  * and cancellation. See `AgentLoopOptions`.
  */
 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, dedupeToolCalls = true, } = options;
+    const { onRequest, onTurn, onToolCall, onToolResult, beforeStep, parallel = false, recoverToolCalls: recover = true, maxContinuations = 0, toolOrder = true, dedupeToolCalls = true, preselectRouting = "exclusive", } = 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
@@ -272,17 +281,32 @@ export async function runAgentLoop(options) {
             maxTokens: hooks.maxTokens,
         })
         : { context: "", notes: [] };
+    // Read once, so what the result hands back is what every step of this run said.
+    const preface = hooks?.preface ?? configureHooks().preface;
     const usage = { prompt: 0, completion: 0, total: 0, cached: 0 };
     const toolCalls = [];
     const loads = { toolsLoaded: 0, redundantLoads: 0, unknownToolNames: 0 };
     let previous;
+    let ledger = options.ledger ?? [];
+    // The request the ledger's last entry came from, which is what the next one is measured against.
+    // Nothing before this run's first: an earlier run's head is not something the loop can see.
+    let measured;
     for (let step = 0; step < config.maxToolIterations; step++) {
         // A stop aborts the request in flight, but a tool call already handed off runs to its own
         // end — so the signal is read between steps as well.
         signal?.throwIfAborted();
-        messages = (await beforeStep?.(messages, step)) ?? messages;
+        const before = messages;
+        messages =
+            (await beforeStep?.(messages, step, {
+                ...(previous && previous.prompt > 0 ? { used: previous.prompt } : {}),
+                limit: config.contextLength ?? 0,
+                ledger,
+            })) ?? messages;
+        ledger = rebaseLedger(ledger, before, messages);
         onEvent({ kind: "turn", text: `turn ${step + 1}` });
-        const routed = preselected.length > 0 && step === 0;
+        // Appended, the shortlist is already in `loaded` — after what was carried, and once — so the
+        // first step needs nothing of its own.
+        const routed = preselectRouting !== "append" && preselected.length > 0 && step === 0;
         // Ordered here rather than left to `buildBody`, so `names` below is what the request actually
         // declared — a diagnosis reading an order the server never saw calls an untouched tool array
         // `tools-changed`.
@@ -293,11 +317,12 @@ export async function runAgentLoop(options) {
                 : tools, toolOrder);
         // Unmarked, so the system prompt is the same text on every step and a load does not throw
         // away the cache for the whole transcript. What is loaded is said in `declared` and in the
-        // `load_tools` result instead. The preselected first step is the one exception, by design.
+        // `load_tools` result instead. The preselected first step is the one exception, by design,
+        // and `preselectRouting: "append"` is the way out of it.
         const prompt = onDemand && !routed ? `${system}\n\n${catalogPrompt(catalog)}`.trim() : system;
         const request = [
             ...(prompt ? [{ role: "system", content: prompt }] : []),
-            ...withContext(messages, question ? messages.indexOf(question) : -1, gathered.context, hooks?.preface),
+            ...withContext(messages, question ? messages.indexOf(question) : -1, gathered.context, preface),
         ];
         const build = (supported, refused) => buildBody(config, supported, refused, request, declared, toolOrder);
         const turnOptions = {
@@ -315,15 +340,37 @@ export async function runAgentLoop(options) {
             onThinking: (text) => onEvent({ kind: "thinking", text }),
             onOutput: (text) => onEvent({ kind: "output", text }),
         };
+        // Built the way `negotiate` is about to build the first attempt — the same flags, the same
+        // model's refusals — so what the host is told is what is sent unless something is refused.
+        if (onRequest) {
+            const opening = build(supports, modelCapabilitiesFor(supports, config.model));
+            onRequest({ messages: opening.messages, tools: opening.tools ?? [], step });
+        }
         const first = await runTurn(client, supports, build, turnOptions);
         const names = declared.map((tool) => (tool.type === "function" ? tool.function.name : ""));
         // Compared before any continuation is joined on: the cache a request meets is the one its own
         // prompt found, and a continuation's prompt is this request's plus the reply so far.
+        // The breakdown measures the array `toolSchemaTokens` does, so where no prompt was reported
+        // the two give one number for the tool block rather than two.
+        const charsPerToken = charsPerTokenFor(supports, config.model);
         Object.assign(first.usage, cacheDiagnosis(previous, request, names, first.usage), {
             toolsDeclared: declared.length,
-            toolSchemaTokens: Math.ceil(toolsChars(declared) / charsPerTokenFor(supports, config.model)),
+            toolSchemaTokens: Math.ceil(toolsChars(declared) / charsPerToken),
+            context: contextTokens({ model: config.model, stream: true, messages: request, tools: declared }, { charsPerToken, promptTokens: first.usage.prompt }),
         });
         const firstPrompt = first.usage.prompt;
+        // Recorded from the first request for the same reason. A cache count above the prompt is a
+        // server reporting its prompt net of the cache, whose differences would measure nothing.
+        const sent = {
+            messages: request,
+            tools: names,
+            prompt: first.usage.cached > firstPrompt ? 0 : firstPrompt,
+            through: messages.length - 1,
+        };
+        const entered = recordRequest(ledger, measured, sent);
+        if (entered !== ledger)
+            measured = sent;
+        ledger = entered;
         const turn = maxContinuations > 0
             ? await continueTurn(client, supports, build, first, { ...turnOptions, maxContinuations })
             : first;
@@ -342,6 +389,7 @@ export async function runAgentLoop(options) {
                 totalTokens: usage.total,
                 cachedTokens: usage.cached,
                 turn: { ...turn.usage, finishReason: turn.finishReason },
+                ledger,
             },
         });
         if (turn.finishReason === "length") {
@@ -391,11 +439,12 @@ export async function runAgentLoop(options) {
                 : {}),
         });
         if (!calls.length) {
+            let afterTurn = Promise.resolve([]);
             if (hooks) {
                 const at = question ? messages.indexOf(question) : -1;
                 // Not awaited: the answer is ready, and remembering it is not something to hold it for.
-                // `notify` never rejects.
-                void notify(hooks.run, "afterTurn", {
+                // Handed back instead, for a host that wants its notes.
+                afterTurn = notify(hooks.run, "afterTurn", {
                     ...hooks.context,
                     reply: turn.content,
                     ...(at >= 0
@@ -417,12 +466,16 @@ export async function runAgentLoop(options) {
                 loaded: [...loaded],
                 used: [...used],
                 notes: gathered.notes,
+                context: gathered.context,
+                preface,
+                afterTurn,
                 metrics: {
                     ...metrics,
                     ...(onDemand ? loads : {}),
                     wallMs: Date.now() - started,
                     outcome: turn.finishReason === "length" ? "truncated" : "answered",
                 },
+                ledger,
             };
         }
         // Per step, not per run: the answer to a call made two steps ago was true before the tools in
@@ -430,7 +483,11 @@ export async function runAgentLoop(options) {
         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) });
+            // Built for every call rather than only the dispatched ones, so a host hears of the calls
+            // the loop answers itself in the same shape. Arguments that could not be read are none.
+            const request = { id: call.id, name, args: args ?? {}, raw };
+            onEvent({ kind: "tool-call", id: call.id, name, text: preview(raw) });
+            onToolCall?.(request);
             let content;
             let ok = true;
             try {
@@ -452,7 +509,6 @@ export async function runAgentLoop(options) {
                     if (onDemand && inCatalog(catalog, name))
                         loaded.add(name);
                     used.add(name);
-                    const request = { id: call.id, name, args, raw };
                     content = dedupable(request)
                         ? await once(answered, `${name}\0${normal}`, () => dispatch(request, signal))
                         : await dispatch(request, signal);
@@ -464,8 +520,10 @@ export async function runAgentLoop(options) {
                 content = errorMessage(error);
                 ok = false;
             }
-            onEvent({ kind: "tool-result", name, ok, text: preview(content) });
-            return { id: call.id, name, ok, content };
+            onEvent({ kind: "tool-result", id: call.id, name, ok, text: preview(content) });
+            const result = { id: call.id, name, ok, content };
+            onToolResult?.(result);
+            return result;
         };
         const outcomes = [];
         if (parallel) {
@@ -479,7 +537,7 @@ export async function runAgentLoop(options) {
             }
         }
         for (const { id, name, ok, content } of outcomes) {
-            toolCalls.push({ name, ok });
+            toolCalls.push({ id, name, ok });
             messages.push({ role: "tool", tool_call_id: id, content });
         }
     }

package/dist/compaction.d.ts

@@ -62,6 +62,17 @@ export interface CompactionOptions {
     compactAt?: number;
     /** The fraction of `limit` the kept tail may fill. `KEEP_RATIO` by default. */
     keepRatio?: number;
+    /**
+     * The fraction of `limit` the whole request should come down to, in place of `keepRatio`: the
+     * cut is the earliest that leaves `used`, less what is folded, plus `summaryTokens`, at or under
+     * it. Absent, or not above zero, plans by `keepRatio` as before.
+     */
+    target?: number;
+    /**
+     * What the summary is assumed to cost when planning to a `target` — the ceiling its writer is
+     * held to, since the plan is made before it is written. 1024 by default, which is `summariser`'s.
+     */
+    summaryTokens?: number;
     /** One message's tokens. `messageTokens` by default, divided by `charsPerToken`. */
     estimate?: (message: Message) => number;
     /**
@@ -91,6 +102,12 @@ export interface CompactionPlan {
     toSummarise: Message[];
     /** The summary an earlier compaction left, which this one continues. */
     previous?: string;
+    /**
+     * What the request is expected to cost once folded, in tokens: what was in use, less what is
+     * summarised, plus the summary's ceiling. Only on a plan made to a `target`, and above the
+     * target where no legal cut reaches it.
+     */
+    after?: number;
 }
 /**
  * Where to fold a transcript that has grown into its window, or `undefined` when it should not be.
@@ -107,11 +124,20 @@ export interface CompactionPlan {
  * 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.
  *
+ * `keepRatio` bounds the kept tail alone, and the system prompt, the tool schemas and the summary
+ * sit in the window on top of it uncounted. Given a `target` the plan is made against what the
+ * request will be afterwards instead: the cut is the first user message at which `used`, less the
+ * folded messages, plus the summary's ceiling, is at or under that share of the window. Where no
+ * cut gets there the plan folds up to the last user message, which is as near as a legal one
+ * comes, and `after` says how far short it fell. An earlier summary the new one replaces is not
+ * credited, so `after` errs high by at most that much. It is only as good as `estimate` — see
+ * `estimateFrom` for one that is measured.
+ *
  * @param messages The transcript, system prompts included if the caller keeps them in it.
  * @param options The window, what is in use, the ratios, and where the last fold ended. See
  * `CompactionOptions`.
  */
-export declare function planCompaction(messages: Message[], { limit, used, compactAt, keepRatio, charsPerToken, estimate, from: givenFrom, previous: givenPrevious, }: CompactionOptions): CompactionPlan | undefined;
+export declare function planCompaction(messages: Message[], { limit, used, compactAt, keepRatio, target, summaryTokens, charsPerToken, estimate, from: givenFrom, previous: givenPrevious, }: CompactionOptions): CompactionPlan | undefined;
 /**
  * What the summariser is handed for a plan: the earlier summary if there was one, then each
  * message as its role and at most 4000 characters of its text.

package/dist/compaction.js

@@ -5,6 +5,8 @@ import { ask } from "./side-task.js";
 export const COMPACT_AT = 0.75;
 /** The fraction of the window the kept tail may fill, leaving room for the run to grow again. */
 export const KEEP_RATIO = 0.35;
+/** The ceiling `summariser` gives a summary, and what `planCompaction` assumes one will cost. */
+const SUMMARY_TOKENS = 1024;
 /** How much of any one message the summariser is shown. A pasted file is not worth it whole. */
 const SUMMARY_SLICE = 4000;
 /**
@@ -104,11 +106,20 @@ export function pruneToolResults(messages, { keepLast = 5, maxChars = 256 } = {}
  * 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.
  *
+ * `keepRatio` bounds the kept tail alone, and the system prompt, the tool schemas and the summary
+ * sit in the window on top of it uncounted. Given a `target` the plan is made against what the
+ * request will be afterwards instead: the cut is the first user message at which `used`, less the
+ * folded messages, plus the summary's ceiling, is at or under that share of the window. Where no
+ * cut gets there the plan folds up to the last user message, which is as near as a legal one
+ * comes, and `after` says how far short it fell. An earlier summary the new one replaces is not
+ * credited, so `after` errs high by at most that much. It is only as good as `estimate` — see
+ * `estimateFrom` for one that is measured.
+ *
  * @param messages The transcript, system prompts included if the caller keeps them in it.
  * @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 }), from: givenFrom, previous: givenPrevious, }) {
+export function planCompaction(messages, { limit, used, compactAt = COMPACT_AT, keepRatio = KEEP_RATIO, target, summaryTokens = SUMMARY_TOKENS, 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);
@@ -117,20 +128,42 @@ export function planCompaction(messages, { limit, used, compactAt = COMPACT_AT,
     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;
-    for (let at = messages.length - 1; at > from; at--) {
-        kept += estimate(messages[at]);
-        if (kept > budget)
-            break;
-        cut = at;
+    let after;
+    if (target !== undefined && target > 0) {
+        // Forward from the head, so the first cut that reaches the target is the one that folds least.
+        let folded = 0;
+        for (let at = from; at < messages.length; at++) {
+            if (messages[at].role === "user") {
+                cut = at;
+                after = cost - folded + summaryTokens;
+                if (after <= limit * target)
+                    break;
+            }
+            folded += estimate(messages[at]);
+        }
+    }
+    else {
+        const budget = limit * keepRatio;
+        let kept = 0;
+        for (let at = messages.length - 1; at > from; at--) {
+            kept += estimate(messages[at]);
+            if (kept > budget)
+                break;
+            cut = at;
+        }
+        while (cut < messages.length && messages[cut].role !== "user")
+            cut++;
     }
-    while (cut < messages.length && messages[cut].role !== "user")
-        cut++;
     if (cut >= messages.length || cut - from < 2)
         return undefined;
-    return { from, cut, toSummarise: messages.slice(from, cut), ...(previous ? { previous } : {}) };
+    return {
+        from,
+        cut,
+        toSummarise: messages.slice(from, cut),
+        ...(previous ? { previous } : {}),
+        ...(after === undefined ? {} : { after: Math.round(after) }),
+    };
 }
 /**
  * What the summariser is handed for a plan: the earlier summary if there was one, then each
@@ -158,7 +191,7 @@ export function summaryInput(plan) {
  * @param options Cancellation and notices; the ceiling is 1024 and the instruction
  * `SUMMARY_PROMPT` unless given.
  */
-export const summariser = (config, model, { system = SUMMARY_PROMPT, maxTokens = 1024, ...options } = {}) => (text) => ask(config, model, system, text, { maxTokens, ...options });
+export const summariser = (config, model, { system = SUMMARY_PROMPT, maxTokens = SUMMARY_TOKENS, ...options } = {}) => (text) => ask(config, model, system, text, { maxTokens, ...options });
 /**
  * The hooks and the summariser for a plan, as a record to store rather than a transcript to send.
  *

package/dist/events.d.ts

@@ -1,3 +1,4 @@
+import type { TokenLedger } from "./ledger.ts";
 import type { TurnUsage } from "./stream.ts";
 /**
  * What a run is doing, while it is doing it.
@@ -76,9 +77,9 @@ export type RunEventKind =
  | "thinking"
 /** Reply tokens, as they arrive. */
  | "output"
-/** The model asked for a tool, with the arguments it chose. */
+/** The model asked for a tool, with the arguments it chose. `id` is the call's. */
  | "tool-call"
-/** A tool came back, with what it said. */
+/** A tool came back, with what it said. `id` is the id of the call it answers. */
  | "tool-result"
 /** Something the runner did that is not the model's doing — a preselection, a retry. */
  | "notice"
@@ -110,6 +111,12 @@ export interface RunUsage {
      * from a caller emitting usage of its own.
      */
     turn?: TurnReport;
+    /**
+     * The run's token ledger as of this turn, whole rather than the entry it added — a host whose
+     * run then fails still holds the latest one, and a rewrite in `beforeStep` moves earlier entries.
+     * Absent from a caller emitting usage of its own.
+     */
+    ledger?: TokenLedger;
 }
 /** One turn's usage and measurements as a `usage` event carries them. */
 export interface TurnReport extends TurnUsage {
@@ -119,8 +126,8 @@ export interface TurnReport extends TurnUsage {
 /**
  * One thing that happened in a run, as a watcher receives it.
  *
- * Every field is always present — the empty ones are `""` or `null` rather than missing — so a
- * client reads it without guarding each key.
+ * Every field but `id` is always present — the empty ones are `""` or `null` rather than
+ * missing — so a client reads it without guarding each key.
  */
 export interface RunEvent {
     /** The run it belongs to. `emit` fills this in; a caller does not pass it. */
@@ -141,6 +148,12 @@ export interface RunEvent {
     text: string;
     /** Tool name on the tool kinds, otherwise empty. */
     name: string;
+    /**
+     * The call's id on the tool kinds, which pairs a `tool-result` with its `tool-call` when one
+     * tool is called twice in a step. The one field `emit` does not fill in: it is there only where
+     * the emitter gave one, and optional so an event built before it existed still compiles.
+     */
+    id?: string;
     /**
      * The caller's own flow step this happened inside, so a watcher can group a run the way the
      * work is written. Empty for events that belong to the run rather than to any one step, and

package/dist/hooks.d.ts

@@ -204,11 +204,17 @@ export declare function assembleContext(outcomes: readonly HookOutcome[], maxTok
  * system prompt that changed every turn would miss the prompt cache every turn. Nothing is written
  * back: a host that stores what the user typed never remembers the context as something they said.
  *
+ * A question keeps its context for as long as it is sent. A host stores `context`, and the preface
+ * it was said under, beside the question and calls this for each stored one on every later request
+ * — a question sent with its blocks one turn and bare the next is a different prompt from that
+ * message on, and loses the server's prefix cache behind it.
+ *
  * @param history The request's messages. Neither the array nor any message in it is changed.
- * @param index Where this turn's question sits in `history` — which is not where it sits in the
+ * @param index Where the question sits in `history` — which is not where it sits in the
  * session once a compaction has folded the head into a summary. Anything but a user message there
  * leaves the request as it was.
- * @param context What `assembleContext` built. Empty returns `history` itself.
+ * @param context What `assembleContext` built, this turn or the turn the question was asked.
+ * Empty returns `history` itself.
  * @param preface Said above the blocks. Absent is what `configureHooks` last set — `HOOK_PREFACE`
  * unless something moved it. Empty says nothing, rather than leaving a blank line where it was.
  * @returns `history` when there was nothing to add or nowhere to add it, otherwise a new array.

package/dist/hooks.js

@@ -128,11 +128,17 @@ export function assembleContext(outcomes, maxTokens) {
  * system prompt that changed every turn would miss the prompt cache every turn. Nothing is written
  * back: a host that stores what the user typed never remembers the context as something they said.
  *
+ * A question keeps its context for as long as it is sent. A host stores `context`, and the preface
+ * it was said under, beside the question and calls this for each stored one on every later request
+ * — a question sent with its blocks one turn and bare the next is a different prompt from that
+ * message on, and loses the server's prefix cache behind it.
+ *
  * @param history The request's messages. Neither the array nor any message in it is changed.
- * @param index Where this turn's question sits in `history` — which is not where it sits in the
+ * @param index Where the question sits in `history` — which is not where it sits in the
  * session once a compaction has folded the head into a summary. Anything but a user message there
  * leaves the request as it was.
- * @param context What `assembleContext` built. Empty returns `history` itself.
+ * @param context What `assembleContext` built, this turn or the turn the question was asked.
+ * Empty returns `history` itself.
  * @param preface Said above the blocks. Absent is what `configureHooks` last set — `HOOK_PREFACE`
  * unless something moved it. Empty says nothing, rather than leaving a blank line where it was.
  * @returns `history` when there was nothing to add or nowhere to add it, otherwise a new array.

package/dist/index.d.ts

@@ -9,7 +9,7 @@
  * prompts, and whatever the run is about — because that is the caller's, and it is the part
  * that differs between one server and the next.
  */
-export { type AgentLoopHooks, type AgentLoopOptions, type AgentLoopResult, buildBody, preselect, preview, resolveApiKey, runAgentLoop, type ToolCallOutcome, type ToolCallRequest, } from "./agent-loop.ts";
+export { type AgentLoopHooks, type AgentLoopOptions, type AgentLoopRequest, type AgentLoopResult, buildBody, preselect, preview, resolveApiKey, runAgentLoop, type StepWindow, type ToolCallOutcome, type ToolCallRequest, type ToolCallResult, } from "./agent-loop.ts";
 export { calibrate, charsPerTokenFor, resetCalibration } from "./calibration.ts";
 export { type Capabilities, capabilitiesFor, EFFORT_LADDER, effortFor, expireCapabilities, type ModelCapabilities, modelCapabilitiesFor, type NegotiateOptions, negotiate, resetCapabilities, } from "./capabilities.ts";
 export type { CatalogServer } from "./catalog.ts";
@@ -20,6 +20,7 @@ export { type ContinueTurnOptions, continueTurn, isContinuable, } from "./contin
 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 { estimateFrom, type LedgerEntry, type LedgerEstimateOptions, type LedgerRequest, rebaseLedger, recordRequest, type TokenLedger, tokensBetween, } from "./ledger.ts";
 export { resetAll } from "./reset.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";

package/dist/index.js

@@ -18,6 +18,7 @@ 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 { estimateFrom, rebaseLedger, recordRequest, tokensBetween, } from "./ledger.js";
 export { resetAll } from "./reset.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";

package/dist/ledger.d.ts

@@ -0,0 +1,132 @@
+import type OpenAI from "openai";
+import { type TokenEstimateOptions } from "./retry.ts";
+/**
+ * What stretches of a transcript cost, read off the prompt counts the server already reported.
+ *
+ * A calibrated divisor fixes the average and nothing else: a transcript is tool results, JSON
+ * arguments, code and prose, each at its own ratio, plus whatever the chat template adds per
+ * message. But a request that only appended to the one before it differs from it by exactly the
+ * cost of what was appended, so two reported prompts and a subtraction say what no estimate can —
+ * the template's tokens and a tool result's real density included, and reasoning, which is never
+ * replayed, left out.
+ *
+ * Everything here is a pure function over a plain array, so a host with its own loop keeps a ledger
+ * the same way `runAgentLoop` does, and stores it however it stores the transcript.
+ */
+type Message = OpenAI.ChatCompletionMessageParam;
+/**
+ * One request's reported prompt, and how far into the transcript that request reached.
+ *
+ * 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.
+ */
+export interface LedgerEntry {
+    /**
+     * The index, in the host's transcript, of the last message the request carried. A system prompt
+     * the host keeps outside the transcript is not counted, and −1 is a request that carried none of
+     * the transcript at all.
+     */
+    through: number;
+    /** The prompt tokens the endpoint reported for that request, everything ahead of it included. */
+    prompt: number;
+    /**
+     * Which unbroken run of appending the request belongs to. Two entries with the same epoch shared
+     * everything up to the earlier one's last message, so their prompts subtract; two with different
+     * epochs did not, and the difference between them means nothing.
+     */
+    epoch: number;
+}
+/** 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 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[];
+    /** 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. */
+    through: number;
+}
+/** 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.
+     */
+    estimate?: (message: Message) => number;
+}
+/**
+ * The ledger with one more request on it, in the epoch the request before it says it belongs to.
+ *
+ * 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.
+ *
+ * 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.
+ *
+ * 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
+ * character share — the way `contextTokens` divides a reported prompt — and messages no pair of
+ * entries covers fall back to the estimate: the ones before the first entry, the group either side
+ * of an epoch's end, and whatever has not been sent yet.
+ *
+ * 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.
+ *
+ * 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 {};