@cubicecho/agent-core 4.17.0 → 4.19.0

package/README.md

@@ -213,6 +213,11 @@ is worth another attempt. The content-free `{"role":"assistant"}` most servers o
 does not set it: nothing has been shown to anybody yet, so an endpoint that primes the stream and
 then wedges is retried like one that never answered at all.
 
+`inFlight` is the other box `streamTurn` takes, for what an attempt had said once it has thrown:
+each call sets its `read` as it starts, so after a retry it reads the attempt that failed last and
+nothing of the one before. `runTurn` and `continueTurn` pass it through, the second with the
+answer it is continuing joined on, and `runAgentLoop` reads it into a failure's `partial`.
+
 `idleMs` is silence, not a deadline: the timer is rearmed on every chunk, so a model that is still
 talking is never cut off however long it takes, and one that has stopped answering raises
 `EndpointSilent` rather than hanging the run. `timeoutMs(config)` returns `undefined` for a
@@ -821,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
@@ -850,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 });
@@ -946,7 +958,7 @@ try {
       store.add(sessionId, turn?.reasoning ? { ...message, reasoning_content: turn.reasoning } : message),
   });
 } catch (error) {
-  const run = failedRun(error); // messages, usage, toolCalls, loaded, used, preselected — or undefined
+  const run = failedRun(error); // messages, partial, usage, toolCalls, loaded, used, preselected — or undefined
   if (run) await store.keep(sessionId, { usage: run.usage, loaded: run.loaded });
   if (signal.aborted) return; // a stop, told by the signal as it always was
   if (error instanceof ContextOverflow) return compactAndRetry(run?.messages);
@@ -973,9 +985,14 @@ A failure while a step's tools are running leaves a transcript that can be sent
 that came back are kept, a call the run was stopped during is answered `Stopped before this call
 finished.`, and one the loop never reached `Not run: the run stopped first.` — a call with no
 result is a transcript an endpoint refuses. Those are announced through `onMessage` like any other
-result. The reply of a request that was in flight when the run stopped is not kept: the host has
-the deltas from its `output` and `thinking` events, and whether half an answer belongs in the
-history is its call.
+result. The reply of a request that was in flight when the run stopped or failed — a stop, the
+endpoint going silent, a stream that broke after its first token — is not in `messages`, because it
+is not a turn an endpoint will take back. It is on the failure as `partial`: its `content`, its
+`reasoning` and the `toolCalls` it had begun, assembled as far as they had arrived, with a
+continuation's piece joined onto the answer it was continuing and, after a retry, only the attempt
+that was in flight. A request that had said nothing leaves no `partial`, and neither does a
+failure while the tools run, since that step's reply is already in `messages`. Whether half an
+answer belongs in the history is the host's call.
 
 `resolveApiKey` is exported and not applied, because which key an endpoint gets is a rule a
 consumer states and a library guessing it could send one where it was not meant to go. The rule

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 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;
     /**
@@ -577,7 +582,8 @@ export interface AgentLoopResult {
  * @remarks
  * What it throws carries the run as it stood — `messages`, `usage`, `toolCalls`, `loaded`, `used`
  * and `preselected` — because the steps before a failure were real and a host that stores its
- * transcript has nothing else to store them from. A spent budget is a `ToolIterationLimit`, an
+ * transcript has nothing else to store them from. What the request in flight had said is on it
+ * as `partial`, and not in `messages`. A spent budget is a `ToolIterationLimit`, an
  * overflow is an `AgentLoopOverflow`, which is still a `ContextOverflow`, and anything else is an
  * `AgentLoopError` with what was caught as its `cause` and its message as its own; `failedRun`
  * reads the run off any of the three. A failure while a step's tools run leaves the transcript

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';
@@ -77,7 +77,8 @@ function cacheDiagnosis(previous, next, usage) {
  * @remarks
  * What it throws carries the run as it stood — `messages`, `usage`, `toolCalls`, `loaded`, `used`
  * and `preselected` — because the steps before a failure were real and a host that stores its
- * transcript has nothing else to store them from. A spent budget is a `ToolIterationLimit`, an
+ * transcript has nothing else to store them from. What the request in flight had said is on it
+ * as `partial`, and not in `messages`. A spent budget is a `ToolIterationLimit`, an
  * overflow is an `AgentLoopOverflow`, which is still a `ContextOverflow`, and anything else is an
  * `AgentLoopError` with what was caught as its `cause` and its message as its own; `failedRun`
  * reads the run off any of the three. A failure while a step's tools run leaves the transcript
@@ -126,7 +127,7 @@ export async function runAgentLoop(options) {
     const standing = {
         read: () => ({
             messages: [...options.messages],
-            usage: noUsage(),
+            usage: loopUsage(noUsage(), false),
             toolCalls: [],
             artifacts: [],
             loaded: [],
@@ -529,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.
@@ -628,18 +635,26 @@ 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();
-    standing.read = () => ({
-        messages,
-        usage,
-        toolCalls,
-        artifacts: [...artifacts.values()],
-        // As the result would have said it: proxied, nothing is loaded that the history does not hold.
-        loaded: proxied ? [] : [...loaded],
-        used: [...used],
-        preselected: [...preselected],
-    });
+    // A box per request, emptied once its turn is in `messages`: a failure while the tools run had
+    // no request in flight.
+    let inFlight = {};
+    standing.read = () => {
+        const partial = inFlight.read?.();
+        return {
+            messages,
+            ...(partial ? { partial } : {}),
+            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.
+            loaded: proxied ? [] : [...loaded],
+            used: [...used],
+            preselected: [...preselected],
+        };
+    };
     const announce = announcer(onMessage);
     // Held by reference rather than by index, so a `beforeStep` that folds the head into a summary
     // moves the question without losing it — and one that summarises the question away takes the
@@ -764,8 +779,10 @@ async function runSteps(options, standing, pin) {
             ...withContext(messages, questionAt(), gathered.context, preface),
         ];
         const build = (supported, refused) => buildBody(sending, supported, refused, request, declared, toolOrder);
+        inFlight = {};
         const turnOptions = {
             model: config.model,
+            inFlight,
             droppable: Object.keys(extraBody ?? {}),
             ...(pin ? { headers: pin.headers } : {}),
             maxRetries,
@@ -819,6 +836,7 @@ async function runSteps(options, standing, pin) {
         const turn = maxContinuations > 0
             ? await continueTurn(client, supports, build, first, { ...turnOptions, maxContinuations })
             : first;
+        inFlight = {};
         previous = {
             messages: request,
             tools: names,
@@ -826,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`);
         }
@@ -862,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/turn/continuation.d.ts

@@ -62,6 +62,8 @@ export declare const isContinuable: (turn: Turn) => boolean;
  * server that takes the request and ignores the prefill — hosted OpenAI among them — shows itself;
  * that check is only as good as a restart being word for word. Either way the answer so far is
  * kept, with a notice. So is it when the continuation fails any other way, since the tokens
- * already in hand are worth more than the error; only a stop is thrown.
+ * already in hand are worth more than the error; only a stop is thrown. An `inFlight` box reads
+ * the answer so far with the continuation's piece joined on, so a stop mid-continuation keeps it
+ * all.
  */
 export declare function continueTurn(client: OpenAI, supports: Capabilities, request: RequestBuilder, turn: Turn, { maxContinuations, ...options }?: ContinueTurnOptions): Promise<Turn>;

package/dist/turn/continuation.js

@@ -97,6 +97,22 @@ function joinUsage(first, next) {
     }
     return joined;
 }
+/**
+ * The answer so far with the piece a continuation in flight had added to it.
+ *
+ * @param sofar - The turn being continued, which may itself be a joined one. Not written to.
+ * @param [piece] - What the continuation had said. Absent adds nothing.
+ * @returns The two joined as `continueTurn` joins turns: content and reasoning in order, and the
+ * continuation's own calls. `reasoning` and `toolCalls` are left out where empty.
+ */
+function joinPartial(sofar, piece) {
+    const reasoning = sofar.reasoning + (piece?.reasoning ?? '');
+    return {
+        content: sofar.content + (piece?.content ?? ''),
+        ...(reasoning ? { reasoning } : {}),
+        ...(piece?.toolCalls ? { toolCalls: piece.toolCalls } : {}),
+    };
+}
 /**
  * Carries on an answer the token ceiling cut off, by sending the transcript again with the answer
  * so far as a trailing assistant message, and joins the pieces into one turn.
@@ -124,17 +140,28 @@ function joinUsage(first, next) {
  * server that takes the request and ignores the prefill — hosted OpenAI among them — shows itself;
  * that check is only as good as a restart being word for word. Either way the answer so far is
  * kept, with a notice. So is it when the continuation fails any other way, since the tokens
- * already in hand are worth more than the error; only a stop is thrown.
+ * already in hand are worth more than the error; only a stop is thrown. An `inFlight` box reads
+ * the answer so far with the continuation's piece joined on, so a stop mid-continuation keeps it
+ * all.
  */
 export async function continueTurn(client, supports, request, turn, { maxContinuations = 1, ...options } = {}) {
     const refused = options.model === undefined ? undefined : modelCapabilitiesFor(supports, options.model);
     const who = modelLabel(options.model);
+    // The caller's box reads the whole answer, not only the piece the continuation streams.
+    const outer = options.inFlight;
+    const piece = {};
+    const told = outer ? { inFlight: piece } : {};
     let joined = turn;
     for (let count = 0; count < maxContinuations && isContinuable(joined); count++) {
         if (refused?.assistantPrefill === false) {
             break;
         }
         const answer = joined.content;
+        if (outer) {
+            const sofar = joined;
+            piece.read = undefined;
+            outer.read = () => joinPartial(sofar, piece.read?.());
+        }
         let next;
         try {
             next = await runTurn(client, supports, (capabilities, forModel) => {
@@ -143,7 +170,7 @@ export async function continueTurn(client, supports, request, turn, { maxContinu
                     ...body,
                     messages: [...body.messages, { role: Role.Assistant, content: answer }],
                 };
-            }, { ...options, startInReasoning: false });
+            }, { ...options, ...told, startInReasoning: false });
         }
         catch (error) {
             if (options.signal?.aborted) {

package/dist/wire/errors.d.ts

@@ -1,6 +1,6 @@
 import type OpenAI from 'openai';
 import { ContextOverflow } from './retry.ts';
-import type { 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.
@@ -27,11 +27,24 @@ export interface AgentLoopFailure {
     /**
      * The transcript, as the result's `messages` would have been: every assistant turn and tool
      * result the run added, and no system prompt. Well-formed — a call the run was stopped during
-     * has a result saying so. The reply of a request that was in flight is not in it.
+     * has a result saying so. The reply of a request that was in flight is not in it: see `partial`.
      */
     messages: OpenAI.ChatCompletionMessageParam[];
-    /** Summed over the turns that came back. A request that failed or was stopped adds nothing. */
-    usage: TurnUsage;
+    /**
+     * What the request in flight had said when the run stopped or failed — a stop, the endpoint
+     * going silent, a stream that broke — continuations joined on. Absent where no request was in
+     * flight or it had said nothing.
+     *
+     * @remarks
+     * Not in `messages`, because it is not a turn an endpoint will take back. It is what a person
+     * 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, 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[];
     /**
@@ -59,7 +72,8 @@ export interface AgentLoopFailure {
 export declare class AgentLoopError extends Error implements AgentLoopFailure {
     readonly name: string;
     readonly messages: OpenAI.ChatCompletionMessageParam[];
-    readonly usage: TurnUsage;
+    readonly partial?: PartialTurn;
+    readonly usage: LoopUsage;
     readonly toolCalls: ToolCallOutcome[];
     readonly artifacts: RunArtifact[];
     readonly loaded: string[];
@@ -93,7 +107,8 @@ export declare class ToolIterationLimit extends AgentLoopError {
  */
 export declare class AgentLoopOverflow extends ContextOverflow implements AgentLoopFailure {
     readonly messages: OpenAI.ChatCompletionMessageParam[];
-    readonly usage: TurnUsage;
+    readonly partial?: PartialTurn;
+    readonly usage: LoopUsage;
     readonly toolCalls: ToolCallOutcome[];
     readonly artifacts: RunArtifact[];
     readonly loaded: string[];

package/dist/wire/errors.js

@@ -24,6 +24,7 @@ export const errorMessage = (error) => (error instanceof Error ? error.message :
 export class AgentLoopError extends Error {
     name = 'AgentLoopError';
     messages;
+    partial;
     usage;
     toolCalls;
     artifacts;
@@ -38,6 +39,9 @@ export class AgentLoopError extends Error {
     constructor(message, run, options) {
         super(message, options);
         this.messages = run.messages;
+        if (run.partial) {
+            this.partial = run.partial;
+        }
         this.usage = run.usage;
         this.toolCalls = run.toolCalls;
         this.artifacts = run.artifacts ?? [];
@@ -67,6 +71,7 @@ export class ToolIterationLimit extends AgentLoopError {
  */
 export class AgentLoopOverflow extends ContextOverflow {
     messages;
+    partial;
     usage;
     toolCalls;
     artifacts;
@@ -81,6 +86,9 @@ export class AgentLoopOverflow extends ContextOverflow {
     constructor(message, run, options) {
         super(message, options);
         this.messages = run.messages;
+        if (run.partial) {
+            this.partial = run.partial;
+        }
         this.usage = run.usage;
         this.toolCalls = run.toolCalls;
         this.artifacts = run.artifacts ?? [];

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.
  *
@@ -213,6 +267,39 @@ export interface Turn {
 export interface Produced {
     any: boolean;
 }
+/**
+ * What a turn had said when it ended without coming back: the answer, the scratchpad and the calls,
+ * as far as each had arrived.
+ *
+ * @remarks
+ * It is not a `Turn`, and not a message an endpoint will take back: it has no usage, no reason it
+ * ended, and a call in it may stop mid-JSON. It is what a person watching had been shown, for a
+ * host to keep or to show.
+ */
+export interface PartialTurn {
+    /** The answer so far, fences taken out; `""` where it had not begun. */
+    content: string;
+    /** The scratchpad so far, from its own field or a fence. Absent where none had arrived. */
+    reasoning?: string;
+    /**
+     * The calls begun, assembled as `Turn.toolCalls` would have been — a name may be missing and
+     * arguments may stop mid-JSON. Absent where none had begun.
+     */
+    toolCalls?: ToolCall[];
+}
+/**
+ * Where the request in flight can be read from, after it has thrown.
+ *
+ * @remarks
+ * A box for the reason `Produced` is one: a rejected promise carries no stream state, and the
+ * error is often the signal's reason, which is shared by every run under it. Each `streamTurn`
+ * sets `read` as it starts, so after a retry or a downgrade it reads the latest attempt and
+ * nothing of the one before.
+ */
+export interface InFlight {
+    /** What the stream had said, or `undefined` where it had said nothing. */
+    read?: () => PartialTurn | undefined;
+}
 /** What `streamTurn` takes besides the request body. */
 export interface StreamTurnOptions {
     /** Cancels the request and the stream being read from it. */
@@ -235,6 +322,11 @@ export interface StreamTurnOptions {
     firstChunkMs?: number;
     /** Set by the first chunk that carries anything, so a failed call knows if it can be retried. */
     produced?: Produced;
+    /**
+     * Given a `read` of what this call has said so far, as the call starts. Read it once the call has
+     * thrown; a turn that came back has it all, and the box is not cleared.
+     */
+    inFlight?: InFlight;
     /**
      * The fences that mark a scratchpad written into `content`.
      *
@@ -282,4 +374,4 @@ export interface StreamTurnOptions {
  * which run it is: `step` is the caller's flow concept, and wrapping these into an `emit` is one
  * line at the call site.
  */
-export declare function streamTurn(client: OpenAI, body: OpenAI.ChatCompletionCreateParamsStreaming, { signal, idleMs, firstChunkMs, produced, fences, startInReasoning, onThinking, onOutput, headers, }?: StreamTurnOptions): Promise<Turn>;
+export declare function streamTurn(client: OpenAI, body: OpenAI.ChatCompletionCreateParamsStreaming, { signal, idleMs, firstChunkMs, produced, inFlight, fences, startInReasoning, onThinking, onOutput, headers, }?: StreamTurnOptions): Promise<Turn>;

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.
  *
@@ -188,6 +213,25 @@ function assembledCalls(calls) {
 }
 /** The largest delay a timer takes, which is as close to none as the SDK's timeout option goes. */
 const NO_SDK_TIMEOUT = 2_147_483_647;
+/**
+ * A partial turn from what a stream had put together, or nothing where it had put nothing.
+ *
+ * @param content - The answer so far.
+ * @param reasoning - The scratchpad so far.
+ * @param calls - The calls begun, as they arrived. Not written to.
+ * @returns `undefined` where all three are empty; otherwise the content, with `reasoning` and
+ * `toolCalls` only where they hold something.
+ */
+function partialTurn(content, reasoning, calls) {
+    if (content === '' && reasoning === '' && calls.length === 0) {
+        return undefined;
+    }
+    return {
+        content,
+        ...(reasoning ? { reasoning } : {}),
+        ...(calls.length ? { toolCalls: assembledCalls(calls) } : {}),
+    };
+}
 /**
  * Runs one turn as a stream, reporting tokens as they arrive and assembling them back into a
  * message.
@@ -208,7 +252,7 @@ const NO_SDK_TIMEOUT = 2_147_483_647;
  * which run it is: `step` is the caller's flow concept, and wrapping these into an `emit` is one
  * line at the call site.
  */
-export async function streamTurn(client, body, { signal, idleMs, firstChunkMs, produced, fences = DEFAULT_FENCES, startInReasoning, onThinking, onOutput, headers, } = {}) {
+export async function streamTurn(client, body, { signal, idleMs, firstChunkMs, produced, inFlight, fences = DEFAULT_FENCES, startInReasoning, onThinking, onOutput, headers, } = {}) {
     // Silence, not duration: the timer is rearmed on every chunk, so a model that is still
     // talking is never cut off however long it takes, and one that has stopped talking does not
     // hang the run until someone notices. A request that never answers at all is the same case
@@ -229,6 +273,10 @@ export async function streamTurn(client, body, { signal, idleMs, firstChunkMs, p
             idle = setTimeout(() => watchdog.abort(), ms);
         }
     };
+    if (inFlight) {
+        // Before the request, so a box an earlier attempt filled reads nothing of it.
+        inFlight.read = () => undefined;
+    }
     try {
         rearm(false);
         const started = Date.now();
@@ -271,6 +319,11 @@ export async function streamTurn(client, body, { signal, idleMs, firstChunkMs, p
         // In arrival order, sorted by index at the end; a call from a server that sent none keeps
         // its place in the order they arrived.
         const calls = [];
+        if (inFlight) {
+            // Lazy, so a stream nobody stops pays nothing for it. Text held back as a possible tag is
+            // left out: it is a few characters that may yet be a marker.
+            inFlight.read = () => partialTurn(splitter.output, reasoning.join('') + splitter.reasoning, calls);
+        }
         const usage = noUsage();
         // The usage block's own cache count wins over llama.cpp's, which is the same number in the
         // servers that send both; kept apart so the order the two arrive in does not decide.

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`.
@@ -387,11 +388,15 @@ Everything about a request failing that is not about what the request said.
 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.17.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",