@cruxy/cli 1.0.2 → 1.0.4

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

package/dist/agent/budget.d.ts

@@ -1,52 +0,0 @@
-import type { Usage } from "@cruxy/sdk";
-import type { LoopBudget } from "./loop.js";
-/**
- * The live budget primitive for the agent loop: iteration + token + optional
- * wall-clock caps, checked by {@link runAgent} before every model turn (see
- * `LoopBudget`). A tripped cap stops the run with a human-readable reason and
- * the coherent partial history — the loop never runs unbounded.
- *
- * It lives beside the loop it guards: the loop defines the `LoopBudget` seam,
- * this is its one concrete implementation, and the subagent orchestrator, the
- * job manager, and {@link Session} (per-turn token guard) all consume it.
- */
-/**
- * Hard caps a run executes under. `maxTokens` is always finite; `maxIterations`
- * is finite for a subagent (bounded by construction) but may be
- * `Number.POSITIVE_INFINITY` for a token-only guard where iteration count is
- * bounded elsewhere (a main turn is already capped by `agent.maxIterations` in
- * the loop). `timeoutMs` is an optional wall-clock backstop on top.
- */
-export interface BudgetLimits {
-    /** Cap on the run's model turns (may be `Infinity` for a token-only guard). */
-    maxIterations: number;
-    /** Cap on the run's combined input+output tokens. */
-    maxTokens: number;
-    /** Optional wall-clock cap in milliseconds. */
-    timeoutMs?: number;
-}
-/**
- * Resolve the effective limits for one spawn: start from the configured
- * ceilings and let overrides only *narrow* them. A request above a ceiling is
- * clamped down, not honored — "budget overrides within limits" by construction.
- */
-export declare function resolveBudget(defaults: BudgetLimits, overrides?: Partial<BudgetLimits>): BudgetLimits;
-/**
- * A live budget for one run. The wall clock starts at construction (spawn /
- * turn start); the clock source is injectable so tests never sleep.
- */
-export declare class Budget implements LoopBudget {
-    private readonly limits;
-    private readonly now;
-    private readonly startedAt;
-    constructor(limits: BudgetLimits, now?: () => number);
-    /**
-     * The reason to stop before the next model turn, or `null` to continue.
-     * Checked at iteration boundaries — the in-flight turn always completes, so
-     * overshoot is bounded by one turn.
-     */
-    exceeded(state: {
-        iterations: number;
-        usage: Usage;
-    }): string | null;
-}

package/dist/agent/index.d.ts

@@ -1,3 +0,0 @@
-export * from "./loop.js";
-export * from "./session.js";
-export * from "./prompts.js";

package/dist/agent/loop.d.ts

@@ -1,159 +0,0 @@
-import type { Message, Provider, Usage } from "@cruxy/sdk";
-import type { CruxyConfig } from "../config/index.js";
-import type { HookEvent } from "../hooks/index.js";
-import type { StreamRenderer } from "../render/index.js";
-import { type Router, type TaskClass } from "../routing/index.js";
-import type { ToolContext } from "../tools/index.js";
-import { ToolRegistry } from "../tools/index.js";
-/** Optional per-fire context (C.26 step 5). For tool-scoped events the loop
- * passes the raw tool-call `input` so a multi-root {@link HookRouter} can resolve
- * the ONE acting root and fire only that root's hooks. Session lifecycle events
- * (`before-run`/`after-run`) carry no hint — they have no acting root and fan
- * every trusted root. Ignored by the single-root runner. */
-export interface HookFireHint {
-    input?: unknown;
-}
-/** The lifecycle-hook firing seam (C.19). Structural so the loop stays
- * decoupled from the concrete `HookRunner`. `fire` resolves when hooks pass (or
- * advisory ones fail) and throws `CRUXY_E_HOOK_FAILED` on a blocking failure. */
-export interface LifecycleHookRunner {
-    fire(event: HookEvent, ctx: ToolContext, hint?: HookFireHint): Promise<void>;
-}
-export interface RunAgentArgs {
-    /**
-     * The full running conversation. The caller owns history and must append the
-     * user turn before calling; `runAgent` does not fabricate the initial array.
-     */
-    messages: Message[];
-    /** A constructed provider to stream from. */
-    provider: Provider;
-    /** The tool catalogue advertised to the model and dispatched against. */
-    registry: ToolRegistry;
-    /** Resolved CLI configuration (turn ceiling, etc.). */
-    config: CruxyConfig;
-    /** Ambient capabilities handed to each tool. */
-    ctx: ToolContext;
-    /**
-     * The render seam (U.2): assistant text streams through `renderer.write`
-     * delta by delta (each non-empty segment closed via `endSegment`), and
-     * tool-call progress is surfaced as transient `status` + committed `note`
-     * lines. When omitted, behavior is unchanged (one buffered print per turn,
-     * no tool-call chrome). The loop never touches stdout directly.
-     */
-    renderer?: StreamRenderer;
-    /** Git context (branch + dirty) for the system prompt's Environment section. */
-    git?: {
-        branch: string;
-        dirty: boolean;
-    } | null;
-    /** Project instructions (e.g. from CRUXY.md) folded into the system prompt. */
-    projectInstructions?: string | null;
-    /** Persistent memory (C.29): the pre-rendered recall block for the system
-     * prompt, or null. Reference data only — never influences the U.3 gate. */
-    recalledMemory?: string | null;
-    /** Plan mode's propose phase (C.31): inject the plan-first system directive. */
-    planMode?: boolean;
-    /** Subagent runs (C.14): inject the bounded-subtask system directive. */
-    subagent?: boolean;
-    /**
-     * Optional hard budget (C.14): checked before every model turn; a non-null
-     * reason stops the loop with `stop: "budget"` and the partial history. The
-     * in-flight turn (model call + its tool executions) always completes, so
-     * histories stay coherent — overshoot is bounded by one turn.
-     */
-    budget?: LoopBudget;
-    /**
-     * Lifecycle hooks (C.19). When set, `before-tool` fires before each tool call
-     * (a blocking failure fails the call closed — the tool does NOT run), and
-     * `after-tool` / `on-file-change` fire after. Omitted for subagents and the
-     * no-hooks path, so their tools never fire hooks.
-     */
-    hooks?: LifecycleHookRunner;
-    /**
-     * Multi-model routing (C.30): when set, the tier for `taskClass` is resolved
-     * ONCE up front (fail loud before any model turn) and its wire model overrides
-     * the provider default for every turn in this run; the tier is surfaced on the
-     * live line. Omitted → no override, the provider's default model is used
-     * (unchanged behavior).
-     */
-    router?: Router;
-    /** 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;
-    /**
-     * Cooperative cancellation (C.33). When the signal aborts, the loop stops at
-     * the NEXT turn boundary and returns `stop: "aborted"` with the coherent
-     * partial history — the in-flight turn (model call + its tool executions)
-     * always completes first, exactly like a tripped {@link budget}, so overshoot
-     * is bounded by one turn. Used by the parallel orchestrator to cancel sibling
-     * subagents on a fatal failure or Ctrl-C; omitted → no cancellation (unchanged).
-     * The same signal reaches tools via `ctx.signal`, so an in-flight shell child
-     * is kill-tree'd rather than orphaned.
-     */
-    signal?: AbortSignal;
-    /**
-     * Mid-loop compaction seam (build item 3). Called at the top of every
-     * iteration with the running history; returns the history to continue from —
-     * unchanged when under threshold, or with its older prefix summarized away
-     * when over. Supplied by {@link Session}, which reuses its own
-     * threshold/cut/summarize machinery, so the loop gains no summarization
-     * knowledge and no logic is duplicated. Omitted → history is never compacted
-     * mid-loop (unchanged behavior; subagents pass nothing).
-     *
-     * This is what keeps a long autonomous turn — where `send` compacts only once
-     * up front and never again — within the context window: without it a run that
-     * drives dozens of tool calls (each result appended, some tens of KB) grows
-     * unbounded until the next `send`, which in one-shot never comes.
-     */
-    compact?: (messages: Message[]) => Promise<Message[]>;
-}
-/**
- * The budget seam for {@link runAgent}: implementations track their own caps
- * (iterations, tokens, wall clock — see `subagent/budget.ts`); the loop only
- * asks "may I start another turn?". Kept a one-method interface so future
- * callers (C.22 cost tracking) can slot in without touching the loop again.
- */
-export interface LoopBudget {
-    /**
-     * Return a human-readable reason to stop *before* the next model turn, or
-     * `null` to continue. `iterations` = model turns completed so far.
-     */
-    exceeded(state: {
-        iterations: number;
-        usage: Usage;
-    }): string | null;
-}
-export interface AgentResult {
-    /** The full conversation, including assistant tool calls and tool results. */
-    messages: Message[];
-    /** Number of model turns consumed. */
-    iterations: number;
-    /** Why the loop ended. */
-    stop: "completed" | "max_iterations" | "budget" | "aborted";
-    /** Which cap tripped, when `stop === "budget"` (from {@link LoopBudget}). */
-    stopReason?: string;
-    /** Accumulated token usage (stashed for cost tracking in C.22). */
-    usage: Usage;
-}
-/**
- * Drive the model/tool loop over an existing conversation. Streams each turn,
- * renders assistant text, reassembles tool calls, executes them, feeds the
- * results back, and repeats until the model stops calling tools or the turn
- * ceiling is hit.
- *
- * Requires a tool-capable provider — it throws up front otherwise rather than
- * silently running tool-less.
- */
-export declare function runAgent(args: RunAgentArgs): Promise<AgentResult>;

package/dist/agent/prompts.d.ts

@@ -1,69 +0,0 @@
-/**
- * cruxy-code agent prompts.
- *
- * These are ORIGINAL prompts written for cruxy — not copied from any other
- * tool. The system prompt is assembled at runtime from a static core plus a
- * dynamic environment block, so the model always knows where it is, what it
- * can do, and how it's expected to behave.
- */
-import type { ShellDialect } from "../tools/shell/resolve-shell.js";
-export interface ToolSummary {
-    name: string;
-}
-export interface PromptContext {
-    /** Absolute working directory the agent is rooted in. */
-    cwd: string;
-    /** node `process.platform`, e.g. "linux", "darwin", "win32". */
-    platform: string;
-    /** Provider/model string, for the model's self-awareness. */
-    model: string;
-    /** Current ISO date (so the model isn't guessing). */
-    date: string;
-    /** Tools available this session (from the tool registry). */
-    tools: ToolSummary[];
-    /** Optional git context, when the cwd is a repo. */
-    git?: {
-        branch: string;
-        dirty: boolean;
-    } | null;
-    /** Optional extra instructions (e.g. from a project CRUXY.md). */
-    projectInstructions?: string | null;
-    /**
-     * Persistent memory (C.29): the pre-rendered, demarcated recall block injected
-     * at session start. It is REFERENCE DATA, not instructions — the block carries
-     * its own data-only framing (see memory/recall.ts) and is appended as an
-     * ordinary section; the U.3 gate never reads it. Null when nothing is recalled.
-     */
-    recalledMemory?: string | null;
-    /** Plan mode's propose phase (C.31): inject the plan-first directive. */
-    planMode?: boolean;
-    /** Subagent run (C.14): inject the bounded-subtask directive. */
-    subagent?: boolean;
-    /**
-     * The resolved shell's command dialect (from resolve-shell.ts). When it is not
-     * a POSIX shell — e.g. PowerShell, because no Git Bash was found on Windows —
-     * a directive tells the model to emit that dialect instead of bash. Absent /
-     * "posix" → no directive (bash-isms are correct there; a nudge would be wrong).
-     */
-    shellDialect?: ShellDialect;
-}
-/** Assemble the full system prompt for a session. */
-export declare function buildSystemPrompt(ctx: PromptContext): string;
-/**
- * Compact reminder injected after tool results when the loop has run long, to
- * keep the model anchored to the original objective and the verify step.
- */
-export declare const PROGRESS_REMINDER = "Reminder: stay focused on the original task. Before declaring done, verify your change actually works (build/tests/lint), then summarize what changed.";
-/**
- * System prompt for the side conversation that compacts an over-long history
- * (see Session.compact). It runs as a standalone, tool-less completion over a
- * rendered transcript — the goal is a synopsis dense enough that the main loop
- * can continue without the verbatim prefix.
- */
-export declare const SUMMARY_SYSTEM = "You are compacting a coding assistant's conversation to fit within its context window. Summarize the conversation so far into a compact synopsis that preserves: decisions made and their rationale, concrete file paths and identifiers touched, the current state of the work, and any open or pending tasks. Be specific and terse \u2014 omit pleasantries and restated instructions. Output only the synopsis.";
-/**
- * Marker embedded in the synthetic messages that replace a compacted prefix, so
- * they're recognizable in the history (and fold cleanly into a later
- * re-summarization rather than being mistaken for live conversation).
- */
-export declare const COMPACTION_MARKER = "[conversation compacted]";