@cruxy/cli 1.2.1 → 1.4.0

package/dist/tui/views.js

@@ -0,0 +1,66 @@
+/** The built-in view: the streaming conversation, and the default selection. */
+export const CONVERSATION_VIEW = "conversation";
+/**
+ * The selectable views, conversation first.
+ *
+ * Conversation is prepended here rather than registered by a caller because it
+ * is the one view the renderer already owns the content for (the scrollback
+ * buffer) and the one that must always exist: it is the default, and it is
+ * unclosable, so nothing may remove it from the list a user can get back to.
+ */
+export function viewOrder(sources) {
+    return [CONVERSATION_VIEW, ...sources.map((s) => s.id)];
+}
+/** Human label for an id — conversation's is built in, the rest self-describe. */
+export function viewLabel(id, sources) {
+    if (id === CONVERSATION_VIEW)
+        return "conversation";
+    return sources.find((s) => s.id === id)?.label ?? id;
+}
+/**
+ * The id `steps` places after `from` in the nav order, wrapping.
+ *
+ * Wrapping (rather than stopping at the ends) because this is reached from a
+ * single cycling key: a ring the user can hold down to get anywhere beats two
+ * bindings that dead-end, and the list is short enough that overshooting costs
+ * one more press. Same reasoning as the mode ring in P5.
+ */
+export function cycleView(from, sources, steps) {
+    const order = viewOrder(sources);
+    const at = order.indexOf(from);
+    // An id that is no longer registered resolves to the conversation rather than
+    // to `order[-1]`: a view can be attached and re-attached, and the fallback has
+    // to be the one that always exists.
+    if (at < 0)
+        return CONVERSATION_VIEW;
+    const next = (at + (steps % order.length) + order.length) % order.length;
+    return order[next];
+}
+/**
+ * The sidebar's nav block: one row per view, the selected one marked.
+ *
+ * FOCUS IS DRAWN, not implied. When the sidebar holds the keyboard the heading
+ * says so and the selected row is highlighted rather than merely marked —
+ * otherwise "which keys go where" is invisible state, and the arrow keys
+ * silently mean two different things depending on something the screen never
+ * showed. The marker glyph stays in both states so a screen reader and a
+ * NO_COLOR terminal can still tell which row is current.
+ */
+export function navLines(theme, sources, selected, focused) {
+    // A WORD, not a glyph. This has to survive NO_COLOR, CRUXY_ASCII and a screen
+    // reader, and "focus" carries the meaning in all three where an arrow or a
+    // colour carries it in none. It also fits the 18-column sidebar.
+    const heading = focused ? "views (focus)" : "views";
+    const lines = [focused ? theme.accent(heading) : theme.strong(heading), ""];
+    for (const id of viewOrder(sources)) {
+        const label = viewLabel(id, sources);
+        const current = id === selected;
+        const row = `${current ? theme.glyph.pointer : " "} ${label}`;
+        if (!current) {
+            lines.push(theme.muted(row));
+            continue;
+        }
+        lines.push(focused ? theme.accent(row) : theme.strong(row));
+    }
+    return lines;
+}

package/dist/usage/collect.js

@@ -60,12 +60,12 @@ export class UsageCollector {
             ...(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".
+            // The server's own cost, persisted verbatim — and now the ONLY source of
+            // the cost `cruxy usage` shows; the user-configured price table it used to
+            // compete with is retired. Amount and currency travel together: a figure
+            // without its unit is not a cost, and the summary refuses to add two
+            // currencies rather than invent a rate. 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 }
                 : {}),

package/dist/usage/index.js

@@ -7,9 +7,17 @@
  * `@cruxy/sdk` import below is a TYPE-only import (`Usage`), erased at build. A
  * future opt-in remote report would be a new, clearly-named seam — this build
  * ships nothing that sends. Asserted by the runtime + static no-phone-home tests.
+ *
+ * The guarantee survived this module gaining SERVER-SOURCED figures (the
+ * gateway's cost, and weighted tokens in the gateway's own metering unit)
+ * because none of them is fetched here: cost rides in on the chat response the
+ * agent loop was already making, and the weighted multipliers are a compiled-in
+ * constant. Reading a number the server sent is not the same as asking it for
+ * one — the second would be the thing this promise forbids.
  */
 export * from "./types.js";
 export { UsageCollector, accumulateCacheTokens, } from "./collect.js";
-export { costFor, priceForTier } from "./cost.js";
+export { TIER_MULTIPLIERS, multiplierForTier, weightedFor, } from "./weighted.js";
 export { loadUsage, appendRun, usageStorePath } from "./store.js";
-export { summarizeRuns, renderSummary, formatCost, } from "./summary.js";
+export { summarizeRuns, renderSummary, formatCost } from "./summary.js";
+export { runCountLabel, selectRuns, usageReport, } from "./report.js";

package/dist/usage/report.js

@@ -0,0 +1,76 @@
+import { renderSummary, summarizeRuns } from "./summary.js";
+/** Narrow the retained runs to `scope`, newest-last order preserved. */
+export function selectRuns(runs, scope = {}) {
+    let selected = [...runs];
+    if (scope.sessionId !== undefined) {
+        selected = selected.filter((r) => r.sessionId === scope.sessionId);
+    }
+    if (scope.last !== undefined) {
+        // Guarded, not `slice(-last)` alone: `slice(-0)` is `slice(0)` and returns
+        // EVERYTHING, so a zero would quietly widen the scope to the whole store —
+        // the exact opposite of what it asks for.
+        selected = scope.last <= 0 ? [] : selected.slice(-scope.last);
+    }
+    return selected;
+}
+/**
+ * Say what the weighted figure IS, every time it is shown.
+ *
+ * The number is meaningless-to-dangerous without its scope: a reader who assumes
+ * it covers their whole account, or reads it as a remaining balance, has been
+ * misled by a figure that is itself correct. These lines are the only thing
+ * standing between the two readings, which is why they are not optional and not
+ * abbreviated for the in-session surface.
+ */
+function weightedNote(summary, t) {
+    if (summary.totalWeightedTokens !== undefined) {
+        return [
+            t.muted("weighted = (billable input + output) × tier weight — weighted tokens used by\n" +
+                "this CLI, over the runs shown. Not a balance or a limit: it cannot see your\n" +
+                "plan, or what cruxy on the web or desktop used from the same account."),
+        ];
+    }
+    // Absent rather than zero, and the reasons are unguessable from a blank line
+    // — so name them instead of leaving the figure silently missing.
+    return [
+        t.muted([
+            "weighted tokens unavailable for these runs — a request can only be weighed",
+            "when it records a tier and the gateway's billable input count. Runs from an",
+            "older cruxy, or against a non-cruxy provider, carry neither.",
+        ].join("\n")),
+    ];
+}
+/**
+ * The full usage report for `runs`, as lines to print.
+ *
+ * Empty `runs` is a first-class outcome, not an early-return the caller has to
+ * remember: it renders the "nothing yet" answer plus, when tracking is off, the
+ * reason — because "you have run nothing" and "nothing is being recorded" are
+ * different facts with the same blank output.
+ */
+export function usageReport(runs, t, opts) {
+    if (runs.length === 0) {
+        const lines = [t.muted("no usage recorded yet")];
+        if (!opts.trackingEnabled) {
+            lines.push(t.muted("usage tracking is off (usage.enabled = false)"));
+        }
+        return lines;
+    }
+    const summary = summarizeRuns(runs);
+    const lines = [
+        t.heading(`usage — ${opts.scopeLabel}`),
+        renderSummary(summary, t),
+        ...weightedNote(summary, t),
+    ];
+    if (opts.legacyPriceConfig) {
+        lines.push(t.muted([
+            "note: usage.prices / usage.currency are no longer used. Cost is now the",
+            "gateway's own figure. You can remove them from your config.",
+        ].join("\n")));
+    }
+    return lines;
+}
+/** `3 runs` / `1 run` — the countable half of a scope label. */
+export function runCountLabel(n) {
+    return `${n} run${n === 1 ? "" : "s"}`;
+}

package/dist/usage/summary.js

@@ -1,14 +1,38 @@
 import { formatTokens } from "../render/state.js";
-import { costFor } from "./cost.js";
+import { weightedFor } from "./weighted.js";
+/**
+ * Usage aggregation + rendering (C.22). Aggregation sums only KNOWN figures and
+ * counts the requests that reported none separately, so a total is never
+ * inflated by a fabricated zero — and the renderer ALWAYS surfaces those counts,
+ * so a total can never be misread as complete while requests are silently
+ * excluded. That rule now applies on three independent axes, because a request
+ * can report tokens but no cost, or a cost but nothing weighable:
+ * `requestsWithoutUsage`, `requestsWithoutCost`, `requestsWithoutWeight`.
+ *
+ * Both derived figures come from the server: cost is the gateway's own quote,
+ * weighted tokens are the gateway's own metering formula. Neither is derived
+ * from a user-configured price — there is no longer such a thing here.
+ *
+ * Only tier names ever reach the output (U.8 gag). Pure — no I/O, no network.
+ */
 /** Aggregate one or more run records into a {@link UsageSummary}. */
-export function summarizeRuns(runs, opts) {
+export function summarizeRuns(runs) {
     const byTier = new Map();
     let totalInputTokens;
     let totalOutputTokens;
     let totalCacheReadTokens;
     let totalCacheCreationTokens;
+    let totalBillableInputTokens;
+    let totalWeightedTokens;
+    let totalCost;
     let requests = 0;
     let requestsWithoutUsage = 0;
+    let requestsWithoutWeight = 0;
+    let requestsWithoutCost = 0;
+    // Every distinct currency the gateway stated. Summing across two of them would
+    // require an exchange rate we don't have and would never be told, so the set
+    // is kept and a >1 outcome withholds the total rather than guessing.
+    const currencies = new Set();
     const addKnown = (acc, v) => (v === undefined ? acc : (acc ?? 0) + v);
     for (const run of runs) {
         for (const e of run.entries) {
@@ -16,10 +40,24 @@ export function summarizeRuns(runs, opts) {
             const known = e.inputTokens !== undefined || e.outputTokens !== undefined;
             if (!known)
                 requestsWithoutUsage++;
+            // Weighed per REQUEST, never from the tier's summed totals: the multiplier
+            // is per-tier, but a tier's bucket can mix weighable and unweighable
+            // requests, and multiplying a sum that includes the latter would silently
+            // weigh tokens that were never eligible.
+            const weighted = weightedFor(e.tier, e.billableInputTokens, e.outputTokens);
+            if (weighted === undefined)
+                requestsWithoutWeight++;
+            if (e.costAmount === undefined)
+                requestsWithoutCost++;
+            else if (e.costCurrency !== undefined)
+                currencies.add(e.costCurrency);
             totalInputTokens = addKnown(totalInputTokens, e.inputTokens);
             totalOutputTokens = addKnown(totalOutputTokens, e.outputTokens);
             totalCacheReadTokens = addKnown(totalCacheReadTokens, e.cacheReadTokens);
             totalCacheCreationTokens = addKnown(totalCacheCreationTokens, e.cacheCreationTokens);
+            totalBillableInputTokens = addKnown(totalBillableInputTokens, e.billableInputTokens);
+            totalWeightedTokens = addKnown(totalWeightedTokens, weighted);
+            totalCost = addKnown(totalCost, e.costAmount);
             // 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.
@@ -27,42 +65,53 @@ export function summarizeRuns(runs, opts) {
                 const b = byTier.get(e.tier) ?? {
                     requests: 0,
                     requestsWithoutUsage: 0,
+                    requestsWithoutWeight: 0,
                 };
                 b.requests++;
                 if (!known)
                     b.requestsWithoutUsage++;
+                if (weighted === undefined)
+                    b.requestsWithoutWeight++;
                 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);
+                b.billableInputTokens = addKnown(b.billableInputTokens, e.billableInputTokens);
+                b.weightedTokens = addKnown(b.weightedTokens, weighted);
+                b.cost = addKnown(b.cost, e.costAmount);
                 byTier.set(e.tier, b);
             }
         }
     }
+    const costMixedCurrency = currencies.size > 1;
     const perTier = [...byTier.entries()].map(([tier, b]) => ({
         tier,
         inputTokens: b.inputTokens,
         outputTokens: b.outputTokens,
         cacheReadTokens: b.cacheReadTokens,
         cacheCreationTokens: b.cacheCreationTokens,
+        billableInputTokens: b.billableInputTokens,
+        weightedTokens: b.weightedTokens,
         requests: b.requests,
         requestsWithoutUsage: b.requestsWithoutUsage,
-        cost: costFor(tier, b.inputTokens, b.outputTokens, opts.prices),
+        requestsWithoutWeight: b.requestsWithoutWeight,
+        // Withheld under mixed currencies for the same reason the total is: a tier's
+        // requests are not guaranteed to share a currency either.
+        cost: costMixedCurrency ? undefined : b.cost,
     }));
-    const costs = perTier
-        .map((p) => p.cost)
-        .filter((c) => c !== undefined);
-    const priced = costs.length > 0;
-    const totalCost = priced ? costs.reduce((a, c) => a + c, 0) : undefined;
     return {
         perTier,
         totalInputTokens,
         totalOutputTokens,
         totalCacheReadTokens,
         totalCacheCreationTokens,
-        totalCost,
-        priced,
-        currency: opts.currency,
+        totalBillableInputTokens,
+        totalWeightedTokens,
+        requestsWithoutWeight,
+        totalCost: costMixedCurrency ? undefined : totalCost,
+        costCurrency: costMixedCurrency ? undefined : [...currencies][0],
+        costMixedCurrency,
+        requestsWithoutCost,
         requestsWithoutUsage,
         requests,
         runCount: runs.length,
@@ -70,15 +119,27 @@ export function summarizeRuns(runs, opts) {
 }
 /**
  * Format a cost figure honestly: enough precision for small per-run costs,
- * trailing zeros trimmed. Prefixed by the currency label only when one is set
- * (never an assumed symbol). Callers pass a cost only when it was actually
- * computed (priced + known tokens).
+ * trailing zeros trimmed. The currency is the gateway's own code (e.g. "usd"),
+ * so it is appended as a UNIT (`0.0021 USD`) rather than prefixed as a symbol —
+ * a code reads as a suffix, and cruxy no longer has a user-configured symbol to
+ * prefix with. An absent currency renders the bare number rather than assuming
+ * one. Callers pass a cost only when the gateway actually quoted it.
  */
 export function formatCost(n, currency) {
     const abs = Math.abs(n);
     const decimals = abs >= 1 ? 2 : abs >= 0.01 ? 4 : 6;
     const trimmed = n.toFixed(decimals).replace(/\.?0+$/, "");
-    return `${currency}${trimmed === "" || trimmed === "-0" ? "0" : trimmed}`;
+    const amount = trimmed === "" || trimmed === "-0" ? "0" : trimmed;
+    return currency ? `${amount} ${currency.toUpperCase()}` : amount;
+}
+/**
+ * Weighted tokens at status-line width. Rounded to a whole token because the
+ * multipliers are fractional (3.25×, 3.8×) and a `812.5` would imply the meter
+ * counts half-tokens; the unrounded value stays on the summary for anything that
+ * needs the exact arithmetic.
+ */
+function formatWeighted(n) {
+    return formatTokens(Math.round(n));
 }
 /** `↑1.2k ↓340` (worded `up 1.2k down 340` under a screen reader). */
 function tokenText(input, output, t) {
@@ -98,7 +159,9 @@ export function renderSummary(summary, t) {
     for (const p of summary.perTier) {
         const known = p.inputTokens !== undefined || p.outputTokens !== undefined;
         if (known) {
-            const cost = p.cost !== undefined ? ` ${formatCost(p.cost, summary.currency)}` : "";
+            const cost = p.cost !== undefined
+                ? ` ${formatCost(p.cost, summary.costCurrency)}`
+                : "";
             parts.push(`${p.tier} ${tokenText(p.inputTokens, p.outputTokens, t)}${t.muted(cost)}`);
         }
         else {
@@ -111,11 +174,19 @@ export function renderSummary(summary, t) {
     const totalKnown = summary.totalInputTokens !== undefined ||
         summary.totalOutputTokens !== undefined;
     const totalCost = summary.totalCost !== undefined
-        ? ` ${formatCost(summary.totalCost, summary.currency)}`
+        ? ` ${formatCost(summary.totalCost, summary.costCurrency)}`
         : "";
     parts.push(totalKnown
         ? `${t.strong("total")} ${tokenText(summary.totalInputTokens, summary.totalOutputTokens, t)}${t.muted(totalCost)}`
         : `${t.strong("total")} —`);
+    // Weighted tokens — the gateway's own metering unit, computed locally from
+    // billable input + output. Shown only when at least one request could actually
+    // be weighed; the label stays "weighted", never anything implying a balance
+    // (`cruxy usage` carries the fuller wording). A reported 0 IS shown, same rule
+    // as `cached ↻0`: it is a measurement, not an absence.
+    if (summary.totalWeightedTokens !== undefined) {
+        parts.push(t.muted(`weighted ${formatWeighted(summary.totalWeightedTokens)}`));
+    }
     // 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
@@ -130,6 +201,24 @@ export function renderSummary(summary, t) {
     if (summary.requestsWithoutUsage > 0) {
         parts.push(t.warning(unreported(summary.requestsWithoutUsage)));
     }
+    // Coverage for the two derived figures. Each is emitted only when it says
+    // something the line doesn't already: `requestsWithoutUsage` above already
+    // explains requests that reported nothing at all, so these fire only for the
+    // EXTRA shortfall — requests that did report tokens but still couldn't be
+    // weighed (unknown tier / no billable input) or weren't quoted a cost.
+    const weightShortfall = summary.requestsWithoutWeight - summary.requestsWithoutUsage;
+    if (summary.totalWeightedTokens !== undefined && weightShortfall > 0) {
+        parts.push(t.muted(`${weightShortfall} not weighted`));
+    }
+    const costShortfall = summary.requestsWithoutCost - summary.requestsWithoutUsage;
+    if (summary.totalCost !== undefined && costShortfall > 0) {
+        parts.push(t.muted(`${costShortfall} without cost`));
+    }
+    // Two gateways quoting two currencies: refuse to add them, and say why rather
+    // than just dropping the cost silently.
+    if (summary.costMixedCurrency) {
+        parts.push(t.warning("cost omitted: mixed currencies"));
+    }
     return parts.join(sep);
 }
 /** `2 requests: usage not reported`. */

package/dist/usage/types.js

@@ -65,8 +65,11 @@ export const UsageEntrySchema = z
     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
+     * excluded, which is what makes the caching win legible. This is the input
+     * term of the weighted-pool formula `(billable_input + output) × multiplier`
+     * that weighted.ts computes, and `inputTokens` is NEVER an acceptable
+     * stand-in for it: substituting a count that includes cache reads overstates
+     * precisely the requests caching made cheaper. 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.

package/dist/usage/weighted.js

@@ -0,0 +1,77 @@
+/**
+ * Weighted tokens (C.22) — the unit the cruxy gateway actually meters a
+ * subscriber in.
+ *
+ * A subscriber is not billed per token and not billed in dollars: the gateway
+ * counts `(billable_input + output) × multiplier` per request and checks that
+ * against two windows. This module computes THAT number, locally, from figures
+ * already on disk — so `cruxy usage` can state consumption in the same unit the
+ * meter uses instead of a currency nobody is charged in.
+ *
+ * WHAT THIS IS NOT: it is not headroom, and it must never be rendered as such.
+ * A cap needs the user's plan, and how much of that plan every OTHER surface
+ * (web chat, desktop, phone) has already spent — neither of which is on this
+ * machine. All this module can honestly say is "this is what the runs in this
+ * CLI's own store weigh". Anything phrased as remaining/left/available would be
+ * a number this process cannot possibly know.
+ *
+ * No network: the multipliers are a compiled-in constant, not a fetched one.
+ */
+/**
+ * Weighted-token multipliers, keyed by tier — mirroring `multipliers` in the
+ * gateway's `internal/budget/config.go`, which is the source of truth.
+ *
+ * MIRRORED, THEREFORE DRIFTABLE. Nothing checks these against the server at
+ * runtime (that would be a network call this module is forbidden to make), so a
+ * gateway-side reweighting silently makes an old CLI's arithmetic stale. That
+ * is the accepted cost of computing offline, and it is why every rendering of
+ * this figure is framed as what THIS CLI reckons it used — never as an
+ * authoritative balance. If they drift, the server is right and this is wrong.
+ *
+ * Only the chat tiers are listed. The gateway also weighs its embed/guard/rerank
+ * models at 0.1×, but the CLI's chat path cannot produce a request on one, so
+ * including them would model traffic that never reaches this store.
+ */
+export const TIER_MULTIPLIERS = {
+    mira: 1.0,
+    vaani: 3.25,
+    kavi: 3.8,
+};
+/** The multiplier for a tier, or `undefined` when the tier isn't a known one. */
+export function multiplierForTier(tier) {
+    return TIER_MULTIPLIERS[tier];
+}
+/**
+ * Weighted tokens for one request's figures, or `undefined` when the request
+ * cannot be weighed honestly.
+ *
+ * BOTH terms are required, and this is the whole discipline of the function.
+ * The meter's formula has two addends; substituting 0 for an unknown one does
+ * not produce an approximate answer, it produces a confidently understated one —
+ * and understating consumption is the direction that flatters, so it is exactly
+ * the error that would go unnoticed. `costFor` could price one known side
+ * because the raw token counts stayed visible beside it; here the weighted
+ * figure IS the deliverable, so a partial one is worse than none. Callers count
+ * the `undefined`s and surface them instead.
+ *
+ * Three ways a request is unweighable, all of them real and all treated alike:
+ *  - no tier, or a tier this build doesn't know (a non-cruxy provider — those
+ *    tokens never touched the weighted pool, so weighing them would be fiction);
+ *  - no `billable_input_tokens` (a gateway too old to send it). Note that
+ *    `inputTokens` is NOT a fallback: it includes cache-read tokens, which the
+ *    meter excludes, so it would overstate every cached request — the precise
+ *    inverse of the caching win the field exists to show;
+ *  - no output count.
+ *
+ * A reported `0` on either side is a real measurement and weighs in as 0.
+ */
+export function weightedFor(tier, billableInputTokens, outputTokens) {
+    if (tier === undefined)
+        return undefined;
+    const multiplier = multiplierForTier(tier);
+    if (multiplier === undefined)
+        return undefined;
+    if (billableInputTokens === undefined || outputTokens === undefined)
+        return undefined;
+    return (billableInputTokens + outputTokens) * multiplier;
+}