agent-nuvira 3.5.2 → 3.5.6

package/dist/learning/cost-ledger-maintenance.js

@@ -0,0 +1,289 @@
+/**
+ * Cost-ledger maintenance — the EXPLICIT, dry-run-default way to repair the rows
+ * already on disk. Nothing here runs on a read: the ledger is repaired only when
+ * an operator asks for it, and every figure it changes is reported before and
+ * after.
+ *
+ * WHY IT EXISTS. Two classes of row in a real profile are not what they look like,
+ * and neither can be fixed by a read:
+ *
+ *  1. LEGACY PRICES. Rows written before `costSource` existed carry a `costUsd`
+ *     computed from the retired hardcoded table (`cost-tracker.ts`'s five-entry
+ *     `DEFAULT_PRICING` plus a `$0.00010/1K` generic fallback). Read-side
+ *     classification already re-derives them for DISPLAY (`cost-classification.ts`
+ *     counts them in `recomputedCalls`), and deliberately never rewrites the file
+ *     — but `recordedTotalUsd` ("the ledger total as recorded") keeps showing the
+ *     old number, and a reprice is what turns the file itself honest.
+ *  2. TEST-ORIGIN ROWS. A row a test run wrote into a real profile. Rows written
+ *     since `origin` was added say so (`origin: 'test'`); rows from before have no
+ *     field at all, and the only sound evidence left in them is the model id — a
+ *     fixture id (`wire-stub-model`: MEASURED 747 rows in a real
+ *     `~/.nuvira/memory/cost-tracker.json`) could not have come from a real call.
+ *
+ * ─── WHAT IT REFUSES TO DO (read before changing either rule) ───────────────
+ *
+ *  - It does NOT re-derive a row that already carries `costSource`. That row was
+ *    written by today's rules under the config in force at the time; re-pricing it
+ *    with a config that has changed since would rewrite history to match the
+ *    present — the exact dishonesty this whole change removes.
+ *  - It does NOT pass a legacy row's stored `costUsd` back in as though the
+ *    provider had reported it. The stored number is the old estimate; feeding it
+ *    into `resolveCallCost` as `reportedCostUsd` would LAUNDER an estimate into an
+ *    exact-looking figure. Only a row already flagged `costReported: true` keeps
+ *    its number verbatim, because that flag was written by the old code and means
+ *    the same thing.
+ *  - It does NOT guess `origin`. A legacy row gets no origin field: we do not know
+ *    which process wrote it, and stamping `live` would make it unprunable forever.
+ *  - It NEVER writes without `apply`, and a write always leaves a `.bak` beside the
+ *    file (the ledger is the user's billing history; a reprice is reversible).
+ */
+import { copyFileSync, existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { dirname } from 'node:path';
+import { costLedgerPath } from './cost-tracker.js';
+import { classifyEntries, getPricingContext, } from './cost-classification.js';
+import { resolveCallCost } from './model-pricing.js';
+import { isFixtureModelId } from './model-selection.js';
+// ─── Row-level rules ────────────────────────────────────────────────────────
+/** True when the row is test-origin by evidence we can actually read. */
+export function testRowVerdict(entry) {
+    if (entry.origin === 'test')
+        return 'test-origin';
+    // An EXPLICIT `live` tag outranks the id heuristic — the same doctrine
+    // `telemetryOrigin` applies (a stated fact beats an inferred one). A row the
+    // recorder itself marked as real usage is not deleted for looking odd.
+    if (entry.origin === 'live')
+        return null;
+    // A fixture id is evidence from the row itself, and it is the ONLY evidence a
+    // legacy row can carry (no `origin` field existed when it was written).
+    if (isFixtureModelId(entry.model ?? ''))
+        return 'fixture-id';
+    return null;
+}
+/**
+ * Re-derive ONE legacy row. Returns the repaired row, or the SAME object when the
+ * row already carries `costSource` (never re-derived — see the header).
+ */
+function repriceRow(entry, ctx) {
+    if (entry.costSource !== undefined)
+        return entry;
+    const reported = entry.costReported === true ? entry.costUsd : undefined;
+    const resolved = resolveCallCost({
+        provider: entry.provider,
+        model: entry.model,
+        inputTokens: entry.inputTokens ?? 0,
+        outputTokens: entry.outputTokens ?? 0,
+        // Only a row ALREADY flagged as provider-reported keeps its figure verbatim.
+        ...(reported !== undefined ? { reportedCostUsd: reported } : {}),
+        billingTier: ctx.billingTierFor(entry.provider),
+        configPricing: ctx.configPricingFor(entry.provider),
+        catalogRow: ctx.catalogRowFor?.(entry.provider, entry.model),
+    });
+    return {
+        ...entry,
+        costUsd: resolved.billedUsd,
+        costSource: resolved.costSource,
+        ...(resolved.listUsd !== undefined ? { listPriceUsd: resolved.listUsd } : {}),
+        billingTier: resolved.billingTier,
+        pricingBasis: resolved.basis,
+        // `origin` is deliberately NOT set: unknown is not `live`.
+    };
+}
+// ─── The pass ───────────────────────────────────────────────────────────────
+/**
+ * Re-price a set of ledger rows and (optionally) drop the test rows among them.
+ * Pure: takes rows, returns rows — the file is written by `maintainCostLedger`.
+ */
+export function repriceLedgerEntries(entries, opts = {}) {
+    const ctx = opts.ctx ?? getPricingContext();
+    const prune = opts.pruneTestRows !== false;
+    const kept = [];
+    const removedCounts = new Map();
+    let repriced = 0;
+    let alreadyClassified = 0;
+    let testOriginRemoved = 0;
+    let fixtureRemoved = 0;
+    for (const entry of entries) {
+        const verdict = prune ? testRowVerdict(entry) : null;
+        if (verdict) {
+            if (verdict === 'test-origin')
+                testOriginRemoved += 1;
+            else
+                fixtureRemoved += 1;
+            const key = `${entry.provider}\u0000${entry.model}`;
+            const existing = removedCounts.get(key);
+            if (existing)
+                existing.count += 1;
+            else
+                removedCounts.set(key, {
+                    provider: entry.provider,
+                    model: entry.model,
+                    count: 1,
+                    fixtureId: verdict === 'fixture-id',
+                });
+            continue;
+        }
+        const repaired = repriceRow(entry, ctx);
+        if (repaired !== entry)
+            repriced += 1;
+        else
+            alreadyClassified += 1;
+        kept.push(repaired);
+    }
+    const beforeTotals = classifyEntries(entries, { ctx, excludeTestOrigin: false });
+    const afterTotals = classifyEntries(kept, { ctx, excludeTestOrigin: false });
+    const sumRecorded = (rows) => Math.round(rows.reduce((s, r) => s + (r.costUsd || 0), 0) * 100000) / 100000;
+    const sumTokens = (rows) => rows.reduce((s, r) => s + (r.totalTokens || 0), 0);
+    const unpricedCalls = (rows) => classifyEntries(rows, { ctx, excludeTestOrigin: false }).unpricedCalls;
+    const removed = [...removedCounts.values()].sort((a, b) => b.count - a.count);
+    const notes = [];
+    if (repriced > 0) {
+        notes.push(`${repriced} legacy row(s) re-priced from the ONE price source (provider catalog + declared model prices + your overrides) — no hardcoded table, no generic fallback.`);
+    }
+    if (alreadyClassified > 0) {
+        notes.push(`${alreadyClassified} row(s) already carried a cost classification and were left exactly as written.`);
+    }
+    if (testOriginRemoved + fixtureRemoved > 0) {
+        notes.push(`${testOriginRemoved} row(s) tagged \`origin: test\` and ${fixtureRemoved} row(s) with a test-fixture model id were removed — a test run is not your usage.`);
+    }
+    if (afterTotals.unverifiedListedUsd > 0) {
+        notes.push(`$${afterTotals.unverifiedListedUsd.toFixed(6)} of list-priced calls are still NOT counted as spend because the billing tier is undeclared: nuvira config set providers.<id>.billingTier paid|free|subscription`);
+    }
+    if (afterTotals.unpricedCalls > 0) {
+        notes.push(`${afterTotals.unpricedCalls} row(s) have no price evidence (an unknown provider, a pass-through gateway, or a model with no price source) — they contribute no dollars, which is honest but incomplete: set pricing.<provider>.inputPer1K/outputPer1K to price them.`);
+    }
+    if (prune && testOriginRemoved + fixtureRemoved === 0) {
+        notes.push('No test-origin rows found — new writes are tagged at record time, so this should stay at zero.');
+    }
+    return {
+        entries: kept,
+        report: {
+            rows: {
+                total: entries.length,
+                repriced,
+                alreadyClassified,
+                testOriginRemoved,
+                fixtureRemoved,
+                kept: kept.length,
+            },
+            before: {
+                recordedUsd: sumRecorded(entries),
+                tokens: sumTokens(entries),
+                unpricedCalls: unpricedCalls(entries),
+            },
+            after: {
+                recordedUsd: sumRecorded(kept),
+                tokens: sumTokens(kept),
+                billedUsd: afterTotals.billedUsd,
+                billedReportedUsd: afterTotals.billedReportedUsd,
+                billedListedUsd: afterTotals.billedListedUsd,
+                unverifiedListedUsd: afterTotals.unverifiedListedUsd,
+                notBilledValueUsd: afterTotals.notBilledValueUsd,
+                unpricedCalls: afterTotals.unpricedCalls,
+            },
+            removed,
+            notes,
+        },
+    };
+}
+// ─── File-level pass ────────────────────────────────────────────────────────
+/** Read the ledger file, tolerating absence and corruption the way the tracker does. */
+function readLedger(file) {
+    try {
+        if (!existsSync(file))
+            return { entries: [], version: 1 };
+        const parsed = JSON.parse(readFileSync(file, 'utf-8'));
+        return { entries: Array.isArray(parsed?.entries) ? parsed.entries : [], version: parsed?.version ?? 1 };
+    }
+    catch {
+        return { entries: [], version: 1 };
+    }
+}
+/**
+ * The whole pass against a FILE. `apply: false` (the default) reads and reports
+ * only — the dry run is the default because the ledger is billing history.
+ *
+ * On `apply` the previous file is copied to `<file>.bak` first (a fixed name, so
+ * the backup is the state immediately before THIS run and cannot itself grow a
+ * chain), and the rewrite goes through a temp-free single write.
+ */
+export function maintainCostLedger(opts = {}) {
+    const file = opts.file ?? costLedgerPath();
+    const ledger = readLedger(file);
+    const { entries, report } = repriceLedgerEntries(ledger.entries, {
+        ctx: opts.ctx,
+        pruneTestRows: opts.pruneTestRows,
+    });
+    let backupPath;
+    if (opts.apply) {
+        try {
+            const dir = dirname(file);
+            if (!existsSync(dir))
+                mkdirSync(dir, { recursive: true });
+            if (existsSync(file)) {
+                backupPath = `${file}.bak`;
+                copyFileSync(file, backupPath);
+            }
+            writeFileSync(file, JSON.stringify({ version: ledger.version, entries }, null, 2), 'utf-8');
+        }
+        catch (err) {
+            // A failed write is reported, never silently swallowed: the operator asked
+            // for a repair and must know it did not happen.
+            return {
+                file,
+                applied: false,
+                ...report,
+                notes: [...report.notes, `✗ write failed: ${err.message} — the ledger is unchanged.`],
+            };
+        }
+    }
+    return { file, applied: opts.apply === true, ...(backupPath ? { backupPath } : {}), ...report };
+}
+/** The report as text — shared by the CLI and the scripts wrapper. */
+export function formatMaintenanceReport(rep) {
+    const usd = (n) => `$${n.toFixed(6)}`;
+    const lines = [
+        rep.applied ? '🛠️  Cost Ledger Repriced (written)' : '🛠️  Cost Ledger Reprice — DRY RUN (nothing written)',
+        '',
+        `   File:  ${rep.file}${rep.backupPath ? `\n   Backup: ${rep.backupPath}` : ''}`,
+        '',
+        '── Rows ──',
+        `   total:              ${rep.rows.total}`,
+        `   re-priced:          ${rep.rows.repriced}  (legacy rows re-derived by today's rules)`,
+        `   already classified: ${rep.rows.alreadyClassified}  (left exactly as written)`,
+        `   removed (origin):   ${rep.rows.testOriginRemoved}  (tagged origin: test)`,
+        `   removed (fixture):  ${rep.rows.fixtureRemoved}  (model id could only be a fixture)`,
+        `   kept:               ${rep.rows.kept}`,
+        '',
+        '── Recorded total ──',
+        `   before: ${usd(rep.before.recordedUsd)}  (${rep.before.tokens} tokens, ${rep.before.unpricedCalls} unpriced calls)`,
+        `   after:  ${usd(rep.after.recordedUsd)}  (${rep.after.tokens} tokens, ${rep.after.unpricedCalls} unpriced calls)`,
+        '',
+        '── After re-pricing, by evidence ──',
+        `   🧾 provider-reported (exact):          ${usd(rep.after.billedReportedUsd)}`,
+        `   📋 list-priced, account paid:          ${usd(rep.after.billedListedUsd)}`,
+        `   = billed:                              ${usd(rep.after.billedUsd)}`,
+        `   ❓ list-priced, tier undeclared:        ${usd(rep.after.unverifiedListedUsd)}  (not counted as spend)`,
+        `   🎁 free/subscription value at list:    ${usd(rep.after.notBilledValueUsd)}`,
+        '',
+    ];
+    if (rep.removed.length > 0) {
+        lines.push('── Rows that would be removed ──');
+        for (const r of rep.removed.slice(0, 20)) {
+            lines.push(`   ${String(r.count).padStart(6)} × ${(r.provider + '/' + r.model).slice(0, 60)}${r.fixtureId ? '  (fixture id)' : '  (origin: test)'}`);
+        }
+        if (rep.removed.length > 20)
+            lines.push(`   … and ${rep.removed.length - 20} more pair(s)`);
+        lines.push('');
+    }
+    if (rep.notes.length > 0) {
+        lines.push('── Notes ──');
+        for (const n of rep.notes)
+            lines.push(`   • ${n}`);
+        lines.push('');
+    }
+    if (!rep.applied) {
+        lines.push('   Nothing was written. Re-run with --apply to write (a .bak is kept).', '');
+    }
+    return lines.join('\n');
+}
+//# sourceMappingURL=cost-ledger-maintenance.js.map

package/dist/learning/cost-ledger-maintenance.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"cost-ledger-maintenance.js","sourceRoot":"","sources":["../../src/learning/cost-ledger-maintenance.ts"],"names":[],"mappings":"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"}

package/dist/learning/cost-reconcile.d.ts

@@ -0,0 +1,160 @@
+/**
+ * Cost reconciliation — the ONLY way the word "actual" can be earned.
+ *
+ * WHAT THIS REPLACES. Every figure the ledger reports is, at best, an ESTIMATE of
+ * money owed: a provider-reported per-call cost is exact about the call, and a
+ * list price on a declared-`paid` account is a guess at the bill. Neither is the
+ * bill. The ledger cannot see one, so the honest headline is "billed by evidence
+ * — $X" and never "you paid $X". This module closes that gap the only way it can
+ * be closed: the operator reads the provider's OWN number off the invoice and
+ * enters it, and everything else here is arithmetic on two figures that came from
+ * outside this machine.
+ *
+ * WHAT IT IS NOT. It never guesses an invoice, never scales one, and never
+ * "adjusts" the ledger to match. It reports the difference and what the
+ * difference most likely consists of — unpriced calls, calls whose list price was
+ * never claimed as spend (an undeclared billing tier), or rows the ledger is
+ * missing.
+ *
+ * ─── THE BILLING FACT, EARNED (read before changing tierEvidence) ───────────
+ *
+ * `providers.<id>.billingTier` decides whether a list-priced call is money owed
+ * (`paid`) or value absorbed (`free`/`subscription`), and it is the single fact
+ * that moves the headline the most. Being user-declared, it is an assumption —
+ * which is exactly what this change is here to remove. An invoice is evidence,
+ * so this module states what the invoice PROVES, and the CLI refuses to record a
+ * tier the invoice contradicts:
+ *
+ *   - $0 charged across N calls in the window, and nothing billed by evidence
+ *     → the key is not being charged per call: `free` is EVIDENCED.
+ *   - A charge that matches the per-call costs the provider itself reported
+ *     → the key is metered and billed: `paid` is EVIDENCED.
+ *   - Anything else (a flat fee, a discounted charge, a mismatch) proves only
+ *     what it says: the key IS charged. `subscription` and `paid` cannot be told
+ *     apart from one invoice line, so no tier is claimed — the operator picks,
+ *     and the CLI says why it is asking rather than picking for them.
+ *
+ * A period that has not closed yet must not be reconciled against (`--days` on a
+ * running month reads a partial invoice). The window is always printed with the
+ * result so the comparison can be judged, and `--until` exists to pin it.
+ */
+import { type ClassifiableEntry, type PricingContext } from './cost-classification.js';
+import type { BillingTier } from './model-pricing.js';
+/**
+ * What the operator read off the provider's bill. Every field is REQUIRED except
+ * `note`: a window is not optional, because comparing an all-time ledger to a
+ * monthly invoice is a meaningless subtraction dressed up as a number.
+ */
+export interface InvoiceClaim {
+    /** The provider id the invoice line belongs to (e.g. `deepseek`). */
+    provider: string;
+    /** The provider's own figure for the window, USD. */
+    invoiceUsd: number;
+    /** Inclusive window start (epoch ms) — normally the billing period's start. */
+    since: number;
+    /**
+     * EXCLUSIVE window end (epoch ms) — normally the billing period's end. Half-open
+     * so consecutive periods cannot count a boundary row twice.
+     *
+     * A caller whose end is a LIVE "now" must pass `now + 1`, not `now`: a ledger
+     * row's timestamp is `Date.now()` and so is the caller's, in the same
+     * millisecond resolution, so an exclusive `now` silently drops whatever was
+     * recorded in the current millisecond (MEASURED — the CLI's default window did
+     * exactly this and reported "no ledger rows for <provider> in this window").
+     */
+    until: number;
+    /** Where the number came from, printed verbatim (e.g. "dashboard, Oct 2026"). */
+    note?: string;
+}
+/**
+ * How the invoice and the ledger relate. Three values, because "off by $0.40"
+ * and "off by $6.30 in the same direction" are different claims with different
+ * remedies, and a boolean would flatten them.
+ */
+export type ReconciliationVerdict = 'match' | 'under-evidenced' | 'over-recorded';
+export interface CostReconciliation {
+    provider: string;
+    since: number;
+    until: number;
+    /** The provider's own figure — the ONE number here that is not ours. */
+    invoiceUsd: number;
+    note?: string;
+    /** Ledger rows for this provider inside the window (test-origin excluded). */
+    requests: number;
+    tokens: number;
+    /** Evidence-backed bill: provider-reported + list-priced with a declared paid account. */
+    billedUsd: number;
+    /** The exact part (provider stated each call's charge). */
+    billedReportedUsd: number;
+    /** The estimated part (list price, account declared `paid`). */
+    billedListedUsd: number;
+    /** List-priced but the tier is undeclared: real tokens, no claim of spend. */
+    unverifiedListedUsd: number;
+    /** List price of calls a free/subscription tier absorbed — never spend. */
+    notBilledValueUsd: number;
+    /** Calls with no price evidence at all (unknown provider or pass-through gateway). */
+    unpricedCalls: number;
+    /** Test-origin rows in the window — excluded from every figure above. */
+    testOriginCalls: number;
+    /** `invoiceUsd - billedUsd`. Positive = the provider charged more than we can evidence. */
+    deltaUsd: number;
+    /** The band inside which the two are called equal (see `toleranceFor`). */
+    toleranceUsd: number;
+    verdict: ReconciliationVerdict;
+    /** One line naming exactly what was compared. Always printed. */
+    basis: string;
+    /** What the invoice PROVES about the key's billing tier, when it proves it. */
+    tierEvidence?: {
+        tier: BillingTier;
+        basis: string;
+    };
+    /** What could account for a non-zero delta — the actionable part. */
+    hints: string[];
+}
+/**
+ * Reconcile a provider's invoice against the ledger rows in the same window.
+ *
+ * Pure with respect to the ledger: it reads rows and returns a report; nothing is
+ * written and no row is modified. `provider` matching is exact — a per-provider
+ * invoice must never be compared against a whole-profile total.
+ *
+ * Test-origin rows are excluded from EVERY figure (a fixture call is not a charge)
+ * and counted in `testOriginCalls`, so a window can be checked for the rows that
+ * were hidden rather than silently shrinking.
+ */
+export declare function reconcileEntries(claim: InvoiceClaim, entries: readonly ClassifiableEntry[], ctx?: PricingContext): CostReconciliation;
+/**
+ * A reconciliation as stored. `recordedAt` is when the operator entered the
+ * invoice figure — a reconciliation is a statement about a moment, and a stored
+ * one without a date invites being read as current.
+ */
+export interface StoredReconciliation extends CostReconciliation {
+    recordedAt: number;
+}
+/** Where the reconciliation records live, resolved lazily (see cost-tracker). */
+export declare function reconciliationLedgerPath(): string;
+/**
+ * Every recorded reconciliation, newest first. Never throws — a corrupt file
+ * reads as empty, because this is display/audit data and a broken history must
+ * not take down the cost page.
+ */
+export declare function readReconciliations(opts?: {
+    file?: string;
+}): StoredReconciliation[];
+/**
+ * Persist a reconciliation. Appending rather than replacing on purpose: the
+ * HISTORY is the audit trail ("this was checked against the October invoice, and
+ * the delta was 3 cents"), and a later check must not erase what an earlier one
+ * established.
+ */
+export declare function recordReconciliation(rec: CostReconciliation, opts?: {
+    file?: string;
+    at?: number;
+}): StoredReconciliation;
+/** The most recent record for a provider, or undefined. */
+export declare function lastReconciliationFor(provider: string, opts?: {
+    file?: string;
+}): StoredReconciliation | undefined;
+/** The reconciliation, as text — shared by the CLI and any surface that prints it. */
+export declare function formatReconciliation(rec: StoredReconciliation | CostReconciliation): string;
+//# sourceMappingURL=cost-reconcile.d.ts.map

package/dist/learning/cost-reconcile.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cost-reconcile.d.ts","sourceRoot":"","sources":["../../src/learning/cost-reconcile.ts"],"names":[],"mappings":"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"}