@cubicecho/agent-core 2.18.0 → 2.19.0

package/dist/ledger.js

@@ -0,0 +1,166 @@
+import { messageChars, messageTokens } from "./retry.js";
+/** Whether two messages say the same thing, by identity first since most of a transcript is. */
+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) => {
+    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])));
+};
+/**
+ * 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 function recordRequest(ledger, previous, next) {
+    if (!(next.prompt > 0))
+        return ledger;
+    const last = ledger.at(-1);
+    if (last && previous && appended(previous, next)) {
+        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 },
+    ];
+}
+/**
+ * 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 function rebaseLedger(ledger, 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]))
+        head++;
+    if (head === before.length)
+        return ledger;
+    let tail = 0;
+    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 }]
+            : []);
+}
+/**
+ * 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.
+ */
+function shares(ledger, messages) {
+    const out = new Map();
+    let floor = 0;
+    for (let at = 1; at < ledger.length; at++) {
+        const from = ledger[at - 1];
+        const to = ledger[at];
+        const tokens = to.prompt - from.prompt;
+        const start = from.through + 1;
+        const end = to.through + 1;
+        if (from.epoch !== to.epoch || !(tokens > 0))
+            continue;
+        if (start < floor || end <= start || end > messages.length)
+            continue;
+        floor = end;
+        const chars = [];
+        let total = 0;
+        for (let index = start; index < end; index++) {
+            chars.push(messageChars(messages[index]));
+            total += chars[index - start];
+        }
+        for (let index = start; index < end; index++) {
+            out.set(index, (tokens * chars[index - start]) / total);
+        }
+    }
+    return out;
+}
+/** The estimate for a message nothing measured, as the options ask for it. */
+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.
+ *
+ * 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 function tokensBetween(ledger, from, to, messages, options = {}) {
+    const measured = shares(ledger, messages);
+    const estimate = fallback(options);
+    let total = 0;
+    for (let at = Math.max(0, from); at < Math.min(to, messages.length); at++) {
+        total += measured.get(at) ?? estimate(messages[at]);
+    }
+    return Math.round(total);
+}
+/**
+ * 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 function estimateFrom(ledger, messages, options = {}) {
+    const estimate = fallback(options);
+    const measured = new Map();
+    for (const [at, tokens] of shares(ledger, messages))
+        measured.set(messages[at], tokens);
+    return (message) => measured.get(message) ?? estimate(message);
+}

package/dist/retry.d.ts

@@ -44,6 +44,12 @@ export interface TokenEstimateOptions {
      */
     charsPerToken?: number;
 }
+/**
+ * How many characters one message is worth: its keys, and its content in whichever shape.
+ *
+ * @param message The message as it will be sent.
+ */
+export declare function messageChars(message: OpenAI.ChatCompletionMessageParam): number;
 /**
  * How many characters a tool array is worth, measured once per array.
  *

package/dist/retry.js

@@ -71,8 +71,12 @@ const REASONING_ALT_KEY = 15;
 export const CHARS_PER_TOKEN = 4;
 /** The divisor an option asked for, or the fallback when it asked for nothing usable. */
 const divisor = (charsPerToken) => charsPerToken !== undefined && charsPerToken > 0 ? charsPerToken : CHARS_PER_TOKEN;
-/** How many characters one message is worth: its keys, and its content in whichever shape. */
-function messageChars(message) {
+/**
+ * How many characters one message is worth: its keys, and its content in whichever shape.
+ *
+ * @param message The message as it will be sent.
+ */
+export function messageChars(message) {
     let chars = message.role.length + ENVELOPE;
     const { content } = message;
     if (typeof content === "string")

package/dist/stream.d.ts

@@ -1,4 +1,5 @@
 import type OpenAI from "openai";
+import { type ContextBreakdown } from "./retry.ts";
 import { type Fence } from "./thinking.ts";
 /**
  * Reading one streamed turn back into a message.
@@ -95,6 +96,16 @@ export interface TurnUsage {
      * prompt, so this is what every change to the tool list costs the cache.
      */
     toolSchemaTokens?: number;
+    /**
+     * What the request was made of, as `contextTokens` cuts it, filled by `runAgentLoop`. Shares of
+     * the prompt the turn's first request reported, summing to it, or an estimate where none was.
+     *
+     * Measured on the request as first built, with the tools as `toolSchemaTokens` measures them. A
+     * continued turn's `prompt` is every request's summed, so it is larger than this `total`; and
+     * where a refusal was answered with a lesser body, the prompt is that body's and the proportions
+     * are still the first one's.
+     */
+    context?: ContextBreakdown;
 }
 /** One streamed turn, put back together into the shape a loop and a transcript work with. */
 export interface Turn {

package/dist/tool-loading.d.ts

@@ -107,21 +107,30 @@ export declare function orderTools(tools: OpenAI.ChatCompletionTool[], order?: T
 export declare const MAX_PER_LOAD = 12;
 /**
  * The most a conversation carries between turns. Bounds the tool array no matter how long the
- * conversation runs; least-recently-used names fall off the front.
+ * conversation runs; past it, the earliest-declared names this turn did not use fall off first.
  *
  * Only a multi-turn caller needs this — a run that starts from nothing each time has nothing to
  * carry. See `carryOver`, which takes another number if this one is not yours.
  */
 export declare const MAX_CARRIED = 16;
 /**
- * The tools to start the next turn with: recently used, newest last, capped.
- *
- * @param previous Last turn's names, oldest first.
- * @param used What this turn called. Moved to the end, so the oldest unused fall off.
- * @param max How many to carry, defaulting to `MAX_CARRIED`. At least one: a cap of zero is
- * read as no cap, which is what `slice` does with it and not what anybody asking for zero meant.
+ * The tools to start the next turn with: last turn's where they were, then what this turn used.
+ *
+ * Nothing carried moves. A template renders the tool array near the head of the prompt, and
+ * moving each used tool to the end — which this did until it was found in a local server's cache
+ * log — reordered the array between turns and re-prefilled the whole transcript from the first
+ * moved definition. Kept in place, the next turn's array is this one's with only the unused
+ * loads gone, a prefix of it when every load was used. Past `max`, dropping a name from the
+ * middle costs the cache from there, so it happens only when the cap forces it.
+ *
+ * @param previous Last turn's names, in the order they were declared.
+ * @param used What this turn called. Names not already carried are appended in the order given,
+ * so pass them in load order to keep them where the tool array had them.
+ * @param max How many to carry, defaulting to `MAX_CARRIED`. Past it, the earliest names not in
+ * `used` go first, then the earliest of all. At least one: a cap of zero is read as one, not as
+ * no cap and not as none.
  */
-export declare const carryOver: (previous: string[], used: Set<string>, max?: number) => string[];
+export declare function carryOver(previous: readonly string[], used: ReadonlySet<string>, max?: number): string[];
 /**
  * Resolves requested names against the catalogue, expanding trailing `*` wildcards.
  *

package/dist/tool-loading.js

@@ -174,21 +174,38 @@ export function orderTools(tools, order = true) {
 export const MAX_PER_LOAD = 12;
 /**
  * The most a conversation carries between turns. Bounds the tool array no matter how long the
- * conversation runs; least-recently-used names fall off the front.
+ * conversation runs; past it, the earliest-declared names this turn did not use fall off first.
  *
  * Only a multi-turn caller needs this — a run that starts from nothing each time has nothing to
  * carry. See `carryOver`, which takes another number if this one is not yours.
  */
 export const MAX_CARRIED = 16;
 /**
- * The tools to start the next turn with: recently used, newest last, capped.
- *
- * @param previous Last turn's names, oldest first.
- * @param used What this turn called. Moved to the end, so the oldest unused fall off.
- * @param max How many to carry, defaulting to `MAX_CARRIED`. At least one: a cap of zero is
- * read as no cap, which is what `slice` does with it and not what anybody asking for zero meant.
+ * The tools to start the next turn with: last turn's where they were, then what this turn used.
+ *
+ * Nothing carried moves. A template renders the tool array near the head of the prompt, and
+ * moving each used tool to the end — which this did until it was found in a local server's cache
+ * log — reordered the array between turns and re-prefilled the whole transcript from the first
+ * moved definition. Kept in place, the next turn's array is this one's with only the unused
+ * loads gone, a prefix of it when every load was used. Past `max`, dropping a name from the
+ * middle costs the cache from there, so it happens only when the cap forces it.
+ *
+ * @param previous Last turn's names, in the order they were declared.
+ * @param used What this turn called. Names not already carried are appended in the order given,
+ * so pass them in load order to keep them where the tool array had them.
+ * @param max How many to carry, defaulting to `MAX_CARRIED`. Past it, the earliest names not in
+ * `used` go first, then the earliest of all. At least one: a cap of zero is read as one, not as
+ * no cap and not as none.
  */
-export const carryOver = (previous, used, max = MAX_CARRIED) => [...previous.filter((name) => !used.has(name)), ...used].slice(-Math.max(1, max));
+export function carryOver(previous, used, max = MAX_CARRIED) {
+    const next = [...previous, ...[...used].filter((name) => !previous.includes(name))];
+    const cap = Math.max(1, max);
+    while (next.length > cap) {
+        const stale = next.findIndex((name) => !used.has(name));
+        next.splice(stale === -1 ? 0 : stale, 1);
+    }
+    return next;
+}
 /**
  * Resolves requested names against the catalogue, expanding trailing `*` wildcards.
  *

package/llms.txt

@@ -15,14 +15,17 @@ The loop above a turn: send, run the tools the model asked for, send again, unti
 
 - `AgentLoopHooks` (type) — The hooks a loop runs around one question.
 - `AgentLoopOptions` (type) — What `runAgentLoop` takes.
+- `AgentLoopRequest` (type) — One step's request as `onRequest` is handed it: what the model is about to read.
 - `AgentLoopResult` (type) — What a finished loop hands back.
 - `buildBody` — The one place a streamed request's body is decided from a config and what the endpoint and the model have refused.
 - `preselect` — The tools a request is likely to need, picked by a small model before the run starts, or none.
 - `preview` — A long tool argument or result cut to what a watcher needs, with the full length said.
 - `resolveApiKey` — The key to send, where an endpoint may inherit one from the settings it overrides.
 - `runAgentLoop` — Runs a question to its answer: one `runTurn` per step, the tools it asks for between them, until a turn asks for none.
+- `StepWindow` (type) — How full the window is as a step is about to be sent, as `beforeStep` is told it.
 - `ToolCallOutcome` (type) — What one tool call did, in the order the model asked.
-- `ToolCallRequest` (type) — One call the model made, as `dispatch` is handed it.
+- `ToolCallRequest` (type) — One call the model made, as `dispatch` and `onToolCall` are handed it.
+- `ToolCallResult` (type) — One call's whole answer, as `onToolResult` is handed it.
 
 ### calibration
 
@@ -163,6 +166,19 @@ Lifecycle hooks, from the host's side: what a session looks like to them, where
 - `untrusted` — Fences text nobody trusted — a fetched page, an email, a submitted card, a tool result — so the model can see where it starts and ends and read it as data rather than as instructions.
 - `withContext` — The request, with the hooks' context added to this turn's question.
 
+### ledger
+
+What stretches of a transcript cost, read off the prompt counts the server already reported.
+
+- `estimateFrom` — A per-message cost for `planCompaction`'s `estimate`: the measured share where the ledger covers the message, the calibrated estimate where it does not.
+- `LedgerEntry` (type) — One request's reported prompt, and how far into the transcript that request reached.
+- `LedgerEstimateOptions` (type) — What `tokensBetween` and `estimateFrom` take besides the ledger and the transcript.
+- `LedgerRequest` (type) — What `recordRequest` needs to know of one request.
+- `rebaseLedger` — The ledger for a transcript that has been rewritten, keeping the boundaries the rewrite left standing.
+- `recordRequest` — The ledger with one more request on it, in the epoch the request before it says it belongs to.
+- `TokenLedger` (type) — A transcript's entries in the order their requests were sent, which is also by `through`.
+- `tokensBetween` — What the messages from `from` up to, not including, `to` cost the window, measured where the ledger can say and estimated where it cannot.
+
 ### reset
 
 - `resetAll` — Forgets everything this package remembers between calls.
@@ -300,7 +316,7 @@ Reading what a model meant by a tool call when it did not write one cleanly.
 
 ### tool-loading
 
-- `carryOver` — The tools to start the next turn with: recently used, newest last, capped.
+- `carryOver` — The tools to start the next turn with: last turn's where they were, then what this turn used.
 - `catalogList` — The catalogue as a plain grouped listing of names, loaded ones marked if asked.
 - `catalogPrompt` — The catalogue block appended to the system prompt.
 - `expandNames` — Resolves requested names against the catalogue, expanding trailing `*` wildcards.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cubicecho/agent-core",
-  "version": "2.18.0",
+  "version": "2.19.0",
   "description": "The endpoint-agnostic half of an OpenAI-compatible agent loop: tool-schema compatibility, on-demand tool loading, one-shot side tasks, run events, and a pooled client.",
   "keywords": [
     "openai",