@cruxy/cli 0.17.0 → 0.19.0

package/dist/memory/store.js

@@ -0,0 +1,100 @@
+import { mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import path from "node:path";
+import { globalDir } from "../config/paths.js";
+import { GLOBAL_DIR_NAME, MEMORY_DIR_NAME, MEMORY_FILE_NAME, } from "../constants.js";
+import { containsSecret } from "./secrets.js";
+import { MemoryEntrySchema, MemoryFileSchema, MEMORY_FILE_VERSION, } from "./types.js";
+/** The default source files for a project root. */
+export function defaultMemorySources(cwd) {
+    const root = path.resolve(cwd);
+    return {
+        user: path.join(globalDir(), MEMORY_DIR_NAME, MEMORY_FILE_NAME),
+        project: path.join(root, GLOBAL_DIR_NAME, MEMORY_DIR_NAME, MEMORY_FILE_NAME),
+    };
+}
+/**
+ * Read and validate one scope's file. A missing file yields an empty result
+ * (not an error). Each entry is (1) schema-validated and (2) scanned for secret
+ * content; failures are excluded and collected. The returned `entries` all carry
+ * the requested `scope` (the on-disk `scope` field is normalized to it, so a
+ * mislabeled entry can't cross scopes).
+ */
+export function loadScope(file, scope) {
+    let raw;
+    try {
+        raw = readFileSync(file, "utf8");
+    }
+    catch {
+        // Missing / unreadable → nothing recalled from this scope (not an error).
+        return { entries: [], errors: [] };
+    }
+    let parsedFile;
+    try {
+        parsedFile = JSON.parse(raw);
+    }
+    catch {
+        return {
+            entries: [],
+            errors: [
+                { scope, reason: "invalid", id: "(file)", message: "not valid JSON" },
+            ],
+        };
+    }
+    const fileResult = MemoryFileSchema.safeParse(parsedFile);
+    if (!fileResult.success) {
+        return {
+            entries: [],
+            errors: [
+                {
+                    scope,
+                    reason: "invalid",
+                    id: "(file)",
+                    message: `malformed memory file: ${fileResult.error.issues[0]?.message ?? "invalid shape"}`,
+                },
+            ],
+        };
+    }
+    const entries = [];
+    const errors = [];
+    fileResult.data.entries.forEach((candidate, i) => {
+        const parsed = MemoryEntrySchema.safeParse(candidate);
+        if (!parsed.success) {
+            const id = candidate && typeof candidate === "object" && "id" in candidate
+                ? String(candidate.id)
+                : `#${i}`;
+            errors.push({
+                scope,
+                reason: "invalid",
+                id,
+                message: parsed.error.issues[0]?.message ?? "invalid entry",
+            });
+            return;
+        }
+        // Secrets denylist on LOAD (defense in depth): a hand-edited file cannot
+        // smuggle a secret into context even though `remember` also refuses on write.
+        const scan = containsSecret(parsed.data.content);
+        if (scan.secret) {
+            errors.push({
+                scope,
+                reason: "secret",
+                id: parsed.data.id,
+                message: `excluded — content looks like a secret (${scan.kind})`,
+            });
+            return;
+        }
+        // Normalize scope to the file it came from (never trust the on-disk label to
+        // move an entry across scopes).
+        entries.push({ ...parsed.data, scope });
+    });
+    return { entries, errors };
+}
+/**
+ * Persist a scope's entries, overwriting the file. Creates the memory dir if
+ * needed. The user scope is written `0600` (it is personal, cross-project data);
+ * the project scope inherits normal repo permissions (it may be committed).
+ */
+export function saveScope(file, entries, scope) {
+    mkdirSync(path.dirname(file), { recursive: true });
+    const body = JSON.stringify({ version: MEMORY_FILE_VERSION, entries }, null, 2);
+    writeFileSync(file, body, scope === "user" ? { mode: 0o600 } : undefined);
+}

package/dist/memory/trust.d.ts

@@ -0,0 +1,52 @@
+import type { MemoryEntry, MemoryTrust } from "./types.js";
+/**
+ * The project-MEMORY trust model (C.29) — the exact supply-chain treatment C.19
+ * applies to project hooks, but with its OWN store so memory and hook trust are
+ * independent (the hook `trust.json` keys a single fingerprint per root; sharing
+ * it would couple the two, so memory gets `~/.cruxy/memory-trust.json`).
+ *
+ * Trust is recorded in the GLOBAL dir — in the user's home, NEVER inside a repo —
+ * so cloning a repo carries zero memory trust and an attacker cannot ship a
+ * pre-trusted marker. It is bound to a {@link fingerprintMemory fingerprint} of
+ * the exact project entries seen at trust time and re-checked on every run: if
+ * the project's memory changes, the fingerprint no longer matches and trust is
+ * stale → the entries are not recalled until re-trusted. This defeats
+ * trust-then-swap.
+ */
+/** ~/.cruxy/memory-trust.json */
+export declare function memoryTrustPath(): string;
+/**
+ * A stable content fingerprint of a repo's PROJECT memory entries. Canonical by
+ * construction so a benign reformat (reordered entries, whitespace, added/removed
+ * `id`/`createdAt` metadata) does NOT change it, while any change to the
+ * meaning-bearing content DOES:
+ * - only `kind` + `content` are hashed (id/createdAt/scope are not meaning);
+ * - content is whitespace-normalized (trim + collapse runs);
+ * - entries are sorted so order doesn't matter.
+ *
+ * The empty set has a fixed fingerprint — trusting "no project memory" is
+ * meaningful (adding the first foreign entry re-gates).
+ */
+export declare function fingerprintMemory(entries: readonly MemoryEntry[]): string;
+/** The persisted trust seam — file-backed in production, injectable for tests. */
+export interface MemoryTrustStore {
+    /** The recorded decision for a repo root, or undefined if never trusted. */
+    get(root: string): MemoryTrust | undefined;
+    /** Persist a trust decision (overwrites any prior one for the same root). */
+    record(trust: MemoryTrust): void;
+}
+/**
+ * Is this repo's current project memory trusted? True only when a decision
+ * exists AND its fingerprint matches the current one — changed project memory is
+ * treated as untrusted (stale), forcing a fresh `cruxy memory trust`.
+ */
+export declare function isMemoryTrusted(store: MemoryTrustStore, root: string, currentFingerprint: string): boolean;
+/**
+ * The real store, persisting to `~/.cruxy/memory-trust.json` as
+ * `{ [root]: MemoryTrust }`. Reads are lazy + cached; a corrupt file is treated
+ * as "no trust recorded" (fail-closed — a broken trust file must never grant
+ * trust).
+ */
+export declare function fileMemoryTrustStore(file?: string): MemoryTrustStore;
+/** An in-memory store for tests (and any ephemeral run). */
+export declare function memoryMemoryTrustStore(seed?: MemoryTrust[]): MemoryTrustStore;

package/dist/memory/trust.js

@@ -0,0 +1,106 @@
+import { createHash } from "node:crypto";
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import path from "node:path";
+import { globalDir } from "../config/paths.js";
+import { MEMORY_TRUST_FILE_NAME } from "../constants.js";
+/**
+ * The project-MEMORY trust model (C.29) — the exact supply-chain treatment C.19
+ * applies to project hooks, but with its OWN store so memory and hook trust are
+ * independent (the hook `trust.json` keys a single fingerprint per root; sharing
+ * it would couple the two, so memory gets `~/.cruxy/memory-trust.json`).
+ *
+ * Trust is recorded in the GLOBAL dir — in the user's home, NEVER inside a repo —
+ * so cloning a repo carries zero memory trust and an attacker cannot ship a
+ * pre-trusted marker. It is bound to a {@link fingerprintMemory fingerprint} of
+ * the exact project entries seen at trust time and re-checked on every run: if
+ * the project's memory changes, the fingerprint no longer matches and trust is
+ * stale → the entries are not recalled until re-trusted. This defeats
+ * trust-then-swap.
+ */
+/** ~/.cruxy/memory-trust.json */
+export function memoryTrustPath() {
+    return path.join(globalDir(), MEMORY_TRUST_FILE_NAME);
+}
+/**
+ * A stable content fingerprint of a repo's PROJECT memory entries. Canonical by
+ * construction so a benign reformat (reordered entries, whitespace, added/removed
+ * `id`/`createdAt` metadata) does NOT change it, while any change to the
+ * meaning-bearing content DOES:
+ * - only `kind` + `content` are hashed (id/createdAt/scope are not meaning);
+ * - content is whitespace-normalized (trim + collapse runs);
+ * - entries are sorted so order doesn't matter.
+ *
+ * The empty set has a fixed fingerprint — trusting "no project memory" is
+ * meaningful (adding the first foreign entry re-gates).
+ */
+export function fingerprintMemory(entries) {
+    const canonical = entries
+        .map((e) => [e.kind, e.content.trim().replace(/\s+/g, " ")])
+        .sort((a, b) => a[0] === b[0] ? a[1].localeCompare(b[1]) : a[0].localeCompare(b[0]));
+    return createHash("sha256").update(JSON.stringify(canonical)).digest("hex");
+}
+/**
+ * Is this repo's current project memory trusted? True only when a decision
+ * exists AND its fingerprint matches the current one — changed project memory is
+ * treated as untrusted (stale), forcing a fresh `cruxy memory trust`.
+ */
+export function isMemoryTrusted(store, root, currentFingerprint) {
+    const record = store.get(path.resolve(root));
+    return record !== undefined && record.fingerprint === currentFingerprint;
+}
+// ── file-backed store ─────────────────────────────────────────────────────────
+/**
+ * The real store, persisting to `~/.cruxy/memory-trust.json` as
+ * `{ [root]: MemoryTrust }`. Reads are lazy + cached; a corrupt file is treated
+ * as "no trust recorded" (fail-closed — a broken trust file must never grant
+ * trust).
+ */
+export function fileMemoryTrustStore(file = memoryTrustPath()) {
+    let cache = null;
+    const load = () => {
+        if (cache)
+            return cache;
+        try {
+            const raw = JSON.parse(readFileSync(file, "utf8"));
+            cache =
+                raw && typeof raw === "object"
+                    ? raw
+                    : {};
+        }
+        catch {
+            // Missing or corrupt → no trust (fail-closed).
+            cache = {};
+        }
+        return cache;
+    };
+    return {
+        get(root) {
+            return load()[path.resolve(root)];
+        },
+        record(trust) {
+            const store = load();
+            store[path.resolve(trust.root)] = {
+                ...trust,
+                root: path.resolve(trust.root),
+            };
+            mkdirSync(path.dirname(file), { recursive: true });
+            // 0600: trust records name local paths; keep them owner-only.
+            writeFileSync(file, JSON.stringify(store, null, 2), { mode: 0o600 });
+            if (existsSync(file))
+                cache = store;
+        },
+    };
+}
+/** An in-memory store for tests (and any ephemeral run). */
+export function memoryMemoryTrustStore(seed = []) {
+    const store = new Map();
+    for (const t of seed)
+        store.set(path.resolve(t.root), t);
+    return {
+        get: (root) => store.get(path.resolve(root)),
+        record: (trust) => void store.set(path.resolve(trust.root), {
+            ...trust,
+            root: path.resolve(trust.root),
+        }),
+    };
+}

package/dist/memory/types.d.ts

@@ -0,0 +1,101 @@
+import { z } from "zod";
+/**
+ * Types for persistent memory (C.29). Everything here is **data**: a memory
+ * entry is validated (fail-loud, malformed excluded) and stored as structured
+ * JSON that is NEVER eval'd. Recalled entries are injected into the model's
+ * context as clearly-demarcated REFERENCE DATA (see `recall.ts`) — they are not
+ * instructions and can never grant authority: the U.3 approval gate is
+ * structural and does not read memory at all (proven in `recall.test.ts`).
+ */
+/**
+ * What a memory entry records. A small, closed set — the enum is the extension
+ * point (out of scope: freeform blobs, which we deliberately reject).
+ * - `fact` — a durable fact about the user or project.
+ * - `decision` — a choice made and its rationale.
+ * - `preference` — how the user likes things done.
+ */
+export declare const MEMORY_KINDS: readonly ["fact", "decision", "preference"];
+export type MemoryKind = (typeof MEMORY_KINDS)[number];
+/**
+ * Where an entry lives. `user` (`~/.cruxy/memory`) is your own memory, authored
+ * on this machine → trusted. `project` (`<repo>/.cruxy/memory`) can arrive with
+ * a cloned repo (another author) → untrusted until explicitly trusted (see
+ * `trust.ts`). This is the supply-chain boundary.
+ */
+export declare const MEMORY_SCOPES: readonly ["user", "project"];
+export type MemoryScope = (typeof MEMORY_SCOPES)[number];
+/** Recall renders `user` first (trusted, cross-project), then `project`. */
+export declare const MEMORY_SCOPE_ORDER: readonly MemoryScope[];
+/** Hard cap on a single note's length — memory is for terse facts, not blobs;
+ * this also bounds the per-entry cost of the recall budget. */
+export declare const MAX_CONTENT_CHARS = 2000;
+/**
+ * Strict schema for one memory entry as persisted. `.strict()` rejects unknown
+ * keys so a malformed/foreign object is a loud validation error (excluded), not
+ * silently absorbed. Parsed with this on every load — the file is never trusted
+ * shape-wise just because it is JSON.
+ */
+export declare const MemoryEntrySchema: z.ZodObject<{
+    /** Stable unique id (crypto.randomUUID) — the handle for `forget`. */
+    id: z.ZodString;
+    kind: z.ZodEnum<["fact", "decision", "preference"]>;
+    /** The note. DATA, never instructions. Non-empty, length-capped. */
+    content: z.ZodString;
+    scope: z.ZodEnum<["user", "project"]>;
+    /** ISO 8601 timestamp the entry was recorded. */
+    createdAt: z.ZodString;
+}, "strict", z.ZodTypeAny, {
+    id: string;
+    kind: "fact" | "decision" | "preference";
+    createdAt: string;
+    content: string;
+    scope: "project" | "user";
+}, {
+    id: string;
+    kind: "fact" | "decision" | "preference";
+    createdAt: string;
+    content: string;
+    scope: "project" | "user";
+}>;
+export type MemoryEntry = z.infer<typeof MemoryEntrySchema>;
+/** Current on-disk file version — lets a future migration detect old files. */
+export declare const MEMORY_FILE_VERSION = 1;
+/** The whole `entries.json` file shape (one file per scope). */
+export declare const MemoryFileSchema: z.ZodObject<{
+    version: z.ZodDefault<z.ZodNumber>;
+    entries: z.ZodDefault<z.ZodArray<z.ZodUnknown, "many">>;
+}, "strict", z.ZodTypeAny, {
+    entries: unknown[];
+    version: number;
+}, {
+    entries?: unknown[] | undefined;
+    version?: number | undefined;
+}>;
+/** Why an entry was rejected on load — surfaced, never silently dropped. */
+export type MemoryLoadReason = "invalid" | "secret";
+/** A rejected entry (malformed, or a detected secret), excluded from recall and
+ * from the writable set, and surfaced loudly. */
+export interface MemoryLoadError {
+    scope: MemoryScope;
+    reason: MemoryLoadReason;
+    /** The offending entry's id when known (else a positional marker). */
+    id: string;
+    message: string;
+}
+/** The validated result of loading one scope's file: the good entries plus the
+ * excluded ones. A missing file is not an error — it yields an empty result. */
+export interface MemoryLoad {
+    entries: MemoryEntry[];
+    errors: MemoryLoadError[];
+}
+/** One repo's recorded PROJECT-memory trust decision (persisted in
+ * `~/.cruxy/memory-trust.json`). The `fingerprint` binds trust to the exact
+ * project entries seen at trust time, so editing them re-gates (see `trust.ts`). */
+export interface MemoryTrust {
+    /** Absolute project root. */
+    root: string;
+    /** sha256 of the canonicalized project entries (see `fingerprintMemory`). */
+    fingerprint: string;
+    /** ISO timestamp the decision was recorded. */
+    at: string;
+}

package/dist/memory/types.js

@@ -0,0 +1,58 @@
+import { z } from "zod";
+/**
+ * Types for persistent memory (C.29). Everything here is **data**: a memory
+ * entry is validated (fail-loud, malformed excluded) and stored as structured
+ * JSON that is NEVER eval'd. Recalled entries are injected into the model's
+ * context as clearly-demarcated REFERENCE DATA (see `recall.ts`) — they are not
+ * instructions and can never grant authority: the U.3 approval gate is
+ * structural and does not read memory at all (proven in `recall.test.ts`).
+ */
+// ── entry kind + scope ────────────────────────────────────────────────────────
+/**
+ * What a memory entry records. A small, closed set — the enum is the extension
+ * point (out of scope: freeform blobs, which we deliberately reject).
+ * - `fact` — a durable fact about the user or project.
+ * - `decision` — a choice made and its rationale.
+ * - `preference` — how the user likes things done.
+ */
+export const MEMORY_KINDS = ["fact", "decision", "preference"];
+/**
+ * Where an entry lives. `user` (`~/.cruxy/memory`) is your own memory, authored
+ * on this machine → trusted. `project` (`<repo>/.cruxy/memory`) can arrive with
+ * a cloned repo (another author) → untrusted until explicitly trusted (see
+ * `trust.ts`). This is the supply-chain boundary.
+ */
+export const MEMORY_SCOPES = ["user", "project"];
+/** Recall renders `user` first (trusted, cross-project), then `project`. */
+export const MEMORY_SCOPE_ORDER = ["user", "project"];
+// ── entry schema ──────────────────────────────────────────────────────────────
+/** Hard cap on a single note's length — memory is for terse facts, not blobs;
+ * this also bounds the per-entry cost of the recall budget. */
+export const MAX_CONTENT_CHARS = 2000;
+/**
+ * Strict schema for one memory entry as persisted. `.strict()` rejects unknown
+ * keys so a malformed/foreign object is a loud validation error (excluded), not
+ * silently absorbed. Parsed with this on every load — the file is never trusted
+ * shape-wise just because it is JSON.
+ */
+export const MemoryEntrySchema = z
+    .object({
+    /** Stable unique id (crypto.randomUUID) — the handle for `forget`. */
+    id: z.string().min(1),
+    kind: z.enum(MEMORY_KINDS),
+    /** The note. DATA, never instructions. Non-empty, length-capped. */
+    content: z.string().min(1).max(MAX_CONTENT_CHARS),
+    scope: z.enum(MEMORY_SCOPES),
+    /** ISO 8601 timestamp the entry was recorded. */
+    createdAt: z.string().min(1),
+})
+    .strict();
+/** Current on-disk file version — lets a future migration detect old files. */
+export const MEMORY_FILE_VERSION = 1;
+/** The whole `entries.json` file shape (one file per scope). */
+export const MemoryFileSchema = z
+    .object({
+    version: z.number().int().positive().default(MEMORY_FILE_VERSION),
+    entries: z.array(z.unknown()).default([]),
+})
+    .strict();

package/dist/plan/service.d.ts

@@ -1,4 +1,4 @@
-import type { Message, Provider } from "@cruxy/sdk";
+import type { Message, Provider, Usage } from "@cruxy/sdk";
 import type { CruxyConfig } from "../config/index.js";
 import type { PromptIO } from "../approval/index.js";
 import { ToolRegistry, type ToolContext } from "../tools/index.js";
@@ -34,6 +34,9 @@ export interface PlanSessionArgs {
         dirty: boolean;
     } | null;
     projectInstructions?: string | null;
+    /** Persistent memory (C.29): recall block injected into the propose + execute
+     * phases' system prompts (reference data only). */
+    recalledMemory?: string | null;
     renderer?: StreamRenderer;
     /** Revision cap (defaults to {@link MAX_PLAN_REVISIONS}). */
     maxRevisions?: number;
@@ -42,5 +45,14 @@ export interface PlanSessionArgs {
      * and step execution on `main-turn`; omitted → the provider default.
      */
     router?: Router;
+    /**
+     * Usage telemetry (C.22): forwarded to every model request the plan turn
+     * drives (propose + each execution step), so plan-mode usage is captured and
+     * tier-attributed exactly like a normal turn.
+     */
+    onRequestUsage?: (req: {
+        tier?: string;
+        usage?: Usage;
+    }) => void;
 }
 export declare function runPlanSession(args: PlanSessionArgs): Promise<AgentResult>;

package/dist/plan/service.js

@@ -73,10 +73,12 @@ export async function runPlanSession(args) {
             ctx: args.ctx,
             git: args.git,
             projectInstructions: args.projectInstructions,
+            recalledMemory: args.recalledMemory,
             renderer: args.renderer,
             planMode: true,
             router: args.router,
             taskClass: "plan",
+            onRequestUsage: args.onRequestUsage,
         }));
         if (!holder.plan) {
             throw planInvalid("the model ended its turn without calling submit_plan");
@@ -107,9 +109,11 @@ export async function runPlanSession(args) {
                     ctx: args.ctx,
                     git: args.git,
                     projectInstructions: args.projectInstructions,
+                    recalledMemory: args.recalledMemory,
                     renderer: args.renderer,
                     router: args.router,
                     taskClass: "main-turn",
+                    onRequestUsage: args.onRequestUsage,
                 }));
             };
             await executePlan(plan, {

package/dist/usage/collect.d.ts

@@ -0,0 +1,40 @@
+import type { Usage } from "@cruxy/sdk";
+import type { UsageRecord } from "./types.js";
+/**
+ * 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.
+ */
+/** What the loop hands over for one completed request. */
+export interface RequestUsage {
+    /** The routing tier (C.30) the request ran on, if routing was active. */
+    tier?: string;
+    /**
+     * The provider's usage for THIS request, or `undefined` when the provider
+     * emitted no usage event (⇒ tokens are unknown, not zero).
+     */
+    usage?: Usage;
+}
+/** Wall clock as an injectable seam so tests are deterministic. */
+export type Clock = () => string;
+export declare class UsageCollector {
+    private readonly now;
+    private readonly entries;
+    constructor(now?: Clock);
+    /**
+     * Record one completed request. When `req.usage` is absent the entry's token
+     * counts stay `undefined` — the provider reported nothing, so we assert
+     * nothing. A real reported `0` is preserved as `0`.
+     */
+    record(req: RequestUsage): void;
+    /** How many requests have been recorded so far. */
+    get count(): number;
+    /** Snapshot the collected entries into a persistable {@link UsageRecord}. */
+    toRecord(runId: string, sessionId: string | undefined, startedAt: string): UsageRecord;
+}

package/dist/usage/collect.js

@@ -0,0 +1,34 @@
+const systemClock = () => new Date().toISOString();
+export class UsageCollector {
+    now;
+    entries = [];
+    constructor(now = systemClock) {
+        this.now = now;
+    }
+    /**
+     * Record one completed request. When `req.usage` is absent the entry's token
+     * counts stay `undefined` — the provider reported nothing, so we assert
+     * nothing. A real reported `0` is preserved as `0`.
+     */
+    record(req) {
+        this.entries.push({
+            tier: req.tier,
+            inputTokens: req.usage?.input_tokens,
+            outputTokens: req.usage?.output_tokens,
+            at: this.now(),
+        });
+    }
+    /** How many requests have been recorded so far. */
+    get count() {
+        return this.entries.length;
+    }
+    /** Snapshot the collected entries into a persistable {@link UsageRecord}. */
+    toRecord(runId, sessionId, startedAt) {
+        return {
+            runId,
+            ...(sessionId !== undefined ? { sessionId } : {}),
+            startedAt,
+            entries: [...this.entries],
+        };
+    }
+}

package/dist/usage/cost.d.ts

@@ -0,0 +1,19 @@
+import type { PriceTable, TierPrice } from "./types.js";
+/**
+ * Token → cost mapping (C.22). The whole discipline lives in one rule: a cost is
+ * produced ONLY when the tier has a configured price AND at least one token side
+ * is known. Otherwise the result is `undefined` — cost is omitted, tokens are
+ * still shown, and NO dollar figure is ever fabricated. Prices are per MILLION
+ * tokens (see {@link TierPrice}). Keyed by tier only (U.8 gag). No network.
+ */
+/** The configured price for a tier, or `undefined` when the tier is unpriced. */
+export declare function priceForTier(tier: string, prices: PriceTable): TierPrice | undefined;
+/**
+ * Compute the cost of a tier's usage, or `undefined` when it cannot be stated
+ * honestly:
+ *  - no configured price for the tier → `undefined` (cost omitted).
+ *  - both token counts unknown → `undefined` (nothing real to price).
+ * A known side is priced; an unknown side contributes nothing (never a
+ * fabricated 0-token charge). tokens/1e6 × price, summed.
+ */
+export declare function costFor(tier: string, inputTokens: number | undefined, outputTokens: number | undefined, prices: PriceTable): number | undefined;

package/dist/usage/cost.js

@@ -0,0 +1,29 @@
+/**
+ * Token → cost mapping (C.22). The whole discipline lives in one rule: a cost is
+ * produced ONLY when the tier has a configured price AND at least one token side
+ * is known. Otherwise the result is `undefined` — cost is omitted, tokens are
+ * still shown, and NO dollar figure is ever fabricated. Prices are per MILLION
+ * tokens (see {@link TierPrice}). Keyed by tier only (U.8 gag). No network.
+ */
+/** The configured price for a tier, or `undefined` when the tier is unpriced. */
+export function priceForTier(tier, prices) {
+    return prices[tier];
+}
+/**
+ * Compute the cost of a tier's usage, or `undefined` when it cannot be stated
+ * honestly:
+ *  - no configured price for the tier → `undefined` (cost omitted).
+ *  - both token counts unknown → `undefined` (nothing real to price).
+ * A known side is priced; an unknown side contributes nothing (never a
+ * fabricated 0-token charge). tokens/1e6 × price, summed.
+ */
+export function costFor(tier, inputTokens, outputTokens, prices) {
+    const price = priceForTier(tier, prices);
+    if (!price)
+        return undefined;
+    if (inputTokens === undefined && outputTokens === undefined)
+        return undefined;
+    const inCost = inputTokens !== undefined ? (inputTokens / 1_000_000) * price.input : 0;
+    const outCost = outputTokens !== undefined ? (outputTokens / 1_000_000) * price.output : 0;
+    return inCost + outCost;
+}

package/dist/usage/index.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Usage telemetry + cost tracking (C.22) — LOCAL usage accounting only.
+ *
+ * NO-PHONE-HOME GUARANTEE: nothing here transmits anything. This module reads
+ * and writes ONE local file under `~/.cruxy/usage` and renders to the terminal;
+ * it imports no provider, no transport, and makes no `fetch`/HTTP call. The
+ * `@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.
+ */
+export * from "./types.js";
+export { UsageCollector, type RequestUsage, type Clock } from "./collect.js";
+export { costFor, priceForTier } from "./cost.js";
+export { loadUsage, appendRun, usageStorePath } from "./store.js";
+export { summarizeRuns, renderSummary, formatCost, type SummarizeOptions, } from "./summary.js";

package/dist/usage/index.js

@@ -0,0 +1,15 @@
+/**
+ * Usage telemetry + cost tracking (C.22) — LOCAL usage accounting only.
+ *
+ * NO-PHONE-HOME GUARANTEE: nothing here transmits anything. This module reads
+ * and writes ONE local file under `~/.cruxy/usage` and renders to the terminal;
+ * it imports no provider, no transport, and makes no `fetch`/HTTP call. The
+ * `@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.
+ */
+export * from "./types.js";
+export { UsageCollector } from "./collect.js";
+export { costFor, priceForTier } from "./cost.js";
+export { loadUsage, appendRun, usageStorePath } from "./store.js";
+export { summarizeRuns, renderSummary, formatCost, } from "./summary.js";