@cruxy/cli 1.2.0 → 1.2.1

package/dist/agent/loop.js

@@ -116,6 +116,12 @@ async function driveLoop(args, renderer, routed) {
         // true and is recorded as a real 0.
         let sawUsage = false;
         const reqUsage = { input_tokens: 0, output_tokens: 0 };
+        // The served tier arrives on the stream's OPENING frame, but usage is only
+        // reported once the stream has closed — so it is held here across the whole
+        // request, exactly like `sawUsage`. Absent for backends that report no
+        // routing, which is why the fallback below still exists.
+        let servedTier;
+        let routingMode;
         // Live progress while waiting on the model; dismissed by the first delta.
         // Token context is whatever the loop has actually accumulated (U.4): zero
         // on the first turn → no figure shown, never a fabricated number.
@@ -133,6 +139,10 @@ async function driveLoop(args, renderer, routed) {
             ...(routed ? { model: routed.model } : {}),
         })) {
             switch (ev.type) {
+                case "routing":
+                    servedTier = ev.routing.tier;
+                    routingMode = ev.routing.mode;
+                    break;
                 case "text_delta":
                     turnText += ev.text;
                     renderer?.write(ev.text);
@@ -178,8 +188,18 @@ async function driveLoop(args, renderer, routed) {
         // event arrived, or `undefined` (unknown) when the provider reported none. A
         // stream that threw above never reaches here, so failed requests aren't
         // recorded with a misleading zero.
+        // THE BACKEND WINS on tier. `routed?.tier` is what this run ASKED for;
+        // `servedTier` is what the gateway says actually ran, which is not the same
+        // claim — a "auto" request is resolved server-side, and any request can be
+        // downgraded under budget pressure. Attributing tokens to the tier we asked
+        // for would misreport exactly the case worth knowing about. The client
+        // choice remains the fallback for backends that report no routing at all.
+        // `routingMode` travels alongside so a difference between the two is
+        // explainable after the fact ("auto_degraded") rather than an unexplained
+        // tier nobody selected.
         args.onRequestUsage?.({
-            tier: routed?.tier,
+            tier: servedTier ?? routed?.tier,
+            ...(routingMode !== undefined ? { routingMode } : {}),
             usage: sawUsage ? { ...reqUsage } : undefined,
         });
         // ── Record the assistant turn ───────────────────────────────────────────

package/dist/agent/session.js

@@ -331,14 +331,22 @@ export class Session {
             ? resolveTaskModel(this.args.router, "summarize")
             : null;
         // Per-request usage capture for telemetry (C.22), same honesty pivot as the
-        // main loop: unknown unless a usage event actually arrives.
+        // main loop: unknown unless a usage event actually arrives. The served tier
+        // is held across the stream for the same reason it is in the loop — it
+        // arrives on the opening frame, and is reported after the close.
         let sawUsage = false;
+        let servedTier;
+        let routingMode;
         for await (const ev of this.args.provider.stream({
             system: SUMMARY_SYSTEM,
             messages: [{ role: "user", content: transcript }],
             ...(routed ? { model: routed.model } : {}),
         })) {
             switch (ev.type) {
+                case "routing":
+                    servedTier = ev.routing.tier;
+                    routingMode = ev.routing.mode;
+                    break;
                 case "text_delta":
                     text += ev.text;
                     break;
@@ -354,9 +362,12 @@ export class Session {
                     break;
             }
         }
-        // Attribute this compaction request to the `summarize` tier honestly.
+        // Attribute this compaction request to the tier that served it — the
+        // gateway's answer over the `summarize` tier this run asked for, same
+        // precedence and same reasoning as the main loop.
         onRequestUsage?.({
-            tier: routed?.tier,
+            tier: servedTier ?? routed?.tier,
+            ...(routingMode !== undefined ? { routingMode } : {}),
             usage: sawUsage ? { ...usage } : undefined,
         });
         if (!text.trim())

package/dist/usage/collect.js

@@ -45,15 +45,33 @@ export class UsageCollector {
             tier: req.tier,
             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.
+            // Every additive field below is conditionally spread so an unreported one
+            // stays ABSENT from the persisted entry rather than landing as a 0 that
+            // reads like a measurement (undefined ≠ 0). The reasons absence happens
+            // differ per field — a non-caching provider, a gateway too old to send
+            // billable input, a request the server quoted no cost for — but the entry
+            // records the same thing for all of them: nothing.
             ...(u?.cache_read_input_tokens !== undefined
                 ? { cacheReadTokens: u.cache_read_input_tokens }
                 : {}),
             ...(u?.cache_creation_input_tokens !== undefined
                 ? { cacheCreationTokens: u.cache_creation_input_tokens }
                 : {}),
+            ...(u?.billable_input_tokens !== undefined
+                ? { billableInputTokens: u.billable_input_tokens }
+                : {}),
+            // The server's own cost, persisted verbatim and NOT yet surfaced (the
+            // summary's cost line still comes from the user's configured price table —
+            // reconciling the two is a deliberate follow-up, not a mechanical merge).
+            // Amount and currency travel together: a figure without its unit is not a
+            // cost. A recorded 0 is a real 0; see UsageEntry.costAmount for why that
+            // must never be read as "unpriced".
+            ...(u?.cost !== undefined
+                ? { costAmount: u.cost.amount, costCurrency: u.cost.currency }
+                : {}),
+            ...(req.routingMode !== undefined
+                ? { routingMode: req.routingMode }
+                : {}),
             at: this.now(),
         });
     }

package/dist/usage/store.js

@@ -73,7 +73,13 @@ export function appendRun(record, opts = { retention: 50 }) {
     const pruned = runs.slice(-retention); // keep the newest `retention` runs
     try {
         mkdirSync(path.dirname(file), { recursive: true });
-        const body = JSON.stringify({ version: USAGE_FILE_VERSION, runs: pruned }, null, 2);
+        // Spread the loaded file first so any key a NEWER cruxy wrote at the top
+        // level survives this rewrite, the same way unknown keys inside runs and
+        // entries do (see the forward-compatibility note in types.ts). Tolerating a
+        // newer file on read but flattening it on the next append would still lose
+        // the data, just one write later. version/runs are re-stated after the
+        // spread so this build's own values always win.
+        const body = JSON.stringify({ ...loaded.data, version: USAGE_FILE_VERSION, runs: pruned }, null, 2);
         writeFileSync(file, body, { mode: 0o600 });
         return {};
     }

package/dist/usage/types.js

@@ -8,6 +8,32 @@ import { z } from "zod";
  */
 /** Bump when the on-disk usage file shape changes (enables future migration). */
 export const USAGE_FILE_VERSION = 1;
+/**
+ * FORWARD COMPATIBILITY, and why every schema below is `.passthrough()` rather
+ * than `.strict()`.
+ *
+ * `loadUsage` discards the ENTIRE file on any parse failure (see store.ts) — it
+ * cannot do otherwise, because a file it can't validate is a file it can't
+ * safely append to. Combined with `.strict()`, that made the store hostile to
+ * its own future: the moment a newer cruxy wrote a field an older one didn't
+ * know, the older binary rejected the whole file and the user silently lost
+ * every run of history. Downgrading a CLI, or running two versions against one
+ * home directory, is ordinary — losing accounting for it is not acceptable.
+ *
+ * A version bump alone does NOT fix this: the old binary is already shipped and
+ * still can't parse the new file, whatever the number says. The fix has to be
+ * in the schema that old binaries already run, so it is made here, once, BEFORE
+ * any new field is persisted — that ordering is the whole point.
+ *
+ * `.passthrough()` also PRESERVES unknown keys rather than stripping them, so an
+ * old CLI that loads, prunes and rewrites the file hands a newer CLI's fields
+ * back intact. `.strip()` (zod's default) would tolerate the read and then
+ * quietly erase them on the next write — tolerant to parse, lossy in practice.
+ *
+ * The tradeoff accepted: a typo'd key is no longer a parse error. That is worth
+ * it — this is a local, additive, append-only telemetry file, and every field
+ * the code reads is still fully validated.
+ */
 /**
  * One model request's usage. A request that reported no usage keeps
  * `inputTokens`/`outputTokens` as `undefined` — the honest "unknown", never
@@ -16,7 +42,13 @@ export const USAGE_FILE_VERSION = 1;
  */
 export const UsageEntrySchema = z
     .object({
-    /** The routing tier (C.30) this request ran on; absent when routing is inert. */
+    /**
+     * The tier this request ACTUALLY ran on. Preferentially the tier the gateway
+     * reported serving (v2 `routing.tier`, which resolves `auto` and reflects a
+     * budget downgrade); the client-side routing choice (C.30) only when the
+     * gateway said nothing. Absent when neither is known — e.g. a non-cruxy
+     * provider with routing inert.
+     */
     tier: z.string().optional(),
     /** Provider-reported prompt tokens; `undefined` ⇔ no usage was reported. */
     inputTokens: z.number().int().nonnegative().optional(),
@@ -31,10 +63,44 @@ export const UsageEntrySchema = z
     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(),
+    /**
+     * Tokens the gateway actually METERED as fresh input — cache-read tokens
+     * excluded, which is what makes the caching win legible (the weighted pool
+     * meters `(billable_input + output) × multiplier`). Reported by the cruxy v2
+     * wire on every request INCLUDING as a literal `0`, so `undefined` here means
+     * a gateway too old to send it or a provider that never does — unknown, not
+     * zero. Never zero-filled.
+     */
+    billableInputTokens: z.number().int().nonnegative().optional(),
+    /**
+     * The gateway's OWN computed cost for this request (`usage.cost.amount`) and
+     * its currency — the same figure persisted to the server-side ledger, so
+     * client and ledger can never disagree. Recorded verbatim; nothing here is
+     * derived from a user-configured price.
+     *
+     * TWO TRAPS, do not "optimize" either away:
+     *  - `costAmount === 0` is a LEGITIMATE cost (a request that billed nothing),
+     *    NOT a signal that the tier is unpriced. Absence is the only unknown.
+     *  - server-side, an unrecognized model falls through to the mira price rather
+     *    than to no price at all, so a cost is always a real quote for SOME tier —
+     *    you cannot infer "unpriced" from the amount under any circumstances.
+     * Read `costAmount !== undefined` and nothing else.
+     */
+    costAmount: z.number().nonnegative().optional(),
+    /** Currency of {@link costAmount} as the gateway stated it (e.g. "usd"); absent with it. */
+    costCurrency: z.string().optional(),
+    /**
+     * How the served tier was chosen, verbatim from the gateway's `routing.mode`
+     * (`explicit` | `auto` | `auto_degraded`). This is what makes a client/server
+     * tier disagreement explainable after the fact rather than silent: when a
+     * run configured `kavi` but the entry reads `tier: "mira"`, the mode says
+     * whether that was routing working as asked or a budget downgrade.
+     */
+    routingMode: z.string().optional(),
     /** ISO-8601 timestamp the request completed. */
     at: z.string(),
 })
-    .strict();
+    .passthrough();
 /** One run's usage: an ordered list of per-request entries. */
 export const UsageRecordSchema = z
     .object({
@@ -46,11 +112,11 @@ export const UsageRecordSchema = z
     startedAt: z.string(),
     entries: z.array(UsageEntrySchema),
 })
-    .strict();
+    .passthrough();
 /** The persisted store: a bounded, newest-last list of run records. */
 export const UsageFileSchema = z
     .object({
     version: z.literal(USAGE_FILE_VERSION),
     runs: z.array(UsageRecordSchema),
 })
-    .strict();
+    .passthrough();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cruxy/cli",
-  "version": "1.2.0",
+  "version": "1.2.1",
   "description": "an agentic coding CLI",
   "type": "module",
   "bin": {
@@ -36,7 +36,7 @@
     "undici": "^6.21.0",
     "zod": "^3.23.8",
     "zod-to-json-schema": "^3.23.5",
-    "@cruxy/sdk": "0.4.0"
+    "@cruxy/sdk": "0.4.1"
   },
   "optionalDependencies": {
     "better-sqlite3": "^12.11.1"