@cubicecho/agent-core 2.11.0 → 2.12.0

package/dist/hooks.d.ts

@@ -89,6 +89,12 @@ export interface HookOutcome {
     inject: boolean;
     /** The most of `text` that is injected, in estimated tokens. */
     maxTokens: number;
+    /**
+     * Asks that what the event announces not happen. Only a `beforeCompact` hook's is read, and
+     * only by a host that waits for it — see `consult` — and never on an outcome that is not `ok`,
+     * since a hook that crashed has not said anything.
+     */
+    veto?: boolean;
 }
 /**
  * One hook's line for whoever is watching: the context it added, or why it added none. A hook
@@ -105,6 +111,8 @@ export interface HookNote {
     text?: string;
     /** Why it added nothing: it failed, timed out, or never ran. */
     error?: string;
+    /** Set when the hook vetoed what the event announced, and was waited for. See `consult`. */
+    veto?: true;
 }
 /**
  * Runs one event's hooks. Should resolve rather than reject — a hook failing is an outcome — but
@@ -297,7 +305,8 @@ export declare function gather(run: HookRunner, events: readonly HookEvent[], co
  * rejects, so a host can fire it without awaiting it.
  *
  * No signal: these run once the turn has been answered, and a reader who stops listening at that
- * point has not asked for the turn not to be remembered.
+ * point has not asked for the turn not to be remembered. Nor is a `veto` read, since whatever it
+ * would stop is already under way; `consult` is the one that waits for it.
  *
  * @param run Runs the event's hooks.
  * @param event `afterTurn`, `beforeCompact`, `sessionEnd` or `sessionDelete`. An injecting event
@@ -307,3 +316,22 @@ export declare function gather(run: HookRunner, events: readonly HookEvent[], co
  * @returns The same notes.
  */
 export declare function notify(run: HookRunner, event: HookEvent, context: HookContext, onNote?: (note: HookNote) => void): Promise<HookNote[]>;
+/**
+ * Runs an event's hooks and waits for their say, for a host that will hold off when one of them
+ * vetoes.
+ *
+ * `notify` runs beside the thing it announces and cannot stop it; this runs ahead of it, so each
+ * hook's time is added to whatever waits on the answer. A host that does not mean to act on a
+ * veto should call `notify` instead. Never rejects: a runner that throws is noted as a failure,
+ * and a failure is not a veto — a memory server that is down has not asked for anything.
+ *
+ * @param run Runs the event's hooks.
+ * @param event What is about to happen. Only `beforeCompact` has anything a veto can stop.
+ * @param context What the hooks are told.
+ * @param onNote Hears each note: every failure, and every veto, naming the hook that made it.
+ * @returns The same notes, and `vetoed` when any `ok` outcome carried `veto`.
+ */
+export declare function consult(run: HookRunner, event: HookEvent, context: HookContext, onNote?: (note: HookNote) => void): Promise<{
+    notes: HookNote[];
+    vetoed: boolean;
+}>;

package/dist/hooks.js

@@ -279,7 +279,8 @@ export async function gather(run, events, context, { signal, onNote, maxTokens,
  * rejects, so a host can fire it without awaiting it.
  *
  * No signal: these run once the turn has been answered, and a reader who stops listening at that
- * point has not asked for the turn not to be remembered.
+ * point has not asked for the turn not to be remembered. Nor is a `veto` read, since whatever it
+ * would stop is already under way; `consult` is the one that waits for it.
  *
  * @param run Runs the event's hooks.
  * @param event `afterTurn`, `beforeCompact`, `sessionEnd` or `sessionDelete`. An injecting event
@@ -297,3 +298,37 @@ export async function notify(run, event, context, onNote) {
         onNote?.(note);
     return notes;
 }
+/**
+ * Runs an event's hooks and waits for their say, for a host that will hold off when one of them
+ * vetoes.
+ *
+ * `notify` runs beside the thing it announces and cannot stop it; this runs ahead of it, so each
+ * hook's time is added to whatever waits on the answer. A host that does not mean to act on a
+ * veto should call `notify` instead. Never rejects: a runner that throws is noted as a failure,
+ * and a failure is not a veto — a memory server that is down has not asked for anything.
+ *
+ * @param run Runs the event's hooks.
+ * @param event What is about to happen. Only `beforeCompact` has anything a veto can stop.
+ * @param context What the hooks are told.
+ * @param onNote Hears each note: every failure, and every veto, naming the hook that made it.
+ * @returns The same notes, and `vetoed` when any `ok` outcome carried `veto`.
+ */
+export async function consult(run, event, context, onNote) {
+    const outcomes = await runSafely(run, event, context);
+    const notes = [];
+    for (const outcome of outcomes) {
+        if (!outcome.ok)
+            notes.push(assembleContext([outcome]).notes[0]);
+        else if (outcome.veto === true) {
+            notes.push({
+                event: outcome.event,
+                source: outcome.label,
+                hookId: outcome.hookId,
+                veto: true,
+            });
+        }
+    }
+    for (const note of notes)
+        onNote?.(note);
+    return { notes, vetoed: notes.some((note) => note.veto) };
+}

package/dist/index.d.ts

@@ -10,16 +10,18 @@
  * 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 { calibrate, charsPerTokenFor, resetCalibration } from "./calibration.ts";
 export { type Capabilities, capabilitiesFor, type ModelCapabilities, modelCapabilitiesFor, type NegotiateOptions, negotiate, resetCapabilities, } from "./capabilities.ts";
 export type { CatalogServer } from "./catalog.ts";
 export { type ClientPoolOptions, configureClients, contextLimitFor, endpointId, endpointKey, FIRST_TOKEN_FACTOR, firstTokenMs, getClient, listModels, type ModelInfo, NO_KEY, resetClients, servedWindow, timeoutMs, } from "./client.ts";
 export { COMPACT_AT, type CompactionOptions, type CompactionPlan, compactTranscript, KEEP_RATIO, type PruneOptions, planCompaction, pruneToolResults, SUMMARY_LEAD, SUMMARY_PROMPT, summariser, summaryInput, } from "./compaction.ts";
 export type { AgentConfig, Endpoint, ModelParams, RetryPolicy, ToolPolicy, } from "./config.ts";
+export { type ContinueTurnOptions, continueTurn, isContinuable, } from "./continuation.ts";
 export { errorMessage } from "./errors.ts";
-export { configureEvents, type EventBusOptions, emit, endRun, fold, history, type RunEvent, type RunEventInput, type RunEventKind, type RunUsage, resetEvents, watch, } from "./events.ts";
-export { assembleContext, configureHooks, 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 { configureEvents, type EventBusOptions, emit, endRun, fold, history, type RunEvent, type RunEventInput, type RunEventKind, type RunMetrics, type RunMetricsOptions, type RunUsage, resetEvents, runMetrics, type TurnReport, watch, } from "./events.ts";
+export { assembleContext, configureHooks, consult, type Gathered, gather, HOOK_CONTEXT_TOKENS, HOOK_EVENTS, HOOK_PREFACE, type HookContext, type HookEvent, type HookMessage, type HookNote, type HookOptions, type HookOutcome, type HookRunner, INJECT_EVENTS, notify, resetHooks, turnIndex, turnMessages, UNTRUSTED_PREFACE, untrusted, withContext, } from "./hooks.ts";
 export { resetAll } from "./reset.ts";
-export { backoffMs, ContextOverflow, compact, EndpointSilent, isModelLoading, isOverflow, isTransient, LOADING_POLL_MS, LOADING_TIMEOUT_MS, messageTokens, requestTokens, SMALLEST_LIKELY_WINDOW, sleep, } from "./retry.ts";
+export { backoffMs, CHARS_PER_TOKEN, ContextOverflow, compact, EndpointSilent, isModelLoading, isOverflow, isTransient, LOADING_POLL_MS, LOADING_TIMEOUT_MS, messageTokens, requestChars, requestTokens, SMALLEST_LIKELY_WINDOW, sleep, type TokenEstimateOptions, toolsChars, } from "./retry.ts";
 export { type RunTurnOptions, runTurn } from "./run-turn.ts";
 export { isGrammarError, relaxTools, sanitizeTools } from "./schema-compat.ts";
 export { type AskJsonOptions, ask, askJson, clean, listLines, parseJson, resetHints, type SideTaskInput, type SideTaskOptions, tryAsk, } from "./side-task.ts";

package/dist/index.js

@@ -10,14 +10,16 @@
  * that differs between one server and the next.
  */
 export { buildBody, preselect, preview, resolveApiKey, runAgentLoop, } from "./agent-loop.js";
+export { calibrate, charsPerTokenFor, resetCalibration } from "./calibration.js";
 export { capabilitiesFor, modelCapabilitiesFor, negotiate, resetCapabilities, } from "./capabilities.js";
 export { configureClients, contextLimitFor, endpointId, endpointKey, FIRST_TOKEN_FACTOR, firstTokenMs, getClient, listModels, NO_KEY, resetClients, servedWindow, timeoutMs, } from "./client.js";
 export { COMPACT_AT, compactTranscript, KEEP_RATIO, planCompaction, pruneToolResults, SUMMARY_LEAD, SUMMARY_PROMPT, summariser, summaryInput, } from "./compaction.js";
+export { continueTurn, isContinuable, } from "./continuation.js";
 export { errorMessage } from "./errors.js";
-export { configureEvents, emit, endRun, fold, history, resetEvents, watch, } from "./events.js";
-export { assembleContext, configureHooks, gather, HOOK_CONTEXT_TOKENS, HOOK_EVENTS, HOOK_PREFACE, INJECT_EVENTS, notify, resetHooks, turnIndex, turnMessages, UNTRUSTED_PREFACE, untrusted, withContext, } from "./hooks.js";
+export { configureEvents, emit, endRun, fold, history, resetEvents, runMetrics, watch, } from "./events.js";
+export { assembleContext, configureHooks, consult, gather, HOOK_CONTEXT_TOKENS, HOOK_EVENTS, HOOK_PREFACE, INJECT_EVENTS, notify, resetHooks, turnIndex, turnMessages, UNTRUSTED_PREFACE, untrusted, withContext, } from "./hooks.js";
 export { resetAll } from "./reset.js";
-export { backoffMs, ContextOverflow, compact, EndpointSilent, isModelLoading, isOverflow, isTransient, LOADING_POLL_MS, LOADING_TIMEOUT_MS, messageTokens, requestTokens, SMALLEST_LIKELY_WINDOW, sleep, } from "./retry.js";
+export { backoffMs, CHARS_PER_TOKEN, ContextOverflow, compact, EndpointSilent, isModelLoading, isOverflow, isTransient, LOADING_POLL_MS, LOADING_TIMEOUT_MS, messageTokens, requestChars, requestTokens, SMALLEST_LIKELY_WINDOW, sleep, toolsChars, } from "./retry.js";
 export { runTurn } from "./run-turn.js";
 export { isGrammarError, relaxTools, sanitizeTools } from "./schema-compat.js";
 export { ask, askJson, clean, listLines, parseJson, resetHints, tryAsk, } from "./side-task.js";

package/dist/reset.d.ts

@@ -1,12 +1,13 @@
 /**
  * Forgets everything this package remembers between calls.
  *
- * Five modules here keep state for the life of the process, each for a good reason and each
+ * Six modules here keep state for the life of the process, each for a good reason and each
  * with its own seam: the pooled clients and their model listings, the endpoints that turned
- * out not to take `stream_options` or a grammar, the models that refused the no-thinking
- * hints, the event bus, and the hooks' configured budget and preface. `resetClients`,
- * `resetCapabilities`, `resetHints`, `resetEvents` and `resetHooks` stay exported, because a
- * test that means to clear one thing should say so.
+ * out not to take `stream_options` or a grammar, each model's measured characters per token,
+ * the models that refused the no-thinking hints, the event bus, and the hooks' configured
+ * budget and preface. `resetClients`, `resetCapabilities`, `resetCalibration`, `resetHints`,
+ * `resetEvents` and `resetHooks` stay exported, because a test that means to clear one thing
+ * should say so.
  *
  * This is for the other case, which is every teardown. What they hold is *latched
  * refusals* — a fact one test taught the process about an endpoint, still true as far as the
@@ -15,7 +16,7 @@
  * one that reads the latch fails only when it happens to run second. `tests/side-task-hints.test.ts`
  * was written that way and only passed because every case had been handed a hostname of its own.
  *
- * It is also the seam that does not need finding again. A sixth module with a cache is a sixth
+ * It is also the seam that does not need finding again. A seventh module with a cache is a seventh
  * line here, rather than an edit to the teardown of three consumers who will not all notice.
  */
 export declare function resetAll(): void;

package/dist/reset.js

@@ -1,3 +1,4 @@
+import { resetCalibration } from "./calibration.js";
 import { resetCapabilities } from "./capabilities.js";
 import { resetClients } from "./client.js";
 import { resetEvents } from "./events.js";
@@ -6,12 +7,13 @@ import { resetHints } from "./side-task.js";
 /**
  * Forgets everything this package remembers between calls.
  *
- * Five modules here keep state for the life of the process, each for a good reason and each
+ * Six modules here keep state for the life of the process, each for a good reason and each
  * with its own seam: the pooled clients and their model listings, the endpoints that turned
- * out not to take `stream_options` or a grammar, the models that refused the no-thinking
- * hints, the event bus, and the hooks' configured budget and preface. `resetClients`,
- * `resetCapabilities`, `resetHints`, `resetEvents` and `resetHooks` stay exported, because a
- * test that means to clear one thing should say so.
+ * out not to take `stream_options` or a grammar, each model's measured characters per token,
+ * the models that refused the no-thinking hints, the event bus, and the hooks' configured
+ * budget and preface. `resetClients`, `resetCapabilities`, `resetCalibration`, `resetHints`,
+ * `resetEvents` and `resetHooks` stay exported, because a test that means to clear one thing
+ * should say so.
  *
  * This is for the other case, which is every teardown. What they hold is *latched
  * refusals* — a fact one test taught the process about an endpoint, still true as far as the
@@ -20,12 +22,13 @@ import { resetHints } from "./side-task.js";
  * one that reads the latch fails only when it happens to run second. `tests/side-task-hints.test.ts`
  * was written that way and only passed because every case had been handed a hostname of its own.
  *
- * It is also the seam that does not need finding again. A sixth module with a cache is a sixth
+ * It is also the seam that does not need finding again. A seventh module with a cache is a seventh
  * line here, rather than an edit to the teardown of three consumers who will not all notice.
  */
 export function resetAll() {
     resetClients();
     resetCapabilities();
+    resetCalibration();
     resetHints();
     resetEvents();
     resetHooks();

package/dist/retry.d.ts

@@ -29,10 +29,41 @@ export declare class ContextOverflow extends Error {
  * @param tokens The count to render.
  */
 export declare const compact: (tokens: number) => string;
+/**
+ * The divisor behind `estimateTokens`, applied here to a character count rather than a string.
+ *
+ * The fallback, not the rule: once a turn has come back with a reported prompt count, `runTurn`
+ * divides by what that endpoint's model was measured at instead. See `charsPerTokenFor`.
+ */
+export declare const CHARS_PER_TOKEN = 4;
+/** What the two token estimates below take besides what they measure. */
+export interface TokenEstimateOptions {
+    /**
+     * The divisor, `CHARS_PER_TOKEN` unless given — `charsPerTokenFor` for a model whose reported
+     * usage has calibrated it. A value that is not a number above zero is ignored.
+     */
+    charsPerToken?: number;
+}
+/**
+ * How many characters a tool array is worth, measured once per array.
+ *
+ * @param tools The tool definitions as they will be sent. An empty array is worth nothing.
+ */
+export declare function toolsChars(tools: OpenAI.ChatCompletionTool[]): number;
+/**
+ * How many characters a request is worth: the walk `requestTokens` divides, without the division.
+ *
+ * What calibration reads a reported prompt count against, since a ratio is only as good as the
+ * character count it was taken over agreeing with the one it is later applied to.
+ *
+ * @param body The request as it was sent, tools included.
+ */
+export declare function requestChars(body: OpenAI.ChatCompletionCreateParamsStreaming): number;
 /**
  * What this request will cost the window, in tokens, near enough.
  *
- * See `estimateTokens` for why it is characters over four and which way it is wrong on purpose.
+ * See `estimateTokens` for why it is characters over four and which way it is wrong on purpose,
+ * and `charsPerTokenFor` for the divisor a model's own reported usage has measured instead.
  *
  * Summed by walking the body rather than by serialising it. `JSON.stringify` on the messages
  * built the entire transcript into a string on every call and threw it away having read nothing
@@ -45,8 +76,9 @@ export declare const compact: (tokens: number) => string;
  * over four.
  *
  * @param body The request as it will be sent, tools included.
+ * @param options The divisor, `CHARS_PER_TOKEN` when none is given.
  */
-export declare const requestTokens: (body: OpenAI.ChatCompletionCreateParamsStreaming) => number;
+export declare const requestTokens: (body: OpenAI.ChatCompletionCreateParamsStreaming, { charsPerToken }?: TokenEstimateOptions) => number;
 /**
  * One message's estimated tokens, by the same count `requestTokens` sums for a whole request.
  *
@@ -54,8 +86,9 @@ export declare const requestTokens: (body: OpenAI.ChatCompletionCreateParamsStre
  * tail — where `estimateTokens` on the text alone would leave out the calls and the envelope.
  *
  * @param message The message as it will be sent.
+ * @param options The divisor, `CHARS_PER_TOKEN` when none is given.
  */
-export declare const messageTokens: (message: OpenAI.ChatCompletionMessageParam) => number;
+export declare const messageTokens: (message: OpenAI.ChatCompletionMessageParam, { charsPerToken }?: TokenEstimateOptions) => number;
 /**
  * Whether a refusal means the request was too big, rather than merely refused.
  *

package/dist/retry.js

@@ -1,5 +1,4 @@
 import OpenAI from "openai";
-import { estimateTokens } from "./tokens.js";
 /**
  * Everything about a request failing that is not about what the request said.
  *
@@ -63,8 +62,15 @@ const REFUSAL_PART = 32;
 const REASONING_KEY = 23;
 /** The same for `"reasoning":"",`, OpenRouter's spelling of it. */
 const REASONING_ALT_KEY = 15;
-/** The divisor behind `estimateTokens`, applied here to a character count rather than a string. */
-const CHARS_PER_TOKEN = 4;
+/**
+ * The divisor behind `estimateTokens`, applied here to a character count rather than a string.
+ *
+ * The fallback, not the rule: once a turn has come back with a reported prompt count, `runTurn`
+ * divides by what that endpoint's model was measured at instead. See `charsPerTokenFor`.
+ */
+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) {
     let chars = message.role.length + ENVELOPE;
@@ -114,22 +120,47 @@ function messageChars(message) {
  * the array-level memoisation `tests/retry.test.ts` pins, which deliberately holds a mutated array
  * to its first reading. Sizing happens once per turn either way, so the miss costs one walk of the
  * schemas rather than a walk per attempt.
+ *
+ * Characters rather than tokens, so a calibrated divisor applies to the schemas without walking
+ * them again.
+ */
+const toolLengths = new WeakMap();
+/**
+ * How many characters a tool array is worth, measured once per array.
+ *
+ * @param tools The tool definitions as they will be sent. An empty array is worth nothing.
  */
-const toolTokens = new WeakMap();
-function toolsCost(tools) {
-    const hit = toolTokens.get(tools);
+export function toolsChars(tools) {
+    if (!tools.length)
+        return 0;
+    const hit = toolLengths.get(tools);
     if (hit !== undefined)
         return hit;
     // Schemas are arbitrarily shaped, so this one really is a serialisation — but it happens once
     // per tool array rather than once per turn.
-    const cost = estimateTokens(JSON.stringify(tools));
-    toolTokens.set(tools, cost);
-    return cost;
+    const length = JSON.stringify(tools).length;
+    toolLengths.set(tools, length);
+    return length;
+}
+/**
+ * How many characters a request is worth: the walk `requestTokens` divides, without the division.
+ *
+ * What calibration reads a reported prompt count against, since a ratio is only as good as the
+ * character count it was taken over agreeing with the one it is later applied to.
+ *
+ * @param body The request as it was sent, tools included.
+ */
+export function requestChars(body) {
+    let chars = 0;
+    for (const message of body.messages)
+        chars += messageChars(message);
+    return chars;
 }
 /**
  * What this request will cost the window, in tokens, near enough.
  *
- * See `estimateTokens` for why it is characters over four and which way it is wrong on purpose.
+ * See `estimateTokens` for why it is characters over four and which way it is wrong on purpose,
+ * and `charsPerTokenFor` for the divisor a model's own reported usage has measured instead.
  *
  * Summed by walking the body rather than by serialising it. `JSON.stringify` on the messages
  * built the entire transcript into a string on every call and threw it away having read nothing
@@ -142,14 +173,15 @@ function toolsCost(tools) {
  * over four.
  *
  * @param body The request as it will be sent, tools included.
+ * @param options The divisor, `CHARS_PER_TOKEN` when none is given.
  */
-export const requestTokens = (body) => {
+export const requestTokens = (body, { charsPerToken } = {}) => {
     // Characters first and the division once at the end, rather than a rounded count per message:
     // `Math.ceil` on every one of a few hundred messages is a few hundred tokens of pure rounding.
-    let chars = 0;
-    for (const message of body.messages)
-        chars += messageChars(message);
-    return Math.ceil(chars / CHARS_PER_TOKEN) + (body.tools?.length ? toolsCost(body.tools) : 0);
+    // The tools are divided on their own, as they were when their tokens were cached, so the
+    // uncalibrated count is the one it always was.
+    const per = divisor(charsPerToken);
+    return Math.ceil(requestChars(body) / per) + Math.ceil(toolsChars(body.tools ?? []) / per);
 };
 /**
  * One message's estimated tokens, by the same count `requestTokens` sums for a whole request.
@@ -158,8 +190,9 @@ export const requestTokens = (body) => {
  * tail — where `estimateTokens` on the text alone would leave out the calls and the envelope.
  *
  * @param message The message as it will be sent.
+ * @param options The divisor, `CHARS_PER_TOKEN` when none is given.
  */
-export const messageTokens = (message) => Math.ceil(messageChars(message) / CHARS_PER_TOKEN);
+export const messageTokens = (message, { charsPerToken } = {}) => Math.ceil(messageChars(message) / divisor(charsPerToken));
 /**
  * Servers refuse an over-long request in their own words; these are the ones worth reading as
  * that rather than as a broken request. Matched loosely — every one of them is some

package/dist/run-turn.d.ts

@@ -22,6 +22,10 @@ import { type StreamTurnOptions, type Turn } from "./stream.ts";
  * attempt would say everything twice. That is what `produced` is, one box per attempt — set by
  * a chunk that carried something rather than by a chunk arriving, so the empty opening chunk
  * most servers send does not cost the retry.
+ *
+ * What the turn cost in attempts comes back on its usage — `wallMs`, `retries`, `timeouts` — and
+ * what its prompt was reported at calibrates the ratio the next request to that model is sized
+ * with. See `calibrate`.
  */
 /** A retry is not the same event as a downgrade, but a watcher wants to be told about both. */
 export interface RunTurnOptions extends Omit<StreamTurnOptions, "produced"> {

package/dist/run-turn.js

@@ -1,6 +1,7 @@
+import { calibrate, charsPerTokenFor } from "./calibration.js";
 import { negotiate } from "./capabilities.js";
 import { errorMessage } from "./errors.js";
-import { backoffMs, ContextOverflow, compact, isModelLoading, isOverflow, isTransient, LOADING_POLL_MS, LOADING_TIMEOUT_MS, requestTokens, SMALLEST_LIKELY_WINDOW, sleep, } from "./retry.js";
+import { backoffMs, ContextOverflow, compact, EndpointSilent, isModelLoading, isOverflow, isTransient, LOADING_POLL_MS, LOADING_TIMEOUT_MS, requestTokens, SMALLEST_LIKELY_WINDOW, sleep, } from "./retry.js";
 import { streamTurn } from "./stream.js";
 /**
  * `request` is a callback rather than a body because the body has to be rebuilt from whatever
@@ -21,11 +22,16 @@ export async function runTurn(client, supports, request, { maxRetries = 0, onNot
     // does not change between attempts — so the first body is the one worth measuring, and
     // measuring the rest would only spend the walk again to reach the same answer.
     let sized = false;
+    // The body the answer was given to, for the calibration once it is in hand.
+    let sent;
     const measured = (capabilities, forModel) => {
         const body = request(capabilities, forModel);
+        sent = body;
         if (!sized && contextLimit >= SMALLEST_LIKELY_WINDOW) {
             sized = true;
-            const needed = requestTokens(body);
+            const needed = requestTokens(body, {
+                charsPerToken: charsPerTokenFor(supports, body.model),
+            });
             // The endpoint refuses on the prompt plus the reply — llama.cpp sizes the slot with
             // `n_predict` in, OpenAI with the ceiling — so a prompt that fits the window but not the
             // window less the ceiling was let through here to be refused one round trip later, which
@@ -45,10 +51,17 @@ export async function runTurn(client, supports, request, { maxRetries = 0, onNot
     // When the server first said it was loading. Unset until then, and never reset: a model that
     // loads, fails and loads again has had its allowance.
     let loadingSince;
+    const started = Date.now();
+    let retries = 0;
+    let timeouts = 0;
     for (let attempt = 0;; attempt++) {
         const produced = { any: false };
         try {
-            return await negotiate(supports, (capabilities, box, forModel) => streamTurn(client, measured(capabilities, forModel), { ...stream, produced: box }), { produced, onNotice, model, droppable });
+            const turn = await negotiate(supports, (capabilities, box, forModel) => streamTurn(client, measured(capabilities, forModel), { ...stream, produced: box }), { produced, onNotice, model, droppable });
+            if (sent)
+                calibrate(supports, sent, turn.usage.prompt);
+            Object.assign(turn.usage, { wallMs: Date.now() - started, retries, timeouts });
+            return turn;
         }
         catch (error) {
             // The abort is read before the classification, not after. A run stopped by its operator
@@ -85,6 +98,9 @@ export async function runTurn(client, supports, request, { maxRetries = 0, onNot
             }
             if (attempt >= maxRetries || !isTransient(error))
                 throw error;
+            retries++;
+            if (error instanceof EndpointSilent)
+                timeouts++;
             const wait = backoffMs(attempt);
             // Reported in whatever unit reads as a number: the first backoff is under a second, and
             // "retrying in 0s" is what rounding it to seconds says.

package/dist/snapshot.d.ts

@@ -15,6 +15,11 @@ export interface ModelSnapshot {
     chosenTemperature: boolean;
     refusedFields: string[];
     structuredOutput: boolean;
+    /**
+     * Continues a trailing assistant message. Absent in a snapshot taken before it was latched, which
+     * reads as not refused.
+     */
+    assistantPrefill: boolean;
     /** Takes the no-thinking hints `ask` sends. */
     thinkingHints: boolean;
 }

package/dist/snapshot.js

@@ -16,6 +16,7 @@ const optimisticModel = () => ({
     chosenTemperature: true,
     refusedFields: [],
     structuredOutput: true,
+    assistantPrefill: true,
     thinkingHints: true,
 });
 const refusedAnything = (model) => !model.reasoningEffort ||
@@ -23,6 +24,7 @@ const refusedAnything = (model) => !model.reasoningEffort ||
     !model.chosenTemperature ||
     !model.thinkingHints ||
     !model.structuredOutput ||
+    !model.assistantPrefill ||
     model.refusedFields.length > 0;
 /**
  * Every refusal this process has latched, as a JSON-safe blob to store and hand back on boot.
@@ -48,6 +50,7 @@ export function exportCapabilities() {
                 chosenTemperature: refused.chosenTemperature,
                 refusedFields: [...refused.refusedFields].sort(),
                 structuredOutput: refused.structuredOutput,
+                assistantPrefill: refused.assistantPrefill,
             };
             if (refusedAnything(model))
                 models[name] = model;
@@ -109,6 +112,8 @@ export function importCapabilities(snapshot) {
                 refused.chosenTemperature = false;
             if (model.structuredOutput === false)
                 refused.structuredOutput = false;
+            if (model.assistantPrefill === false)
+                refused.assistantPrefill = false;
             if (Array.isArray(model.refusedFields)) {
                 for (const field of model.refusedFields) {
                     if (typeof field === "string")

package/dist/stream.d.ts

@@ -10,7 +10,16 @@ import { type Fence } from "./thinking.ts";
  * hangs the turn until somebody presses stop. `EndpointSilent` and `timeoutMs` were exported for
  * this loop long before the loop itself was.
  */
-/** What a turn cost. Zero throughout means the server did not say. */
+/**
+ * What a turn cost, and how it went. Zero throughout the four counts means the server did not say.
+ *
+ * The four counts are always there, as they always were. Everything after them is absent rather
+ * than zero when nothing reported or measured it, because a zero cache hit and a server that says
+ * nothing about its cache are different findings, and a consumer drawing one as the other is
+ * explaining a slow turn with a number nobody sent. Which layer fills each is said on the field:
+ * `streamTurn` reads what the endpoint sends, `runTurn` measures the attempts, and
+ * `runAgentLoop` compares one request with the one before it.
+ */
 export interface TurnUsage {
     prompt: number;
     completion: number;
@@ -20,9 +29,72 @@ export interface TurnUsage {
      *
      * The only way a caller can tell whether the prefix it is careful to keep still is actually
      * being reused: a prefix that stops hitting the cache otherwise shows up as a bill and nothing
-     * else. Zero is also what a server that does not report it sends.
+     * else. Zero is also what a server that does not report it sends; `uncached` is the field whose
+     * presence says the count was reported. llama.cpp's `timings.cache_n` stands in for it where the
+     * usage block has none.
      */
     cached: number;
+    /**
+     * `prompt` less `cached`: the tokens actually prefilled, and the number a cache miss moves.
+     * Present only where both a cache count and the prompt were reported, so its absence is how a
+     * zero `cached` reads as unknown.
+     */
+    uncached?: number;
+    /** How much of `completion` was reasoning, where the usage block breaks it out. Never estimated. */
+    reasoningTokens?: number;
+    /** Prefill time, from llama.cpp's `timings`. On a local box it dominates once the cache misses. */
+    promptMs?: number;
+    /** Prefill speed, from the same `timings`. */
+    promptTokensPerSecond?: number;
+    /** Decode time, from the same `timings`. */
+    predictedMs?: number;
+    /** Decode speed, from the same `timings`. */
+    tokensPerSecond?: number;
+    /**
+     * Tokens a draft model or MTP head proposed, from the same `timings`. Against `draftAccepted`,
+     * whether speculative decoding is paying for itself.
+     */
+    draftTotal?: number;
+    /** How many of `draftTotal` the target model kept. */
+    draftAccepted?: number;
+    /**
+     * From sending the request to the first chunk that carried anything, measured by `streamTurn`.
+     * The latency a watcher feels, and absent on a turn that said nothing at all.
+     */
+    firstTokenMs?: number;
+    /** The whole turn as `runTurn` saw it, queue, retries, downgrades and loading wait included. */
+    wallMs?: number;
+    /** How many times `runTurn` sent a lost request again. A downgrade is not a retry. */
+    retries?: number;
+    /** How many of those were the endpoint going silent, rather than refusing or dropping it. */
+    timeouts?: number;
+    /** How many requests `continueTurn` joined onto the first. Absent on a turn not continued. */
+    continuations?: number;
+    /**
+     * What this request should have reused of the one before it in the loop: that request's prompt
+     * and its reply, which is what a cache holds once the reply is generated. Filled by
+     * `runAgentLoop` from the second request on, where the previous prompt was reported.
+     */
+    cacheExpected?: number;
+    /**
+     * `cached` came in under nine tenths of the previous request's prompt — the part of
+     * `cacheExpected` no re-rendering of the reply can disturb. Present only where both sides were
+     * reported, so a server that says nothing about its cache is never accused of losing it.
+     */
+    cacheBroken?: boolean;
+    /**
+     * What the loop changed that would explain `cacheBroken`, the earliest in the prompt first,
+     * since a change there is the one that costs the rest. `none-known` is the server's doing — an
+     * eviction, another client on the slot — or a change the loop cannot see. Only on a broken turn.
+     */
+    cacheBreakReason?: "tools-changed" | "system-changed" | "history-rewritten" | "none-known";
+    /** How many tools the request declared, filled by `runAgentLoop`. */
+    toolsDeclared?: number;
+    /**
+     * The declared tool block's estimated tokens. A chat template renders it ahead of the system
+     * prompt, so this is what every change to the tool list costs the cache.
+     */
+    toolSchemaTokens?: number;
 }
 /** One streamed turn, put back together into the shape a loop and a transcript work with. */
 export interface Turn {