@cubicecho/agent-core 2.11.0 → 2.12.0

package/dist/compaction.d.ts

@@ -62,8 +62,14 @@ export interface CompactionOptions {
     compactAt?: number;
     /** The fraction of `limit` the kept tail may fill. `KEEP_RATIO` by default. */
     keepRatio?: number;
-    /** One message's tokens. `messageTokens` by default. */
+    /** One message's tokens. `messageTokens` by default, divided by `charsPerToken`. */
     estimate?: (message: Message) => number;
+    /**
+     * The divisor the default `estimate` uses — `charsPerTokenFor` the model, for a transcript
+     * weighed the way `runTurn` sizes its requests. `CHARS_PER_TOKEN` when absent; ignored beside
+     * an `estimate` of the caller's own.
+     */
+    charsPerToken?: number;
 }
 /** Where to cut, as `compactTranscript` takes it. */
 export interface CompactionPlan {
@@ -89,7 +95,7 @@ export interface CompactionPlan {
  * @param messages The transcript, system prompts included if the caller keeps them in it.
  * @param options The window, what is in use, and the ratios. See `CompactionOptions`.
  */
-export declare function planCompaction(messages: Message[], { limit, used, compactAt, keepRatio, estimate, }: CompactionOptions): CompactionPlan | undefined;
+export declare function planCompaction(messages: Message[], { limit, used, compactAt, keepRatio, charsPerToken, estimate, }: CompactionOptions): CompactionPlan | undefined;
 /**
  * What the summariser is handed for a plan: the earlier summary if there was one, then each
  * message as its role and at most 4000 characters of its text.
@@ -113,21 +119,33 @@ export declare const summariser: (config: Endpoint, model: string, { system, max
  *
  * `beforeCompact` is told what is being folded while the summary is written, beside it rather
  * than ahead of it — a memory server filing it is not a rescue worth making the run wait for, and
- * `notify` never rejects. A hook cannot veto the compaction: `HookOutcome` has no way to say so,
- * and a run over its window has no better option anyway. An empty summary folds nothing, and the
- * transcript comes back as it was. Rewrites the prefix; see the module comment on when to run it.
+ * `notify` never rejects. A host that wants its hooks able to stop a compaction sets
+ * `honourVeto`, and then they run first and the summary waits on them: any `ok` outcome carrying
+ * `veto` leaves the transcript as it was, and each vetoing hook is noted by name. A `forced`
+ * compaction ignores a veto and runs the hooks beside the summary as before, because a run already
+ * past its window has no better option — a veto there only trades the summary for a
+ * `ContextOverflow`. An empty summary folds nothing either. Rewrites the prefix; see the module
+ * comment on when to run it.
  *
  * @param messages The transcript the plan was made for. Not written to.
  * @param plan What `planCompaction` returned for it.
- * @param summarise Writes the summary from `summaryInput`'s text. See `summariser`.
+ * @param summarise Writes the summary from `summaryInput`'s text. See `summariser`. Not called
+ * when a hook vetoes.
  * @param options Hooks to tell. `context` is extended with `compacting` and `range`, whose
- * indexes are the plan's.
+ * indexes are the plan's. `honourVeto` waits for the hooks and lets one stop the compaction; off
+ * by default, which adds no latency. `forced` says the window is already exceeded — the caller
+ * caught a `ContextOverflow`, or is compacting to make a refused request fit — and overrides
+ * `honourVeto`.
+ * @returns `messages` itself when nothing was folded — a veto or an empty summary — otherwise a
+ * new array.
  */
-export declare function compactTranscript(messages: Message[], plan: CompactionPlan, summarise: (text: string) => Promise<string>, { hooks, }?: {
+export declare function compactTranscript(messages: Message[], plan: CompactionPlan, summarise: (text: string) => Promise<string>, { hooks, forced, }?: {
     hooks?: {
         run: HookRunner;
         context: HookContext;
         onNote?: (note: HookNote) => void;
+        honourVeto?: boolean;
     };
+    forced?: boolean;
 }): Promise<Message[]>;
 export {};

package/dist/compaction.js

@@ -1,4 +1,4 @@
-import { notify, turnMessages } from "./hooks.js";
+import { consult, notify, turnMessages, } from "./hooks.js";
 import { messageTokens } from "./retry.js";
 import { ask } from "./side-task.js";
 /** The fraction of the window in use before a summary is worth its own round trip. */
@@ -83,7 +83,7 @@ export function pruneToolResults(messages, { keepLast = 5, maxChars = 256 } = {}
  * @param messages The transcript, system prompts included if the caller keeps them in it.
  * @param options The window, what is in use, and the ratios. See `CompactionOptions`.
  */
-export function planCompaction(messages, { limit, used, compactAt = COMPACT_AT, keepRatio = KEEP_RATIO, estimate = messageTokens, }) {
+export function planCompaction(messages, { limit, used, compactAt = COMPACT_AT, keepRatio = KEEP_RATIO, charsPerToken, estimate = (message) => messageTokens(message, { charsPerToken }), }) {
     if (!(limit > 0))
         return undefined;
     const cost = used ?? messages.reduce((total, message) => total + estimate(message), 0);
@@ -143,26 +143,45 @@ export const summariser = (config, model, { system = SUMMARY_PROMPT, maxTokens =
  *
  * `beforeCompact` is told what is being folded while the summary is written, beside it rather
  * than ahead of it — a memory server filing it is not a rescue worth making the run wait for, and
- * `notify` never rejects. A hook cannot veto the compaction: `HookOutcome` has no way to say so,
- * and a run over its window has no better option anyway. An empty summary folds nothing, and the
- * transcript comes back as it was. Rewrites the prefix; see the module comment on when to run it.
+ * `notify` never rejects. A host that wants its hooks able to stop a compaction sets
+ * `honourVeto`, and then they run first and the summary waits on them: any `ok` outcome carrying
+ * `veto` leaves the transcript as it was, and each vetoing hook is noted by name. A `forced`
+ * compaction ignores a veto and runs the hooks beside the summary as before, because a run already
+ * past its window has no better option — a veto there only trades the summary for a
+ * `ContextOverflow`. An empty summary folds nothing either. Rewrites the prefix; see the module
+ * comment on when to run it.
  *
  * @param messages The transcript the plan was made for. Not written to.
  * @param plan What `planCompaction` returned for it.
- * @param summarise Writes the summary from `summaryInput`'s text. See `summariser`.
+ * @param summarise Writes the summary from `summaryInput`'s text. See `summariser`. Not called
+ * when a hook vetoes.
  * @param options Hooks to tell. `context` is extended with `compacting` and `range`, whose
- * indexes are the plan's.
+ * indexes are the plan's. `honourVeto` waits for the hooks and lets one stop the compaction; off
+ * by default, which adds no latency. `forced` says the window is already exceeded — the caller
+ * caught a `ContextOverflow`, or is compacting to make a refused request fit — and overrides
+ * `honourVeto`.
+ * @returns `messages` itself when nothing was folded — a veto or an empty summary — otherwise a
+ * new array.
  */
-export async function compactTranscript(messages, plan, summarise, { hooks, } = {}) {
-    const [summary] = await Promise.all([
-        summarise(summaryInput(plan)),
-        hooks &&
-            notify(hooks.run, "beforeCompact", {
-                ...hooks.context,
-                compacting: turnMessages(hooks.context.session.id, messages, plan.from, plan.cut),
-                range: { from: plan.from, through: plan.cut },
-            }, hooks.onNote),
-    ]);
+export async function compactTranscript(messages, plan, summarise, { hooks, forced = false, } = {}) {
+    const context = hooks && {
+        ...hooks.context,
+        compacting: turnMessages(hooks.context.session.id, messages, plan.from, plan.cut),
+        range: { from: plan.from, through: plan.cut },
+    };
+    let summary;
+    if (hooks && context && hooks.honourVeto && !forced) {
+        const { vetoed } = await consult(hooks.run, "beforeCompact", context, hooks.onNote);
+        if (vetoed)
+            return messages;
+        summary = await summarise(summaryInput(plan));
+    }
+    else {
+        [summary] = await Promise.all([
+            summarise(summaryInput(plan)),
+            hooks && context && notify(hooks.run, "beforeCompact", context, hooks.onNote),
+        ]);
+    }
     if (!summary.trim())
         return messages;
     return [

package/dist/continuation.d.ts

@@ -0,0 +1,59 @@
+import OpenAI from "openai";
+import { type Capabilities, type ModelCapabilities } from "./capabilities.ts";
+import { type RunTurnOptions } from "./run-turn.ts";
+import type { Turn } from "./stream.ts";
+/**
+ * Picking up an answer the token ceiling cut off, instead of keeping half of it.
+ *
+ * A turn that stops at `maxTokens` mid-answer comes back looking finished, and the half answer
+ * becomes the answer. A server that renders a trailing assistant message as a prefill lets the
+ * model carry on from the last token as if nothing had happened, which costs the rest of the
+ * reply and a prefill the cache mostly already holds.
+ */
+/** What `continueTurn` takes besides what `runTurn` does. */
+export interface ContinueTurnOptions extends RunTurnOptions {
+    /**
+     * How many more requests one answer may be given, 1 unless given; zero continues nothing.
+     * The cap is what stops a model that never reaches a stop token from looping on the ceiling.
+     */
+    maxContinuations?: number;
+}
+/**
+ * Whether a turn is one a continuation can finish: cut off at the ceiling, with an answer begun
+ * and no tool call in it.
+ *
+ * An answer not begun is a turn cut off in its scratchpad, and prefilling a half-closed fence is
+ * the template's business rather than something this can do the same way everywhere — llama.cpp
+ * refuses a prefill outright on a template with thinking enabled. A tool call is excluded because
+ * its arguments are what was cut, and `parseToolArguments` already reports that truncation.
+ *
+ * @param turn The turn as it came back.
+ */
+export declare const isContinuable: (turn: Turn) => boolean;
+/**
+ * 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.
+ *
+ * Only a turn `isContinuable` accepts is continued; any other comes back as it was. Content and
+ * reasoning are joined in order, the tool calls a continuation makes are kept, and usage is summed
+ * across the requests with `continuations` counting them. The continuation is read as starting in
+ * the answer, whatever `startInReasoning` says: a template that opens a fence for a fresh reply
+ * does not open one for a prefill. Its tokens reach `onOutput` as they arrive, so a watcher sees
+ * one answer carry on rather than two.
+ *
+ * Whether the server continues at all is latched per model as `assistantPrefill`. A refusal of the
+ * request latches it off, and so does a continuation that begins the answer again, which is how a
+ * 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.
+ *
+ * @param client The pooled client for this endpoint.
+ * @param supports What the endpoint has already refused.
+ * @param request Builds the body the cut-off turn was sent, exactly as `runTurn` was given it. The
+ * prefill is appended to what it builds.
+ * @param turn The turn that came back cut off.
+ * @param options `runTurn`'s options, with `model` needed for the latch — without one nothing is
+ * latched and each continuation finds out again — and the cap on continuations.
+ */
+export declare function continueTurn(client: OpenAI, supports: Capabilities, request: (supports: Capabilities, model: ModelCapabilities | undefined) => OpenAI.ChatCompletionCreateParamsStreaming, turn: Turn, { maxContinuations, ...options }?: ContinueTurnOptions): Promise<Turn>;

package/dist/continuation.js

@@ -0,0 +1,159 @@
+import OpenAI from "openai";
+import { modelCapabilitiesFor } from "./capabilities.js";
+import { errorMessage } from "./errors.js";
+import { ContextOverflow } from "./retry.js";
+import { runTurn } from "./run-turn.js";
+/**
+ * Whether a turn is one a continuation can finish: cut off at the ceiling, with an answer begun
+ * and no tool call in it.
+ *
+ * An answer not begun is a turn cut off in its scratchpad, and prefilling a half-closed fence is
+ * the template's business rather than something this can do the same way everywhere — llama.cpp
+ * refuses a prefill outright on a template with thinking enabled. A tool call is excluded because
+ * its arguments are what was cut, and `parseToolArguments` already reports that truncation.
+ *
+ * @param turn The turn as it came back.
+ */
+export const isContinuable = (turn) => turn.finishReason === "length" && turn.content.trim() !== "" && turn.toolCalls.length === 0;
+/** How much of the answer's opening a reply has to repeat to have started over. */
+const RESTART_PROBE = 40;
+/** The shortest opening worth testing for a restart; shorter ones are repeated by chance. */
+const RESTART_MIN = 12;
+/**
+ * Whether the continuation began the answer again rather than carrying it on — how a server that
+ * ignores the prefill shows itself, since it takes the request without complaint.
+ */
+const restarted = (answer, continuation) => {
+    const opening = answer.trimStart().slice(0, RESTART_PROBE);
+    return opening.length >= RESTART_MIN && continuation.trimStart().startsWith(opening);
+};
+/** The fields of a usage that add across two requests, when both reported them. */
+const ADDED = [
+    "uncached",
+    "reasoningTokens",
+    "promptMs",
+    "predictedMs",
+    "draftTotal",
+    "draftAccepted",
+    "wallMs",
+    "retries",
+    "timeouts",
+];
+/** A rate, and the duration it was measured over, which is what weights it in a mean. */
+const RATES = [
+    ["promptTokensPerSecond", "promptMs"],
+    ["tokensPerSecond", "predictedMs"],
+];
+/**
+ * Two requests' usage as one turn's. The first request's own measurements and the loop's
+ * comparison with the request before it stay as they were; a field only one of them reported is
+ * dropped rather than passed off as the total.
+ */
+function joinUsage(first, next) {
+    const joined = {
+        ...first,
+        prompt: first.prompt + next.prompt,
+        completion: first.completion + next.completion,
+        total: first.total + next.total,
+        cached: first.cached + next.cached,
+        continuations: (first.continuations ?? 0) + 1,
+    };
+    for (const field of ADDED) {
+        const a = first[field];
+        const b = next[field];
+        if (a !== undefined && b !== undefined)
+            joined[field] = a + b;
+        else
+            delete joined[field];
+    }
+    for (const [rate, over] of RATES) {
+        const a = first[rate];
+        const b = next[rate];
+        const aMs = first[over];
+        const bMs = next[over];
+        // Tokens over time for both together, which is each rate weighted by the time it held.
+        if (a !== undefined && b !== undefined && aMs !== undefined && bMs !== undefined && aMs + bMs)
+            joined[rate] = (a * aMs + b * bMs) / (aMs + bMs);
+        else
+            delete joined[rate];
+    }
+    return joined;
+}
+/** Whether a failure is the endpoint refusing the request as written, rather than losing it. */
+const refusesRequest = (error) => error instanceof OpenAI.APIError && (error.status === 400 || error.status === 422);
+/**
+ * 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.
+ *
+ * Only a turn `isContinuable` accepts is continued; any other comes back as it was. Content and
+ * reasoning are joined in order, the tool calls a continuation makes are kept, and usage is summed
+ * across the requests with `continuations` counting them. The continuation is read as starting in
+ * the answer, whatever `startInReasoning` says: a template that opens a fence for a fresh reply
+ * does not open one for a prefill. Its tokens reach `onOutput` as they arrive, so a watcher sees
+ * one answer carry on rather than two.
+ *
+ * Whether the server continues at all is latched per model as `assistantPrefill`. A refusal of the
+ * request latches it off, and so does a continuation that begins the answer again, which is how a
+ * 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.
+ *
+ * @param client The pooled client for this endpoint.
+ * @param supports What the endpoint has already refused.
+ * @param request Builds the body the cut-off turn was sent, exactly as `runTurn` was given it. The
+ * prefill is appended to what it builds.
+ * @param turn The turn that came back cut off.
+ * @param options `runTurn`'s options, with `model` needed for the latch — without one nothing is
+ * latched and each continuation finds out again — and the cap on continuations.
+ */
+export async function continueTurn(client, supports, request, turn, { maxContinuations = 1, ...options } = {}) {
+    const refused = options.model === undefined ? undefined : modelCapabilitiesFor(supports, options.model);
+    const who = options.model ?? "the model";
+    let joined = turn;
+    for (let count = 0; count < maxContinuations && isContinuable(joined); count++) {
+        if (refused?.assistantPrefill === false)
+            break;
+        const answer = joined.content;
+        let next;
+        try {
+            next = await runTurn(client, supports, (capabilities, forModel) => {
+                const body = request(capabilities, forModel);
+                return {
+                    ...body,
+                    messages: [...body.messages, { role: "assistant", content: answer }],
+                };
+            }, { ...options, startInReasoning: false });
+        }
+        catch (error) {
+            if (options.signal?.aborted)
+                throw error;
+            if (error instanceof ContextOverflow) {
+                options.onNotice?.("no room left in the window to continue the cut-off reply");
+            }
+            else if (refusesRequest(error)) {
+                if (refused)
+                    refused.assistantPrefill = false;
+                options.onNotice?.(`${who} refused a trailing assistant message (${errorMessage(error)}); keeping the cut-off reply`);
+            }
+            else {
+                options.onNotice?.(`could not continue the cut-off reply: ${errorMessage(error)}`);
+            }
+            break;
+        }
+        if (restarted(answer, next.content)) {
+            if (refused)
+                refused.assistantPrefill = false;
+            options.onNotice?.(`${who} answered afresh instead of continuing its reply; keeping the cut-off reply`);
+            break;
+        }
+        joined = {
+            content: joined.content + next.content,
+            toolCalls: next.toolCalls,
+            usage: joinUsage(joined.usage, next.usage),
+            finishReason: next.finishReason,
+            reasoning: joined.reasoning + next.reasoning,
+        };
+    }
+    return joined;
+}

package/dist/events.d.ts

@@ -1,3 +1,4 @@
+import type { TurnUsage } from "./stream.ts";
 /**
  * What a run is doing, while it is doing it.
  *
@@ -81,7 +82,11 @@ export type RunEventKind =
  | "tool-result"
 /** Something the runner did that is not the model's doing — a preselection, a retry. */
  | "notice"
-/** What the run has cost so far, as the endpoint reported it at the end of a turn. */
+/**
+ * What the run has cost so far, at the end of every turn, and what that one turn did. Sent
+ * whether or not the endpoint reported tokens, since the timings and the cache comparison are
+ * measured either way.
+ */
  | "usage"
 /** The run ended. Always last, and always sent. */
  | "done";
@@ -99,6 +104,17 @@ export interface RunUsage {
      * emitting usage before this field existed still compiles; absent reads the same as zero.
      */
     cachedTokens?: number;
+    /**
+     * 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
+     * from a caller emitting usage of its own.
+     */
+    turn?: TurnReport;
+}
+/** One turn's usage and measurements as a `usage` event carries them. */
+export interface TurnReport extends TurnUsage {
+    /** Why the model stopped, as `Turn.finishReason` says it; `length` is a turn cut short. */
+    finishReason: string;
 }
 /**
  * One thing that happened in a run, as a watcher receives it.
@@ -209,3 +225,98 @@ export declare const resetEvents: () => void;
  * @param events Events in `seq` order, from `history` or collected from `watch`.
  */
 export declare function fold(events: RunEvent[]): RunEvent[];
+/** Why a turn's cache broke, as `TurnUsage.cacheBreakReason` names it. */
+type CacheBreakReason = NonNullable<TurnUsage["cacheBreakReason"]>;
+/**
+ * A run summed and derived from its events: what it cost, where the time went, and why.
+ *
+ * The counts are always there, zero when nothing happened. Every other field is absent where no
+ * turn reported what it is made of, and summed over the turns that did where only some did —
+ * a mean of a number a server never sent would be a number nobody measured.
+ */
+export interface RunMetrics {
+    /** The caller's own `step` events. */
+    steps: number;
+    /** Turns of the agent loop, one per `usage` report. */
+    turns: number;
+    /** Model requests, which is turns plus the continuations joined onto them. */
+    requests: number;
+    /** Tool results, `load_tools` included. */
+    toolCalls: number;
+    /** Tool results that came back not ok, by tool name. */
+    toolErrors: Record<string, number>;
+    /** `load_tools` calls. */
+    loadCalls: number;
+    /**
+     * Tools `load_tools` loaded that were not loaded already. Filled by `runAgentLoop`, which sees
+     * the resolution; the events carry only its text.
+     */
+    toolsLoaded?: number;
+    /** Tools the model asked `load_tools` for that it already had, filled the same way. */
+    redundantLoads?: number;
+    /** Names the model asked `load_tools` for that are in no catalogue, filled the same way. */
+    unknownToolNames?: number;
+    promptTokens: number;
+    completionTokens: number;
+    cachedTokens: number;
+    /** Summed over the turns that reported a cache count. */
+    uncachedTokens?: number;
+    reasoningTokens?: number;
+    /** Cached over prompt tokens, across only the turns that reported a cache count. */
+    cacheHitRatio?: number;
+    /** Turns whose cache fell short of what the turn before left it. */
+    cacheBreaks: number;
+    /** Those turns by what the loop changed. */
+    cacheBreakReasons: Partial<Record<CacheBreakReason, number>>;
+    /** Turns cut off at `maxTokens` after any continuation. */
+    truncatedTurns: number;
+    /** From the first event to the last, which a still-running run keeps moving. */
+    wallMs?: number;
+    /** Prefill time summed over the turns. */
+    promptMs?: number;
+    /** Decode time summed over the turns. */
+    predictedMs?: number;
+    /**
+     * Time from each tool call to its result, summed per call — so calls run in parallel can add up
+     * to more than the wall time they took.
+     */
+    toolMs?: number;
+    /** The longest any one turn took, retries and continuations in. */
+    slowestTurnMs?: number;
+    /** The mean time to first token over the turns that produced one. */
+    firstTokenMs?: number;
+    draftTotal?: number;
+    draftAccepted?: number;
+    /** Accepted over drafted. */
+    draftAcceptance?: number;
+    /** The biggest prompt any turn reported. */
+    largestPrompt?: number;
+    /** `largestPrompt` over the window `runMetrics` was told, for how close the run came. */
+    largestPromptShare?: number;
+    /**
+     * How it ended, read off `done` and the last turn: `truncated` is an answer the ceiling cut off.
+     * A failure does not say whether it was an error, a stop or the tool budget — that is in the
+     * host's own `done` text.
+     */
+    outcome?: "answered" | "truncated" | "failed";
+}
+/** What `runMetrics` takes besides the events. */
+export interface RunMetricsOptions {
+    /** The window the run was served, for `largestPromptShare`. Absent or zero leaves it out. */
+    contextLength?: number;
+}
+/**
+ * A run's totals, timings and cache findings, derived from the events it emitted.
+ *
+ * A sibling of `fold` rather than part of it. `fold` hands back events, and a client renders
+ * 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.
+ *
+ * @param events A run's events in `seq` order, from `history` or collected from `watch`. A backlog
+ * that has lost its oldest events to the cap sums what it still has.
+ * @param options The served window, for how full the run came to it.
+ */
+export declare function runMetrics(events: RunEvent[], { contextLength }?: RunMetricsOptions): RunMetrics;
+export {};

package/dist/events.js

@@ -1,14 +1,4 @@
-/**
- * What a run is doing, while it is doing it.
- *
- * A run row only exists as a before and an after: it is written when the agent starts and
- * updated when it stops, and everything in between — the thinking, the tool the model reached
- * for, the argument it got wrong — is gone by the time anyone can read it. This is that middle,
- * kept in memory and handed to whoever is watching.
- *
- * In memory on purpose: it is debugging output, worth nothing once the run has finished and its
- * outcome is in the database. Nothing here survives a restart, and nothing here is the record.
- */
+import { LOAD_TOOLS } from "./tool-loading.js";
 /** The numbers a run of the shape this bus was written for wants. */
 const DEFAULTS = {
     maxEvents: 1000,
@@ -348,3 +338,113 @@ export function fold(events) {
     close();
     return blocks;
 }
+/**
+ * A run's totals, timings and cache findings, derived from the events it emitted.
+ *
+ * A sibling of `fold` rather than part of it. `fold` hands back events, and a client renders
+ * 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.
+ *
+ * @param events A run's events in `seq` order, from `history` or collected from `watch`. A backlog
+ * that has lost its oldest events to the cap sums what it still has.
+ * @param options The served window, for how full the run came to it.
+ */
+export function runMetrics(events, { contextLength } = {}) {
+    const metrics = {
+        steps: 0,
+        turns: 0,
+        requests: 0,
+        toolCalls: 0,
+        toolErrors: {},
+        loadCalls: 0,
+        promptTokens: 0,
+        completionTokens: 0,
+        cachedTokens: 0,
+        cacheBreaks: 0,
+        cacheBreakReasons: {},
+        truncatedTurns: 0,
+    };
+    /** Adds to a field that is absent until something reports it. */
+    const add = (field, value) => {
+        if (value === undefined)
+            return;
+        const known = metrics;
+        known[field] = (known[field] ?? 0) + value;
+    };
+    let reportedPrompt = 0;
+    let reportedCached = 0;
+    let firstTokens = 0;
+    // Calls waiting for their results, by tool name, oldest first.
+    const pending = new Map();
+    let last;
+    for (const event of events) {
+        if (event.kind === "step")
+            metrics.steps++;
+        else if (event.kind === "tool-call") {
+            if (event.name === LOAD_TOOLS)
+                metrics.loadCalls++;
+            const waiting = pending.get(event.name) ?? [];
+            waiting.push(event.at);
+            pending.set(event.name, waiting);
+        }
+        else if (event.kind === "tool-result") {
+            metrics.toolCalls++;
+            if (event.ok === false)
+                metrics.toolErrors[event.name] = (metrics.toolErrors[event.name] ?? 0) + 1;
+            const called = pending.get(event.name)?.shift();
+            if (called !== undefined)
+                add("toolMs", event.at - called);
+        }
+        else if (event.kind === "usage" && event.usage?.turn) {
+            const turn = event.usage.turn;
+            last = turn;
+            metrics.turns++;
+            metrics.requests += 1 + (turn.continuations ?? 0);
+            metrics.promptTokens += turn.prompt;
+            metrics.completionTokens += turn.completion;
+            metrics.cachedTokens += turn.cached;
+            if (turn.uncached !== undefined) {
+                add("uncachedTokens", turn.uncached);
+                reportedPrompt += turn.prompt;
+                reportedCached += turn.cached;
+            }
+            add("reasoningTokens", turn.reasoningTokens);
+            add("promptMs", turn.promptMs);
+            add("predictedMs", turn.predictedMs);
+            add("draftTotal", turn.draftTotal);
+            add("draftAccepted", turn.draftAccepted);
+            if (turn.cacheBroken) {
+                metrics.cacheBreaks++;
+                const reason = turn.cacheBreakReason ?? "none-known";
+                metrics.cacheBreakReasons[reason] = (metrics.cacheBreakReasons[reason] ?? 0) + 1;
+            }
+            if (turn.finishReason === "length")
+                metrics.truncatedTurns++;
+            if (turn.wallMs !== undefined)
+                metrics.slowestTurnMs = Math.max(metrics.slowestTurnMs ?? 0, turn.wallMs);
+            if (turn.firstTokenMs !== undefined) {
+                add("firstTokenMs", turn.firstTokenMs);
+                firstTokens++;
+            }
+            if (turn.prompt > 0)
+                metrics.largestPrompt = Math.max(metrics.largestPrompt ?? 0, turn.prompt);
+        }
+        else if (event.kind === "done") {
+            metrics.outcome =
+                event.ok === false ? "failed" : last?.finishReason === "length" ? "truncated" : "answered";
+        }
+    }
+    if (events.length > 1)
+        metrics.wallMs = events[events.length - 1].at - events[0].at;
+    if (reportedPrompt > 0)
+        metrics.cacheHitRatio = reportedCached / reportedPrompt;
+    if (metrics.firstTokenMs !== undefined)
+        metrics.firstTokenMs /= firstTokens;
+    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;
+}