@cubicecho/agent-core 4.18.0 → 4.19.0

package/README.md

@@ -826,7 +826,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 +860,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 });

package/dist/index.d.ts

@@ -20,7 +20,7 @@ export { CACHE_PROMPT_FIELD, resetSlots, SESSION_HEADER, SLOT_FIELD, type SlotAl
 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 { 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';
@@ -497,8 +497,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 +553,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,7 +16,7 @@ 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';
@@ -127,7 +127,7 @@ export async function runAgentLoop(options) {
     const standing = {
         read: () => ({
             messages: [...options.messages],
-            usage: noUsage(),
+            usage: loopUsage(noUsage(), false),
             toolCalls: [],
             artifacts: [],
             loaded: [],
@@ -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.
@@ -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,7 +844,8 @@ 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`);
         }
@@ -873,7 +881,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.
  *
@@ -89,11 +89,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

@@ -155,17 +155,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 +184,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
@@ -353,6 +365,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 +373,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 +406,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 });
@@ -521,10 +541,11 @@ export async function loadShortlist(run, shortlist, messages) {
     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) });
+    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/llms.txt

@@ -187,6 +187,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 +389,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.19.0",
   "description": "The endpoint-agnostic half of an OpenAI-compatible agent loop: tool-schema compatibility, on-demand tool loading, one-shot side tasks, run events, and a pooled client.",
   "keywords": [
     "openai",