@cubicecho/agent-core 4.18.0 → 4.20.0

package/README.md

@@ -610,8 +610,10 @@ string. What still is not an object throws a `ToolArgumentsError` whose `kind` i
 the turn stopped at the ceiling, with a message telling the model so, and `malformed` otherwise.
 The repaired JSON is what the transcript keeps, and an unreadable call is replayed as `{}`, because
 a server that parses replayed arguments refuses the originals on every later request. `dispatch`
-is still handed the model's own text as `raw`, and the dedupe compares repaired arguments,
-so `{'a': 1}` and `{"a": 1}` are one call.
+is still handed the model's own text as `raw`, with `repaired` true where reading it took a repair
+— whitespace and blank arguments do not count — and the dedupe compares repaired arguments, so
+`{'a': 1}` and `{"a": 1}` are one call. A call recovered from text, below, is always `repaired`,
+and its `raw` is the arguments recovery read out of the reply, as JSON.
 
 A server whose tool-call parser was written for another template streams the model's call as
 plain text, and the run ends on a reply that is nothing but a call nobody made. Unless
@@ -826,7 +828,12 @@ failure short of a stop, the cut-off answer is kept with a notice. The cap is on
 continue, one to find out.
 
 Every turn ends in a `usage` event, whether or not the endpoint reported tokens. Its totals are the
-run's so far; its `turn` is that turn's own `TurnUsage` and `finishReason`. The loop adds what only
+run's so far — `promptTokens`, `completionTokens`, `totalTokens`, `cachedTokens` and
+`cacheReported`, the `UsageTotals` spelling that `result.usage` and a failed run's `usage` share
+(their older `prompt`, `completion`, `total` and `cached` are still there, deprecated). A
+`cachedTokens` of zero is a miss only where `cacheReported` is true; false is an endpoint that never
+said. Its `turn` is that turn's own `TurnUsage` and `finishReason`, with the `contextLength` the loop
+was told. The loop adds what only
 it can know: `toolsDeclared` and `toolSchemaTokens` for the tool block it sent, and, from the second
 request on, `cacheExpected` (the previous prompt plus its reply) and — where a cache count was
 reported — `cacheBroken`, a hit short of 90% of the previous prompt. A broken cache is given a
@@ -855,10 +862,12 @@ a lesser body and a continuation with the reply so far on the end, and neither i
 
 `runMetrics(events)` adds a run up from those events — tokens, cache hit ratio and breaks by
 reason, prefill, decode and tool time, the slowest turn, mean time to first token, draft
-acceptance, the largest prompt against a `contextLength`, turns cut off, tool errors by name, and
-an `outcome`. The loop returns it as `metrics`, with the `load_tools` counts only it can see
-(`toolsLoaded`, `redundantLoads`, `unknownToolNames`). It is a sibling of `fold` rather than part
-of it, since `fold`'s blocks are for display and a summary is not one:
+acceptance, the largest prompt against its window, turns cut off, tool errors by name, what
+`load_tools` resolved to (`toolsLoaded`, `redundantLoads`, `unknownToolNames`, off each load's
+result as `loads`), and an `outcome`. The loop returns it as `metrics`. Every turn carries its own
+window and every load its own counts, so a host that runs one loop per step gets the whole run from
+`runMetrics` over all the loops' events, with no per-loop result to merge. It is a sibling of `fold`
+rather than part of it, since `fold`'s blocks are for display and a summary is not one:
 
 ```ts
 const metrics = runMetrics(history(runId), { contextLength: config.contextLength });
@@ -962,7 +971,11 @@ try {
 
 `onMessage` hears the assistant message as it will be replayed — recovered calls folded in, and
 arguments repaired, which the turn `onTurn` is handed does not show — together with that `Turn`,
-and then each tool result, in transcript order. `onTurn` is not awaited and never sees a tool
+and then each tool result, in transcript order. Beside an assistant message the model wrote comes a
+fourth argument, `{ raw }`: the same message as the model produced it, its text whole with any call
+written into it left there, and its calls' arguments exactly as streamed, under the same ids. Store
+or show `raw` to keep what the model said; replay `message` to keep what an endpoint will take back.
+The loop's own messages — a proxied run's preselected load — come without it. `onTurn` is not awaited and never sees a tool
 result; this is the one to store from. What it returns is ignored, since `beforeStep` is the one way to rewrite
 the transcript, and what it throws ends the run.
 

package/dist/index.d.ts

@@ -19,8 +19,8 @@ export { isGrammarError, relaxSchema, relaxTools, sanitizeSchema, sanitizeTools,
 export { CACHE_PROMPT_FIELD, resetSlots, SESSION_HEADER, SLOT_FIELD, type SlotAllocator, slotAllocator, } from './endpoint/slots.ts';
 export { HOOK_EVENTS, HookEvent, INJECT_EVENTS } from './hooks/hook-events.ts';
 export { assembleContext, configureHooks, consult, type Gathered, gather, HOOK_CONTEXT_TOKENS, HOOK_PREFACE, type HookContext, type HookMessage, type HookNote, type HookOptions, type HookOutcome, type HookRunner, notify, resetHooks, turnIndex, turnMessages, UNTRUSTED_PREFACE, untrusted, withContext, } from './hooks/hooks.ts';
-export { type AgentLoopHooks, type AgentLoopOptions, type AgentLoopRequest, type AgentLoopResult, PRESELECT_APPEND, PRESELECT_EXCLUSIVE, PRESELECTED_NOTICE, runAgentLoop, type StepWindow, } from './run/agent-loop.ts';
-export { configureEvents, type EventBusOptions, emit, endRun, fold, history, type RunEvent, type RunEventInput, RunEventKind, type RunMetrics, type RunMetricsOptions, RunOutcome, type RunUsage, resetEvents, runMetrics, type TurnReport, watch, } from './run/events.ts';
+export { type AgentLoopHooks, type AgentLoopOptions, type AgentLoopRequest, type AgentLoopResult, PRESELECT_APPEND, PRESELECT_EXCLUSIVE, PRESELECTED_NOTICE, runAgentLoop, type StepWindow, type WrittenMessage, } from './run/agent-loop.ts';
+export { configureEvents, type EventBusOptions, emit, endRun, fold, history, type LoadCounts, type RunEvent, type RunEventInput, RunEventKind, type RunMetrics, type RunMetricsOptions, RunOutcome, type RunUsage, resetEvents, runMetrics, type TurnReport, watch, } from './run/events.ts';
 export { buildBody } from './run/request-body.ts';
 export { preview, type ToolDispatch } from './run/run-calls.ts';
 export { resetAll } from './runtime/reset.ts';
@@ -37,7 +37,7 @@ export { type RunTurnOptions, runTurn } from './turn/run-turn.ts';
 export { type AskJsonOptions, ask, askJson, askReply, clean, listLines, parseJson, resetHints, type SideTask, type SideTaskInput, type SideTaskOptions, type SideTaskReply, taskCall, tryAsk, } from './turn/side-task.ts';
 export { AgentLoopError, type AgentLoopFailure, AgentLoopOverflow, errorMessage, failedRun, ToolIterationLimit, } from './wire/errors.ts';
 export { backoffMs, ContextOverflow, EndpointSilent, isModelLoading, isOverflow, isTransient, SMALLEST_LIKELY_WINDOW, } from './wire/retry.ts';
-export { CacheBreakReason, type InFlight, type PartialTurn, type Produced, type StreamTurnOptions, streamTurn, type Turn, type TurnUsage, } from './wire/stream.ts';
+export { CacheBreakReason, type InFlight, type LoopUsage, type PartialTurn, type Produced, type StreamTurnOptions, streamTurn, type Turn, type TurnUsage, type UsageTotals, } from './wire/stream.ts';
 export { ALL_FENCES, DEFAULT_FENCES, type Fence, FenceSplitter, type FenceSplitterOptions, SPLIT_OUTPUT, SPLIT_REASONING, type Split, stripThinking, THINK_FENCE, } from './wire/thinking.ts';
 export { type ContextBreakdown, type ContextBreakdownOptions, compact, contextChars, contextTokens, estimateTokens, messageTokens, requestChars, requestTokens, type TokenEstimateOptions, } from './wire/tokens.ts';
 export { ARGUMENTS_MALFORMED, ARGUMENTS_TRUNCATED, type EndedBy, parseToolArguments, type ResourceLink, type RunArtifact, recoverToolCalls, type ServerLogEntry, ServerLogLevel, type ToolAnswer, ToolArgumentsError, type ToolCall, type ToolCallOutcome, type ToolCallReport, type ToolCallRequest, type ToolCallResult, } from './wire/tool-calls.ts';

package/dist/run/agent-loop.d.ts

@@ -9,7 +9,7 @@ import { type ServerInstructionsOptions } from '../tools/instructions.ts';
 import { type KeywordPreselectOptions } from '../tools/preselect.ts';
 import { type ToolOrder } from '../tools/tool-loading.ts';
 import { type SideTask } from '../turn/side-task.ts';
-import { type Turn, type TurnUsage } from '../wire/stream.ts';
+import { type LoopUsage, type Turn } from '../wire/stream.ts';
 import { type EndedBy, type RunArtifact, type ToolCallOutcome, type ToolCallRequest, type ToolCallResult } from '../wire/tool-calls.ts';
 import { type RunEventInput, type RunMetrics } from './events.ts';
 import { type ToolDispatch } from './run-calls.ts';
@@ -23,6 +23,24 @@ import { type ToolDispatch } from './run-calls.ts';
  * and two never did. What is here is the part that does not know what the run is for; the
  * prompts, the tools and what a run means stay with the caller.
  */
+/**
+ * What `onMessage` is handed beside an assistant message the model wrote: that message as the model
+ * produced it.
+ *
+ * @remarks
+ * The message `onMessage` is handed is what later requests replay — arguments repaired, `{}` for
+ * none, recovered calls taken out of the text and made calls — which is right to send and quietly
+ * wrong to show as the model's. Absent for a message the loop wrote itself, such as a proxied
+ * run's preselected load.
+ */
+export interface WrittenMessage {
+    /**
+     * The reply as it streamed: its text whole, a call written into it as text left there, and the
+     * calls it sent as calls with their arguments as streamed. A call that never got a name is left
+     * off, since nothing answers it. Ids are the turn's, so the tool results pair with either.
+     */
+    raw: OpenAI.ChatCompletionAssistantMessageParam;
+}
 /**
  * One step's request as `onRequest` is handed it: what the model is about to read.
  *
@@ -459,8 +477,12 @@ export interface AgentLoopOptions {
      * a proxied run writes for its `preselected` shortlist, told as step zero's before any request.
      * What it returns is ignored: `beforeStep` is the one way to rewrite the transcript. What it
      * throws ends the run, and it is not called again for that run.
+     *
+     * Beside an assistant message the model wrote comes `written`, whose `raw` is the message as the
+     * model produced it, for a host that shows or stores what was said rather than what is replayed.
+     * See `WrittenMessage`.
      */
-    onMessage?: (message: OpenAI.ChatCompletionMessageParam, step: number, turn?: Turn) => void | Promise<void>;
+    onMessage?: (message: OpenAI.ChatCompletionMessageParam, step: number, turn?: Turn, written?: WrittenMessage) => void | Promise<void>;
     /**
      * How many times an answer cut off at `maxTokens` is continued, zero for never. Opt-in because
      * it spends another request, and on a server that does not continue a trailing assistant
@@ -497,8 +519,11 @@ export interface AgentLoopResult {
     ended?: EndedBy;
     /** The transcript, with every assistant turn and tool result the run added. No system prompt. */
     messages: OpenAI.ChatCompletionMessageParam[];
-    /** Summed over every turn of the run. */
-    usage: TurnUsage;
+    /**
+     * Summed over every turn of the run, in the spelling the `usage` events use, with whether any
+     * turn reported a cache count. The four counts are also under their older names.
+     */
+    usage: LoopUsage;
     /**
      * Every call, `load_tools` included, in the order they were made, each under its call id — a
      * proxied preselection's among them, first.
@@ -550,8 +575,10 @@ export interface AgentLoopResult {
      */
     afterTurn: Promise<HookNote[]>;
     /**
-     * The run summed and derived: what `runMetrics` makes of the events this loop emitted, plus the
-     * `load_tools` findings only the loop sees, `wallMs` from the call to the return, and `outcome`.
+     * The run summed and derived: what `runMetrics` makes of the events this loop emitted, with the
+     * `load_tools` counts at zero rather than absent in a run on demand, `wallMs` from the call to
+     * the return, and `outcome`. A host running several loops for one run gets its counts from
+     * `runMetrics` over all their events, without these results beside it.
      */
     metrics: RunMetrics;
     /**

package/dist/run/agent-loop.js

@@ -16,13 +16,13 @@ import { runTurn } from '../turn/run-turn.js';
 import { taskCall, tryAsk } from '../turn/side-task.js';
 import { AgentLoopError, AgentLoopOverflow, errorMessage, ToolIterationLimit, } from '../wire/errors.js';
 import { ContextOverflow } from '../wire/retry.js';
-import { addCounts, noUsage } from '../wire/stream.js';
+import { addCounts, loopUsage, noUsage, reportsCache, } from '../wire/stream.js';
 import { contextTokens, toolsChars } from '../wire/tokens.js';
 import { recoverToolCalls, } from '../wire/tool-calls.js';
 import { FinishReason, PartType, Role } from '../wire/wire.js';
 import { RunEventKind, RunOutcome, runMetrics, stamp, } from './events.js';
 import { buildBody } from './request-body.js';
-import { assistantMessage, definedAs, loadShortlist, readCalls, runCalls, } from './run-calls.js';
+import { assistantMessage, definedAs, loadShortlist, readCalls, runCalls, writtenMessage, } from './run-calls.js';
 /** The `preselectRouting` that sends the first step the shortlist alone. */
 export const PRESELECT_EXCLUSIVE = 'exclusive';
 /** The `preselectRouting` that loads the shortlist after what was carried, and sends the first step like any other. */
@@ -127,7 +127,7 @@ export async function runAgentLoop(options) {
     const standing = {
         read: () => ({
             messages: [...options.messages],
-            usage: noUsage(),
+            usage: loopUsage(noUsage(), false),
             toolCalls: [],
             artifacts: [],
             loaded: [],
@@ -502,8 +502,8 @@ function definitionsByName(tools) {
  * Offers each message written into the transcript to the host.
  *
  * @param onMessage - The host's callback, awaited. Absent offers nothing.
- * @returns The offer, taking a message, its step and the turn it came with: it resolves once the
- * host has taken the message, and rejects with what the host threw — once.
+ * @returns The offer, taking a message, its step, the turn it came with and what the model wrote:
+ * it resolves once the host has taken the message, and rejects with what the host threw — once.
  *
  * @remarks
  * Once `onMessage` has thrown the run is ending on that, and the results still to be written are
@@ -511,12 +511,12 @@ function definitionsByName(tools) {
  */
 function announcer(onMessage) {
     let heard = true;
-    return async (message, step, turn) => {
+    return async (message, step, turn, written) => {
         if (!onMessage || !heard) {
             return;
         }
         try {
-            await onMessage(message, step, turn);
+            await onMessage(message, step, turn, written);
         }
         catch (error) {
             heard = false;
@@ -530,19 +530,25 @@ function announcer(onMessage) {
  * @param usage - The run's totals, this turn's already added.
  * @param turn - The turn just finished, read for its usage and why it ended.
  * @param ledger - The ledger as it stands. Carried on the event as it is, not copied.
+ * @param [contextLength] - The window the turn was served. Absent or zero leaves it off the report.
  * @returns The event, for the caller to emit.
  */
-const usageEvent = (usage, turn, ledger) => ({
-    kind: RunEventKind.Usage,
-    usage: {
-        promptTokens: usage.prompt,
-        completionTokens: usage.completion,
-        totalTokens: usage.total,
-        cachedTokens: usage.cached,
-        turn: { ...turn.usage, finishReason: turn.finishReason },
-        ledger,
-    },
-});
+const usageEvent = (usage, turn, ledger, contextLength) => {
+    const { promptTokens, completionTokens, totalTokens, cachedTokens, cacheReported } = usage;
+    const window = contextLength ? { contextLength } : {};
+    return {
+        kind: RunEventKind.Usage,
+        usage: {
+            promptTokens,
+            completionTokens,
+            totalTokens,
+            cachedTokens,
+            cacheReported,
+            turn: { ...turn.usage, finishReason: turn.finishReason, ...window },
+            ledger,
+        },
+    };
+};
 /**
  * The calls a turn made and the answer beside them, with calls the model wrote as text taken out
  * of the answer and counted as calls.
@@ -552,21 +558,21 @@ const usageEvent = (usage, turn, ledger) => ({
  * nothing is looked for in a turn that made a named call of its own or has no text.
  * @param notice - Told when calls were recovered, and how many.
  * @returns `calls`, the turn's own less any with no name, and `content`, its text as it was — or,
- * where calls were recovered, those calls and the text without them.
+ * where calls were recovered, those calls and the text without them, and `recovered` true.
  */
 function turnCalls(turn, recoverable, notice) {
     // A call with no name is a fragment the server never finished sending: nothing to run, and
     // an assistant message naming it would be answered by nothing.
     const calls = turn.toolCalls.filter((call) => call.function.name);
     if (!recoverable || calls.length || !turn.content) {
-        return { calls, content: turn.content };
+        return { calls, content: turn.content, recovered: false };
     }
     const recovered = recoverToolCalls(turn.content, { names: recoverable });
     if (!recovered.toolCalls.length) {
-        return { calls, content: turn.content };
+        return { calls, content: turn.content, recovered: false };
     }
     notice(`recovered ${counted(recovered.toolCalls.length, 'tool call')} the model wrote as text; the server's tool-call parser does not match this model's template`);
-    return { calls: recovered.toolCalls, content: recovered.content };
+    return { calls: recovered.toolCalls, content: recovered.content, recovered: true };
 }
 /**
  * The steps of `runAgentLoop`, throwing what they caught as it was caught.
@@ -629,6 +635,7 @@ async function runSteps(options, standing, pin) {
     const byName = (names) => definedAs(definitions, names);
     let messages = [...options.messages];
     let usage = noUsage();
+    let cacheReported = false;
     const toolCalls = [];
     const artifacts = new Map();
     // A box per request, emptied once its turn is in `messages`: a failure while the tools run had
@@ -639,7 +646,7 @@ async function runSteps(options, standing, pin) {
         return {
             messages,
             ...(partial ? { partial } : {}),
-            usage,
+            usage: loopUsage(usage, cacheReported),
             toolCalls,
             artifacts: [...artifacts.values()],
             // As the result would have said it: proxied, nothing is loaded that the history does not hold.
@@ -837,20 +844,22 @@ async function runSteps(options, standing, pin) {
             completion: turn.usage.completion,
         };
         usage = addCounts(usage, turn.usage);
-        onEvent(usageEvent(usage, turn, ledger));
+        cacheReported ||= reportsCache(turn.usage);
+        onEvent(usageEvent(loopUsage(usage, cacheReported), turn, ledger, config.contextLength));
         if (turn.finishReason === FinishReason.Length) {
             notice(`the model stopped at maxTokens (${config.maxTokens}); this turn is cut short`);
         }
         const canRecover = recover && (tools.length > 0 || hostTools.length > 0 || onDemand);
-        const { calls, content } = turnCalls(turn, canRecover ? recoverable : undefined, notice);
+        const { calls, content, recovered } = turnCalls(turn, canRecover ? recoverable : undefined, notice);
         const shown = { ...turn, content, toolCalls: calls };
         onTurn?.(shown, step);
         // Read before the assistant message is written, so what is replayed on every later request
         // is the repaired JSON.
-        const parsed = readCalls(calls, turn.finishReason);
+        const parsed = readCalls(calls, turn.finishReason, recovered);
         const assistant = assistantMessage(content, parsed);
         messages.push(assistant);
-        await announce(assistant, step, shown);
+        // Recovered calls were never calls on the wire: what the model said is the text they came from.
+        await announce(assistant, step, shown, { raw: writtenMessage(turn.content, recovered ? [] : calls) });
         const isAnswer = calls.length === 0;
         const ended = isAnswer ? undefined : await runCalls(calling, parsed, messages, step);
         if (ended) {
@@ -873,7 +882,7 @@ async function runSteps(options, standing, pin) {
                 turn: shown,
                 ...(ended ? { ended } : {}),
                 messages,
-                usage,
+                usage: loopUsage(usage, cacheReported),
                 toolCalls,
                 artifacts: [...artifacts.values()],
                 loaded: proxied ? [] : [...loaded],

package/dist/run/events.d.ts

@@ -121,6 +121,10 @@ export type RunEventKind = (typeof RunEventKind)[keyof typeof RunEventKind];
  * What a run has spent, counted from the start of the run rather than for the turn that
  * carried it: a client draws the latest one it has seen and needs no arithmetic of its own,
  * and one lost to the backlog cap costs nothing because the next supersedes it.
+ *
+ * @remarks
+ * The counts are `UsageTotals`, the spelling `AgentLoopResult.usage` shares, with the cache's two
+ * fields optional so a host emitting usage of its own need not know them.
  */
 export interface RunUsage {
     promptTokens: number;
@@ -131,6 +135,12 @@ export interface RunUsage {
      * emitting usage before this field existed still compiles; absent reads the same as zero.
      */
     cachedTokens?: number;
+    /**
+     * Whether any turn so far reported a cache count, as `UsageTotals.cacheReported` says it — so a
+     * `cachedTokens` of zero reads as a miss or as nothing said. `runAgentLoop` always sets it;
+     * optional for the reason `cachedTokens` is, and absent reads as not known.
+     */
+    cacheReported?: boolean;
     /**
      * The turn that carried this report, on its own rather than added in — the half `runMetrics`
      * reads, since a total says nothing about which turn was slow or where the cache broke. Absent
@@ -148,6 +158,30 @@ export interface RunUsage {
 export interface TurnReport extends TurnUsage {
     /** Why the model stopped, as `Turn.finishReason` says it; `length` is a turn cut short. */
     finishReason: string;
+    /**
+     * The window the turn was served, where the loop was told one, for `largestPromptShare`.
+     *
+     * @remarks
+     * On the turn rather than only in `runMetrics`' options, because a run of several loops can put
+     * them on models with different windows, and one window for the whole run misstates how close
+     * any of them came.
+     */
+    contextLength?: number;
+}
+/**
+ * What `load_tools` calls resolved to: new tools, ones already loaded, and names in no catalogue.
+ *
+ * @remarks
+ * Carried on each `load_tools` result as `loads`, so `runMetrics` over every loop's events adds
+ * them up without the loops' results beside it.
+ */
+export interface LoadCounts {
+    /** Tools loaded that were not loaded already. */
+    toolsLoaded: number;
+    /** Tools asked for that were loaded already. */
+    redundantLoads: number;
+    /** Names asked for that are in no catalogue. */
+    unknownToolNames: number;
 }
 /**
  * One thing that happened in a run, as a watcher receives it.
@@ -202,6 +236,11 @@ export interface RunEvent {
      * `id` is.
      */
     level?: string;
+    /**
+     * What the call loaded, on a `load_tools` `tool-result` and on no other event. Absent from one
+     * whose arguments did not parse, which loaded nothing. Optional for the reason `id` is.
+     */
+    loads?: LoadCounts;
 }
 /**
  * What `emit` is given: the run and the sequence are the bus's to assign.
@@ -334,13 +373,14 @@ export interface RunMetrics {
     /** `server-log` events at `error` or above: `critical`, `alert` and `emergency` with it. */
     serverErrors: number;
     /**
-     * Tools `load_tools` loaded that were not loaded already. Filled by `runAgentLoop`, which sees
-     * the resolution; the events carry only its text.
+     * Tools `load_tools` loaded that were not loaded already, summed from each result's `loads`.
+     * Absent where no result carried any; `runAgentLoop` fills all three with zero in a run on
+     * demand that loaded nothing.
      */
     toolsLoaded?: number;
-    /** Tools the model asked `load_tools` for that it already had, filled the same way. */
+    /** Tools the model asked `load_tools` for that it already had, summed the same way. */
     redundantLoads?: number;
-    /** Names the model asked `load_tools` for that are in no catalogue, filled the same way. */
+    /** Names the model asked `load_tools` for that are in no catalogue, summed the same way. */
     unknownToolNames?: number;
     promptTokens: number;
     completionTokens: number;
@@ -382,7 +422,10 @@ export interface RunMetrics {
     draftAcceptance?: number;
     /** The biggest prompt any turn reported. */
     largestPrompt?: number;
-    /** `largestPrompt` over the window `runMetrics` was told, for how close the run came. */
+    /**
+     * The highest share of its window any turn's prompt took, for how close the run came: each
+     * turn over its own `contextLength`, or over the one `runMetrics` was told where it has none.
+     */
     largestPromptShare?: number;
     /** How it ended, read off `done` and the last turn. */
     outcome?: RunOutcome;
@@ -408,7 +451,10 @@ export declare const RunOutcome: {
 export type RunOutcome = (typeof RunOutcome)[keyof typeof RunOutcome];
 /** What `runMetrics` takes besides the events. */
 export interface RunMetricsOptions {
-    /** The window the run was served, for `largestPromptShare`. Absent or zero leaves it out. */
+    /**
+     * The window the run was served, for `largestPromptShare` over the turns that do not carry
+     * their own. Absent or zero leaves those out.
+     */
     contextLength?: number;
 }
 /**
@@ -425,6 +471,8 @@ export interface RunMetricsOptions {
  * what it returns as blocks; a summary is another shape, and folding one in would give every
  * consumer of `fold` a block it does not know how to draw. Derived from the `usage` reports' own
  * `turn` rather than the running totals, so a run with several loops in it — a question per loop —
- * adds up the same as one with a single loop.
+ * adds up the same as one with a single loop. That holds for everything here: what `load_tools`
+ * resolved to rides on its results, and each turn carries the window it was served, so the events
+ * of every loop of a run, concatenated, are a complete account of it.
  */
 export declare function runMetrics(events: RunEvent[], { contextLength }?: RunMetricsOptions): RunMetrics;

package/dist/run/events.js

@@ -522,7 +522,9 @@ function outcomeOf({ ok, name }, last) {
  * what it returns as blocks; a summary is another shape, and folding one in would give every
  * consumer of `fold` a block it does not know how to draw. Derived from the `usage` reports' own
  * `turn` rather than the running totals, so a run with several loops in it — a question per loop —
- * adds up the same as one with a single loop.
+ * adds up the same as one with a single loop. That holds for everything here: what `load_tools`
+ * resolved to rides on its results, and each turn carries the window it was served, so the events
+ * of every loop of a run, concatenated, are a complete account of it.
  */
 export function runMetrics(events, { contextLength } = {}) {
     const metrics = {
@@ -570,6 +572,11 @@ export function runMetrics(events, { contextLength } = {}) {
             if (event.ok === false) {
                 metrics.toolErrors[event.name] = (metrics.toolErrors[event.name] ?? 0) + 1;
             }
+            if (event.loads) {
+                add('toolsLoaded', event.loads.toolsLoaded);
+                add('redundantLoads', event.loads.redundantLoads);
+                add('unknownToolNames', event.loads.unknownToolNames);
+            }
             const called = pending.get(event.name)?.shift();
             if (called !== undefined) {
                 add('toolMs', event.at - called);
@@ -625,6 +632,10 @@ export function runMetrics(events, { contextLength } = {}) {
             }
             if (turn.prompt > 0) {
                 metrics.largestPrompt = Math.max(metrics.largestPrompt ?? 0, turn.prompt);
+                const window = turn.contextLength ?? contextLength ?? 0;
+                if (window > 0) {
+                    metrics.largestPromptShare = Math.max(metrics.largestPromptShare ?? 0, turn.prompt / window);
+                }
             }
         }
         else if (event.kind === RunEventKind.Done) {
@@ -643,8 +654,5 @@ export function runMetrics(events, { contextLength } = {}) {
     if (metrics.draftTotal && metrics.draftAccepted !== undefined) {
         metrics.draftAcceptance = metrics.draftAccepted / metrics.draftTotal;
     }
-    if (metrics.largestPrompt !== undefined && contextLength && contextLength > 0) {
-        metrics.largestPromptShare = metrics.largestPrompt / contextLength;
-    }
     return metrics;
 }

package/dist/run/run-calls.d.ts

@@ -2,7 +2,7 @@ import type OpenAI from 'openai';
 import type { CatalogServer } from '../tools/catalog.ts';
 import type { Turn } from '../wire/stream.ts';
 import { type EndedBy, type RunArtifact, type ToolAnswer, type ToolCall, type ToolCallOutcome, type ToolCallReport, type ToolCallRequest, type ToolCallResult } from '../wire/tool-calls.ts';
-import type { RunEventInput } from './events.ts';
+import type { LoadCounts, RunEventInput } from './events.ts';
 /**
  * The tools between two turns: a step's calls read, run and written into the transcript.
  *
@@ -31,12 +31,15 @@ export interface ReadCall {
     error?: unknown;
     /** The arguments as every later request replays them: the repaired JSON, or `{}` for none. */
     normal: string;
+    /** Whether `args` took a repair to read, as `ToolCallRequest.repaired` says. */
+    repaired: boolean;
 }
 /**
  * A turn's calls with their arguments read.
  *
  * @param calls - The turn's calls, in the order the model made them.
  * @param finishReason - Why the turn ended, which tells a call cut off from one written wrongly.
+ * @param [recovered] - Whether the calls were recovered from the reply's text.
  * @returns One entry per call, in the same order. Unreadable arguments do not throw: the entry
  * carries the error in place of them.
  *
@@ -44,7 +47,7 @@ export interface ReadCall {
  * A server that parses replayed arguments refuses the almost-JSON a model wrote, so each is
  * normalised here, and one that could not be read at all is replayed as no arguments.
  */
-export declare const readCalls: (calls: ToolCall[], finishReason: Turn['finishReason']) => ReadCall[];
+export declare const readCalls: (calls: ToolCall[], finishReason: Turn['finishReason'], recovered?: boolean) => ReadCall[];
 /**
  * The assistant message a turn is written into the transcript as, its calls' arguments repaired.
  *
@@ -54,6 +57,15 @@ export declare const readCalls: (calls: ToolCall[], finishReason: Turn['finishRe
  * @returns A new message, each call on it a copy with `normal` for its arguments.
  */
 export declare const assistantMessage: (content: string, parsed: ReadCall[]) => OpenAI.ChatCompletionAssistantMessageParam;
+/**
+ * The assistant message a turn is, as the model produced it: its text and calls as they streamed.
+ *
+ * @param content - The turn's text, recovered calls left in it. Empty is written as `null`.
+ * @param calls - The calls the model sent as calls, with their arguments as streamed. Not written
+ * to. None leaves `tool_calls` off the message rather than empty.
+ * @returns A new message, each call on it a copy.
+ */
+export declare const writtenMessage: (content: string, calls: ToolCall[]) => OpenAI.ChatCompletionAssistantMessageParam;
 /**
  * The definitions the host gave for these names, in the order the names are given.
  *
@@ -89,11 +101,7 @@ export interface Calling {
     /** The host's own tools by name: declared on every step, and never reached through `call_tool`. */
     hostNames: ReadonlySet<string>;
     loaded: Set<string>;
-    loads: {
-        toolsLoaded: number;
-        redundantLoads: number;
-        unknownToolNames: number;
-    };
+    loads: LoadCounts;
     used: Set<string>;
     toolCalls: ToolCallOutcome[];
     /** What the run's calls linked to, by uri, in the order first seen. */

package/dist/run/run-calls.js

@@ -1,3 +1,4 @@
+import { isRecord } from '../core/guards.js';
 import { CALL_TOOL, expandNames, inCatalog, LOAD_TOOLS, loadResult, proxiedCall, proxyLoadResult, requestedNames, shownCall, toolName, } from '../tools/tool-loading.js';
 import { errorMessage } from '../wire/errors.js';
 import { parseToolArguments, } from '../wire/tool-calls.js';
@@ -26,20 +27,40 @@ export const preview = (text, limit = 2000) => text.length > limit ? `${text.sli
 const STOPPED_CALL = 'Stopped before this call finished.';
 /** The same for a call of that step the loop never got to. */
 const UNRUN_CALL = 'Not run: the run stopped first.';
+/**
+ * Whether a call's arguments are, as written, the JSON of an object — or no arguments at all.
+ *
+ * @param raw - The arguments as the turn carried them: a string, or an object a server parsed.
+ * @returns False where reading them took `parseToolArguments`' repairs.
+ */
+function readsAsWritten(raw) {
+    if (typeof raw !== 'string' || !raw.trim()) {
+        return true;
+    }
+    try {
+        return isRecord(JSON.parse(raw));
+    }
+    catch {
+        return false;
+    }
+}
 /**
  * One call with its arguments read, or with why they could not be.
  *
  * @param call - The call as the turn carried it.
  * @param finishReason - Why the turn ended, which tells a call cut off from one written wrongly.
+ * @param recovered - Whether the call was recovered from the reply's text, which makes it repaired
+ * whatever its arguments.
  * @returns The call beside its arguments and their repaired JSON, or beside the error and `{}`.
  */
-function readCall(call, finishReason) {
+function readCall(call, finishReason, recovered) {
     try {
         const args = parseToolArguments(call.function.arguments, { finishReason });
-        return { call, args, normal: JSON.stringify(args) };
+        const repaired = recovered || !readsAsWritten(call.function.arguments);
+        return { call, args, normal: JSON.stringify(args), repaired };
     }
     catch (error) {
-        return { call, error, normal: '{}' };
+        return { call, error, normal: '{}', repaired: false };
     }
 }
 /**
@@ -47,6 +68,7 @@ function readCall(call, finishReason) {
  *
  * @param calls - The turn's calls, in the order the model made them.
  * @param finishReason - Why the turn ended, which tells a call cut off from one written wrongly.
+ * @param [recovered] - Whether the calls were recovered from the reply's text.
  * @returns One entry per call, in the same order. Unreadable arguments do not throw: the entry
  * carries the error in place of them.
  *
@@ -54,7 +76,7 @@ function readCall(call, finishReason) {
  * A server that parses replayed arguments refuses the almost-JSON a model wrote, so each is
  * normalised here, and one that could not be read at all is replayed as no arguments.
  */
-export const readCalls = (calls, finishReason) => calls.map((call) => readCall(call, finishReason));
+export const readCalls = (calls, finishReason, recovered = false) => calls.map((call) => readCall(call, finishReason, recovered));
 /**
  * The assistant message a turn is written into the transcript as, its calls' arguments repaired.
  *
@@ -75,6 +97,19 @@ export const assistantMessage = (content, parsed) => ({
         }
         : {}),
 });
+/**
+ * The assistant message a turn is, as the model produced it: its text and calls as they streamed.
+ *
+ * @param content - The turn's text, recovered calls left in it. Empty is written as `null`.
+ * @param calls - The calls the model sent as calls, with their arguments as streamed. Not written
+ * to. None leaves `tool_calls` off the message rather than empty.
+ * @returns A new message, each call on it a copy.
+ */
+export const writtenMessage = (content, calls) => ({
+    role: Role.Assistant,
+    content: content || null,
+    ...(calls.length ? { tool_calls: calls.map((call) => ({ ...call, function: { ...call.function } })) } : {}),
+});
 /**
  * The definitions the host gave for these names, in the order the names are given.
  *
@@ -155,17 +190,28 @@ function answerOf(answer) {
 const shownAs = (run, { call, args, normal }) => run.proxies && call.function.name === CALL_TOOL
     ? shownCall(CALL_TOOL, args ? normal : call.function.arguments)
     : { name: call.function.name, input: call.function.arguments };
+/**
+ * Adds one call's load counts to the run's.
+ *
+ * @param into - The run's counts. Written to.
+ * @param counts - The call's. Not written to.
+ */
+function addLoads(into, counts) {
+    into.toolsLoaded += counts.toolsLoaded;
+    into.redundantLoads += counts.redundantLoads;
+    into.unknownToolNames += counts.unknownToolNames;
+}
 /**
  * Answers a `load_tools`, counting what it loaded.
  *
  * @param run - The run. Written to: the names this call loads are added to `loaded`, and `loads`
  * counts the new ones, the ones already loaded and the ones not in the catalogue.
  * @param args - The call's arguments, read as `requestedNames` reads them.
- * @returns The text the model reads, and `ok`: false where nothing it named was loadable, true
- * where it named even one tool that was loaded already.
+ * @returns The text the model reads; `ok`, false where nothing it named was loadable and true
+ * where it named even one tool that was loaded already; and `counts`, this call's alone.
  */
 function answerLoad(run, args) {
-    const { catalog, proxied, definitions, loaded, loads } = run;
+    const { catalog, proxied, definitions, loaded } = run;
     const resolved = expandNames(requestedNames(args), catalog);
     const content = proxied
         ? proxyLoadResult(resolved, catalog, definedAs(definitions, resolved.matched), loaded)
@@ -173,14 +219,15 @@ function answerLoad(run, args) {
     // Proxied, a load is only of what the result could define: a catalogued name the host
     // gave no definition for was not loaded, and is not counted or remembered as though it was.
     const hits = proxied ? resolved.matched.filter((hit) => definitions.has(hit)) : resolved.matched;
+    const counts = { toolsLoaded: 0, redundantLoads: 0, unknownToolNames: resolved.unknown.length };
     for (const hit of hits) {
-        loads[loaded.has(hit) ? 'redundantLoads' : 'toolsLoaded']++;
+        counts[loaded.has(hit) ? 'redundantLoads' : 'toolsLoaded']++;
     }
-    loads.unknownToolNames += resolved.unknown.length;
+    addLoads(run.loads, counts);
     for (const hit of hits) {
         loaded.add(hit);
     }
-    return { content, ok: hits.length > 0 };
+    return { content, ok: hits.length > 0, counts };
 }
 /**
  * Makes a call at most once per key, sharing the in-flight promise so two identical calls in one
@@ -272,7 +319,7 @@ function prepare(run, entry) {
     }
     // 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: inner, raw };
+    const request = { id: call.id, name, args: inner, raw, repaired: entry.repaired };
     // By the name the model called, not the one a `call_tool` wraps: `load_tools` is not in
     // the catalogue, and one reached through `call_tool` is refused like any other.
     const load = onDemand && call.function.name === LOAD_TOOLS;
@@ -353,6 +400,7 @@ async function runCall(run, prepared, answered, step) {
     let links = [];
     let end = false;
     let ok = true;
+    let loads;
     // Answered from an earlier identical call of the step, whose links are already counted.
     let shared = false;
     try {
@@ -360,7 +408,7 @@ async function runCall(run, prepared, answered, step) {
             throw unreadable;
         }
         if (load) {
-            ({ content, ok } = answerLoad(run, args));
+            ({ content, ok, counts: loads } = answerLoad(run, args));
         }
         else {
             if (refused) {
@@ -393,7 +441,14 @@ async function runCall(run, prepared, answered, step) {
     finally {
         close();
     }
-    run.onEvent({ kind: RunEventKind.ToolResult, id: call.id, name, ok, text: preview(content) });
+    run.onEvent({
+        kind: RunEventKind.ToolResult,
+        id: call.id,
+        name,
+        ok,
+        text: preview(content),
+        ...(loads ? { loads } : {}),
+    });
     const isFirstAnswer = shared === false;
     if (isFirstAnswer) {
         collect(run, links, { callId: call.id, tool: name, step });
@@ -520,11 +575,12 @@ export async function loadShortlist(run, shortlist, messages) {
     // host that shortlisted more has already chosen.
     const content = proxyLoadResult(expandNames(names, catalog, names.length), catalog, shortlist);
     run.onEvent({ kind: RunEventKind.ToolCall, id, name: LOAD_TOOLS, text: preview(args) });
-    run.onToolCall?.({ id, name: LOAD_TOOLS, args: { names }, raw: args });
-    run.onEvent({ kind: RunEventKind.ToolResult, id, name: LOAD_TOOLS, ok: true, text: preview(content) });
+    run.onToolCall?.({ id, name: LOAD_TOOLS, args: { names }, raw: args, repaired: false });
+    const loads = { toolsLoaded: names.length, redundantLoads: 0, unknownToolNames: 0 };
+    run.onEvent({ kind: RunEventKind.ToolResult, id, name: LOAD_TOOLS, ok: true, text: preview(content), loads });
     run.onToolResult?.({ id, name: LOAD_TOOLS, ok: true, content });
     run.toolCalls.push({ id, name: LOAD_TOOLS, ok: true });
-    run.loads.toolsLoaded += names.length;
+    addLoads(run.loads, loads);
     for (const name of names) {
         run.loaded.add(name);
     }

package/dist/wire/errors.d.ts

@@ -1,6 +1,6 @@
 import type OpenAI from 'openai';
 import { ContextOverflow } from './retry.ts';
-import type { PartialTurn, TurnUsage } from './stream.ts';
+import type { LoopUsage, PartialTurn } from './stream.ts';
 import type { RunArtifact, ToolCallOutcome } from './tool-calls.ts';
 /**
  * What went wrong, as a string.
@@ -40,8 +40,11 @@ export interface AgentLoopFailure {
      * watching had been shown, and whether it belongs in the history is the host's call.
      */
     partial?: PartialTurn;
-    /** Summed over the turns that came back. A request that failed or was stopped adds nothing. */
-    usage: TurnUsage;
+    /**
+     * Summed over the turns that came back, as the result's `usage` would have said it. A request
+     * that failed or was stopped adds nothing.
+     */
+    usage: LoopUsage;
     /** Every call that was made, in order. One the run was stopped during is `ok: false`. */
     toolCalls: ToolCallOutcome[];
     /**
@@ -70,7 +73,7 @@ export declare class AgentLoopError extends Error implements AgentLoopFailure {
     readonly name: string;
     readonly messages: OpenAI.ChatCompletionMessageParam[];
     readonly partial?: PartialTurn;
-    readonly usage: TurnUsage;
+    readonly usage: LoopUsage;
     readonly toolCalls: ToolCallOutcome[];
     readonly artifacts: RunArtifact[];
     readonly loaded: string[];
@@ -105,7 +108,7 @@ export declare class ToolIterationLimit extends AgentLoopError {
 export declare class AgentLoopOverflow extends ContextOverflow implements AgentLoopFailure {
     readonly messages: OpenAI.ChatCompletionMessageParam[];
     readonly partial?: PartialTurn;
-    readonly usage: TurnUsage;
+    readonly usage: LoopUsage;
     readonly toolCalls: ToolCallOutcome[];
     readonly artifacts: RunArtifact[];
     readonly loaded: string[];

package/dist/wire/stream.d.ts

@@ -145,6 +145,60 @@ export interface TurnUsage {
  * nothing reported them.
  */
 export declare const noUsage: () => TurnUsage;
+/**
+ * A run's token totals, in the spelling every run-level usage shares.
+ *
+ * @remarks
+ * The spelling of `RunUsage`, which is what the `usage` events carry and what hosts persist, so a
+ * host reads a loop's result and its events with one mapping rather than two. A single turn's own
+ * report, `TurnUsage`, keeps its shorter names: it is a different thing, a turn's measurements,
+ * and every field on it is that turn's.
+ */
+export interface UsageTotals {
+    promptTokens: number;
+    completionTokens: number;
+    totalTokens: number;
+    /** How much of `promptTokens` came from the endpoint's prompt cache. Zero where none said. */
+    cachedTokens: number;
+    /**
+     * Whether any turn of the run reported a cache count, which is what tells a `cachedTokens` of
+     * zero that is a miss from one the endpoint never reports. A turn reported one where its usage
+     * carries `uncached`.
+     */
+    cacheReported: boolean;
+}
+/**
+ * What a loop spent, as `AgentLoopResult.usage` and a failed run's `usage` carry it.
+ *
+ * @remarks
+ * `UsageTotals`, with the four counts also under the names this field had before it: a host that
+ * reads `usage.prompt` keeps compiling and reads the same number as `usage.promptTokens`.
+ */
+export interface LoopUsage extends TurnUsage, UsageTotals {
+    /** @deprecated Read `promptTokens`, the same number. */
+    prompt: number;
+    /** @deprecated Read `completionTokens`, the same number. */
+    completion: number;
+    /** @deprecated Read `totalTokens`, the same number. */
+    total: number;
+    /** @deprecated Read `cachedTokens`, the same number, and `cacheReported` for whether it was reported. */
+    cached: number;
+}
+/**
+ * Whether a turn's usage says the endpoint reported its cache.
+ *
+ * @param usage - One turn's report.
+ * @returns True where it carries `uncached`, which is present only where a cache count was.
+ */
+export declare const reportsCache: (usage: TurnUsage) => boolean;
+/**
+ * A loop's summed counts in both spellings, for its result and its `usage` events.
+ *
+ * @param counts - The four counts summed over the loop's turns. Not written to.
+ * @param cacheReported - Whether any of those turns reported a cache count.
+ * @returns A new usage holding the four counts under both names, and the flag.
+ */
+export declare const loopUsage: (counts: TurnUsage, cacheReported: boolean) => LoopUsage;
 /**
  * The four token counts of two usages, added.
  *

package/dist/wire/stream.js

@@ -42,6 +42,31 @@ export const CacheBreakReason = {
  * nothing reported them.
  */
 export const noUsage = () => ({ prompt: 0, completion: 0, total: 0, cached: 0 });
+/**
+ * Whether a turn's usage says the endpoint reported its cache.
+ *
+ * @param usage - One turn's report.
+ * @returns True where it carries `uncached`, which is present only where a cache count was.
+ */
+export const reportsCache = (usage) => usage.uncached !== undefined;
+/**
+ * A loop's summed counts in both spellings, for its result and its `usage` events.
+ *
+ * @param counts - The four counts summed over the loop's turns. Not written to.
+ * @param cacheReported - Whether any of those turns reported a cache count.
+ * @returns A new usage holding the four counts under both names, and the flag.
+ */
+export const loopUsage = (counts, cacheReported) => ({
+    prompt: counts.prompt,
+    completion: counts.completion,
+    total: counts.total,
+    cached: counts.cached,
+    promptTokens: counts.prompt,
+    completionTokens: counts.completion,
+    totalTokens: counts.total,
+    cachedTokens: counts.cached,
+    cacheReported,
+});
 /**
  * The four token counts of two usages, added.
  *

package/dist/wire/tool-calls.d.ts

@@ -114,9 +114,24 @@ export interface ToolCallRequest {
     args: Record<string, unknown>;
     /**
      * The arguments as the model wrote them, before any repair. Through `call_tool`, the inner
-     * arguments as JSON text.
+     * arguments as JSON text. For a call recovered from the reply's text, the arguments recovery read
+     * out of it, as JSON text: the words the model wrote are the reply's content, which `onMessage`'s
+     * `raw` message carries.
      */
     raw: string;
+    /**
+     * Whether `args` took a repair to read: true where `raw` does not parse, as written, to the JSON
+     * object `args` holds — near-JSON, or JSON inside a string — and for every call recovered from
+     * text, which the model never sent as a call. False for blank arguments, which every reader takes
+     * as none, and for arguments that could not be read at all. Through `call_tool`, whether the
+     * `call_tool`'s own arguments did.
+     *
+     * @remarks
+     * A host that shows or stores what the model said reads `raw` where this is true. Whitespace is
+     * not a repair, though the replayed arguments are re-serialised either way. `runAgentLoop` always
+     * sets it; optional so a request built before it existed still compiles.
+     */
+    repaired?: boolean;
 }
 /** What one tool call did, in the order the model asked. */
 export interface ToolCallOutcome {

package/llms.txt

@@ -176,6 +176,7 @@ The loop above a turn: send, run the tools the model asked for, send again, unti
 - `PRESELECTED_NOTICE` — What opens the notice naming the loop's own picks, ahead of the names.
 - `runAgentLoop` — Runs a question to its answer: one `runTurn` per step, the tools it asks for between them, until a turn asks for none or a call's answer ends the run.
 - `StepWindow` (type) — How full the window is as a step is about to be sent, as `beforeStep` is told it.
+- `WrittenMessage` (type) — What `onMessage` is handed beside an assistant message the model wrote: that message as the model produced it.
 
 ### events
 
@@ -187,6 +188,7 @@ What a run is doing, while it is doing it.
 - `endRun` — Forgets a run that will not be emitting `done` — one whose process is tearing down, or whose loop threw where it could not be caught.
 - `fold` — A run's events with each stretch of `thinking` or of `output` joined into one block, for a reader that takes a run in snapshots.
 - `history` — The backlog alone, for a caller that wants a snapshot rather than a subscription.
+- `LoadCounts` (type) — What `load_tools` calls resolved to: new tools, ones already loaded, and names in no catalogue.
 - `RunEvent` (type) — One thing that happened in a run, as a watcher receives it.
 - `RunEventInput` (type) — What `emit` is given: the run and the sequence are the bus's to assign.
 - `RunEventKind` — Any one of the kinds in `RunEventKind`.
@@ -388,12 +390,14 @@ Reading one streamed turn back into a message.
 
 - `CacheBreakReason` — Any one of the reasons in `CacheBreakReason`.
 - `InFlight` (type) — Where the request in flight can be read from, after it has thrown.
+- `LoopUsage` (type) — What a loop spent, as `AgentLoopResult.usage` and a failed run's `usage` carry it.
 - `PartialTurn` (type) — What a turn had said when it ended without coming back: the answer, the scratchpad and the calls, as far as each had arrived.
 - `Produced` (type) — Whether the model has said anything a second attempt would say twice.
 - `StreamTurnOptions` (type) — What `streamTurn` takes besides the request body.
 - `streamTurn` — Runs one turn as a stream, reporting tokens as they arrive and assembling them back into a message.
 - `Turn` (type) — One streamed turn, put back together into the shape a loop and a transcript work with.
 - `TurnUsage` (type) — What a turn cost, and how it went.
+- `UsageTotals` (type) — A run's token totals, in the spelling every run-level usage shares.
 
 ### thinking
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cubicecho/agent-core",
-  "version": "4.18.0",
+  "version": "4.20.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",