agent-nuvira 3.5.2 → 3.5.6

package/dist/learning/cost-classification.js

@@ -0,0 +1,294 @@
+/**
+ * Cost classification — the ONE place that decides which bucket a ledger row
+ * belongs to, and what "billed" means for it.
+ *
+ * WHY IT IS ITS OWN MODULE. Three surfaces judge the same rows — `cost-tracker`
+ * (the CLI summary), `web-dashboard/server` (the Cost page + `/api/cost`) and the
+ * reconciliation check — and the defect being fixed is precisely that two places
+ * priced the same call differently (a hardcoded ledger table vs the provider
+ * catalog, disagreeing 25×–100×). So the rule lives here, once, and every surface
+ * asks this module instead of deriving its own answer.
+ *
+ * THE ONE THING TO UNDERSTAND. A ledger row carries two different dollar amounts,
+ * and the bug was conflating them:
+ *
+ *   billedUsd     money we have EVIDENCE was charged.
+ *                 - exact when the provider reported the call's cost,
+ *                 - an estimate when the account is declared `paid` and a list
+ *                   price is known,
+ *                 - otherwise 0 (free tier, unknown price, pass-through gateway).
+ *   listValueUsd  what the same tokens would cost at the resolved list price —
+ *                 the VALUE a free/subscription tier absorbed, and the figure an
+ *                 undeclared account's rows sit at until the tier is declared.
+ *
+ * Neither is ever presented as the other, and "unpriced" is a first-class answer
+ * rather than a fabricated rate (see `model-pricing.ts` for why: a generic
+ * `$0.00010/1K` fallback invented $0.40 of spend on a localhost gateway and
+ * under-reported the one provider the user actually pays for).
+ *
+ * ─── LEGACY ROWS (read before changing classifyEntry) ───────────────────────
+ *
+ * Rows written before this module existed have no `costSource`: their `costUsd`
+ * came from the old hardcoded table. They are NOT trusted for classification and
+ * NOT silently relabelled. They are re-derived HERE, at read time, from the fields
+ * they do carry (provider, model, tokens, `costReported`) using TODAY's rules —
+ * and counted in `recomputedCalls` so a reader can tell re-derived rows from
+ * recorded ones. The file is never rewritten by a read: mutating a profile's
+ * history to make a dashboard look right is the failure this whole change exists
+ * to remove. `scripts/prune-cost-ledger-rows.mjs` is the explicit, dry-run-default
+ * way to rewrite them.
+ */
+import { ConfigManager } from '../config/manager.js';
+import { asBillingTier, resolveCallCost, } from './model-pricing.js';
+/** Everything is `unknown`/unset — the honest floor when config cannot be read. */
+export const UNKNOWN_PRICING_CONTEXT = {
+    billingTierFor: () => 'unknown',
+    configPricingFor: () => undefined,
+};
+/** Build a context from a loaded config (the production path). */
+export function configPricingContext(cm) {
+    return {
+        billingTierFor(provider) {
+            try {
+                const p = (cm.getAll().providers || {})[provider];
+                return asBillingTier(p?.billingTier);
+            }
+            catch {
+                return 'unknown';
+            }
+        },
+        configPricingFor(provider) {
+            try {
+                const p = (cm.getAll().pricing || {})[provider];
+                if (!p)
+                    return undefined;
+                const input = typeof p.inputPer1K === 'number' ? p.inputPer1K : undefined;
+                const output = typeof p.outputPer1K === 'number' ? p.outputPer1K : undefined;
+                if (input === undefined && output === undefined)
+                    return undefined;
+                // A half-declared override is not a price: filling the missing side with
+                // the other one would invent a rate the user never wrote.
+                if (input === undefined || output === undefined)
+                    return undefined;
+                return { inputPer1K: input, outputPer1K: output };
+            }
+            catch {
+                return undefined;
+            }
+        },
+    };
+}
+/** A process-wide override for hosts and tests. `null` restores the config path. */
+let overrideContext = null;
+let cachedConfigContext = null;
+export function setPricingContext(ctx) {
+    overrideContext = ctx;
+}
+/** Drop the cached config-backed context (tests that switch profiles mid-file). */
+export function resetPricingContextCache() {
+    cachedConfigContext = null;
+    overrideContext = null;
+}
+/**
+ * The context to classify with. Config is read LAZILY and cached, and a failure
+ * to read it degrades to `unknown` rather than to an assumption — an accounting
+ * layer must never invent a tier.
+ */
+export function getPricingContext() {
+    if (overrideContext)
+        return overrideContext;
+    if (!cachedConfigContext) {
+        try {
+            cachedConfigContext = configPricingContext(new ConfigManager());
+        }
+        catch {
+            cachedConfigContext = UNKNOWN_PRICING_CONTEXT;
+        }
+    }
+    return cachedConfigContext;
+}
+const round6 = (usd) => Math.round(usd * 100000) / 100000;
+/**
+ * Classify ONE ledger row.
+ *
+ * A row that already carries `costSource` is taken at its word — it was written
+ * by these rules, and re-deriving it with a config that may have changed since
+ * would rewrite history. A legacy row (no `costSource`) is re-derived from the
+ * fields it has; `costReported` is the one thing a legacy row can be exact about.
+ */
+export function classifyEntry(entry, ctx = getPricingContext()) {
+    if (entry.costReported === true) {
+        // The provider's own figure, exact — for a legacy row too (the flag was
+        // written by the old code and means the same thing).
+        return {
+            billedUsd: round6(entry.costUsd ?? 0),
+            ...(typeof entry.listPriceUsd === 'number' ? { listValueUsd: entry.listPriceUsd } : {}),
+            costSource: 'reported',
+            bucket: 'billed-reported',
+            billingTier: entry.billingTier ?? ctx.billingTierFor(entry.provider),
+            basis: entry.pricingBasis ?? 'provider-reported cost for this call (exact)',
+            recomputed: entry.costSource === undefined,
+        };
+    }
+    if (entry.costSource !== undefined) {
+        // Recorded by the current rules: its numbers stand, its bucket is derived.
+        const tier = entry.billingTier ?? ctx.billingTierFor(entry.provider);
+        return {
+            billedUsd: round6(entry.costUsd ?? 0),
+            ...(typeof entry.listPriceUsd === 'number' ? { listValueUsd: entry.listPriceUsd } : {}),
+            costSource: entry.costSource,
+            bucket: bucketOf(entry.costSource, tier),
+            billingTier: tier,
+            basis: entry.pricingBasis ?? 'recorded by the pricing rules',
+            recomputed: false,
+        };
+    }
+    // Legacy row: re-derive with today's rules. `reportedCostUsd` is deliberately
+    // NOT passed — the stored `costUsd` is the OLD table's number, and feeding it
+    // in as though the provider had said it would launder an estimate into an exact
+    // figure, which is the single worst mistake this module could make.
+    const resolved = resolveCallCost({
+        provider: entry.provider,
+        model: entry.model,
+        inputTokens: entry.inputTokens ?? 0,
+        outputTokens: entry.outputTokens ?? 0,
+        billingTier: ctx.billingTierFor(entry.provider),
+        configPricing: ctx.configPricingFor(entry.provider),
+        catalogRow: ctx.catalogRowFor?.(entry.provider, entry.model),
+    });
+    return {
+        billedUsd: resolved.billedUsd,
+        ...(resolved.listUsd !== undefined ? { listValueUsd: resolved.listUsd } : {}),
+        costSource: resolved.costSource,
+        bucket: resolved.bucket,
+        billingTier: resolved.billingTier,
+        basis: resolved.basis,
+        recomputed: true,
+    };
+}
+/** The bucket for a recorded row — mirrors `model-pricing.bucketFor` for stored data. */
+function bucketOf(source, tier) {
+    switch (source) {
+        case 'reported':
+            return 'billed-reported';
+        case 'free':
+            return 'not-billed-value';
+        case 'passthrough':
+        case 'unknown':
+            return 'unpriced';
+        case 'catalog':
+            return tier === 'paid' ? 'billed-listed' : 'unverified-listed';
+    }
+}
+function emptyProviderTotals() {
+    return {
+        billedUsd: 0,
+        unverifiedListedUsd: 0,
+        notBilledValueUsd: 0,
+        unpricedCalls: 0,
+        unverifiedCalls: 0,
+        valueCalls: 0,
+        requests: 0,
+    };
+}
+/**
+ * Classify a list of rows and sum them.
+ *
+ * `excludeTestOrigin` defaults to FALSE, deliberately: this function is also how
+ * a TEST measures its own writes (`costSince` reads back rows that are, by
+ * definition, test-origin in a test process), so dropping them here would make
+ * the ledger read as empty the moment a test runner was involved. The exclusion
+ * belongs to the DISPLAY surfaces — the dashboard's cost endpoint and the CLI
+ * summary opt in — because that is the claim being made: "this is YOUR usage".
+ * `testOriginCalls` is always reported, so a surface can say how many it hid.
+ */
+export function classifyEntries(entries, opts = {}) {
+    const ctx = opts.ctx ?? getPricingContext();
+    const totals = {
+        billedReportedUsd: 0,
+        billedReportedCalls: 0,
+        billedListedUsd: 0,
+        billedListedCalls: 0,
+        billedUsd: 0,
+        unverifiedListedUsd: 0,
+        unverifiedListedCalls: 0,
+        notBilledValueUsd: 0,
+        notBilledValueCalls: 0,
+        unpricedCalls: 0,
+        unpricedTokens: 0,
+        recomputedCalls: 0,
+        testOriginCalls: 0,
+        recordedTotalUsd: 0,
+        tokens: 0,
+        requests: 0,
+        byProvider: {},
+        byModel: {},
+    };
+    for (const entry of entries) {
+        if (entry.origin === 'test') {
+            totals.testOriginCalls += 1;
+            if (opts.excludeTestOrigin)
+                continue;
+        }
+        const c = classifyEntry(entry, ctx);
+        const tokens = entry.totalTokens ?? (entry.inputTokens ?? 0) + (entry.outputTokens ?? 0);
+        totals.requests += 1;
+        totals.tokens += tokens;
+        totals.recordedTotalUsd += entry.costUsd ?? 0;
+        if (c.recomputed)
+            totals.recomputedCalls += 1;
+        if (c.bucket === 'billed-reported') {
+            totals.billedReportedUsd += c.billedUsd;
+            totals.billedReportedCalls += 1;
+        }
+        else if (c.bucket === 'billed-listed') {
+            totals.billedListedUsd += c.billedUsd;
+            totals.billedListedCalls += 1;
+        }
+        else if (c.bucket === 'unverified-listed') {
+            totals.unverifiedListedUsd += c.listValueUsd ?? 0;
+            totals.unverifiedListedCalls += 1;
+        }
+        else if (c.bucket === 'not-billed-value') {
+            totals.notBilledValueUsd += c.listValueUsd ?? 0;
+            totals.notBilledValueCalls += 1;
+        }
+        else {
+            totals.unpricedCalls += 1;
+            totals.unpricedTokens += tokens;
+        }
+        const provider = entry.provider || 'unknown';
+        const p = (totals.byProvider[provider] ??= emptyProviderTotals());
+        const m = (totals.byModel[entry.model || 'unknown'] ??= emptyProviderTotals());
+        p.requests += 1;
+        m.requests += 1;
+        if (c.bucket === 'billed-reported' || c.bucket === 'billed-listed') {
+            p.billedUsd += c.billedUsd;
+            m.billedUsd += c.billedUsd;
+        }
+        else if (c.bucket === 'unverified-listed') {
+            p.unverifiedListedUsd += c.listValueUsd ?? 0;
+            p.unverifiedCalls += 1;
+            m.unverifiedListedUsd += c.listValueUsd ?? 0;
+            m.unverifiedCalls += 1;
+        }
+        else if (c.bucket === 'not-billed-value') {
+            p.notBilledValueUsd += c.listValueUsd ?? 0;
+            p.valueCalls += 1;
+            m.notBilledValueUsd += c.listValueUsd ?? 0;
+            m.valueCalls += 1;
+        }
+        else {
+            p.unpricedCalls += 1;
+            m.unpricedCalls += 1;
+        }
+    }
+    totals.billedUsd = round6(totals.billedReportedUsd + totals.billedListedUsd);
+    totals.billedReportedUsd = round6(totals.billedReportedUsd);
+    totals.billedListedUsd = round6(totals.billedListedUsd);
+    totals.unverifiedListedUsd = round6(totals.unverifiedListedUsd);
+    totals.notBilledValueUsd = round6(totals.notBilledValueUsd);
+    totals.recordedTotalUsd = round6(totals.recordedTotalUsd);
+    return totals;
+}
+//# sourceMappingURL=cost-classification.js.map

package/dist/learning/cost-classification.js.map

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

package/dist/learning/cost-ledger-maintenance.d.ts

@@ -0,0 +1,122 @@
+/**
+ * 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 type { CostEntry } from './cost-tracker.js';
+import { type PricingContext } from './cost-classification.js';
+/** One grouped removal, so the report says WHAT is being dropped, not just how many. */
+export interface RemovedRows {
+    provider: string;
+    model: string;
+    count: number;
+    /** True when the id itself is the evidence (a fixture id), not an `origin` tag. */
+    fixtureId: boolean;
+}
+export interface LedgerMaintenanceReport {
+    file: string;
+    applied: boolean;
+    backupPath?: string;
+    rows: {
+        total: number;
+        /** Legacy rows re-derived by today's rules (they gained `costSource`). */
+        repriced: number;
+        /** Rows already written by these rules — left exactly as they were. */
+        alreadyClassified: number;
+        /** Rows flagged `origin: 'test'`. */
+        testOriginRemoved: number;
+        /** Rows whose model id could only be a test fixture (no `origin` field). */
+        fixtureRemoved: number;
+        kept: number;
+    };
+    /** The ledger's own recorded sum before and after — the number a reader sees. */
+    before: {
+        recordedUsd: number;
+        tokens: number;
+        unpricedCalls: number;
+    };
+    /**
+     * Re-priced totals, classified: `recordedUsd` is the new sum of the rows'
+     * `costUsd` (the evidence-backed figure), and the rest is the honest split.
+     */
+    after: {
+        recordedUsd: number;
+        tokens: number;
+        billedUsd: number;
+        billedReportedUsd: number;
+        billedListedUsd: number;
+        unverifiedListedUsd: number;
+        notBilledValueUsd: number;
+        unpricedCalls: number;
+    };
+    removed: RemovedRows[];
+    /** Plain-language notes: what changed and what still needs the operator. */
+    notes: string[];
+}
+/** True when the row is test-origin by evidence we can actually read. */
+export declare function testRowVerdict(entry: {
+    origin?: string;
+    model?: string;
+}): 'test-origin' | 'fixture-id' | null;
+/**
+ * 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 declare function repriceLedgerEntries(entries: readonly CostEntry[], opts?: {
+    ctx?: PricingContext;
+    pruneTestRows?: boolean;
+}): {
+    entries: CostEntry[];
+    report: Omit<LedgerMaintenanceReport, 'file' | 'applied' | 'backupPath'>;
+};
+/**
+ * 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 declare function maintainCostLedger(opts?: {
+    file?: string;
+    apply?: boolean;
+    pruneTestRows?: boolean;
+    ctx?: PricingContext;
+}): LedgerMaintenanceReport;
+/** The report as text — shared by the CLI and the scripts wrapper. */
+export declare function formatMaintenanceReport(rep: LedgerMaintenanceReport): string;
+//# sourceMappingURL=cost-ledger-maintenance.d.ts.map

package/dist/learning/cost-ledger-maintenance.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cost-ledger-maintenance.d.ts","sourceRoot":"","sources":["../../src/learning/cost-ledger-maintenance.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAsCG;AAKH,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,mBAAmB,CAAC;AAEnD,OAAO,EAIL,KAAK,cAAc,EACpB,MAAM,0BAA0B,CAAC;AAWlC,wFAAwF;AACxF,MAAM,WAAW,WAAW;IAC1B,QAAQ,EAAE,MAAM,CAAC;IACjB,KAAK,EAAE,MAAM,CAAC;IACd,KAAK,EAAE,MAAM,CAAC;IACd,mFAAmF;IACnF,SAAS,EAAE,OAAO,CAAC;CACpB;AAED,MAAM,WAAW,uBAAuB;IACtC,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,OAAO,CAAC;IACjB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,IAAI,EAAE;QACJ,KAAK,EAAE,MAAM,CAAC;QACd,0EAA0E;QAC1E,QAAQ,EAAE,MAAM,CAAC;QACjB,uEAAuE;QACvE,iBAAiB,EAAE,MAAM,CAAC;QAC1B,qCAAqC;QACrC,iBAAiB,EAAE,MAAM,CAAC;QAC1B,4EAA4E;QAC5E,cAAc,EAAE,MAAM,CAAC;QACvB,IAAI,EAAE,MAAM,CAAC;KACd,CAAC;IACF,iFAAiF;IACjF,MAAM,EAAE;QAAE,WAAW,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,MAAM,CAAC;QAAC,aAAa,EAAE,MAAM,CAAA;KAAE,CAAC;IACvE;;;OAGG;IACH,KAAK,EAAE;QACL,WAAW,EAAE,MAAM,CAAC;QACpB,MAAM,EAAE,MAAM,CAAC;QACf,SAAS,EAAE,MAAM,CAAC;QAClB,iBAAiB,EAAE,MAAM,CAAC;QAC1B,eAAe,EAAE,MAAM,CAAC;QACxB,mBAAmB,EAAE,MAAM,CAAC;QAC5B,iBAAiB,EAAE,MAAM,CAAC;QAC1B,aAAa,EAAE,MAAM,CAAC;KACvB,CAAC;IACF,OAAO,EAAE,WAAW,EAAE,CAAC;IACvB,4EAA4E;IAC5E,KAAK,EAAE,MAAM,EAAE,CAAC;CACjB;AAID,yEAAyE;AACzE,wBAAgB,cAAc,CAAC,KAAK,EAAE;IAAE,MAAM,CAAC,EAAE,MAAM,CAAC;IAAC,KAAK,CAAC,EAAE,MAAM,CAAA;CAAE,GAAG,aAAa,GAAG,YAAY,GAAG,IAAI,CAU9G;AAmCD;;;GAGG;AACH,wBAAgB,oBAAoB,CAClC,OAAO,EAAE,SAAS,SAAS,EAAE,EAC7B,IAAI,GAAE;IAAE,GAAG,CAAC,EAAE,cAAc,CAAC;IAAC,aAAa,CAAC,EAAE,OAAO,CAAA;CAAO,GAC3D;IAAE,OAAO,EAAE,SAAS,EAAE,CAAC;IAAC,MAAM,EAAE,IAAI,CAAC,uBAAuB,EAAE,MAAM,GAAG,SAAS,GAAG,YAAY,CAAC,CAAA;CAAE,CAyGpG;AAeD;;;;;;;GAOG;AACH,wBAAgB,kBAAkB,CAChC,IAAI,GAAE;IAAE,IAAI,CAAC,EAAE,MAAM,CAAC;IAAC,KAAK,CAAC,EAAE,OAAO,CAAC;IAAC,aAAa,CAAC,EAAE,OAAO,CAAC;IAAC,GAAG,CAAC,EAAE,cAAc,CAAA;CAAO,GAC3F,uBAAuB,CA+BzB;AAED,sEAAsE;AACtE,wBAAgB,uBAAuB,CAAC,GAAG,EAAE,uBAAuB,GAAG,MAAM,CAgD5E"}