@cubicecho/agent-core 2.18.1 → 2.20.0

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";
@@ -31,4 +32,4 @@ export { type Produced, type StreamTurnOptions, streamTurn, type Turn, type Turn
 export { ALL_FENCES, DEFAULT_FENCES, type Fence, FenceSplitter, type FenceSplitterOptions, type Split, stripThinking, THINK_FENCE, } from "./thinking.ts";
 export { estimateTokens } from "./tokens.ts";
 export { parseToolArguments, recoverToolCalls, ToolArgumentsError, type ToolCall, } from "./tool-calls.ts";
-export { carryOver, catalogList, catalogPrompt, expandNames, inCatalog, KEYWORD_DROPOFF, KEYWORD_MIN_SCORE, type KeywordPreselection, type KeywordPreselectOptions, LOAD_TOOLS, LOAD_TOOLS_DEFINITION, loadedTools, loadResult, MAX_CARRIED, MAX_PER_LOAD, orderTools, PRESELECT_SCHEMA, PRESELECT_SYSTEM, preselectByKeywords, preselectInput, preselection, preselectSystem, requestedNames, type ToolMatch, type ToolOrder, } from "./tool-loading.ts";
+export { CALL_TOOL, carryOver, catalogList, catalogPrompt, expandNames, holdsDefinitions, inCatalog, KEYWORD_DROPOFF, KEYWORD_MIN_SCORE, type KeywordPreselection, type KeywordPreselectOptions, 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, type ToolMatch, type ToolOrder, } from "./tool-loading.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";
@@ -29,4 +30,4 @@ export { streamTurn, } from "./stream.js";
 export { ALL_FENCES, DEFAULT_FENCES, FenceSplitter, stripThinking, THINK_FENCE, } from "./thinking.js";
 export { estimateTokens } from "./tokens.js";
 export { parseToolArguments, recoverToolCalls, ToolArgumentsError, } from "./tool-calls.js";
-export { carryOver, catalogList, catalogPrompt, expandNames, inCatalog, KEYWORD_DROPOFF, KEYWORD_MIN_SCORE, LOAD_TOOLS, LOAD_TOOLS_DEFINITION, loadedTools, loadResult, MAX_CARRIED, MAX_PER_LOAD, orderTools, PRESELECT_SCHEMA, PRESELECT_SYSTEM, preselectByKeywords, preselectInput, preselection, preselectSystem, requestedNames, } from "./tool-loading.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";

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 {};

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/spec.d.ts

@@ -105,7 +105,11 @@ export interface PromptPart {
 }
 /** How tools reach the model, and which servers this agent may reach at all. */
 export interface ToolsSpec {
-    discovery?: "eager" | "ondemand";
+    /**
+     * How tool definitions reach the model: all of them on every request, a name-only catalogue
+     * the model loads from, or that catalogue behind a fixed `load_tools` and `call_tool`.
+     */
+    discovery?: "eager" | "ondemand" | "proxy";
     /** The hard stop on a tool loop. At least one. */
     maxIterations?: number;
     /**

package/dist/spec.js

@@ -206,10 +206,12 @@ function parseTools(report, value) {
         return void report.drop("tools", "must be an object");
     let discovery;
     if (!absent(value.discovery)) {
-        if (value.discovery === "eager" || value.discovery === "ondemand")
+        if (value.discovery === "eager" ||
+            value.discovery === "ondemand" ||
+            value.discovery === "proxy")
             discovery = value.discovery;
         else
-            report.drop("tools.discovery", 'must be "eager" or "ondemand"');
+            report.drop("tools.discovery", 'must be "eager", "ondemand" or "proxy"');
     }
     let servers;
     if (!absent(value.servers)) {

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

@@ -180,6 +180,104 @@ export declare const inCatalog: (catalog: CatalogServer[], name: string) => bool
  * @param args The tool call's arguments, exactly as the model sent them.
  */
 export declare function requestedNames(args: Record<string, unknown>): string[];
+/**
+ * The one tool a proxied run reaches every catalogued tool through.
+ *
+ * Proxied discovery is on-demand loading with a tool array that never changes. On-demand mode
+ * declares each tool as it is loaded, and a chat template renders the tool array in the system
+ * turn, ahead of the whole conversation — so appending one definition there moves every token
+ * after it, and on a model llama.cpp can only rewind to a saved checkpoint a single load
+ * re-prefills the transcript from the first token. Proxied, the array is `load_tools` and
+ * `call_tool` for the life of the session: a load answers with the definitions as its result, at
+ * the end of the history where the cache already stops, and the model runs a loaded tool through
+ * this one. The price is a level of indirection the model has to get right, which a small model
+ * does less reliably than a native call.
+ */
+export declare const CALL_TOOL = "call_tool";
+/**
+ * The whole tool array of a proxied run, `load_tools` then `call_tool`, frozen because it is
+ * shared.
+ *
+ * The load keeps `LOAD_TOOLS` as its name, so `requestedNames` and `expandNames` read its
+ * arguments as they do on demand; only what it promises differs, which is why it is not
+ * `LOAD_TOOLS_DEFINITION`. `call_tool`'s `arguments` says `additionalProperties: true` and has to:
+ * `sanitizeTools` gives an object with no properties an empty property list, a grammar-constrained
+ * server compiles that to `{}`, and without the keyword the model is left no way to pass an
+ * argument at all.
+ */
+export declare const PROXY_TOOLS: readonly OpenAI.ChatCompletionTool[];
+/**
+ * The catalogue block for a proxied run's system prompt, worded for `call_tool` rather than for a
+ * tool list.
+ *
+ * `catalogPrompt` tells the model a loaded tool is in its tool list, which proxied is never true —
+ * a model told so looks for it there and calls it natively. The listing itself is the same, and
+ * like that one it is never marked, so the head of the prompt is one text for the whole session.
+ *
+ * @param catalog The connected servers. A catalogue with no tools in it produces an empty string.
+ */
+export declare function proxyCatalogPrompt(catalog: CatalogServer[]): string;
+/**
+ * Whether a tool result is a proxied load carrying definitions, which is the only copy of them
+ * the model has.
+ *
+ * On demand the definitions are in the tool array and a load's result only repeats their
+ * descriptions, so clearing it loses nothing. Proxied, the result is the schema, and
+ * `pruneToolResults` asks this before it stubs one. Told by how `proxyLoadResult` opens, the way
+ * a summary is told by `SUMMARY_LEAD`, because a `tool` message carries no tool name of its own.
+ *
+ * @param result The tool message's text. A load that only pointed back or refused is not one.
+ */
+export declare const holdsDefinitions: (result: string) => boolean;
+/**
+ * What a proxied `load_tools` answers: each new tool's whole definition as a line of JSON, since
+ * the result is the only place the model will ever see it.
+ *
+ * A name loaded before this call is answered with a pointer back rather than its definition a
+ * second time, and one the catalogue lists but `definitions` does not hold is said to have none,
+ * so the model is not left waiting on a schema that is not coming. The refusals — too broad, over
+ * the per-call cap, not in the catalogue, nothing asked for — are `loadResult`'s, worded the same
+ * in both modes.
+ *
+ * @param resolved What the call asked for, from `expandNames`.
+ * @param catalog The servers, read for the refusals' wording.
+ * @param definitions The definitions of `resolved.matched`, as many as the host has. Ones that
+ * are not functions are skipped.
+ * @param loaded What was loaded before this call. Absent reports every match as newly loaded.
+ */
+export declare function proxyLoadResult(resolved: ReturnType<typeof expandNames>, catalog: CatalogServer[], definitions: readonly OpenAI.ChatCompletionTool[], loaded?: ReadonlySet<string>): string;
+/**
+ * The tool a `call_tool` names and the arguments to run it with, or a throw the model can read.
+ *
+ * `arguments` arrives as an object when the model follows the schema and as a JSON string when it
+ * copies the shape of a native call instead; both are taken, since the intent is the same. A name
+ * outside the catalogue is refused here rather than handed to a dispatcher, which is what keeps
+ * `call_tool` from reaching anything the catalogue does not offer.
+ *
+ * @param args The `call_tool` call's own arguments, parsed. An absent `arguments` is no arguments.
+ * @param catalog What may be called. The name is trimmed and then matched exactly.
+ */
+export declare function proxiedCall(args: Record<string, unknown>, catalog: CatalogServer[]): {
+    name: string;
+    input: Record<string, unknown>;
+};
+/**
+ * A tool call as a watcher should see it: a `call_tool` as the tool it ran, anything else as it
+ * is.
+ *
+ * The transcript keeps the `call_tool` the model wrote, since the next request has to repeat it
+ * word for word to stay in the cache; only the display looks through it. Anything that does not
+ * parse as a proxied call is left as it came.
+ *
+ * @param name The name the model called.
+ * @param input The call's arguments as JSON text.
+ * @returns The inner name and its arguments as JSON text — the string itself where the model
+ * passed `arguments` as one.
+ */
+export declare function shownCall(name: string, input: string): {
+    name: string;
+    input: string;
+};
 /**
  * The system prompt a preselector is given, holding it to the cap its answer will be held to.
  *