@aragon-agent/cli 0.6.3 → 0.6.7

package/dist/agent/reducer.d.ts

@@ -14,8 +14,9 @@ import type { AgentEvent, ModelCost, ToolResult, TokenUsage } from '@aragon-agen
 import type { AgentMode } from './agent-mode.js';
 import type { DispatchOutcome, SubagentRun, SubagentSpec, TeamSnapshot } from '../team/types.js';
 import type { FastReview, FastSnapshot } from '../fast/types.js';
-import type { CompactionMode, CompactionRecord, CompactionSnapshot, CompactionUiTrigger } from '../compaction/types.js';
+import type { CompactionMode, CompactionRecord, CompactionSnapshot, CompactionUiTrigger, ContextUsageSnapshot } from '../compaction/types.js';
 import type { TodoItem, TodoSnapshot } from '../todo/types.js';
+import type { ServiceSnapshot, ServiceStatus } from '../proc/types.js';
 import type { RetryPhase } from './retry-view.js';
 import type { FilePatch } from '../tools/patch.js';
 export type NoticeLevel = 'info' | 'warn' | 'error';
@@ -274,10 +275,70 @@ export type Entry = {
         charsRemoved: number;
     };
     live: boolean;
+}
+/**
+ * One supervised background service (background-service-supervision §3.10).
+ *
+ * JSON-SERIALIZABLE by construction, so `/save` needs no format change.
+ *
+ * IT IS THE ONE LIVE CARD THAT DOES **NOT** BLOCK THE SETTLED BOUNDARY ONCE IT
+ * IS UP (D-11 / P0-4). Every other live clause in
+ * `Transcript.tsx::computeSettledCount` is bounded by an OPERATION — a
+ * dispatch, a turn, one LLM call, one countdown — and each carries a comment
+ * saying that an entry which never settles is re-rendered on every frame for
+ * the rest of the session. A service is bounded by the USER'S INTENT: a dev
+ * server left up for an hour is the normal case. So only `starting` blocks
+ * (bounded by `readyTimeoutMs`), a `ready`/`running` card commits its body to
+ * `<Static>`, and a later terminal transition appends a NEW one-row entry
+ * rather than trying to rewrite a card `<Static>` has already printed.
+ *
+ * `terminal: true` marks that second entry. `session/persist.ts` rewrites any
+ * restored non-terminal card to `stopped`, next to `team.active`, `todo.live`,
+ * the retry phase, `fast.live` and `compaction.live`, and for the identical
+ * reason.
+ */
+ | {
+    id: string;
+    kind: 'service';
+    /** `s1`, `s2`, ... — the id the model quotes back. */
+    serviceId: string;
+    command: string;
+    status: ServiceStatus;
+    url?: string;
+    port?: number;
+    exitCode: number | null;
+    startedAt: number;
+    readyAt?: number;
+    endedAt?: number;
+    rows: readonly string[];
+    /**
+     * MONOTONIC row cursor — the revision term, NEVER `rows.length` (P0-3).
+     *
+     * The tail is a FIXED-SIZE RING: it evicts its oldest row while appending
+     * a new one, so the joined length is unchanged while the content is not.
+     * That is verbatim the non-append mutation the `tool` branch's `liveSeq`
+     * comment was written for, and a length term would go on matching while
+     * the card changed underneath it.
+     */
+    rowsSeen: number;
+    /** The one-row entry a terminal transition appends (D-11). */
+    terminal?: boolean;
+    /** The stop reported the pid still alive afterwards (R-2 / P2-6). */
+    killIncomplete?: boolean;
 };
 export interface UsageTotal {
     inputTokens: number;
     outputTokens: number;
+    /**
+     * Cache read hits (context-usage-gauge-accuracy §3.6 / P1-3).
+     *
+     * `occupiedTokens` counts them and `computeCost` PRICES them, so a session
+     * total that omits them makes the status bar's `^` read lower than the `$`
+     * next to it - on the same row, from the same turns. That was three units on
+     * one line, and this field plus its sibling are what collapse them to one.
+     */
+    cacheReadTokens: number;
+    cacheWriteTokens: number;
     costUsd: number;
 }
 /**
@@ -298,8 +359,20 @@ export interface ViewState {
     entries: Entry[];
     status: 'idle' | 'running';
     usageTotal: UsageTotal;
-    /** Running input size of the most recent turn vs. the model context window. */
-    contextTokens: number;
+    /**
+     * Context occupancy, as published by `AgentController`'s `ContextMeter`.
+     *
+     * ITS ONLY WRITER IS `case 'contextUsage'` (I-1), and that is the structural
+     * half of the P0-1 fix. It replaced `contextTokens` + `contextTokensEstimated`,
+     * which between them had THREE writing branches (`turnEnd`,
+     * `contextTokensEstimated`, `resetConversation`) fed by two competing
+     * upstreams. Two writers in one synchronous fan-out means the later one wins,
+     * and the later one was the stale `snapshot` carrying the PRE-compaction
+     * figure - so the bar fell and bounced straight back, every time, with nothing
+     * logging a fault. `context-one-writer.test.ts` scans this file to keep it
+     * that way.
+     */
+    context: ContextUsageSnapshot;
     overlay: Overlay;
     thinkingVisible: boolean;
     /** Ephemeral acks; auto-dismissed by App (spec §3.9). */
@@ -357,16 +430,6 @@ export interface ViewState {
      * totals. `null` is what leaves an ordinary session's status bar unchanged.
      */
     compaction: CompactionSnapshot | null;
-    /**
-     * Whether `contextTokens` is currently a DERIVED figure rather than a measured
-     * one (§6.2 / P1-11).
-     *
-     * Set by `compactionEnd`, cleared by the next `turnEnd`. The status bar widens
-     * its leading `~` to cover it: today `~` means "the window is a guess", and
-     * this makes it also mean "the occupancy is a guess". Honesty about a guess is
-     * cheaper than a support thread about a wrong percentage.
-     */
-    contextTokensEstimated: boolean;
     seq: number;
     /** The `kind: 'team'` entry the live dispatch is writing into. */
     teamEntryId?: string;
@@ -597,15 +660,35 @@ export type ViewAction = {
     snapshot: CompactionSnapshot;
 }
 /**
- * Overwrite the gauge with a DERIVED occupancy (§6.2).
+ * The occupancy reading, from `AgentController.subscribeContextUsage`.
+ *
+ * THE ONLY ACTION THAT WRITES `state.context`, AND IT IS DISPATCHED FROM
+ * EXACTLY ONE PLACE (I-1 / T11). It replaced `contextTokensEstimated`, which
+ * `App` fired from two branches of the compaction stream while `turnEnd` wrote
+ * the same field from the agent stream - three writers, two upstreams, one
+ * number, and the P0-1 bounce as the result.
+ */
+ | {
+    type: 'contextUsage';
+    snapshot: ContextUsageSnapshot;
+} | {
+    type: 'serviceStart';
+    service: ServiceSnapshot;
+} | {
+    type: 'serviceUpdate';
+    service: ServiceSnapshot;
+}
+/**
+ * A service reached a terminal state.
  *
- * Separate from `compactionEnd` because the value is not always available at
- * the same instant, and because the flag it sets — `contextTokensEstimated` —
- * has to be clearable by the next `turnEnd` independently.
+ * IT APPENDS A NEW ONE-ROW ENTRY rather than rewriting the card (D-11). The
+ * card may already have been printed into `<Static>`, and `<Static>` cannot
+ * un-print — so any design that rewrites a printed card is wrong whatever it
+ * claims. A second event at a second time is also simply more honest.
  */
  | {
-    type: 'contextTokensEstimated';
-    tokens: number;
+    type: 'serviceEnd';
+    service: ServiceSnapshot;
 };
 export declare const STORED_PREVIEW_CHARS = 8000;
 export declare const STORED_PREVIEW_LINES = 200;

package/dist/agent/reducer.js

@@ -11,11 +11,25 @@
  *     synthesizes a generic error notice (a swallowed throw is never a no-op).
  */
 import process from 'node:process';
-import { occupiedTokens } from '../compaction/pressure.js';
-import { computeCost } from './usage.js';
+import { emptyContextUsage } from '../compaction/meter.js';
+import { addUsage, computeCost } from './usage.js';
 import { ENTRY_LIMITS, appendBounded, entryRetain, trimEntries } from './entry-limits.js';
 /** Default auto-dismiss window for a toast. */
 export const DEFAULT_TOAST_TTL_MS = 2500;
+/**
+ * The zero session total.
+ *
+ * ONE LITERAL FOR TWO SITES (`initialViewState` and `resetConversation`). They
+ * used to spell the object out twice, which is how `cacheReadTokens` would have
+ * been added to one of them and not the other.
+ */
+const EMPTY_USAGE_TOTAL = {
+    inputTokens: 0,
+    outputTokens: 0,
+    cacheReadTokens: 0,
+    cacheWriteTokens: 0,
+    costUsd: 0,
+};
 /**
  * The initial view state, optionally seeded from config.
  *
@@ -33,8 +47,8 @@ export function initialViewState(seed = {}) {
     return {
         entries: [],
         status: 'idle',
-        usageTotal: { inputTokens: 0, outputTokens: 0, costUsd: 0 },
-        contextTokens: 0,
+        usageTotal: EMPTY_USAGE_TOTAL,
+        context: emptyContextUsage(),
         overlay: null,
         thinkingVisible: seed.thinkingVisible ?? false,
         toasts: [],
@@ -48,7 +62,6 @@ export function initialViewState(seed = {}) {
         retry: null,
         fast: null,
         compaction: null,
-        contextTokensEstimated: false,
         seq: 0,
         teamEntryId: undefined,
         todoEntryId: undefined,
@@ -610,22 +623,12 @@ export function viewReducer(state, action) {
                 ...state,
                 streamingId: undefined,
                 turnProduced: true,
-                // ONE FUNCTION, SHARED WITH THE COMPACTION TRIGGER (§3.4.1 / R-11 /
-                // AC-3). The old expression — `inputTokens + outputTokens` — silently
-                // UNDER-reports for anyone behind a caching gateway, because Anthropic
-                // reports `input_tokens` EXCLUDING cached tokens and puts them in two
-                // separate fields. That was a live defect in the number this gauge shows;
-                // it becomes a much worse one the moment a trigger fires on a different
-                // number from the one the user is watching.
-                contextTokens: occupiedTokens(action.usage),
-                // A MEASUREMENT SUPERSEDES A DERIVATION (§6.2). `compactionEnd` writes an
-                // estimate so the bar falls immediately; this is where it stops being one.
-                contextTokensEstimated: false,
-                usageTotal: {
-                    inputTokens: state.usageTotal.inputTokens + action.usage.inputTokens,
-                    outputTokens: state.usageTotal.outputTokens + action.usage.outputTokens,
-                    costUsd: state.usageTotal.costUsd + action.costDelta,
-                },
+                // `contextTokens` IS NOT WRITTEN HERE ANY MORE (I-1). The occupancy this
+                // turn produced reaches the view through `ContextMeter`, which subscribes
+                // to the same `turn_end` and publishes the measured pressure - window,
+                // percentage and approximation markers included, none of which this
+                // branch ever had. Two branches writing one number is what P0-1 was.
+                usageTotal: addUsage(state.usageTotal, action.usage, action.costDelta),
                 // The turn produced an answer, so whatever it had to retry, it recovered.
                 ...settleRetryCard(state, entries, 'recovered'),
             };
@@ -763,8 +766,13 @@ export function viewReducer(state, action) {
                 droppedEntries: 0,
                 streamingId: undefined,
                 expandedToolIds: {},
-                contextTokens: 0,
-                usageTotal: { inputTokens: 0, outputTokens: 0, costUsd: 0 },
+                // `context` IS DELIBERATELY UNTOUCHED (I-1). `builtins.ts` calls
+                // `controller.clearMessages()` BEFORE dispatching this, and that marks
+                // the meter dirty and schedules a publication; zeroing here would make
+                // the final state `0` rather than the meter's real answer - which for an
+                // emptied conversation is the system prompt's own couple of percent, not
+                // nothing. `usageTotal` DOES reset: that is session spend, not occupancy.
+                usageTotal: EMPTY_USAGE_TOTAL,
                 teamEntryId: undefined,
                 // `/reset` clears `messages`, so the belief is gone and the list goes
                 // with it — the other half of I-2. `controller.clearMessages()` clears
@@ -774,10 +782,6 @@ export function viewReducer(state, action) {
                 retryEntryId: undefined,
                 retry: null,
                 compactionEntryId: undefined,
-                // `contextTokens` is zeroed above, so the flag that says it is a
-                // DERIVATION has to go with it — otherwise a fresh conversation renders
-                // `~0%` and the tilde is a lie about a number that is simply zero.
-                contextTokensEstimated: false,
             };
         case 'setOverlay':
             return { ...state, overlay: action.overlay };
@@ -860,18 +864,11 @@ export function viewReducer(state, action) {
         }
         case 'teamUsage':
             // `usageTotal` AND NOTHING ELSE (§3.9 / AC-15). In particular NOT
-            // `contextTokens`: that gauge shows the LEAD's context occupancy against
+            // `context`: that gauge shows the LEAD's context occupancy against
             // the model's window, and folding five children into it would read 180%
             // on a perfectly healthy session. Child spend is real money and has to
             // appear in the cost readout; it is not the lead's context.
-            return {
-                ...state,
-                usageTotal: {
-                    inputTokens: state.usageTotal.inputTokens + action.usage.inputTokens,
-                    outputTokens: state.usageTotal.outputTokens + action.usage.outputTokens,
-                    costUsd: state.usageTotal.costUsd + action.costDelta,
-                },
-            };
+            return { ...state, usageTotal: addUsage(state.usageTotal, action.usage, action.costDelta) };
         case 'teamEnd': {
             const { outcome } = action;
             const entries = state.teamEntryId
@@ -991,20 +988,19 @@ export function viewReducer(state, action) {
         }
         case 'fastUsage':
             // `usageTotal` AND NOTHING ELSE, exactly as `teamUsage` (§3.6 / AC-18). In
-            // particular NOT `contextTokens`: that gauge shows the LEAD's context
+            // particular NOT `context`: that gauge shows the LEAD's context
             // occupancy against the lead model's window, and a review is a separate
             // conversation with a different model entirely.
-            return {
-                ...state,
-                usageTotal: {
-                    inputTokens: state.usageTotal.inputTokens + action.usage.inputTokens,
-                    outputTokens: state.usageTotal.outputTokens + action.usage.outputTokens,
-                    costUsd: state.usageTotal.costUsd + action.costDelta,
-                },
-            };
+            return { ...state, usageTotal: addUsage(state.usageTotal, action.usage, action.costDelta) };
         case 'fastTier':
             return { ...state, fast: action.snapshot };
         // --- Context compaction (context-auto-compaction §5.5) ----------------
+        // NOT A TOTAL FUNCTION OVER COMPACTION ATTEMPTS (quiet-noop §3.1). A
+        // `pressure` compaction that declines before calling a model or changing the
+        // history dispatches NOTHING - no `compactionStart`, no `compactionEnd`, no
+        // entry - exactly as a checkpoint below the threshold dispatches nothing.
+        // Counting cards here counts compactions that RAN, never checkpoints that
+        // fired; `/compact status` and the diagnostic log are where the attempts are.
         case 'compactionStart': {
             const { id, seq } = nextId(state);
             let entries = state.entries;
@@ -1122,40 +1118,41 @@ export function viewReducer(state, action) {
         }
         case 'compactionUsage':
             // `usageTotal` AND NOTHING ELSE, exactly as `teamUsage` and `fastUsage`. In
-            // particular NOT `contextTokens`: that gauge shows the LEAD's context
+            // particular NOT `context`: that gauge shows the LEAD's context
             // occupancy against the lead model's window, and a summarization is a
             // separate conversation with a possibly different model entirely.
-            return {
-                ...state,
-                usageTotal: {
-                    inputTokens: state.usageTotal.inputTokens + action.usage.inputTokens,
-                    outputTokens: state.usageTotal.outputTokens + action.usage.outputTokens,
-                    costUsd: state.usageTotal.costUsd + action.costDelta,
-                },
-            };
+            return { ...state, usageTotal: addUsage(state.usageTotal, action.usage, action.costDelta) };
         case 'compactionSnapshot':
             return { ...state, compaction: action.snapshot };
         /**
-         * THE GAUGE MUST FALL IMMEDIATELY (§6.2 / AC-5).
+         * THE ONE WRITER OF `state.context` (I-1).
          *
-         * `contextTokens` is otherwise only written at `turnEnd`, so a compaction
-         * that took the session from 92 % to 24 % would leave the bar at 92 % until
-         * the next turn completes — and the user would reasonably conclude that
-         * nothing happened. This is a small change and it is the difference between
-         * the feature feeling real and feeling broken.
+         * THE IDENTITY SHORT-CIRCUIT BELOW IS LOAD-BEARING, NOT A MICRO-OPTIMISATION
+         * (§5.2 / R-3). The meter publishes on a 400 ms tick throughout a turn and
+         * most of those ticks measure the same number - the history did not change
+         * between two tool calls of the same size, or the percentage rounded to the
+         * same integer. Returning the SAME state object lets React skip the whole
+         * subtree; returning a fresh one would make a permanently visible row into a
+         * 2.5 Hz re-render source and walk the render governor up its ladder for no
+         * visible change at all.
          *
-         * The value arrives ALREADY CALIBRATED from `App` (§6.2 / P1-11): it replaces
-         * a MEASUREMENT that included the tool schemas, and core's raw estimator
-         * never counts them, so writing the raw figure would make the bar fall too
-         * far and then visibly climb again on the next `turn_end` for no reason the
-         * user can see.
+         * `ContextUsageSnapshot` carries no timestamp for exactly this reason: a
+         * field that moves every tick would make this comparison never hold.
          */
-        case 'contextTokensEstimated':
-            return {
-                ...state,
-                contextTokens: Math.max(0, Math.round(action.tokens)),
-                contextTokensEstimated: true,
-            };
+        case 'contextUsage': {
+            const prev = state.context;
+            const next = action.snapshot;
+            if (prev.occupied === next.occupied &&
+                prev.window === next.window &&
+                prev.pct === next.pct &&
+                prev.source === next.source &&
+                prev.deltaTokens === next.deltaTokens &&
+                prev.windowKnown === next.windowKnown &&
+                prev.windowOverridden === next.windowOverridden) {
+                return state;
+            }
+            return { ...state, context: next };
+        }
         // --- API retry (llm-api-retry-backoff §6.4) ---------------------------
         case 'retryScheduled': {
             const snapshot = {
@@ -1317,10 +1314,104 @@ export function viewReducer(state, action) {
                 fastEntryId: undefined,
             };
         }
+        // --- Background services (§3.10 / D-11) -----------------------------
+        case 'serviceStart': {
+            const { id, seq } = nextId(state);
+            const entry = { id, ...serviceFields(action.service) };
+            const appended = appendEntry(state, state.entries, entry);
+            return {
+                ...state,
+                seq,
+                entries: appended.entries,
+                droppedEntries: appended.droppedEntries,
+            };
+        }
+        /**
+         * Rewrite the LIVE card in place.
+         *
+         * SAFE ONLY BECAUSE OF D-11'S OTHER HALF: a `ready` / `running` card has
+         * reached `<Static>` and cannot be re-printed, so `serviceEnd` appends a new
+         * entry instead of routing through here. What this handles is the window in
+         * which the card is still in the live region — `starting`, and the one
+         * transition out of it — plus the output tail while it is there.
+         *
+         * The lookup is by `serviceId` and SKIPS terminal entries, so a stray update
+         * cannot rewrite the one-row record `serviceEnd` appended.
+         */
+        case 'serviceUpdate': {
+            const target = findServiceEntryId(state, action.service.id);
+            if (!target)
+                return state;
+            return {
+                ...state,
+                entries: mapEntry(state.entries, target, (e) => e.kind === 'service' ? { ...e, ...serviceFields(action.service) } : e),
+            };
+        }
+        /**
+         * A service reached a terminal state.
+         *
+         * TWO WRITES, AND BOTH ARE REQUIRED. The live card is settled in place so
+         * `computeSettledCount` can move past it and `estimateEntryRows` stops
+         * charging for a tail nothing will add to; the NEW one-row entry is what the
+         * user actually reads, because the card may already be printed into
+         * `<Static>` and `<Static>` cannot un-print (D-11 / R-13).
+         */
+        case 'serviceEnd': {
+            const target = findServiceEntryId(state, action.service.id);
+            const settled = target
+                ? mapEntry(state.entries, target, (e) => e.kind === 'service' ? { ...e, ...serviceFields(action.service) } : e)
+                : state.entries;
+            const { id, seq } = nextId(state);
+            const appended = appendEntry(state, settled, {
+                id,
+                ...serviceFields(action.service),
+                terminal: true,
+            });
+            return {
+                ...state,
+                seq,
+                entries: appended.entries,
+                droppedEntries: appended.droppedEntries,
+            };
+        }
         default:
             return state;
     }
 }
+/**
+ * Project a supervisor snapshot onto the entry's own fields.
+ *
+ * ONE PROJECTION FOR ALL THREE ACTIONS, so a field that reaches the card through
+ * `serviceStart` can never fail to reach it through `serviceUpdate` — the kind of
+ * asymmetry that produces a card frozen at its first values with nothing
+ * reporting it.
+ */
+function serviceFields(service) {
+    return {
+        kind: 'service',
+        serviceId: service.id,
+        command: service.command,
+        status: service.status,
+        ...(service.url !== undefined ? { url: service.url } : {}),
+        ...(service.port !== undefined ? { port: service.port } : {}),
+        exitCode: service.exitCode,
+        startedAt: service.startedAt,
+        ...(service.readyAt !== undefined ? { readyAt: service.readyAt } : {}),
+        ...(service.endedAt !== undefined ? { endedAt: service.endedAt } : {}),
+        rows: service.rows,
+        rowsSeen: service.rowsSeen,
+        ...(service.killIncomplete ? { killIncomplete: true } : {}),
+    };
+}
+/** The LIVE card for a service id, newest first; terminal records are skipped. */
+function findServiceEntryId(state, serviceId) {
+    for (let i = state.entries.length - 1; i >= 0; i -= 1) {
+        const e = state.entries[i];
+        if (e && e.kind === 'service' && e.serviceId === serviceId && !e.terminal)
+            return e.id;
+    }
+    return undefined;
+}
 function safeStringify(value) {
     try {
         return JSON.stringify(value);

package/dist/agent/system-prompt.d.ts

@@ -88,6 +88,20 @@ export interface SystemPromptParams {
      * for a fixed `tools` array. Every existing caller passes nothing.
      */
     appendSystemPrompt?: string;
+    /**
+     * The rendered `<background_services>` block, or `''`
+     * (background-service-supervision §5.2).
+     *
+     * Spliced conditionally exactly as `skillsBlock`, the plan block, `teamBlock`,
+     * `todoBlock` and `fastBlock` are, which is what keeps I-2 true:
+     * `bash.background: false` produces the pre-feature prompt BYTE FOR BYTE for a
+     * fixed tool array.
+     *
+     * A CHILD'S PROMPT NEVER CARRIES IT: subagents build tools from the same
+     * factory but are given no supervisor, so telling one about `bash_output` /
+     * `bash_kill` would describe tools it does not have.
+     */
+    backgroundBlock?: string;
 }
 /** Describe the active shell so the model does not emit incompatible syntax. */
 export declare function describeShell(): {

package/dist/agent/system-prompt.js

@@ -41,6 +41,7 @@ export function buildSystemPrompt(params) {
     const subagentBlock = params.subagentBlock ?? '';
     const todoBlock = params.todoBlock ?? '';
     const fastBlock = params.fastBlock ?? '';
+    const backgroundBlock = params.backgroundBlock ?? '';
     const appended = (params.appendSystemPrompt ?? '').trim();
     return [
         'You are AragonAgent, an autonomous coding assistant operating inside a terminal (TUI).',
@@ -59,6 +60,7 @@ export function buildSystemPrompt(params) {
         ...(subagentBlock ? ['', subagentBlock] : []),
         ...(todoBlock ? ['', todoBlock] : []),
         ...(fastBlock ? ['', fastBlock] : []),
+        ...(backgroundBlock ? ['', backgroundBlock] : []),
         '',
         'Operating guidance:',
         '- Prefer reading files and inspecting the workspace before making changes.',

package/dist/agent/usage.d.ts

@@ -3,8 +3,42 @@
  * (which is expressed in USD per 1M tokens). See spec §6.2 status bar.
  */
 import type { ModelCost, TokenUsage } from '@aragon-agent/core';
+import type { UsageTotal } from './reducer.js';
 /** Compute the USD cost of a single `TokenUsage` given a model's cost table. */
 export declare function computeCost(usage: TokenUsage, cost?: ModelCost): number;
+/**
+ * Fold one `TokenUsage` into a running session total
+ * (context-usage-gauge-accuracy §3.6 / W5).
+ *
+ * THE ONE ADDITION SITE, and collapsing four hand-written copies into it is the
+ * point rather than a tidy-up. The reducer had the same three lines in four
+ * branches - `turnEnd`, `teamUsage`, `fastUsage`, `compactionUsage` - and all
+ * four silently omitted the cache terms, so the status bar's `^` read LOWER than
+ * the `$` beside it on any session behind a caching gateway. A fifth source
+ * added later would have made the identical omission; now it cannot.
+ *
+ * `costDelta` IS PRECOMPUTED BY THE CALLER, exactly as the four branches already
+ * required: the summarizer and the fast tier may be different models with
+ * different price tables, and a reducer that priced its own would have to know
+ * about three of them.
+ */
+export declare function addUsage(total: UsageTotal, usage: TokenUsage, costDelta: number): UsageTotal;
+/**
+ * The number the status bar's `^` shows: the PROMPT side of the session total.
+ *
+ * DELIBERATELY THE SAME TERMS AS `occupiedTokens` MINUS `outputTokens`
+ * (`compaction/pressure.ts`). Anthropic reports `input_tokens` EXCLUDING cached
+ * tokens and puts them in two separate fields, so `inputTokens` alone
+ * under-reports for anyone behind a caching gateway - while `computeCost` above
+ * has always priced all three. That is the "three units on one row" defect
+ * (P1-3): the percentage counted cache, the dollars counted cache, and the arrow
+ * did not.
+ *
+ * `$` IS STILL NOT THE SAME TOTAL, and the distinction is worth keeping straight
+ * (RV-14): `computeCost` also prices OUTPUT tokens. What this function asserts is
+ * narrower and exact - both cache terms are counted, on both sides.
+ */
+export declare function promptTokensOf(total: UsageTotal): number;
 /** Format a USD amount for the status bar (`$0.0000`, or `$1.23` when large). */
 export declare function formatCost(usd: number): string;
 /** Format a token count compactly (`1.2k`, `3.4M`). */

package/dist/agent/usage.js

@@ -12,6 +12,49 @@ export function computeCost(usage, cost) {
         perM(usage.cacheReadTokens ?? 0, cost.cacheRead) +
         perM(usage.cacheWriteTokens ?? 0, cost.cacheWrite));
 }
+/**
+ * Fold one `TokenUsage` into a running session total
+ * (context-usage-gauge-accuracy §3.6 / W5).
+ *
+ * THE ONE ADDITION SITE, and collapsing four hand-written copies into it is the
+ * point rather than a tidy-up. The reducer had the same three lines in four
+ * branches - `turnEnd`, `teamUsage`, `fastUsage`, `compactionUsage` - and all
+ * four silently omitted the cache terms, so the status bar's `^` read LOWER than
+ * the `$` beside it on any session behind a caching gateway. A fifth source
+ * added later would have made the identical omission; now it cannot.
+ *
+ * `costDelta` IS PRECOMPUTED BY THE CALLER, exactly as the four branches already
+ * required: the summarizer and the fast tier may be different models with
+ * different price tables, and a reducer that priced its own would have to know
+ * about three of them.
+ */
+export function addUsage(total, usage, costDelta) {
+    return {
+        inputTokens: total.inputTokens + usage.inputTokens,
+        outputTokens: total.outputTokens + usage.outputTokens,
+        cacheReadTokens: total.cacheReadTokens + (usage.cacheReadTokens ?? 0),
+        cacheWriteTokens: total.cacheWriteTokens + (usage.cacheWriteTokens ?? 0),
+        costUsd: total.costUsd + costDelta,
+    };
+}
+/**
+ * The number the status bar's `^` shows: the PROMPT side of the session total.
+ *
+ * DELIBERATELY THE SAME TERMS AS `occupiedTokens` MINUS `outputTokens`
+ * (`compaction/pressure.ts`). Anthropic reports `input_tokens` EXCLUDING cached
+ * tokens and puts them in two separate fields, so `inputTokens` alone
+ * under-reports for anyone behind a caching gateway - while `computeCost` above
+ * has always priced all three. That is the "three units on one row" defect
+ * (P1-3): the percentage counted cache, the dollars counted cache, and the arrow
+ * did not.
+ *
+ * `$` IS STILL NOT THE SAME TOTAL, and the distinction is worth keeping straight
+ * (RV-14): `computeCost` also prices OUTPUT tokens. What this function asserts is
+ * narrower and exact - both cache terms are counted, on both sides.
+ */
+export function promptTokensOf(total) {
+    return total.inputTokens + total.cacheReadTokens + total.cacheWriteTokens;
+}
 /** Format a USD amount for the status bar (`$0.0000`, or `$1.23` when large). */
 export function formatCost(usd) {
     if (usd <= 0)