@cruxy/cli 1.0.2 → 1.0.3

package/dist/agent/loop.js

@@ -1,5 +1,6 @@
 import { CruxyError, providerUnsupported } from "../errors/index.js";
 import { resolveTaskModel, } from "../routing/index.js";
+import { accumulateCacheTokens } from "../usage/collect.js";
 import { buildSystemPrompt } from "./prompts.js";
 import { resolveShell } from "../tools/shell/resolve-shell.js";
 /** Tools whose successful call is a file change (drives the `on-file-change`
@@ -155,12 +156,14 @@ async function driveLoop(args, renderer, routed) {
                 case "usage":
                     usage.input_tokens = ev.usage.input_tokens || usage.input_tokens;
                     usage.output_tokens += ev.usage.output_tokens;
+                    accumulateCacheTokens(usage, ev.usage);
                     // Mirror the accumulation into the per-request figure the telemetry
                     // callback reports (same last-non-zero-in / summed-out semantics).
                     sawUsage = true;
                     reqUsage.input_tokens =
                         ev.usage.input_tokens || reqUsage.input_tokens;
                     reqUsage.output_tokens += ev.usage.output_tokens;
+                    accumulateCacheTokens(reqUsage, ev.usage);
                     break;
                 case "message_stop":
                     // Turn complete; the stream ends after this.

package/dist/agent/session.js

@@ -1,7 +1,7 @@
 import { randomUUID } from "node:crypto";
 import { loadProjectInstructions } from "../config/index.js";
 import { resolveTaskModel } from "../routing/index.js";
-import { UsageCollector, } from "../usage/index.js";
+import { UsageCollector, accumulateCacheTokens, } from "../usage/index.js";
 import { Budget } from "./budget.js";
 import { runAgent, } from "./loop.js";
 import { SUMMARY_SYSTEM, COMPACTION_MARKER } from "./prompts.js";
@@ -345,6 +345,7 @@ export class Session {
                 case "usage":
                     usage.input_tokens = ev.usage.input_tokens || usage.input_tokens;
                     usage.output_tokens += ev.usage.output_tokens;
+                    accumulateCacheTokens(usage, ev.usage);
                     sawUsage = true;
                     break;
                 case "error":

package/dist/theme/tokens.d.ts

@@ -43,6 +43,12 @@ export interface ThemeGlyphs {
     arrow: string;
     caretUp: string;
     caretDown: string;
+    /**
+     * Cache-hit marker for the usage line (`cached ↻N`). Decorative — the word
+     * "cached" carries the meaning, so it degrades to empty on ASCII / screen
+     * reader rather than a cryptic symbol.
+     */
+    cached: string;
     /** Text-cursor bar in the fuzzy query line. */
     cursorBar: string;
     bullet: string;

package/dist/theme/tokens.js

@@ -20,6 +20,7 @@ export const UNICODE_GLYPHS = {
     arrow: "→",
     caretUp: "↑",
     caretDown: "↓",
+    cached: "↻",
     cursorBar: "▏",
     bullet: "•",
     sep: "·",
@@ -42,6 +43,7 @@ export const ASCII_GLYPHS = {
     arrow: "->",
     caretUp: "^",
     caretDown: "v",
+    cached: "",
     cursorBar: "|",
     bullet: "*",
     sep: "-",
@@ -68,6 +70,7 @@ export const SCREEN_READER_GLYPHS = {
     arrow: "->",
     caretUp: "up",
     caretDown: "down",
+    cached: "",
     cursorBar: "",
     bullet: "-",
     sep: "-",

package/dist/usage/collect.d.ts

@@ -11,6 +11,19 @@ import type { UsageRecord } from "./types.js";
  * `Usage` and is stored as `0`. Nothing is estimated, re-tokenized, or
  * zero-filled, and this module makes ZERO network calls.
  */
+/**
+ * Fold a streamed {@link Usage} event's cache counters into an accumulator.
+ *
+ * Phase-A prompt caching (Anthropic dev path only) reports `cache_read_*` /
+ * `cache_creation_*` ONCE per request but echoes the same value on both the
+ * `message_start` and terminal `message_delta` usage events — so we ASSIGN
+ * (never `+=`) to avoid double-counting within a request. `undefined` is left
+ * untouched: a provider that doesn't cache (the cruxy gateway, OpenAI-compat)
+ * never sets these, so the accumulator's fields stay `undefined` — the honest
+ * "unknown", never a fabricated `0`. A real reported `0` (cache in play, no read
+ * this request) is captured as `0`.
+ */
+export declare function accumulateCacheTokens(acc: Usage, ev: Usage): void;
 /** What the loop hands over for one completed request. */
 export interface RequestUsage {
     /** The routing tier (C.30) the request ran on, if routing was active. */

package/dist/usage/collect.js

@@ -1,3 +1,32 @@
+/**
+ * Usage collection (C.22). Accumulates per-request usage exactly as the agent
+ * loop reports it — one {@link UsageEntry} per completed model request — and
+ * emits a {@link UsageRecord} for the run.
+ *
+ * The one honesty invariant: `usage: undefined` (the loop's signal that the
+ * provider returned NO usage event for a request) is recorded as `undefined`
+ * token counts — the honest "unknown". A provider-reported `0` arrives as a real
+ * `Usage` and is stored as `0`. Nothing is estimated, re-tokenized, or
+ * zero-filled, and this module makes ZERO network calls.
+ */
+/**
+ * Fold a streamed {@link Usage} event's cache counters into an accumulator.
+ *
+ * Phase-A prompt caching (Anthropic dev path only) reports `cache_read_*` /
+ * `cache_creation_*` ONCE per request but echoes the same value on both the
+ * `message_start` and terminal `message_delta` usage events — so we ASSIGN
+ * (never `+=`) to avoid double-counting within a request. `undefined` is left
+ * untouched: a provider that doesn't cache (the cruxy gateway, OpenAI-compat)
+ * never sets these, so the accumulator's fields stay `undefined` — the honest
+ * "unknown", never a fabricated `0`. A real reported `0` (cache in play, no read
+ * this request) is captured as `0`.
+ */
+export function accumulateCacheTokens(acc, ev) {
+    if (ev.cache_read_input_tokens !== undefined)
+        acc.cache_read_input_tokens = ev.cache_read_input_tokens;
+    if (ev.cache_creation_input_tokens !== undefined)
+        acc.cache_creation_input_tokens = ev.cache_creation_input_tokens;
+}
 const systemClock = () => new Date().toISOString();
 export class UsageCollector {
     now;
@@ -11,10 +40,20 @@ export class UsageCollector {
      * nothing. A real reported `0` is preserved as `0`.
      */
     record(req) {
+        const u = req.usage;
         this.entries.push({
             tier: req.tier,
-            inputTokens: req.usage?.input_tokens,
-            outputTokens: req.usage?.output_tokens,
+            inputTokens: u?.input_tokens,
+            outputTokens: u?.output_tokens,
+            // Cache counters are conditionally spread so an unreported field stays
+            // absent from the persisted entry (undefined ≠ 0) — only the Anthropic
+            // dev path ever populates them.
+            ...(u?.cache_read_input_tokens !== undefined
+                ? { cacheReadTokens: u.cache_read_input_tokens }
+                : {}),
+            ...(u?.cache_creation_input_tokens !== undefined
+                ? { cacheCreationTokens: u.cache_creation_input_tokens }
+                : {}),
             at: this.now(),
         });
     }

package/dist/usage/index.d.ts

@@ -9,7 +9,7 @@
  * ships nothing that sends. Asserted by the runtime + static no-phone-home tests.
  */
 export * from "./types.js";
-export { UsageCollector, type RequestUsage, type Clock } from "./collect.js";
+export { UsageCollector, accumulateCacheTokens, type RequestUsage, type Clock, } from "./collect.js";
 export { costFor, priceForTier } from "./cost.js";
 export { loadUsage, appendRun, usageStorePath } from "./store.js";
 export { summarizeRuns, renderSummary, formatCost, type SummarizeOptions, } from "./summary.js";

package/dist/usage/index.js

@@ -9,7 +9,7 @@
  * ships nothing that sends. Asserted by the runtime + static no-phone-home tests.
  */
 export * from "./types.js";
-export { UsageCollector } from "./collect.js";
+export { UsageCollector, accumulateCacheTokens, } from "./collect.js";
 export { costFor, priceForTier } from "./cost.js";
 export { loadUsage, appendRun, usageStorePath } from "./store.js";
 export { summarizeRuns, renderSummary, formatCost, } from "./summary.js";

package/dist/usage/summary.js

@@ -5,6 +5,8 @@ export function summarizeRuns(runs, opts) {
     const byTier = new Map();
     let totalInputTokens;
     let totalOutputTokens;
+    let totalCacheReadTokens;
+    let totalCacheCreationTokens;
     let requests = 0;
     let requestsWithoutUsage = 0;
     const addKnown = (acc, v) => (v === undefined ? acc : (acc ?? 0) + v);
@@ -16,6 +18,8 @@ export function summarizeRuns(runs, opts) {
                 requestsWithoutUsage++;
             totalInputTokens = addKnown(totalInputTokens, e.inputTokens);
             totalOutputTokens = addKnown(totalOutputTokens, e.outputTokens);
+            totalCacheReadTokens = addKnown(totalCacheReadTokens, e.cacheReadTokens);
+            totalCacheCreationTokens = addKnown(totalCacheCreationTokens, e.cacheCreationTokens);
             // Per-tier attribution only for entries that carry a tier. Untiered
             // requests (routing inert) still count toward totals — the total stays
             // honest — but there is no tier label to bucket them under.
@@ -29,6 +33,8 @@ export function summarizeRuns(runs, opts) {
                     b.requestsWithoutUsage++;
                 b.inputTokens = addKnown(b.inputTokens, e.inputTokens);
                 b.outputTokens = addKnown(b.outputTokens, e.outputTokens);
+                b.cacheReadTokens = addKnown(b.cacheReadTokens, e.cacheReadTokens);
+                b.cacheCreationTokens = addKnown(b.cacheCreationTokens, e.cacheCreationTokens);
                 byTier.set(e.tier, b);
             }
         }
@@ -37,6 +43,8 @@ export function summarizeRuns(runs, opts) {
         tier,
         inputTokens: b.inputTokens,
         outputTokens: b.outputTokens,
+        cacheReadTokens: b.cacheReadTokens,
+        cacheCreationTokens: b.cacheCreationTokens,
         requests: b.requests,
         requestsWithoutUsage: b.requestsWithoutUsage,
         cost: costFor(tier, b.inputTokens, b.outputTokens, opts.prices),
@@ -50,6 +58,8 @@ export function summarizeRuns(runs, opts) {
         perTier,
         totalInputTokens,
         totalOutputTokens,
+        totalCacheReadTokens,
+        totalCacheCreationTokens,
         totalCost,
         priced,
         currency: opts.currency,
@@ -106,6 +116,15 @@ export function renderSummary(summary, t) {
     parts.push(totalKnown
         ? `${t.strong("total")} ${tokenText(summary.totalInputTokens, summary.totalOutputTokens, t)}${t.muted(totalCost)}`
         : `${t.strong("total")} —`);
+    // Cache reads (phase-A caching, Anthropic dev path): shown ONLY when the
+    // provider actually reported cache usage — `undefined` on the cruxy gateway
+    // and every OpenAI-compat path, so normal users never see this segment. A
+    // reported 0 IS shown (`cached ↻0`): honest proof the counter is flowing,
+    // e.g. the first request of a run that writes the cache but reads nothing.
+    if (summary.totalCacheReadTokens !== undefined) {
+        const glyph = t.glyph.cached;
+        parts.push(t.muted(`cached ${glyph}${formatTokens(summary.totalCacheReadTokens)}`));
+    }
     // The honesty guard on display: a visible note whenever any request went
     // unreported, so the total above is never read as the whole story.
     if (summary.requestsWithoutUsage > 0) {

package/dist/usage/types.d.ts

@@ -22,6 +22,15 @@ export declare const UsageEntrySchema: z.ZodObject<{
     inputTokens: z.ZodOptional<z.ZodNumber>;
     /** Provider-reported completion tokens; `undefined` ⇔ no usage was reported. */
     outputTokens: z.ZodOptional<z.ZodNumber>;
+    /**
+     * Prompt-cache tokens READ from a warm cache (phase-A caching, Anthropic dev
+     * path). `undefined` ⇔ the provider doesn't cache / reported nothing (the
+     * cruxy gateway today) — never zero-filled. Optional, so older on-disk
+     * entries without the field still parse.
+     */
+    cacheReadTokens: z.ZodOptional<z.ZodNumber>;
+    /** Prompt-cache tokens WRITTEN this request (the ~1.25× write premium); same `undefined`-≠-0 rule. */
+    cacheCreationTokens: z.ZodOptional<z.ZodNumber>;
     /** ISO-8601 timestamp the request completed. */
     at: z.ZodString;
 }, "strict", z.ZodTypeAny, {
@@ -29,11 +38,15 @@ export declare const UsageEntrySchema: z.ZodObject<{
     tier?: string | undefined;
     inputTokens?: number | undefined;
     outputTokens?: number | undefined;
+    cacheReadTokens?: number | undefined;
+    cacheCreationTokens?: number | undefined;
 }, {
     at: string;
     tier?: string | undefined;
     inputTokens?: number | undefined;
     outputTokens?: number | undefined;
+    cacheReadTokens?: number | undefined;
+    cacheCreationTokens?: number | undefined;
 }>;
 export type UsageEntry = z.infer<typeof UsageEntrySchema>;
 /** One run's usage: an ordered list of per-request entries. */
@@ -51,6 +64,15 @@ export declare const UsageRecordSchema: z.ZodObject<{
         inputTokens: z.ZodOptional<z.ZodNumber>;
         /** Provider-reported completion tokens; `undefined` ⇔ no usage was reported. */
         outputTokens: z.ZodOptional<z.ZodNumber>;
+        /**
+         * Prompt-cache tokens READ from a warm cache (phase-A caching, Anthropic dev
+         * path). `undefined` ⇔ the provider doesn't cache / reported nothing (the
+         * cruxy gateway today) — never zero-filled. Optional, so older on-disk
+         * entries without the field still parse.
+         */
+        cacheReadTokens: z.ZodOptional<z.ZodNumber>;
+        /** Prompt-cache tokens WRITTEN this request (the ~1.25× write premium); same `undefined`-≠-0 rule. */
+        cacheCreationTokens: z.ZodOptional<z.ZodNumber>;
         /** ISO-8601 timestamp the request completed. */
         at: z.ZodString;
     }, "strict", z.ZodTypeAny, {
@@ -58,11 +80,15 @@ export declare const UsageRecordSchema: z.ZodObject<{
         tier?: string | undefined;
         inputTokens?: number | undefined;
         outputTokens?: number | undefined;
+        cacheReadTokens?: number | undefined;
+        cacheCreationTokens?: number | undefined;
     }, {
         at: string;
         tier?: string | undefined;
         inputTokens?: number | undefined;
         outputTokens?: number | undefined;
+        cacheReadTokens?: number | undefined;
+        cacheCreationTokens?: number | undefined;
     }>, "many">;
 }, "strict", z.ZodTypeAny, {
     entries: {
@@ -70,6 +96,8 @@ export declare const UsageRecordSchema: z.ZodObject<{
         tier?: string | undefined;
         inputTokens?: number | undefined;
         outputTokens?: number | undefined;
+        cacheReadTokens?: number | undefined;
+        cacheCreationTokens?: number | undefined;
     }[];
     runId: string;
     startedAt: string;
@@ -80,6 +108,8 @@ export declare const UsageRecordSchema: z.ZodObject<{
         tier?: string | undefined;
         inputTokens?: number | undefined;
         outputTokens?: number | undefined;
+        cacheReadTokens?: number | undefined;
+        cacheCreationTokens?: number | undefined;
     }[];
     runId: string;
     startedAt: string;
@@ -103,6 +133,15 @@ export declare const UsageFileSchema: z.ZodObject<{
             inputTokens: z.ZodOptional<z.ZodNumber>;
             /** Provider-reported completion tokens; `undefined` ⇔ no usage was reported. */
             outputTokens: z.ZodOptional<z.ZodNumber>;
+            /**
+             * Prompt-cache tokens READ from a warm cache (phase-A caching, Anthropic dev
+             * path). `undefined` ⇔ the provider doesn't cache / reported nothing (the
+             * cruxy gateway today) — never zero-filled. Optional, so older on-disk
+             * entries without the field still parse.
+             */
+            cacheReadTokens: z.ZodOptional<z.ZodNumber>;
+            /** Prompt-cache tokens WRITTEN this request (the ~1.25× write premium); same `undefined`-≠-0 rule. */
+            cacheCreationTokens: z.ZodOptional<z.ZodNumber>;
             /** ISO-8601 timestamp the request completed. */
             at: z.ZodString;
         }, "strict", z.ZodTypeAny, {
@@ -110,11 +149,15 @@ export declare const UsageFileSchema: z.ZodObject<{
             tier?: string | undefined;
             inputTokens?: number | undefined;
             outputTokens?: number | undefined;
+            cacheReadTokens?: number | undefined;
+            cacheCreationTokens?: number | undefined;
         }, {
             at: string;
             tier?: string | undefined;
             inputTokens?: number | undefined;
             outputTokens?: number | undefined;
+            cacheReadTokens?: number | undefined;
+            cacheCreationTokens?: number | undefined;
         }>, "many">;
     }, "strict", z.ZodTypeAny, {
         entries: {
@@ -122,6 +165,8 @@ export declare const UsageFileSchema: z.ZodObject<{
             tier?: string | undefined;
             inputTokens?: number | undefined;
             outputTokens?: number | undefined;
+            cacheReadTokens?: number | undefined;
+            cacheCreationTokens?: number | undefined;
         }[];
         runId: string;
         startedAt: string;
@@ -132,6 +177,8 @@ export declare const UsageFileSchema: z.ZodObject<{
             tier?: string | undefined;
             inputTokens?: number | undefined;
             outputTokens?: number | undefined;
+            cacheReadTokens?: number | undefined;
+            cacheCreationTokens?: number | undefined;
         }[];
         runId: string;
         startedAt: string;
@@ -145,6 +192,8 @@ export declare const UsageFileSchema: z.ZodObject<{
             tier?: string | undefined;
             inputTokens?: number | undefined;
             outputTokens?: number | undefined;
+            cacheReadTokens?: number | undefined;
+            cacheCreationTokens?: number | undefined;
         }[];
         runId: string;
         startedAt: string;
@@ -158,6 +207,8 @@ export declare const UsageFileSchema: z.ZodObject<{
             tier?: string | undefined;
             inputTokens?: number | undefined;
             outputTokens?: number | undefined;
+            cacheReadTokens?: number | undefined;
+            cacheCreationTokens?: number | undefined;
         }[];
         runId: string;
         startedAt: string;
@@ -191,6 +242,10 @@ export interface TierUsage {
     inputTokens?: number;
     /** Sum of KNOWN output tokens; `undefined` if none reported. */
     outputTokens?: number;
+    /** Sum of KNOWN cache-read tokens on this tier; `undefined` if none reported. */
+    cacheReadTokens?: number;
+    /** Sum of KNOWN cache-creation tokens on this tier; `undefined` if none reported. */
+    cacheCreationTokens?: number;
     /** Requests attributed to this tier. */
     requests: number;
     /** How many of those reported no usage (surfaced, never silently dropped). */
@@ -205,6 +260,14 @@ export interface UsageSummary {
     totalInputTokens?: number;
     /** Sum of KNOWN output tokens across all runs; `undefined` if none known. */
     totalOutputTokens?: number;
+    /**
+     * Sum of KNOWN cache-read tokens across all runs; `undefined` if none known
+     * (i.e. every request ran on a non-caching provider). Drives the `cached ↻N`
+     * figure, which is the observable proof that phase-A caching is working.
+     */
+    totalCacheReadTokens?: number;
+    /** Sum of KNOWN cache-creation tokens across all runs; `undefined` if none known. */
+    totalCacheCreationTokens?: number;
     /** Sum of per-tier costs; `undefined` unless ≥1 tier was priced. */
     totalCost?: number;
     /** True iff at least one tier had a configured price (cost is shown). */

package/dist/usage/types.js

@@ -22,6 +22,15 @@ export const UsageEntrySchema = z
     inputTokens: z.number().int().nonnegative().optional(),
     /** Provider-reported completion tokens; `undefined` ⇔ no usage was reported. */
     outputTokens: z.number().int().nonnegative().optional(),
+    /**
+     * Prompt-cache tokens READ from a warm cache (phase-A caching, Anthropic dev
+     * path). `undefined` ⇔ the provider doesn't cache / reported nothing (the
+     * cruxy gateway today) — never zero-filled. Optional, so older on-disk
+     * entries without the field still parse.
+     */
+    cacheReadTokens: z.number().int().nonnegative().optional(),
+    /** Prompt-cache tokens WRITTEN this request (the ~1.25× write premium); same `undefined`-≠-0 rule. */
+    cacheCreationTokens: z.number().int().nonnegative().optional(),
     /** ISO-8601 timestamp the request completed. */
     at: z.string(),
 })

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cruxy/cli",
-  "version": "1.0.2",
+  "version": "1.0.3",
   "description": "an agentic coding CLI",
   "type": "module",
   "bin": {