@cruxy/cli 1.0.0 → 1.0.3

package/README.md

@@ -161,7 +161,7 @@ branch on them:
 | `5`  | network    | `CRUXY_E_GATEWAY_UNREACHABLE`, `CRUXY_E_GIT_PUSH_FAILED`                                                                                                                                             |
 | `6`  | api        | `CRUXY_E_API`, `CRUXY_E_API_RATE_LIMIT`, `CRUXY_E_API_OVERLOADED`, `CRUXY_E_BUDGET_EXHAUSTED`, `CRUXY_E_FORGE_API`                                                                                   |
 | `7`  | filesystem | `CRUXY_E_FILE_NOT_FOUND`, `CRUXY_E_PERMISSION_DENIED`, `CRUXY_E_PATH_ESCAPE`, `CRUXY_E_CHECKPOINT_FAILED`                                                                                            |
-| `8`  | index      | `CRUXY_E_INDEX_EMBEDDER_UNAVAILABLE`, `CRUXY_E_INDEX_STORE_UNAVAILABLE`, `CRUXY_E_INDEX_FAILED`                                                                                                      |
+| `8`  | index      | `CRUXY_E_INDEX_EMBEDDER_UNAVAILABLE`, `CRUXY_E_INDEX_EMBEDDER_DOWNLOAD_FAILED`, `CRUXY_E_INDEX_STORE_UNAVAILABLE`, `CRUXY_E_INDEX_FAILED`                                                            |
 | `9`  | skill      | `CRUXY_E_SKILL_INVALID`, `CRUXY_E_SKILL_NOT_FOUND`                                                                                                                                                   |
 | `10` | approval   | `CRUXY_E_APPROVAL_REQUIRED`, `CRUXY_E_PLAN_APPROVAL_REQUIRED`, `CRUXY_E_ROLLBACK_APPROVAL_REQUIRED`                                                                                                  |
 

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/cli/commands/usage.js

@@ -44,8 +44,15 @@ export function usageCommand() {
         logger.print(t.heading(`usage — ${scopeLabel}`));
         logger.print(renderSummary(summary, t));
         // State when NO price is configured, so an absent cost never reads as $0.
+        // Self-contained: set a number, see cost — copy-pasteable commands, no
+        // docs lookup and no jargon needed.
         if (!summary.priced) {
-            logger.print(t.muted("cost omitted — no prices configured (set usage.prices.<tier>.{input,output}, per million tokens)"));
+            logger.print(t.muted([
+                "cost omitted — no prices set. To see cost, set your per-million-token",
+                "rates for each tier (kavi, vaani, mira):",
+                "  cruxy config set usage.prices.kavi.input 0.5",
+                "  cruxy config set usage.prices.kavi.output 1.5",
+            ].join("\n")));
         }
     });
 }

package/dist/config/schema.d.ts

@@ -185,15 +185,30 @@ export declare const IndexConfigSchema: z.ZodObject<{
     /**
      * Embedding backend. Only `fastembed` (bge-small-en-v1.5, local ONNX; the
      * model downloads and caches on first use) is selectable — if it cannot be
-     * loaded, indexing fails loudly rather than degrading. (The deterministic
-     * hashing embedder exists for tests and is injected directly, never chosen
-     * here.)
+     * loaded, or the model cannot be downloaded/initialized, indexing fails
+     * loudly rather than degrading. (The deterministic hashing embedder exists
+     * for tests and is injected directly, never chosen here.)
+     *
+     * THE STORE-VS-EMBEDDER ASYMMETRY (deliberate — see `store` below). The
+     * embedder has NO degrade path while the store's `auto` does, and that is
+     * correct, not an inconsistency: a store fallback (sqlite → in-memory) loses
+     * only PERSISTENCE — search results are byte-identical, you just re-index
+     * each session, a quality-NEUTRAL trade. The embedder's only cheaper
+     * substitute is the lexical hashing backend, whose degrade is a SILENT
+     * QUALITY LOSS — semantic search quietly stops being semantic. That is the
+     * "reads like success, isn't" trap C.17 forbids, so the embedder fails loud
+     * (module-load → CRUXY_E_INDEX_EMBEDDER_UNAVAILABLE; first-run download/init
+     * → CRUXY_E_INDEX_EMBEDDER_DOWNLOAD_FAILED) and `search_codebase` routes the
+     * model to `grep_files` rather than substituting a weaker index.
      */
     embedder: z.ZodDefault<z.ZodEnum<["fastembed"]>>;
     /**
      * Vector store backend. `sqlite` persists to `.cruxy/index.db` via
      * better-sqlite3; `memory` is ephemeral (tests). `auto` prefers sqlite and
-     * falls back to memory when the native dependency cannot be loaded.
+     * falls back to memory when the native dependency cannot be loaded — a
+     * quality-NEUTRAL degrade (only persistence is lost; results are identical).
+     * This is why `auto` may degrade while `embedder` may not — see the
+     * asymmetry note above.
      */
     store: z.ZodDefault<z.ZodEnum<["auto", "sqlite", "memory"]>>;
     /** Hard per-file size cap, in bytes; larger files are skipped entirely. */
@@ -1184,15 +1199,30 @@ export declare const CruxyConfigSchema: z.ZodObject<{
         /**
          * Embedding backend. Only `fastembed` (bge-small-en-v1.5, local ONNX; the
          * model downloads and caches on first use) is selectable — if it cannot be
-         * loaded, indexing fails loudly rather than degrading. (The deterministic
-         * hashing embedder exists for tests and is injected directly, never chosen
-         * here.)
+         * loaded, or the model cannot be downloaded/initialized, indexing fails
+         * loudly rather than degrading. (The deterministic hashing embedder exists
+         * for tests and is injected directly, never chosen here.)
+         *
+         * THE STORE-VS-EMBEDDER ASYMMETRY (deliberate — see `store` below). The
+         * embedder has NO degrade path while the store's `auto` does, and that is
+         * correct, not an inconsistency: a store fallback (sqlite → in-memory) loses
+         * only PERSISTENCE — search results are byte-identical, you just re-index
+         * each session, a quality-NEUTRAL trade. The embedder's only cheaper
+         * substitute is the lexical hashing backend, whose degrade is a SILENT
+         * QUALITY LOSS — semantic search quietly stops being semantic. That is the
+         * "reads like success, isn't" trap C.17 forbids, so the embedder fails loud
+         * (module-load → CRUXY_E_INDEX_EMBEDDER_UNAVAILABLE; first-run download/init
+         * → CRUXY_E_INDEX_EMBEDDER_DOWNLOAD_FAILED) and `search_codebase` routes the
+         * model to `grep_files` rather than substituting a weaker index.
          */
         embedder: z.ZodDefault<z.ZodEnum<["fastembed"]>>;
         /**
          * Vector store backend. `sqlite` persists to `.cruxy/index.db` via
          * better-sqlite3; `memory` is ephemeral (tests). `auto` prefers sqlite and
-         * falls back to memory when the native dependency cannot be loaded.
+         * falls back to memory when the native dependency cannot be loaded — a
+         * quality-NEUTRAL degrade (only persistence is lost; results are identical).
+         * This is why `auto` may degrade while `embedder` may not — see the
+         * asymmetry note above.
          */
         store: z.ZodDefault<z.ZodEnum<["auto", "sqlite", "memory"]>>;
         /** Hard per-file size cap, in bytes; larger files are skipped entirely. */

package/dist/config/schema.js

@@ -146,15 +146,30 @@ export const IndexConfigSchema = z
     /**
      * Embedding backend. Only `fastembed` (bge-small-en-v1.5, local ONNX; the
      * model downloads and caches on first use) is selectable — if it cannot be
-     * loaded, indexing fails loudly rather than degrading. (The deterministic
-     * hashing embedder exists for tests and is injected directly, never chosen
-     * here.)
+     * loaded, or the model cannot be downloaded/initialized, indexing fails
+     * loudly rather than degrading. (The deterministic hashing embedder exists
+     * for tests and is injected directly, never chosen here.)
+     *
+     * THE STORE-VS-EMBEDDER ASYMMETRY (deliberate — see `store` below). The
+     * embedder has NO degrade path while the store's `auto` does, and that is
+     * correct, not an inconsistency: a store fallback (sqlite → in-memory) loses
+     * only PERSISTENCE — search results are byte-identical, you just re-index
+     * each session, a quality-NEUTRAL trade. The embedder's only cheaper
+     * substitute is the lexical hashing backend, whose degrade is a SILENT
+     * QUALITY LOSS — semantic search quietly stops being semantic. That is the
+     * "reads like success, isn't" trap C.17 forbids, so the embedder fails loud
+     * (module-load → CRUXY_E_INDEX_EMBEDDER_UNAVAILABLE; first-run download/init
+     * → CRUXY_E_INDEX_EMBEDDER_DOWNLOAD_FAILED) and `search_codebase` routes the
+     * model to `grep_files` rather than substituting a weaker index.
      */
     embedder: z.enum(["fastembed"]).default("fastembed"),
     /**
      * Vector store backend. `sqlite` persists to `.cruxy/index.db` via
      * better-sqlite3; `memory` is ephemeral (tests). `auto` prefers sqlite and
-     * falls back to memory when the native dependency cannot be loaded.
+     * falls back to memory when the native dependency cannot be loaded — a
+     * quality-NEUTRAL degrade (only persistence is lost; results are identical).
+     * This is why `auto` may degrade while `embedder` may not — see the
+     * asymmetry note above.
      */
     store: z.enum(["auto", "sqlite", "memory"]).default("auto"),
     /** Hard per-file size cap, in bytes; larger files are skipped entirely. */

package/dist/errors/constructors.d.ts

@@ -41,6 +41,22 @@ export declare function budgetExhausted(underlying?: unknown): CruxyError;
 export declare function fileNotFound(path: string, underlying?: unknown): CruxyError;
 export declare function permissionDenied(path: string, underlying?: unknown): CruxyError;
 export declare function indexEmbedderUnavailable(underlying?: unknown): CruxyError;
+/**
+ * The fastembed module loaded, but the model could not be brought up at runtime
+ * — the first-run download/decompress of bge-small-en-v1.5, or the ONNX-runtime
+ * init, failed. This is the COMMON first-run failure (offline, the model bucket
+ * is unreachable, a corporate proxy blocks it), and it is deliberately kept
+ * distinct from both {@link indexEmbedderUnavailable} (a module *load* failure)
+ * and the generic {@link indexFailed} ("re-run --verbose") so the cause is
+ * actionable rather than a shrug.
+ *
+ * Fail-loud, not degrade: there is no fallback to the lexical hashing embedder
+ * (a silent quality loss). `cruxy index` treats this as fatal — the user
+ * explicitly asked to build the index, so a silent no-op index would be the
+ * exact "reads like success, isn't" trap C.17 forbids. The `search_codebase`
+ * tool instead surfaces it as a tool error and points the model at `grep_files`.
+ */
+export declare function indexEmbedderDownloadFailed(underlying?: unknown): CruxyError;
 export declare function indexStoreUnavailable(underlying?: unknown): CruxyError;
 export declare function indexFailed(underlying?: unknown): CruxyError;
 /**

package/dist/errors/constructors.js

@@ -266,6 +266,34 @@ export function indexEmbedderUnavailable(underlying) {
         underlying,
     });
 }
+/**
+ * The fastembed module loaded, but the model could not be brought up at runtime
+ * — the first-run download/decompress of bge-small-en-v1.5, or the ONNX-runtime
+ * init, failed. This is the COMMON first-run failure (offline, the model bucket
+ * is unreachable, a corporate proxy blocks it), and it is deliberately kept
+ * distinct from both {@link indexEmbedderUnavailable} (a module *load* failure)
+ * and the generic {@link indexFailed} ("re-run --verbose") so the cause is
+ * actionable rather than a shrug.
+ *
+ * Fail-loud, not degrade: there is no fallback to the lexical hashing embedder
+ * (a silent quality loss). `cruxy index` treats this as fatal — the user
+ * explicitly asked to build the index, so a silent no-op index would be the
+ * exact "reads like success, isn't" trap C.17 forbids. The `search_codebase`
+ * tool instead surfaces it as a tool error and points the model at `grep_files`.
+ */
+export function indexEmbedderDownloadFailed(underlying) {
+    return new CruxyError({
+        code: ErrorCode.IndexEmbedderDownloadFailed,
+        title: "the local embedding model could not be downloaded or initialized",
+        cause: messageOf(underlying),
+        nextSteps: [
+            "check your internet connection — the model (bge-small-en-v1.5) downloads once on first use",
+            "if you are behind a proxy or firewall, allow access to the model host (Hugging Face) and set HTTPS_PROXY",
+            "once the download succeeds it is cached under ~/.cruxy/models and never re-fetched",
+        ],
+        underlying,
+    });
+}
 export function indexStoreUnavailable(underlying) {
     return new CruxyError({
         code: ErrorCode.IndexStoreUnavailable,

package/dist/errors/types.d.ts

@@ -46,7 +46,18 @@ export declare const ErrorCode: {
     readonly PermissionDenied: "CRUXY_E_PERMISSION_DENIED";
     readonly PathEscape: "CRUXY_E_PATH_ESCAPE";
     readonly CheckpointFailed: "CRUXY_E_CHECKPOINT_FAILED";
+    /** The fastembed native module could not be LOADED (missing/broken install,
+     * un-built onnxruntime-node addon). Fail-loud by design — the embedder never
+     * silently degrades to the lexical hashing backend (that would be a silent
+     * quality loss). See the store-vs-embedder asymmetry note in `schema.ts`. */
     readonly IndexEmbedderUnavailable: "CRUXY_E_INDEX_EMBEDDER_UNAVAILABLE";
+    /** The fastembed module loaded, but the model could not be brought up at
+     * RUNTIME — the first-run download/decompress, or the ONNX-runtime init,
+     * failed (offline, the model bucket is unreachable, a proxy blocks it). Kept
+     * DISTINCT from `IndexEmbedderUnavailable` (a load failure) and from the
+     * generic `IndexFailed` ("re-run --verbose") so the actual, common first-run
+     * failure carries an actionable cause instead of a shrug. */
+    readonly IndexEmbedderDownloadFailed: "CRUXY_E_INDEX_EMBEDDER_DOWNLOAD_FAILED";
     readonly IndexStoreUnavailable: "CRUXY_E_INDEX_STORE_UNAVAILABLE";
     readonly IndexFailed: "CRUXY_E_INDEX_FAILED";
     readonly SkillInvalid: "CRUXY_E_SKILL_INVALID";

package/dist/errors/types.js

@@ -54,7 +54,18 @@ export const ErrorCode = {
     PathEscape: "CRUXY_E_PATH_ESCAPE",
     CheckpointFailed: "CRUXY_E_CHECKPOINT_FAILED",
     // index (exit 8)
+    /** The fastembed native module could not be LOADED (missing/broken install,
+     * un-built onnxruntime-node addon). Fail-loud by design — the embedder never
+     * silently degrades to the lexical hashing backend (that would be a silent
+     * quality loss). See the store-vs-embedder asymmetry note in `schema.ts`. */
     IndexEmbedderUnavailable: "CRUXY_E_INDEX_EMBEDDER_UNAVAILABLE",
+    /** The fastembed module loaded, but the model could not be brought up at
+     * RUNTIME — the first-run download/decompress, or the ONNX-runtime init,
+     * failed (offline, the model bucket is unreachable, a proxy blocks it). Kept
+     * DISTINCT from `IndexEmbedderUnavailable` (a load failure) and from the
+     * generic `IndexFailed` ("re-run --verbose") so the actual, common first-run
+     * failure carries an actionable cause instead of a shrug. */
+    IndexEmbedderDownloadFailed: "CRUXY_E_INDEX_EMBEDDER_DOWNLOAD_FAILED",
     IndexStoreUnavailable: "CRUXY_E_INDEX_STORE_UNAVAILABLE",
     IndexFailed: "CRUXY_E_INDEX_FAILED",
     // skill (exit 9)
@@ -275,6 +286,7 @@ const EXIT_CODES = {
     [ErrorCode.PathEscape]: 7,
     [ErrorCode.CheckpointFailed]: 7,
     [ErrorCode.IndexEmbedderUnavailable]: 8,
+    [ErrorCode.IndexEmbedderDownloadFailed]: 8,
     [ErrorCode.IndexStoreUnavailable]: 8,
     [ErrorCode.IndexFailed]: 8,
     [ErrorCode.SkillInvalid]: 9,

package/dist/indexing/embedder.js

@@ -1,5 +1,5 @@
 import { promises as fs } from "node:fs";
-import { indexEmbedderUnavailable } from "../errors/index.js";
+import { indexEmbedderDownloadFailed, indexEmbedderUnavailable, } from "../errors/index.js";
 import { l2normalize } from "./util.js";
 /**
  * Output dimensionality of bge-small-en-v1.5, and the default size of the
@@ -84,18 +84,30 @@ export class FastEmbedEmbedder {
     getModel() {
         if (!this.model) {
             this.model = (async () => {
-                const mod = await import("fastembed");
-                // fastembed's init does a non-recursive mkdir of the cache dir, so it
-                // fails if an ancestor (e.g. ~/.cruxy) doesn't exist yet. Create it first.
-                if (this.opts.cacheDir) {
-                    await fs.mkdir(this.opts.cacheDir, { recursive: true });
+                try {
+                    const mod = await import("fastembed");
+                    // fastembed's init does a non-recursive mkdir of the cache dir, so it
+                    // fails if an ancestor (e.g. ~/.cruxy) doesn't exist yet. Create it first.
+                    if (this.opts.cacheDir) {
+                        await fs.mkdir(this.opts.cacheDir, { recursive: true });
+                    }
+                    return (await mod.FlagEmbedding.init({
+                        model: mod.EmbeddingModel.BGESmallENV15,
+                        maxLength: this.opts.maxLength ?? 512,
+                        cacheDir: this.opts.cacheDir,
+                        showDownloadProgress: this.opts.showDownloadProgress ?? false,
+                    }));
+                }
+                catch (err) {
+                    // The heavy path: first-run model download/decompress or ONNX-runtime
+                    // init failed (offline, unreachable model bucket, proxy). Surface a
+                    // typed, actionable error instead of letting it collapse into the
+                    // generic CRUXY_E_INDEX_FAILED ("re-run --verbose"). Still fail-loud —
+                    // this never degrades to the lexical backend. (Module-*load* failure is
+                    // caught earlier and eagerly in `createEmbedder`, so what reaches here is
+                    // a runtime bring-up failure, not a missing install.)
+                    throw indexEmbedderDownloadFailed(err);
                 }
-                return (await mod.FlagEmbedding.init({
-                    model: mod.EmbeddingModel.BGESmallENV15,
-                    maxLength: this.opts.maxLength ?? 512,
-                    cacheDir: this.opts.cacheDir,
-                    showDownloadProgress: this.opts.showDownloadProgress ?? false,
-                }));
             })();
         }
         return this.model;

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/tools/search-codebase.js

@@ -1,8 +1,38 @@
 import { z } from "zod";
+import { CruxyError, ErrorCode } from "../errors/index.js";
 import { getIndexService, mergeRankedHits } from "../indexing/index.js";
 import { contextWorkspace, labelName, resolveReadRoots } from "./file/paths.js";
 /** Hard cap on `k`, mirroring the retriever. */
 const MAX_K = 50;
+/**
+ * The embedder is unavailable — it failed to load, or the model failed to
+ * download/init. Fail-loud is preserved (the embedder never degrades to a
+ * lexical backend), so semantic search genuinely cannot run right now. This
+ * ROUTES THE MODEL to a working alternative: it is a hint in the error text, NOT
+ * an embedder fallback — `grep_files` is a different tool with different
+ * semantics (exact strings / symbols), and choosing it is the model's call.
+ */
+const GREP_ROUTE_HINT = "semantic search is unavailable right now — use grep_files to find code by exact string or symbol name instead";
+/** True when `err` is a semantic-search-blocking embedder unavailability. */
+function isEmbedderUnavailable(err) {
+    return (err instanceof CruxyError &&
+        (err.code === ErrorCode.IndexEmbedderUnavailable ||
+            err.code === ErrorCode.IndexEmbedderDownloadFailed));
+}
+/**
+ * The model-facing message for a failed search. For an embedder unavailability
+ * it appends the grep_files routing hint (and the actionable cause, if any) so
+ * the model has both the reason and a productive next move; every other failure
+ * passes through unchanged.
+ */
+function searchErrorMessage(err) {
+    const base = err.message;
+    if (isEmbedderUnavailable(err)) {
+        const cause = err instanceof CruxyError && err.cause ? ` (${err.cause})` : "";
+        return `${base}${cause}. ${GREP_ROUTE_HINT}.`;
+    }
+    return base;
+}
 const parameters = z.object({
     query: z
         .string()
@@ -76,7 +106,9 @@ export const searchCodebaseTool = {
                 return { ok: true, output: formatHits(hits, false) };
             }
             catch (err) {
-                return { ok: false, error: err.message };
+                // Embedder-unavailable errors carry a grep_files routing hint (a hint,
+                // NOT a fallback — the embedder still failed loud).
+                return { ok: false, error: searchErrorMessage(err) };
             }
         }
         // Multi-root fan: one independent search per root, per-root failures isolated
@@ -85,6 +117,9 @@ export const searchCodebaseTool = {
         const rawByRoot = new Map();
         const searched = [];
         const failed = [];
+        // Set if ANY root's failure was an embedder unavailability, so the fanned
+        // footer routes the model to grep_files ONCE rather than per failing root.
+        let embedderUnavailable = false;
         for (const root of roots) {
             try {
                 const service = await getIndexService(root.absPath, ctx.config, ctx.logger);
@@ -101,7 +136,11 @@ export const searchCodebaseTool = {
                 searched.push(root.name);
             }
             catch (err) {
+                // The root is NAMED (never conflated with "no matches"); the grep_files
+                // hint is added once, in the footer, not repeated per root.
                 failed.push({ name: root.name, reason: err.message });
+                if (isEmbedderUnavailable(err))
+                    embedderUnavailable = true;
             }
         }
         // Global rank + budget + cap AFTER the merge (⚖︎JC-I): a strong hit in one root
@@ -113,7 +152,12 @@ export const searchCodebaseTool = {
         });
         return {
             ok: true,
-            output: renderFanned(merged, { searched, failed, rawByRoot }),
+            output: renderFanned(merged, {
+                searched,
+                failed,
+                rawByRoot,
+                embedderUnavailable,
+            }),
         };
     },
 };
@@ -156,6 +200,11 @@ function renderFanned(merged, ctx) {
     for (const f of ctx.failed) {
         notes.push(`${f.name}: index unavailable — ${f.reason}`);
     }
+    // One routing hint for the whole fan when the embedder is the blocker (a hint,
+    // NOT a fallback — the embedder still failed loud on every affected root).
+    if (ctx.embedderUnavailable) {
+        notes.push(GREP_ROUTE_HINT);
+    }
     const scope = ctx.searched.length
         ? `searched ${ctx.searched.length} root${ctx.searched.length === 1 ? "" : "s"}: ${ctx.searched.join(", ")}`
         : "no roots could be searched";

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.0",
+  "version": "1.0.3",
   "description": "an agentic coding CLI",
   "type": "module",
   "bin": {