@cruxy/cli 0.17.0 → 0.19.0

package/dist/usage/store.d.ts

@@ -0,0 +1,37 @@
+import { CruxyError } from "../errors/index.js";
+import { type UsageFile, type UsageRecord } from "./types.js";
+/**
+ * The usage store (C.22): a single JSON file under `~/.cruxy/usage`, holding a
+ * bounded, newest-last list of run records. Pure DATA — parsed with the strict
+ * schema, NEVER eval'd — and written `0600` (personal accounting). This module
+ * touches only the local filesystem; it makes ZERO network calls.
+ *
+ * Reads are non-fatal by contract: a missing file is empty (not an error); a
+ * corrupt/unreadable one yields an empty result plus a coded
+ * {@link usageRead} error the caller can surface and SKIP — a broken usage file
+ * never crashes a run.
+ */
+/** `~/.cruxy/usage/runs.json` — the single usage store file. */
+export declare function usageStorePath(): string;
+/**
+ * Load and validate the store. Never throws. A missing file → empty, no error.
+ * Invalid JSON or a schema mismatch → empty + a `CRUXY_E_USAGE_READ` error
+ * (skip, don't crash). The raw text is parsed with `JSON.parse` only — a store
+ * file is never executed, so a hand-edited file cannot run code.
+ */
+export declare function loadUsage(file?: string): {
+    data: UsageFile;
+    error?: CruxyError;
+};
+/**
+ * Append one run's usage, pruning oldest-first to the last `retention` runs.
+ * Never throws — any failure (a corrupt existing file that cannot be safely
+ * appended to, or a write error) is returned as a coded error for the caller to
+ * downgrade to a warning, so persistence never takes a run down with it.
+ */
+export declare function appendRun(record: UsageRecord, opts?: {
+    retention: number;
+    file?: string;
+}): {
+    error?: CruxyError;
+};

package/dist/usage/store.js

@@ -0,0 +1,83 @@
+import { mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import path from "node:path";
+import { globalDir } from "../config/paths.js";
+import { USAGE_DIR_NAME, USAGE_FILE_NAME } from "../constants.js";
+import { usageRead } from "../errors/index.js";
+import { UsageFileSchema, USAGE_FILE_VERSION, } from "./types.js";
+/**
+ * The usage store (C.22): a single JSON file under `~/.cruxy/usage`, holding a
+ * bounded, newest-last list of run records. Pure DATA — parsed with the strict
+ * schema, NEVER eval'd — and written `0600` (personal accounting). This module
+ * touches only the local filesystem; it makes ZERO network calls.
+ *
+ * Reads are non-fatal by contract: a missing file is empty (not an error); a
+ * corrupt/unreadable one yields an empty result plus a coded
+ * {@link usageRead} error the caller can surface and SKIP — a broken usage file
+ * never crashes a run.
+ */
+/** `~/.cruxy/usage/runs.json` — the single usage store file. */
+export function usageStorePath() {
+    return path.join(globalDir(), USAGE_DIR_NAME, USAGE_FILE_NAME);
+}
+/** An empty (fresh) store. */
+function emptyFile() {
+    return { version: USAGE_FILE_VERSION, runs: [] };
+}
+/**
+ * Load and validate the store. Never throws. A missing file → empty, no error.
+ * Invalid JSON or a schema mismatch → empty + a `CRUXY_E_USAGE_READ` error
+ * (skip, don't crash). The raw text is parsed with `JSON.parse` only — a store
+ * file is never executed, so a hand-edited file cannot run code.
+ */
+export function loadUsage(file = usageStorePath()) {
+    let raw;
+    try {
+        raw = readFileSync(file, "utf8");
+    }
+    catch {
+        // Missing / unreadable → nothing recorded yet (not an error).
+        return { data: emptyFile() };
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch (err) {
+        return { data: emptyFile(), error: usageRead(file, "not valid JSON", err) };
+    }
+    const result = UsageFileSchema.safeParse(parsed);
+    if (!result.success) {
+        return {
+            data: emptyFile(),
+            error: usageRead(file, result.error.issues[0]?.message ?? "invalid shape"),
+        };
+    }
+    return { data: result.data };
+}
+/**
+ * Append one run's usage, pruning oldest-first to the last `retention` runs.
+ * Never throws — any failure (a corrupt existing file that cannot be safely
+ * appended to, or a write error) is returned as a coded error for the caller to
+ * downgrade to a warning, so persistence never takes a run down with it.
+ */
+export function appendRun(record, opts = { retention: 50 }) {
+    const file = opts.file ?? usageStorePath();
+    // A corrupt existing file is NOT overwritten — surface it and skip, rather
+    // than silently destroying whatever the user has (or blindly appending to a
+    // shape we couldn't validate).
+    const loaded = loadUsage(file);
+    if (loaded.error)
+        return { error: loaded.error };
+    const runs = [...loaded.data.runs, record];
+    const retention = Math.max(1, Math.floor(opts.retention));
+    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);
+        writeFileSync(file, body, { mode: 0o600 });
+        return {};
+    }
+    catch (err) {
+        return { error: usageRead(file, "could not write the usage store", err) };
+    }
+}

package/dist/usage/summary.d.ts

@@ -0,0 +1,32 @@
+import type { Theme } from "../theme/index.js";
+import type { PriceTable, UsageRecord, UsageSummary } from "./types.js";
+/**
+ * Usage aggregation + rendering (C.22). Aggregation sums only KNOWN token
+ * counts and counts the requests that reported none separately, so a total is
+ * never inflated by a fabricated zero — and the renderer ALWAYS surfaces that
+ * count, so a total can never be misread as complete while requests are silently
+ * excluded. Costs appear only for priced tiers. Only tier names ever reach the
+ * output (U.8 gag). Pure — no I/O, no network.
+ */
+export interface SummarizeOptions {
+    prices: PriceTable;
+    /** Currency label to prefix costs; "" when the user configured none. */
+    currency: string;
+}
+/** Aggregate one or more run records into a {@link UsageSummary}. */
+export declare function summarizeRuns(runs: readonly UsageRecord[], opts: SummarizeOptions): UsageSummary;
+/**
+ * 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).
+ */
+export declare function formatCost(n: number, currency: string): string;
+/**
+ * Render a {@link UsageSummary} to a single themed line. Honors the theme
+ * end-to-end: NO_COLOR yields zero ANSI (identity stylers), and screen-reader
+ * mode swaps the arrow glyphs for words. The count of requests that reported no
+ * usage is ALWAYS shown when non-zero, so the total is never mistaken for a
+ * complete accounting.
+ */
+export declare function renderSummary(summary: UsageSummary, t: Theme): string;

package/dist/usage/summary.js

@@ -0,0 +1,119 @@
+import { formatTokens } from "../render/state.js";
+import { costFor } from "./cost.js";
+/** Aggregate one or more run records into a {@link UsageSummary}. */
+export function summarizeRuns(runs, opts) {
+    const byTier = new Map();
+    let totalInputTokens;
+    let totalOutputTokens;
+    let requests = 0;
+    let requestsWithoutUsage = 0;
+    const addKnown = (acc, v) => (v === undefined ? acc : (acc ?? 0) + v);
+    for (const run of runs) {
+        for (const e of run.entries) {
+            requests++;
+            const known = e.inputTokens !== undefined || e.outputTokens !== undefined;
+            if (!known)
+                requestsWithoutUsage++;
+            totalInputTokens = addKnown(totalInputTokens, e.inputTokens);
+            totalOutputTokens = addKnown(totalOutputTokens, e.outputTokens);
+            // 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.
+            if (e.tier !== undefined) {
+                const b = byTier.get(e.tier) ?? {
+                    requests: 0,
+                    requestsWithoutUsage: 0,
+                };
+                b.requests++;
+                if (!known)
+                    b.requestsWithoutUsage++;
+                b.inputTokens = addKnown(b.inputTokens, e.inputTokens);
+                b.outputTokens = addKnown(b.outputTokens, e.outputTokens);
+                byTier.set(e.tier, b);
+            }
+        }
+    }
+    const perTier = [...byTier.entries()].map(([tier, b]) => ({
+        tier,
+        inputTokens: b.inputTokens,
+        outputTokens: b.outputTokens,
+        requests: b.requests,
+        requestsWithoutUsage: b.requestsWithoutUsage,
+        cost: costFor(tier, b.inputTokens, b.outputTokens, opts.prices),
+    }));
+    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,
+        totalCost,
+        priced,
+        currency: opts.currency,
+        requestsWithoutUsage,
+        requests,
+        runCount: runs.length,
+    };
+}
+/**
+ * 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).
+ */
+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}`;
+}
+/** `↑1.2k ↓340` (worded `up 1.2k down 340` under a screen reader). */
+function tokenText(input, output, t) {
+    const g = t.glyph;
+    return `${g.caretUp} ${formatTokens(input ?? 0)} ${g.caretDown} ${formatTokens(output ?? 0)}`;
+}
+/**
+ * Render a {@link UsageSummary} to a single themed line. Honors the theme
+ * end-to-end: NO_COLOR yields zero ANSI (identity stylers), and screen-reader
+ * mode swaps the arrow glyphs for words. The count of requests that reported no
+ * usage is ALWAYS shown when non-zero, so the total is never mistaken for a
+ * complete accounting.
+ */
+export function renderSummary(summary, t) {
+    const sep = t.sep;
+    const parts = [t.strong("usage")];
+    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)}` : "";
+            parts.push(`${p.tier} ${tokenText(p.inputTokens, p.outputTokens, t)}${t.muted(cost)}`);
+        }
+        else {
+            // Every request on this tier reported nothing — say so, don't show 0.
+            parts.push(`${p.tier} ${t.muted(unreported(p.requestsWithoutUsage))}`);
+        }
+    }
+    // Total: known figures only. A run with no reported usage at all shows `—`,
+    // never a fabricated 0.
+    const totalKnown = summary.totalInputTokens !== undefined ||
+        summary.totalOutputTokens !== undefined;
+    const totalCost = summary.totalCost !== undefined
+        ? ` ${formatCost(summary.totalCost, summary.currency)}`
+        : "";
+    parts.push(totalKnown
+        ? `${t.strong("total")} ${tokenText(summary.totalInputTokens, summary.totalOutputTokens, t)}${t.muted(totalCost)}`
+        : `${t.strong("total")} —`);
+    // 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) {
+        parts.push(t.warning(unreported(summary.requestsWithoutUsage)));
+    }
+    return parts.join(sep);
+}
+/** `2 requests: usage not reported`. */
+function unreported(n) {
+    return `${n} request${n === 1 ? "" : "s"}: usage not reported`;
+}

package/dist/usage/types.d.ts

@@ -0,0 +1,220 @@
+import { z } from "zod";
+import { MODEL_TIERS } from "../brand/voice.js";
+/**
+ * Usage telemetry + cost tracking (C.22): types for LOCAL, honest usage
+ * accounting. Every number here is a real figure the provider reported — a token
+ * count is present only when the provider returned usage for that request, and
+ * `undefined` (never `0`) when it did not. Nothing in this module is ever
+ * transmitted anywhere (see the module barrel's no-phone-home note).
+ */
+/** Bump when the on-disk usage file shape changes (enables future migration). */
+export declare const USAGE_FILE_VERSION: 1;
+/**
+ * One model request's usage. A request that reported no usage keeps
+ * `inputTokens`/`outputTokens` as `undefined` — the honest "unknown", never
+ * zero-filled or re-tokenized. A provider-reported `0` is stored as `0` (a real
+ * count), so the two cases stay distinguishable downstream.
+ */
+export declare const UsageEntrySchema: z.ZodObject<{
+    /** The routing tier (C.30) this request ran on; absent when routing is inert. */
+    tier: z.ZodOptional<z.ZodString>;
+    /** Provider-reported prompt tokens; `undefined` ⇔ no usage was reported. */
+    inputTokens: z.ZodOptional<z.ZodNumber>;
+    /** Provider-reported completion tokens; `undefined` ⇔ no usage was reported. */
+    outputTokens: z.ZodOptional<z.ZodNumber>;
+    /** ISO-8601 timestamp the request completed. */
+    at: z.ZodString;
+}, "strict", z.ZodTypeAny, {
+    at: string;
+    tier?: string | undefined;
+    inputTokens?: number | undefined;
+    outputTokens?: number | undefined;
+}, {
+    at: string;
+    tier?: string | undefined;
+    inputTokens?: number | undefined;
+    outputTokens?: number | undefined;
+}>;
+export type UsageEntry = z.infer<typeof UsageEntrySchema>;
+/** One run's usage: an ordered list of per-request entries. */
+export declare const UsageRecordSchema: z.ZodObject<{
+    /** Unique id for this run (one `session.send`). */
+    runId: z.ZodString;
+    /** Groups runs of one interactive session, so `--session` aggregates them. */
+    sessionId: z.ZodOptional<z.ZodString>;
+    /** ISO-8601 timestamp the run started. */
+    startedAt: z.ZodString;
+    entries: z.ZodArray<z.ZodObject<{
+        /** The routing tier (C.30) this request ran on; absent when routing is inert. */
+        tier: z.ZodOptional<z.ZodString>;
+        /** Provider-reported prompt tokens; `undefined` ⇔ no usage was reported. */
+        inputTokens: z.ZodOptional<z.ZodNumber>;
+        /** Provider-reported completion tokens; `undefined` ⇔ no usage was reported. */
+        outputTokens: z.ZodOptional<z.ZodNumber>;
+        /** ISO-8601 timestamp the request completed. */
+        at: z.ZodString;
+    }, "strict", z.ZodTypeAny, {
+        at: string;
+        tier?: string | undefined;
+        inputTokens?: number | undefined;
+        outputTokens?: number | undefined;
+    }, {
+        at: string;
+        tier?: string | undefined;
+        inputTokens?: number | undefined;
+        outputTokens?: number | undefined;
+    }>, "many">;
+}, "strict", z.ZodTypeAny, {
+    entries: {
+        at: string;
+        tier?: string | undefined;
+        inputTokens?: number | undefined;
+        outputTokens?: number | undefined;
+    }[];
+    runId: string;
+    startedAt: string;
+    sessionId?: string | undefined;
+}, {
+    entries: {
+        at: string;
+        tier?: string | undefined;
+        inputTokens?: number | undefined;
+        outputTokens?: number | undefined;
+    }[];
+    runId: string;
+    startedAt: string;
+    sessionId?: string | undefined;
+}>;
+export type UsageRecord = z.infer<typeof UsageRecordSchema>;
+/** The persisted store: a bounded, newest-last list of run records. */
+export declare const UsageFileSchema: z.ZodObject<{
+    version: z.ZodLiteral<1>;
+    runs: z.ZodArray<z.ZodObject<{
+        /** Unique id for this run (one `session.send`). */
+        runId: z.ZodString;
+        /** Groups runs of one interactive session, so `--session` aggregates them. */
+        sessionId: z.ZodOptional<z.ZodString>;
+        /** ISO-8601 timestamp the run started. */
+        startedAt: z.ZodString;
+        entries: z.ZodArray<z.ZodObject<{
+            /** The routing tier (C.30) this request ran on; absent when routing is inert. */
+            tier: z.ZodOptional<z.ZodString>;
+            /** Provider-reported prompt tokens; `undefined` ⇔ no usage was reported. */
+            inputTokens: z.ZodOptional<z.ZodNumber>;
+            /** Provider-reported completion tokens; `undefined` ⇔ no usage was reported. */
+            outputTokens: z.ZodOptional<z.ZodNumber>;
+            /** ISO-8601 timestamp the request completed. */
+            at: z.ZodString;
+        }, "strict", z.ZodTypeAny, {
+            at: string;
+            tier?: string | undefined;
+            inputTokens?: number | undefined;
+            outputTokens?: number | undefined;
+        }, {
+            at: string;
+            tier?: string | undefined;
+            inputTokens?: number | undefined;
+            outputTokens?: number | undefined;
+        }>, "many">;
+    }, "strict", z.ZodTypeAny, {
+        entries: {
+            at: string;
+            tier?: string | undefined;
+            inputTokens?: number | undefined;
+            outputTokens?: number | undefined;
+        }[];
+        runId: string;
+        startedAt: string;
+        sessionId?: string | undefined;
+    }, {
+        entries: {
+            at: string;
+            tier?: string | undefined;
+            inputTokens?: number | undefined;
+            outputTokens?: number | undefined;
+        }[];
+        runId: string;
+        startedAt: string;
+        sessionId?: string | undefined;
+    }>, "many">;
+}, "strict", z.ZodTypeAny, {
+    version: 1;
+    runs: {
+        entries: {
+            at: string;
+            tier?: string | undefined;
+            inputTokens?: number | undefined;
+            outputTokens?: number | undefined;
+        }[];
+        runId: string;
+        startedAt: string;
+        sessionId?: string | undefined;
+    }[];
+}, {
+    version: 1;
+    runs: {
+        entries: {
+            at: string;
+            tier?: string | undefined;
+            inputTokens?: number | undefined;
+            outputTokens?: number | undefined;
+        }[];
+        runId: string;
+        startedAt: string;
+        sessionId?: string | undefined;
+    }[];
+}>;
+export type UsageFile = z.infer<typeof UsageFileSchema>;
+/**
+ * A per-tier price, in the user's own currency, PER MILLION TOKENS. Chosen over
+ * per-token so prices read the way LLM pricing is quoted and don't lose
+ * precision to tiny floats. Configured by the user under `usage.prices.<tier>`;
+ * cruxy ships NO prices (a bundled table would imply upstream identities and go
+ * stale) — with none configured, cost is omitted entirely.
+ */
+export interface TierPrice {
+    /** Price per 1,000,000 input tokens. */
+    input: number;
+    /** Price per 1,000,000 output tokens. */
+    output: number;
+}
+/**
+ * Prices keyed by TIER ONLY (kavi/vaani/mira) — the type literally cannot name
+ * an upstream model, so the U.8 gag holds by construction. Partial: any tier may
+ * be unpriced (its cost is then omitted, tokens still shown).
+ */
+export type PriceTable = Partial<Record<(typeof MODEL_TIERS)[number], TierPrice>>;
+/** Aggregated usage for one tier across the summarized runs. */
+export interface TierUsage {
+    tier: string;
+    /** Sum of KNOWN input tokens; `undefined` if no request on this tier reported usage. */
+    inputTokens?: number;
+    /** Sum of KNOWN output tokens; `undefined` if none reported. */
+    outputTokens?: number;
+    /** Requests attributed to this tier. */
+    requests: number;
+    /** How many of those reported no usage (surfaced, never silently dropped). */
+    requestsWithoutUsage: number;
+    /** Cost, ONLY when this tier is priced AND has known tokens; else omitted. */
+    cost?: number;
+}
+/** The aggregate over one or more runs — what the summary renderer consumes. */
+export interface UsageSummary {
+    perTier: TierUsage[];
+    /** Sum of KNOWN input tokens across all runs; `undefined` if none known. */
+    totalInputTokens?: number;
+    /** Sum of KNOWN output tokens across all runs; `undefined` if none known. */
+    totalOutputTokens?: 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). */
+    priced: boolean;
+    /** Currency label to prefix costs with; "" when the user configured none. */
+    currency: string;
+    /** Total requests across all runs that reported no usage (rendered visibly). */
+    requestsWithoutUsage: number;
+    /** Total requests across all runs. */
+    requests: number;
+    /** How many runs were aggregated. */
+    runCount: number;
+}

package/dist/usage/types.js

@@ -0,0 +1,47 @@
+import { z } from "zod";
+/**
+ * Usage telemetry + cost tracking (C.22): types for LOCAL, honest usage
+ * accounting. Every number here is a real figure the provider reported — a token
+ * count is present only when the provider returned usage for that request, and
+ * `undefined` (never `0`) when it did not. Nothing in this module is ever
+ * transmitted anywhere (see the module barrel's no-phone-home note).
+ */
+/** Bump when the on-disk usage file shape changes (enables future migration). */
+export const USAGE_FILE_VERSION = 1;
+/**
+ * One model request's usage. A request that reported no usage keeps
+ * `inputTokens`/`outputTokens` as `undefined` — the honest "unknown", never
+ * zero-filled or re-tokenized. A provider-reported `0` is stored as `0` (a real
+ * count), so the two cases stay distinguishable downstream.
+ */
+export const UsageEntrySchema = z
+    .object({
+    /** The routing tier (C.30) this request ran on; absent when routing is inert. */
+    tier: z.string().optional(),
+    /** Provider-reported prompt tokens; `undefined` ⇔ no usage was reported. */
+    inputTokens: z.number().int().nonnegative().optional(),
+    /** Provider-reported completion tokens; `undefined` ⇔ no usage was reported. */
+    outputTokens: z.number().int().nonnegative().optional(),
+    /** ISO-8601 timestamp the request completed. */
+    at: z.string(),
+})
+    .strict();
+/** One run's usage: an ordered list of per-request entries. */
+export const UsageRecordSchema = z
+    .object({
+    /** Unique id for this run (one `session.send`). */
+    runId: z.string(),
+    /** Groups runs of one interactive session, so `--session` aggregates them. */
+    sessionId: z.string().optional(),
+    /** ISO-8601 timestamp the run started. */
+    startedAt: z.string(),
+    entries: z.array(UsageEntrySchema),
+})
+    .strict();
+/** 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();

package/package.json

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