@cruxy/cli 0.18.0 → 0.19.0

package/dist/agent/loop.d.ts

@@ -72,6 +72,18 @@ export interface RunAgentArgs {
     /** The declared task class for routing; defaults to `main-turn`. Ignored
      * unless `router` is set. */
     taskClass?: TaskClass;
+    /**
+     * Usage telemetry (C.22): fired ONCE per completed model request with the
+     * routing tier (C.30) and the provider's usage for THAT request — or
+     * `usage: undefined` when the provider emitted no usage event, so the caller
+     * records it as unknown (never a fabricated zero). LOCAL accounting only:
+     * this is a callback into the process, nothing is transmitted. Omitted → no
+     * collection, behavior unchanged.
+     */
+    onRequestUsage?: (req: {
+        tier?: string;
+        usage?: Usage;
+    }) => void;
 }
 /**
  * The budget seam for {@link runAgent}: implementations track their own caps

package/dist/agent/loop.js

@@ -81,6 +81,12 @@ async function driveLoop(args, renderer, routed) {
         let turnText = "";
         const pending = new Map();
         const toolUses = [];
+        // Per-request usage capture for telemetry (C.22). `sawUsage` is the honesty
+        // pivot: a request that emits NO usage event stays `false`, so it is reported
+        // as unknown rather than a fabricated zero. A provider-reported 0 flips it
+        // true and is recorded as a real 0.
+        let sawUsage = false;
+        const reqUsage = { input_tokens: 0, output_tokens: 0 };
         // 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.
@@ -121,6 +127,12 @@ 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;
+                    // 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;
                     break;
                 case "message_stop":
                     // Turn complete; the stream ends after this.
@@ -131,6 +143,14 @@ async function driveLoop(args, renderer, routed) {
                     break;
             }
         }
+        // Request complete: report its usage honestly — the real figure when a usage
+        // 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.
+        args.onRequestUsage?.({
+            tier: routed?.tier,
+            usage: sawUsage ? { ...reqUsage } : undefined,
+        });
         // ── Record the assistant turn ───────────────────────────────────────────
         if (turnText) {
             // Streaming (renderer set): the text already reached the user delta by

package/dist/agent/session.d.ts

@@ -4,6 +4,7 @@ import type { StreamRenderer } from "../render/index.js";
 import { type Router } from "../routing/index.js";
 import type { ToolContext } from "../tools/index.js";
 import type { ToolRegistry } from "../tools/index.js";
+import { type RequestUsage, type UsageRecord } from "../usage/index.js";
 import { type AgentResult, type LifecycleHookRunner } from "./loop.js";
 /**
  * Plan-mode turn runner (C.31), injected so the agent package doesn't depend on
@@ -16,6 +17,10 @@ export type PlanRunner = (args: {
     projectInstructions: string | null;
     recalledMemory: string | null;
     renderer?: StreamRenderer;
+    /** Usage telemetry (C.22): forwarded to every model request the plan-mode
+     * turn drives (propose + each execution step), so plan runs are attributed
+     * exactly like a normal turn. */
+    onRequestUsage?: (req: RequestUsage) => void;
 }) => Promise<AgentResult>;
 export interface SessionArgs {
     /** A constructed provider to stream from. */
@@ -56,6 +61,12 @@ export interface SessionArgs {
      * context compaction on `summarize`; omitted → the provider default (unchanged).
      */
     router?: Router;
+    /**
+     * Usage telemetry sink (C.22): called once per `send` with that run's
+     * {@link UsageRecord} (real per-request usage, tier-attributed). The sink
+     * persists it locally — it never transmits. Omitted → no persistence.
+     */
+    onRunUsage?: (record: UsageRecord) => void;
 }
 /**
  * Estimate the token footprint of a message list with a cheap chars/4 heuristic
@@ -80,6 +91,12 @@ export declare class Session {
     messages: Message[];
     /** Token usage summed across every `send` (and every compaction) in this session. */
     readonly usage: Usage;
+    /** Stable id for this session (C.22), so a run's usage record groups with the
+     * other runs of the same interactive session (`cruxy usage --session`). */
+    readonly sessionId: string;
+    /** The most recent run's usage record (C.22) — the one-shot path reads it to
+     * print the end-of-run summary. */
+    lastRun?: UsageRecord;
     private readonly args;
     /** Mutable so `/reload` can refresh CRUXY.md mid-session. */
     private projectInstructions;
@@ -120,7 +137,7 @@ export declare class Session {
      * returns the number of older messages folded into the summary; otherwise
      * returns `null` (under threshold, nothing safe to cut, or summary failed).
      */
-    maybeCompact(): Promise<number | null>;
+    maybeCompact(onRequestUsage?: (req: RequestUsage) => void): Promise<number | null>;
     /**
      * Force compaction regardless of the threshold (backs `/compact`). Returns the
      * number of older messages summarized, or `null` if there was nothing safe to

package/dist/agent/session.js

@@ -1,5 +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 { runAgent, } from "./loop.js";
 import { SUMMARY_SYSTEM, COMPACTION_MARKER } from "./prompts.js";
 /**
@@ -47,6 +49,12 @@ export class Session {
     messages = [];
     /** Token usage summed across every `send` (and every compaction) in this session. */
     usage = { input_tokens: 0, output_tokens: 0 };
+    /** Stable id for this session (C.22), so a run's usage record groups with the
+     * other runs of the same interactive session (`cruxy usage --session`). */
+    sessionId = randomUUID();
+    /** The most recent run's usage record (C.22) — the one-shot path reads it to
+     * print the end-of-run summary. */
+    lastRun;
     args;
     /** Mutable so `/reload` can refresh CRUXY.md mid-session. */
     projectInstructions;
@@ -86,8 +94,15 @@ export class Session {
      */
     async send(userPrompt, renderer) {
         this.messages.push({ role: "user", content: userPrompt });
+        // Usage telemetry (C.22): one collector per run. `onReq` is threaded into
+        // every real model request this turn drives — the main loop, compaction, and
+        // (in plan mode) the propose + execution steps — so usage is captured exactly
+        // where the provider reports it, honestly (unknown when it reports nothing).
+        const collector = new UsageCollector();
+        const startedAt = new Date().toISOString();
+        const onReq = (req) => collector.record(req);
         // Compact *before* the agent call so the turn runs against a bounded history.
-        await this.maybeCompact();
+        await this.maybeCompact(onReq);
         // before-run (C.19): a blocking pre-run hook — or an untrusted project's
         // hooks — throws here and aborts the turn before the model is engaged
         // (fail-closed). No-op when hooks are disabled or none are registered.
@@ -101,6 +116,7 @@ export class Session {
                 projectInstructions: this.projectInstructions,
                 recalledMemory: this.args.recalledMemory ?? null,
                 renderer,
+                onRequestUsage: onReq,
             })
             : await runAgent({
                 messages: this.messages,
@@ -110,10 +126,17 @@ export class Session {
                 projectInstructions: this.projectInstructions,
                 planMode: false, // the plan directive belongs only to the runner's propose phase
                 renderer,
+                onRequestUsage: onReq,
             });
         this.messages = result.messages;
         this.usage.input_tokens += result.usage.input_tokens;
         this.usage.output_tokens += result.usage.output_tokens;
+        // Publish the run's usage record (C.22): stash it for the one-shot summary
+        // and hand it to the persistence sink. Building the record never touches the
+        // network and never blocks the turn's result.
+        const record = collector.toRecord(randomUUID(), this.sessionId, startedAt);
+        this.lastRun = record;
+        this.args.onRunUsage?.(record);
         // after-run (C.19): advisory by default (a blocking after-run hook throws
         // and surfaces at the boundary). The turn already completed and its history
         // is adopted above — an advisory failure never rewrites it.
@@ -139,12 +162,12 @@ export class Session {
      * returns the number of older messages folded into the summary; otherwise
      * returns `null` (under threshold, nothing safe to cut, or summary failed).
      */
-    async maybeCompact() {
+    async maybeCompact(onRequestUsage) {
         const { maxTokens, compactThreshold } = this.args.config.context;
         if (estimateTokens(this.messages) <= compactThreshold * maxTokens) {
             return null;
         }
-        const n = await this.runCompaction();
+        const n = await this.runCompaction(onRequestUsage);
         if (n) {
             this.args.ctx.logger.info(`compacted ${n} older message${n === 1 ? "" : "s"} to stay within context`);
         }
@@ -164,7 +187,7 @@ export class Session {
      * failed summary call leaves the history untouched and returns `null` (fail
      * open — losing compaction is degraded, not unsafe).
      */
-    async runCompaction() {
+    async runCompaction(onRequestUsage) {
         const cut = this.findCut();
         if (cut === null)
             return null;
@@ -172,7 +195,7 @@ export class Session {
         const kept = this.messages.slice(cut);
         let synopsis;
         try {
-            const summary = await this.summarize(prefix);
+            const summary = await this.summarize(prefix, onRequestUsage);
             synopsis = summary.text;
             this.usage.input_tokens += summary.usage.input_tokens;
             this.usage.output_tokens += summary.usage.output_tokens;
@@ -225,7 +248,7 @@ export class Session {
      * Summarize a prefix via a standalone, tool-less provider call over a rendered
      * transcript. Throws on a stream error or empty output so callers fail open.
      */
-    async summarize(prefix) {
+    async summarize(prefix, onRequestUsage) {
         const transcript = renderTranscript(prefix);
         const usage = { input_tokens: 0, output_tokens: 0 };
         let text = "";
@@ -234,6 +257,9 @@ export class Session {
         const routed = this.args.router
             ? 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.
+        let sawUsage = false;
         for await (const ev of this.args.provider.stream({
             system: SUMMARY_SYSTEM,
             messages: [{ role: "user", content: transcript }],
@@ -246,6 +272,7 @@ export class Session {
                 case "usage":
                     usage.input_tokens = ev.usage.input_tokens || usage.input_tokens;
                     usage.output_tokens += ev.usage.output_tokens;
+                    sawUsage = true;
                     break;
                 case "error":
                     throw ev.error;
@@ -253,6 +280,11 @@ export class Session {
                     break;
             }
         }
+        // Attribute this compaction request to the `summarize` tier honestly.
+        onRequestUsage?.({
+            tier: routed?.tier,
+            usage: sawUsage ? { ...usage } : undefined,
+        });
         if (!text.trim())
             throw new Error("summary was empty");
         return { text: text.trim(), usage };

package/dist/cli/commands/run.js

@@ -4,6 +4,7 @@ import { loadConfig, resolveApiKey } from "../../config/index.js";
 import { authMissingKey, shouldUseColor, usageError, } from "../../errors/index.js";
 import { createRenderer } from "../../render/index.js";
 import { themeForColor } from "../../theme/index.js";
+import { summarizeRuns, renderSummary, } from "../../usage/index.js";
 import { CheckpointService } from "../../checkpoint/index.js";
 import { SandboxService } from "../../sandbox/index.js";
 import { buildHooksService } from "../../hooks/index.js";
@@ -110,5 +111,23 @@ export function runCommand() {
         finally {
             renderer.close();
         }
+        // End-of-run usage summary (C.22): honest tokens + per-tier breakdown +
+        // cost (only when priced). Printed after the live region is torn down.
+        // Reaches here only on success — a thrown run propagates past it — and
+        // never affects the run's outcome.
+        if (config.usage.enabled && session.lastRun) {
+            printRunUsage(session.lastRun, config);
+        }
+    });
+}
+/** Render the just-finished run's usage as a single themed line (C.22). */
+function printRunUsage(record, config) {
+    if (record.entries.length === 0)
+        return;
+    const t = themeForColor(shouldUseColor(process.stdout));
+    const summary = summarizeRuns([record], {
+        prices: config.usage.prices,
+        currency: config.usage.currency,
     });
+    logger.print(renderSummary(summary, t));
 }

package/dist/cli/commands/usage.d.ts

@@ -0,0 +1,9 @@
+import { Command } from "commander";
+/**
+ * `cruxy usage` (C.22) — show LOCAL token usage and (when priced) cost, read
+ * back from `~/.cruxy/usage`. Read-only and local: it prints your own accounting
+ * and transmits nothing. Every figure is real — a request the provider never
+ * reported usage for is shown as unreported, never a fabricated number, and cost
+ * appears only for tiers you have priced.
+ */
+export declare function usageCommand(): Command;

package/dist/cli/commands/usage.js

@@ -0,0 +1,81 @@
+import { Command } from "commander";
+import { loadConfig } from "../../config/index.js";
+import { shouldUseColor, usageError } from "../../errors/index.js";
+import { themeForColor } from "../../theme/index.js";
+import { logger } from "../../utils/logger.js";
+import { loadUsage, summarizeRuns, renderSummary, } from "../../usage/index.js";
+/**
+ * `cruxy usage` (C.22) — show LOCAL token usage and (when priced) cost, read
+ * back from `~/.cruxy/usage`. Read-only and local: it prints your own accounting
+ * and transmits nothing. Every figure is real — a request the provider never
+ * reported usage for is shown as unreported, never a fabricated number, and cost
+ * appears only for tiers you have priced.
+ */
+export function usageCommand() {
+    return new Command("usage")
+        .description("show token usage and cost for the session and recent runs")
+        .option("--session", "only the most recent session's runs")
+        .option("--last <n>", "only the last N runs")
+        .action((opts) => {
+        const t = themeForColor(shouldUseColor(process.stdout));
+        const { config } = loadConfig();
+        // A corrupt/unreadable store is surfaced as CRUXY_E_USAGE_READ with an
+        // actionable fix — it is not silently ignored, and it never crashes.
+        const { data, error } = loadUsage();
+        if (error)
+            throw error;
+        const scoped = selectRuns(data.runs, opts);
+        if (scoped.length === 0) {
+            logger.print(t.muted("no usage recorded yet"));
+            if (!config.usage.enabled) {
+                logger.print(t.muted("usage tracking is off (usage.enabled = false)"));
+            }
+            return;
+        }
+        const summary = summarizeRuns(scoped, {
+            prices: config.usage.prices,
+            currency: config.usage.currency,
+        });
+        const scopeLabel = opts.session
+            ? "current session"
+            : opts.last
+                ? `last ${scoped.length} run${scoped.length === 1 ? "" : "s"}`
+                : `all ${scoped.length} run${scoped.length === 1 ? "" : "s"}`;
+        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.
+        if (!summary.priced) {
+            logger.print(t.muted("cost omitted — no prices configured (set usage.prices.<tier>.{input,output}, per million tokens)"));
+        }
+    });
+}
+/**
+ * Narrow the stored runs to the requested scope. `--last N` keeps the newest N;
+ * `--session` keeps the runs sharing the most recent run's session id; no flag
+ * keeps everything retained. `--session` and `--last` are mutually exclusive.
+ */
+function selectRuns(runs, opts) {
+    if (opts.session && opts.last !== undefined) {
+        throw usageError("pass only one of --session or --last", [
+            "cruxy usage --session   (the most recent session)",
+            "cruxy usage --last 5    (the last 5 runs)",
+        ]);
+    }
+    if (opts.last !== undefined) {
+        const n = Number(opts.last);
+        if (!Number.isInteger(n) || n <= 0) {
+            throw usageError(`--last must be a positive integer (got "${opts.last}")`);
+        }
+        return runs.slice(-n);
+    }
+    if (opts.session) {
+        const latest = runs[runs.length - 1];
+        if (!latest)
+            return [];
+        // Runs without a session id can't be grouped; scope to the latest run alone.
+        if (latest.sessionId === undefined)
+            return [latest];
+        return runs.filter((r) => r.sessionId === latest.sessionId);
+    }
+    return [...runs];
+}

package/dist/cli/program.js

@@ -16,6 +16,7 @@ import { rollbackCommand } from "./commands/rollback.js";
 import { testCommand } from "./commands/test.js";
 import { hooksCommand } from "./commands/hooks.js";
 import { memoryCommand } from "./commands/memory.js";
+import { usageCommand } from "./commands/usage.js";
 import { loadConfig } from "../config/index.js";
 import { maybeRunOnboarding } from "./onboard.js";
 export function buildProgram() {
@@ -47,6 +48,7 @@ export function buildProgram() {
     program.addCommand(testCommand());
     program.addCommand(hooksCommand());
     program.addCommand(memoryCommand());
+    program.addCommand(usageCommand());
     // Default action: bare `cruxy` -> entrypoint. An unrecognized first operand
     // means an unknown command (Commander runs the default action with it as an
     // operand rather than erroring), so reject it as a usage error.

package/dist/cli/session-factory.js

@@ -9,6 +9,7 @@ import { Session, } from "../agent/index.js";
 import { PlanExecutionPolicy, runPlanSession } from "../plan/index.js";
 import { routerForConfig } from "../routing/index.js";
 import { MemoryService, rememberTool } from "../memory/index.js";
+import { appendRun } from "../usage/index.js";
 import { SubagentOrchestrator, makeSpawnSubagentTool, } from "../subagent/index.js";
 /**
  * Wrap a PromptIO so the live region yields before any prompt text lands
@@ -102,6 +103,19 @@ export function buildAgentSession(config, apiKey, cwd, ttyInteractive, planMode
     // session, so the default path threads `undefined` and behaves exactly as
     // before. One router is shared by the main loop, subagents, and plan mode.
     const router = routerForConfig(config) ?? undefined;
+    // Usage telemetry (C.22): when enabled, each run's usage record is persisted
+    // to the LOCAL store. Best-effort and non-fatal — a corrupt/unwritable store
+    // is downgraded to a warning (CRUXY_E_USAGE_READ) and NEVER takes a run down.
+    // Nothing is transmitted. Off → the sink is undefined and no usage is written.
+    const onRunUsage = config.usage.enabled
+        ? (record) => {
+            const { error } = appendRun(record, {
+                retention: config.usage.retention,
+            });
+            if (error)
+                logger.warn(`${error.code}: ${error.title} — ${error.cause}`);
+        }
+        : undefined;
     const execRegistry = buildDefaultRegistry();
     const git = getGitInfo(cwd);
     const projectInstructions = loadProjectInstructions(cwd);
@@ -168,7 +182,7 @@ export function buildAgentSession(config, apiKey, cwd, ttyInteractive, planMode
             requestApproval: gate(approval),
             sandbox,
         };
-        const planRunner = ({ messages, projectInstructions, recalledMemory: turnMemory, renderer: turnRenderer, }) => runPlanSession({
+        const planRunner = ({ messages, projectInstructions, recalledMemory: turnMemory, renderer: turnRenderer, onRequestUsage, }) => runPlanSession({
             provider,
             config,
             ctx,
@@ -182,6 +196,7 @@ export function buildAgentSession(config, apiKey, cwd, ttyInteractive, planMode
             recalledMemory: turnMemory,
             renderer: turnRenderer,
             router,
+            onRequestUsage,
         });
         return new Session({
             provider,
@@ -195,6 +210,7 @@ export function buildAgentSession(config, apiKey, cwd, ttyInteractive, planMode
             planRunner,
             hooks,
             router,
+            onRunUsage,
         });
     }
     const approval = new ApprovalService({
@@ -213,5 +229,6 @@ export function buildAgentSession(config, apiKey, cwd, ttyInteractive, planMode
         recalledMemory,
         hooks,
         router,
+        onRunUsage,
     });
 }