@agentguard-run/burn 0.2.3 → 0.2.6

package/dist/src/insights/live.js

@@ -0,0 +1,211 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.pacePath = pacePath;
+exports.readPricing = readPricing;
+exports.dollars = dollars;
+exports.hostWindows = hostWindows;
+exports.heavyTurnMessage = heavyTurnMessage;
+exports.observeTool = observeTool;
+exports.renderStatusLine = renderStatusLine;
+const node_fs_1 = require("node:fs");
+const node_crypto_1 = require("node:crypto");
+const node_path_1 = require("node:path");
+const transcript_1 = require("./transcript");
+const attribution_1 = require("./attribution");
+const pricing_1 = require("./pricing");
+const pace_1 = require("./pace");
+const digest = (text) => (0, node_crypto_1.createHash)('sha256').update(text).digest('hex');
+const wait = new Int32Array(new SharedArrayBuffer(4));
+function pacePath(home, sessionId) { return (0, node_path_1.join)(home, 'pace', `${digest(sessionId)}.json`); }
+function readPricing(home, policy) {
+    const file = process.env.AGENTGUARD_BURN_PRICING_FILE || policy?.insights?.pricingFile || (0, node_path_1.join)(home, 'burn-pricing.json');
+    return (0, node_fs_1.existsSync)(file) ? (0, pricing_1.loadPricingOverrides)(file) : {};
+}
+function dollars(value) {
+    return value === null ? 'unpriced' : Math.abs(value.max - value.min) < 0.000001 ? `$${value.min.toFixed(2)}` : `$${value.min.toFixed(2)} to $${value.max.toFixed(2)}`;
+}
+function hostWindows(value, source, at) {
+    if (!value || typeof value !== 'object')
+        return [];
+    const result = [];
+    const record = value;
+    const names = source === 'claude-statusline' ? ['five_hour', 'seven_day'] : ['primary', 'secondary'];
+    for (const name of names) {
+        const raw = record[name];
+        if (!raw || typeof raw !== 'object')
+            continue;
+        const v = raw;
+        const percent = v.used_percentage ?? v.used_percent;
+        if (typeof percent !== 'number' || percent < 0 || percent > 100 || !Number.isFinite(percent) || typeof v.resets_at !== 'number' || !Number.isFinite(v.resets_at))
+            continue;
+        result.push({ name, usedPercent: percent, resetsAt: v.resets_at * 1000, observedAt: at, source,
+            pool: typeof record.limit_id === 'string' ? digest(record.limit_id) : 'default',
+            windowMinutes: typeof v.window_minutes === 'number' && Number.isFinite(v.window_minutes) ? v.window_minutes : undefined });
+    }
+    return result;
+}
+function readAppended(path, old) {
+    const info = (0, node_fs_1.statSync)(path), pathDigest = digest(path);
+    const reset = !old || old.cursor.inode !== info.ino || old.cursor.pathDigest !== pathDigest || info.size < old.cursor.offset;
+    const offset = reset ? 0 : old.cursor.offset;
+    const fd = (0, node_fs_1.openSync)(path, 'r');
+    let bytes;
+    try {
+        bytes = Buffer.alloc(info.size - offset);
+        let read = 0;
+        while (read < bytes.length) {
+            const count = (0, node_fs_1.readSync)(fd, bytes, read, bytes.length - read, offset + read);
+            if (!count)
+                break;
+            read += count;
+        }
+        bytes = bytes.subarray(0, read);
+    }
+    finally {
+        (0, node_fs_1.closeSync)(fd);
+    }
+    const newline = bytes.lastIndexOf(10);
+    const committed = newline < 0 ? 0 : newline + 1;
+    return { text: bytes.subarray(0, committed).toString('utf8'), cursor: { offset: offset + committed, inode: info.ino, pathDigest }, reset };
+}
+function heavyTurnMessage(turn, rates) {
+    const estimated = (0, pricing_1.priceTurn)({ ...turn, inputTokens: 0, cacheReadTokens: 0, outputTokens: 0, cacheWriteTokens: turn.contextTokens,
+        cacheWrite5mTokens: undefined, cacheWrite1hTokens: undefined }, rates);
+    return `Heavy turn: ${(0, pace_1.formatCount)(turn.contextTokens)} context tokens. Compaction may pause this session and rewrite its prefix (${dollars(estimated.usd)} at the list cache-write rate). Start a fresh session with a handoff note. Context weight is not your account usage limit.`;
+}
+/** Local advisory observer. No tool input or output content enters this API. */
+function observeTool(home, input, host, policy, now = Date.now()) {
+    if (!input.session_id || !input.transcript_path)
+        return { messages: [] };
+    const file = pacePath(home, input.session_id), lock = `${file}.lock`;
+    let fd;
+    try {
+        (0, node_fs_1.mkdirSync)((0, node_path_1.join)(home, 'pace'), { recursive: true, mode: 0o700 });
+        const started = Date.now();
+        while (fd === undefined) {
+            try {
+                fd = (0, node_fs_1.openSync)(lock, 'wx', 0o600);
+                (0, node_fs_1.writeFileSync)(fd, String(process.pid));
+            }
+            catch (error) {
+                if (error.code !== 'EEXIST')
+                    throw error;
+                try {
+                    if (Date.now() - (0, node_fs_1.statSync)(lock).mtimeMs > 60_000) {
+                        (0, node_fs_1.unlinkSync)(lock);
+                        continue;
+                    }
+                }
+                catch {
+                    continue;
+                }
+                if (Date.now() - started > 1500)
+                    return { messages: [] };
+                Atomics.wait(wait, 0, 0, 5);
+            }
+        }
+        let previous;
+        try {
+            previous = JSON.parse((0, node_fs_1.readFileSync)(file, 'utf8'));
+            if (previous.schema !== 1)
+                previous = undefined;
+        }
+        catch { /* first observation */ }
+        // A 0.2.4 cache has no interval byte metadata. Re-read the transcript once
+        // rather than treating later intervals as if their earlier reads were new.
+        const appended = readAppended(input.transcript_path, previous?.parser?.intervalStateVersion === 1 ? previous : undefined);
+        const parsed = (0, transcript_1.parseInsightTranscript)(appended.text, { host, sessionId: input.session_id, state: appended.reset ? undefined : previous?.parser });
+        const turns = parsed.turns, rates = readPricing(home, policy);
+        const windows = (previous?.windows ?? []).filter(s => s.observedAt >= now - 600_000 && s.resetsAt > now);
+        windows.push(...hostWindows(input.rate_limits, 'claude-statusline', now));
+        const acceptedQuotaLines = new Set(parsed.acceptedQuotaLineNumbers);
+        if (host === 'codex')
+            for (const [lineNumber, line] of appended.text.split('\n').entries()) {
+                if (!acceptedQuotaLines.has(lineNumber))
+                    continue;
+                try {
+                    const raw = JSON.parse(line);
+                    const at = Date.parse(raw.timestamp ?? '');
+                    if (Number.isFinite(at) && raw.payload?.type === 'token_count')
+                        windows.push(...hostWindows(raw.payload.rate_limits, 'codex-transcript', at));
+                }
+                catch { /* malformed or partial records are not quota evidence */ }
+            }
+        const uniqueWindows = [...new Map(windows.filter(w => w.observedAt >= now - 600_000 && w.resetsAt > now)
+                .map(w => [`${w.name}:${w.source}:${w.pool}:${w.windowMinutes}:${w.observedAt}:${w.resetsAt}`, w])).values()];
+        const messages = [];
+        let heavyAbove = appended.reset ? false : previous?.heavyAbove ?? false;
+        const configuredHeavy = policy.insights?.heavyTurnTokens;
+        const heavy = typeof configuredHeavy === 'number' && Number.isFinite(configuredHeavy) && configuredHeavy >= 0 ? configuredHeavy : 500_000;
+        const updates = appended.reset ? parsed.updatedTurns.slice(-1) : parsed.updatedTurns;
+        for (const turn of updates) {
+            if (turn === parsed.updatedTurns.at(-1) && turn.contextTokens > heavy && !heavyAbove)
+                messages.push(heavyTurnMessage(turn, rates));
+            heavyAbove = turn.contextTokens > heavy;
+        }
+        const today = new Date(now);
+        today.setHours(0, 0, 0, 0);
+        let todayMin = 0, todayMax = 0, hourMin = 0, hourMax = 0, unknown = 0, hourUnknown = 0;
+        const causes = {};
+        for (const turn of turns) {
+            const rewrite = (0, attribution_1.classifyRewrite)(turn);
+            if (!rewrite || turn.at === undefined || turn.at > now || turn.at < today.getTime() && turn.at <= now - 3_600_000)
+                continue;
+            const price = (0, pricing_1.priceTurn)({ ...turn, inputTokens: 0, cacheReadTokens: 0, outputTokens: 0 }, rates).usd;
+            if (turn.at >= today.getTime()) {
+                if (price) {
+                    todayMin += price.min;
+                    todayMax += price.max;
+                }
+                else
+                    unknown++;
+            }
+            if (turn.at > now - 3_600_000) {
+                causes[rewrite.explanation] = (causes[rewrite.explanation] ?? 0) + 1;
+                if (price) {
+                    hourMin += price.min;
+                    hourMax += price.max;
+                }
+                else
+                    hourUnknown++;
+            }
+        }
+        const configuredRewrite = policy.insights?.rewriteWarnDollarsPerHour;
+        const rewriteThreshold = typeof configuredRewrite === 'number' && Number.isFinite(configuredRewrite) && configuredRewrite >= 0 ? configuredRewrite : 5;
+        const rewriteAbove = hourMin > rewriteThreshold;
+        if (rewriteAbove && (appended.reset || !previous?.rewriteAbove))
+            messages.push(`Cache rewrites: ${hourUnknown ? 'at least ' : ''}${dollars({ min: hourMin, max: hourMax })} API list equivalent in the past hour${hourUnknown ? `, plus ${hourUnknown} unpriced rewrites` : ''}: ${Object.entries(causes).map(([cause, count]) => `${count} ${cause}`).join('; ')}.`);
+        const timed = turns.filter((t) => typeof t.at === 'number');
+        const snapshot = { schema: 1, host, sessionId: input.session_id, updatedAt: now, toolEvents: (previous?.toolEvents ?? 0) + (input.tool_name ? 1 : 0),
+            cursor: appended.cursor, parser: parsed.state, pace: (0, pace_1.calculatePace)(timed, now), windows: uniqueWindows,
+            forecast: parsed.state.forkHistoryBoundaryUnknown ? { minutes: null, reason: 'inherited host quota history has no verifiable boundary' } : (0, pace_1.forecastLimit)(uniqueWindows, now), lastTurnTokens: turns.at(-1)?.contextTokens ?? 0,
+            rewriteDollarsToday: unknown ? null : { min: todayMin, max: todayMax }, unpricedRewritesToday: unknown, heavyAbove, rewriteAbove };
+        const temporary = `${file}.${(0, node_crypto_1.randomUUID)()}.tmp`;
+        (0, node_fs_1.writeFileSync)(temporary, JSON.stringify(snapshot), { mode: 0o600 });
+        (0, node_fs_1.renameSync)(temporary, file);
+        return { snapshot, messages };
+    }
+    catch (error) {
+        // Hosts can create their transcript after the first tool event. Keep the
+        // existing admission response until usage exists, instead of warning per call.
+        if (error.code === 'ENOENT')
+            return { messages: [] };
+        return { messages: ['AgentGuard pace unavailable. Local usage metadata could not be updated.'] };
+    }
+    finally {
+        if (fd !== undefined) {
+            (0, node_fs_1.closeSync)(fd);
+            try {
+                (0, node_fs_1.unlinkSync)(lock);
+            }
+            catch { /* already removed */ }
+        }
+    }
+}
+function renderStatusLine(snapshot) {
+    const pace = snapshot.pace;
+    const limit = snapshot.forecast.minutes === null ? `limit unknown (${snapshot.forecast.reason})` : `at this pace you reach your limit in ${Math.ceil(snapshot.forecast.minutes)} minutes`;
+    if (snapshot.parser?.forkHistoryBoundaryUnknown)
+        return `AgentGuard pace unknown | last turn unknown | rewrites today unknown | inherited Codex history has no verifiable boundary | ${limit}`;
+    return `AgentGuard ${(0, pace_1.formatCount)(pace.cachedPerMinute)} cached + ${(0, pace_1.formatCount)(pace.uncachedPerMinute)} uncached tokens/min | last ${(0, pace_1.formatCount)(snapshot.lastTurnTokens)} | rewrites today ${dollars(snapshot.rewriteDollarsToday)} | next hour ${(0, pace_1.formatCount)(pace.projectedNextHour)} tokens | ${limit}`;
+}

package/dist/src/insights/pace.d.ts

@@ -0,0 +1,34 @@
+export interface PaceUsage {
+    id: string;
+    at: number;
+    cacheReadTokens: number;
+    inputTokens: number;
+    cacheWriteTokens: number;
+    outputTokens: number;
+}
+export interface Pace {
+    cachedPerMinute: number;
+    uncachedPerMinute: number;
+    totalPerMinute: number;
+    projectedNextHour: number;
+    intervalMinutes: number;
+}
+export interface UsageWindow {
+    name: string;
+    usedPercent: number;
+    resetsAt: number;
+    observedAt: number;
+    source: 'claude-statusline' | 'codex-transcript';
+    pool?: string;
+    windowMinutes?: number;
+}
+export interface LimitForecast {
+    minutes: number | null;
+    reason: string;
+    source?: string;
+}
+/** Wall-clock ten-minute pace. Cached means cache reads; writes count as uncached. */
+export declare function calculatePace(turns: PaceUsage[], now?: number): Pace;
+/** Forecast only observed host percentage consumption, never a token-to-quota conversion. */
+export declare function forecastLimit(samples: UsageWindow[], now?: number): LimitForecast;
+export declare function formatCount(n: number): string;

package/dist/src/insights/pace.js

@@ -0,0 +1,54 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.calculatePace = calculatePace;
+exports.forecastLimit = forecastLimit;
+exports.formatCount = formatCount;
+/** Wall-clock ten-minute pace. Cached means cache reads; writes count as uncached. */
+function calculatePace(turns, now = Date.now()) {
+    const latest = new Map();
+    for (const turn of turns)
+        latest.set(turn.id, turn);
+    let cached = 0, uncached = 0;
+    for (const turn of latest.values()) {
+        if (turn.at > now || turn.at <= now - 600_000)
+            continue;
+        cached += turn.cacheReadTokens;
+        uncached += turn.inputTokens + turn.cacheWriteTokens + turn.outputTokens;
+    }
+    return { cachedPerMinute: cached / 10, uncachedPerMinute: uncached / 10, totalPerMinute: (cached + uncached) / 10,
+        projectedNextHour: (cached + uncached) * 6, intervalMinutes: 10 };
+}
+/** Forecast only observed host percentage consumption, never a token-to-quota conversion. */
+function forecastLimit(samples, now = Date.now()) {
+    const valid = samples.filter(s => Number.isFinite(s.usedPercent) && s.usedPercent >= 0 && s.usedPercent <= 100 &&
+        Number.isFinite(s.resetsAt) && s.resetsAt > now && s.observedAt <= now && s.observedAt >= now - 600_000);
+    if (!valid.length)
+        return { minutes: null, reason: 'host does not expose a usage window here' };
+    const identity = (s) => `${s.source}:${s.pool ?? 'default'}:${s.name}:${s.windowMinutes ?? ''}:${s.resetsAt}`;
+    const latest = new Map();
+    for (const sample of valid)
+        if (!latest.has(identity(sample)) || latest.get(identity(sample)).observedAt < sample.observedAt)
+            latest.set(identity(sample), sample);
+    let earliest;
+    for (const current of latest.values()) {
+        if (current.observedAt < now - 60_000)
+            continue;
+        const previous = valid.filter(s => identity(s) === identity(current) && s.observedAt < current.observedAt)
+            .sort((a, b) => a.observedAt - b.observedAt)[0];
+        if (current.usedPercent >= 100)
+            return { minutes: 0, reason: 'host reports its usage window exhausted', source: current.source };
+        if (!previous || previous.usedPercent >= current.usedPercent)
+            continue;
+        const rate = (current.usedPercent - previous.usedPercent) / ((current.observedAt - previous.observedAt) / 60_000);
+        const minutes = (100 - current.usedPercent) / rate;
+        if (minutes > (current.resetsAt - now) / 60_000)
+            continue;
+        if (!earliest || minutes < earliest.minutes)
+            earliest = { minutes, source: current.source };
+    }
+    return earliest ? { ...earliest, reason: 'based on observed host usage percentage, not token weighting' }
+        : { minutes: null, reason: 'host window present; insufficient rising samples before reset' };
+}
+function formatCount(n) {
+    return n >= 1e9 ? `${(n / 1e9).toFixed(2)}B` : n >= 1e6 ? `${(n / 1e6).toFixed(2)}M` : n >= 1e3 ? `${(n / 1e3).toFixed(1)}K` : `${Math.round(n)}`;
+}

package/dist/src/insights/pricing.d.ts

@@ -0,0 +1,48 @@
+import type { InsightTurn } from './types';
+/** USD per million tokens. Null means that this rate has not been verified. */
+export interface ModelPricing {
+    input: number | null;
+    cacheRead: number | null;
+    cacheWrite5m: number | null;
+    cacheWrite1h: number | null;
+    output: number | null;
+    sourceUrl: string;
+    verifiedAt: string;
+    /** Some providers publish one cache-write rate, independent of TTL. */
+    cacheWriteTtl?: 'not_tiered';
+    longContext?: {
+        aboveInputTokens: number;
+        inputMultiplier: number;
+        outputMultiplier: number;
+    };
+}
+export type PricingTable = Readonly<Record<string, ModelPricing>>;
+export interface DollarRange {
+    min: number;
+    max: number;
+}
+export interface TurnPrice {
+    model: string | null;
+    sourceUrl: string | null;
+    verifiedAt: string | null;
+    basis: 'estimated_api_list_price';
+    usd: DollarRange | null;
+    categories: {
+        input: DollarRange | null;
+        cacheRead: DollarRange | null;
+        cacheWrite: DollarRange | null;
+        output: DollarRange | null;
+    };
+    unknownCacheWriteTokens: number;
+    reason?: string;
+}
+/** Exact IDs only. Never price an unknown model by a similar family name. */
+export declare const MODEL_PRICING: PricingTable;
+/** Local JSON only. Errors are generic so neither file contents nor paths leak. */
+export declare function loadPricingOverrides(file: string): PricingTable;
+type PriceableTurn = Omit<InsightTurn, 'contextTokens'> & {
+    contextTokens?: number;
+};
+/** API list-price equivalent, never a subscription charge or quota conversion. */
+export declare function priceTurn(turn: PriceableTurn, overrides?: PricingTable): TurnPrice;
+export {};

package/dist/src/insights/pricing.js

@@ -0,0 +1,139 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.MODEL_PRICING = void 0;
+exports.loadPricingOverrides = loadPricingOverrides;
+exports.priceTurn = priceTurn;
+const node_fs_1 = require("node:fs");
+const SOURCE = 'https://platform.claude.com/docs/en/about-claude/pricing';
+const DATE = '2026-09-17';
+const rates = (input, cacheRead, cacheWrite5m, cacheWrite1h, output) => Object.freeze({ input, cacheRead, cacheWrite5m, cacheWrite1h, output, sourceUrl: SOURCE, verifiedAt: DATE });
+const openaiRates = (input, cacheRead, cacheWrite, output, sourceUrl, longContext = true) => Object.freeze({ input, cacheRead, cacheWrite5m: cacheWrite, cacheWrite1h: cacheWrite, output, sourceUrl, verifiedAt: DATE,
+    cacheWriteTtl: 'not_tiered', ...(longContext ? { longContext: Object.freeze({ aboveInputTokens: 272_000, inputMultiplier: 2, outputMultiplier: 1.5 }) } : {}) });
+/** Exact IDs only. Never price an unknown model by a similar family name. */
+exports.MODEL_PRICING = Object.freeze({
+    'claude-fable-5-1': rates(10, 0.25, 12.5, 20, 50),
+    'claude-fable-5': rates(10, 1, 12.5, 20, 50),
+    'claude-opus-5': rates(5, 0.5, 6.25, 10, 25),
+    'claude-opus-4-8': rates(5, 0.5, 6.25, 10, 25),
+    'claude-sonnet-5': rates(2, 0.2, 2.5, 4, 10),
+    'claude-haiku-4-5-20251001': rates(1, 0.1, 1.25, 2, 5),
+    'gpt-6-astra': openaiRates(10, 1, 12.5, 50, 'https://developers.openai.com/api/docs/pricing'),
+    'gpt-5.6-sol': openaiRates(4, 0.4, 5, 20, 'https://developers.openai.com/api/docs/pricing'),
+    'gpt-5.6-luna': openaiRates(0.2, 0.02, 0.25, 1.2, 'https://developers.openai.com/api/docs/pricing'),
+    'gpt-5.4-mini': openaiRates(0.75, 0.075, null, 4.5, 'https://developers.openai.com/api/docs/models/gpt-5.4-mini', false),
+});
+const RATE_KEYS = ['input', 'cacheRead', 'cacheWrite5m', 'cacheWrite1h', 'output'];
+const isRecord = (value) => typeof value === 'object' && value !== null && !Array.isArray(value);
+/** Local JSON only. Errors are generic so neither file contents nor paths leak. */
+function loadPricingOverrides(file) {
+    let value;
+    try {
+        value = JSON.parse((0, node_fs_1.readFileSync)(file, 'utf8'));
+    }
+    catch {
+        throw new Error('Cannot read pricing override JSON');
+    }
+    if (!isRecord(value) || !isRecord(value.models))
+        throw new Error('Pricing overrides require a models object');
+    const table = Object.create(null);
+    for (const [model, row] of Object.entries(value.models)) {
+        if (!model || !isRecord(row) || !RATE_KEYS.every(key => row[key] === null || (typeof row[key] === 'number' && Number.isFinite(row[key]) && row[key] >= 0))) {
+            throw new Error('Pricing overrides require nonnegative rates or null for every token category');
+        }
+        if (typeof row.sourceUrl !== 'string' || !/^https?:\/\//.test(row.sourceUrl)
+            || typeof row.verifiedAt !== 'string' || !/^\d{4}-\d{2}-\d{2}$/.test(row.verifiedAt)
+            || !Number.isFinite(Date.parse(row.verifiedAt)) || new Date(row.verifiedAt).toISOString().slice(0, 10) !== row.verifiedAt) {
+            throw new Error('Pricing overrides require a sourceUrl and verifiedAt date');
+        }
+        if (row.cacheWriteTtl !== undefined && row.cacheWriteTtl !== 'not_tiered')
+            throw new Error('Invalid cache-write pricing mode');
+        if (row.cacheWriteTtl === 'not_tiered' && row.cacheWrite5m !== row.cacheWrite1h)
+            throw new Error('A single cache-write rate requires matching rates');
+        const extra = row.cacheWriteTtl === 'not_tiered' ? { cacheWriteTtl: 'not_tiered' } : {};
+        if (row.longContext !== undefined) {
+            const tier = row.longContext;
+            if (!isRecord(tier) || !Number.isSafeInteger(tier.aboveInputTokens) || Number(tier.aboveInputTokens) < 0
+                || !['inputMultiplier', 'outputMultiplier'].every(key => typeof tier[key] === 'number' && Number.isFinite(tier[key]) && tier[key] >= 0)) {
+                throw new Error('Invalid long-context pricing tier');
+            }
+            extra.longContext = Object.freeze({ aboveInputTokens: tier.aboveInputTokens, inputMultiplier: tier.inputMultiplier, outputMultiplier: tier.outputMultiplier });
+        }
+        table[model] = Object.freeze({ ...Object.fromEntries([...RATE_KEYS, 'sourceUrl', 'verifiedAt'].map(key => [key, row[key]])), ...extra });
+    }
+    return Object.freeze(table);
+}
+function charge(tokens, rate) {
+    if (tokens === 0)
+        return { min: 0, max: 0 };
+    if (rate === null)
+        return null;
+    const dollars = tokens * rate / 1_000_000;
+    return { min: dollars, max: dollars };
+}
+function sum(values) {
+    if (values.some(value => value === null))
+        return null;
+    return values.reduce((total, value) => ({ min: total.min + value.min, max: total.max + value.max }), { min: 0, max: 0 });
+}
+/** API list-price equivalent, never a subscription charge or quota conversion. */
+function priceTurn(turn, overrides = {}) {
+    const model = turn.model ?? null;
+    const baseRate = model === null ? undefined : Object.hasOwn(overrides, model) ? overrides[model] : Object.hasOwn(exports.MODEL_PRICING, model) ? exports.MODEL_PRICING[model] : undefined;
+    let rate = baseRate;
+    const result = {
+        model, sourceUrl: rate?.sourceUrl ?? null, verifiedAt: rate?.verifiedAt ?? null, basis: 'estimated_api_list_price',
+        usd: null, categories: { input: null, cacheRead: null, cacheWrite: null, output: null }, unknownCacheWriteTokens: 0,
+    };
+    const counts = [turn.inputTokens, turn.cacheReadTokens, turn.cacheWriteTokens, turn.outputTokens, turn.cacheWrite5mTokens ?? 0, turn.cacheWrite1hTokens ?? 0];
+    if (counts.some(n => !Number.isSafeInteger(n) || n < 0))
+        return { ...result, reason: 'invalid_token_count' };
+    if (turn.contextTokens !== undefined && (!Number.isSafeInteger(turn.contextTokens) || turn.contextTokens < 0))
+        return { ...result, reason: 'invalid_context_count' };
+    if (!rate)
+        return { ...result, reason: 'unknown_model_price' };
+    // Bucket and rewrite prices retain the complete request context. A subset
+    // must not fall back to the short-context tier after other categories vanish.
+    const actualInput = turn.inputTokens + turn.cacheReadTokens + turn.cacheWriteTokens;
+    const pricingContext = Math.max(turn.contextTokens ?? actualInput, actualInput);
+    if (rate.longContext && pricingContext > rate.longContext.aboveInputTokens) {
+        const tier = rate.longContext;
+        const scale = (value, factor) => value === null ? null : value * factor;
+        rate = { ...rate, input: scale(rate.input, tier.inputMultiplier), cacheRead: scale(rate.cacheRead, tier.inputMultiplier),
+            cacheWrite5m: scale(rate.cacheWrite5m, tier.inputMultiplier), cacheWrite1h: scale(rate.cacheWrite1h, tier.inputMultiplier), output: scale(rate.output, tier.outputMultiplier) };
+    }
+    let five = turn.cacheWrite5mTokens ?? 0;
+    let hour = turn.cacheWrite1hTokens ?? 0;
+    let unknown = turn.cacheWriteTokens - five - hour;
+    if (unknown < 0)
+        return { ...result, reason: 'cache_write_breakdown_exceeds_total' };
+    if (turn.cacheTtlSeconds === 300) {
+        five += unknown;
+        unknown = 0;
+    }
+    if (turn.cacheTtlSeconds === 3600) {
+        hour += unknown;
+        unknown = 0;
+    }
+    if (rate.cacheWriteTtl === 'not_tiered') {
+        five += unknown;
+        unknown = 0;
+    }
+    const lowRate = rate.cacheWrite5m === null || rate.cacheWrite1h === null ? null : Math.min(rate.cacheWrite5m, rate.cacheWrite1h);
+    const highRate = rate.cacheWrite5m === null || rate.cacheWrite1h === null ? null : Math.max(rate.cacheWrite5m, rate.cacheWrite1h);
+    const lower = charge(unknown, lowRate);
+    const upper = charge(unknown, highRate);
+    const unresolved = lower && upper ? { min: lower.min, max: upper.max } : null;
+    result.categories = {
+        input: charge(turn.inputTokens, rate.input),
+        cacheRead: charge(turn.cacheReadTokens, rate.cacheRead),
+        cacheWrite: sum([charge(five, rate.cacheWrite5m), charge(hour, rate.cacheWrite1h), unresolved]),
+        output: charge(turn.outputTokens, rate.output),
+    };
+    result.usd = sum(Object.values(result.categories));
+    result.unknownCacheWriteTokens = unknown;
+    if (!result.usd)
+        result.reason = 'unknown_token_category_price';
+    else if (unknown > 0)
+        result.reason = 'cache_write_ttl_unknown';
+    return result;
+}

package/dist/src/insights/render.d.ts

@@ -0,0 +1,8 @@
+import { type DollarRange, type PricingTable } from './pricing';
+import { type InsightTranscript, type InsightTurn } from './types';
+export declare function sumPrices(values: Array<DollarRange | null>): DollarRange | null;
+export declare function totalTokens(turn: InsightTurn): number;
+export declare function renderWhy(transcript: InsightTranscript, rates?: PricingTable): string;
+export declare function rewriteReport(transcripts: InsightTranscript[], rates?: PricingTable): Record<string, unknown>;
+export declare function renderRewrites(transcripts: InsightTranscript[], rates?: PricingTable): string;
+export declare function renderPricing(overrides?: PricingTable): string;

package/dist/src/insights/render.js

@@ -0,0 +1,126 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.sumPrices = sumPrices;
+exports.totalTokens = totalTokens;
+exports.renderWhy = renderWhy;
+exports.rewriteReport = rewriteReport;
+exports.renderRewrites = renderRewrites;
+exports.renderPricing = renderPricing;
+const attribution_1 = require("./attribution");
+const pricing_1 = require("./pricing");
+const live_1 = require("./live");
+const transcript_1 = require("./transcript");
+const types_1 = require("./types");
+const labels = {
+    instruction_stack: 'Instruction stack + system', conversation: 'Conversation', history_resent: 'History re-sent', reread_files: 'Re-read files',
+    subagent_fanout: 'Subagent fan-out', tool_output: 'Tool output', full_prefix_rewrites: 'Full-prefix rewrites', output: 'Output', unattributed: 'Unattributed',
+};
+function sumPrices(values) {
+    return values.some(value => value === null) ? null : values.reduce((sum, value) => ({ min: sum.min + value.min, max: sum.max + value.max }), { min: 0, max: 0 });
+}
+function totalTokens(turn) { return turn.inputTokens + turn.cacheWriteTokens + turn.cacheReadTokens + turn.outputTokens; }
+function bucketPrice(turn, allocation, rates) {
+    const quantities = allocation.categories;
+    if (Object.values(quantities).every(value => value === 0))
+        return { min: 0, max: 0 };
+    const completeWrites = quantities.cacheCreation === turn.cacheWriteTokens;
+    const mixedWrites = (turn.cacheWrite5mTokens ?? 0) > 0 && (turn.cacheWrite1hTokens ?? 0) > 0;
+    return (0, pricing_1.priceTurn)({ ...turn, inputTokens: quantities.input, cacheReadTokens: quantities.cacheRead,
+        cacheWriteTokens: quantities.cacheCreation, outputTokens: quantities.output,
+        cacheTtlSeconds: !completeWrites && mixedWrites ? undefined : turn.cacheTtlSeconds,
+        cacheWrite5mTokens: completeWrites ? turn.cacheWrite5mTokens : undefined,
+        cacheWrite1hTokens: completeWrites ? turn.cacheWrite1hTokens : undefined }, rates).usd;
+}
+function table(headers, rows) {
+    const widths = headers.map((header, i) => Math.max(header.length, ...rows.map(row => row[i]?.length ?? 0)));
+    return [headers, ...rows].map(row => row.map((cell, i) => cell.padEnd(widths[i])).join('  ').trimEnd()).join('\n');
+}
+const count = (n) => n.toLocaleString('en-US');
+function renderWhy(transcript, rates = {}) {
+    if (transcript.state.forkHistoryBoundaryUnknown)
+        return [
+            `AgentGuard why: ${transcript.sessionId}`,
+            'Usage unavailable: inherited Codex history has no verifiable boundary. Copied usage is excluded, not counted as zero.',
+            table(['Bucket', 'Tokens', 'List USD', 'Session tokens', 'Last turn tokens'], types_1.INSIGHT_BUCKETS.map(bucket => [labels[bucket], 'unattributed', 'unattributed', 'unattributed', 'unattributed'])),
+        ].join('\n');
+    const turns = (0, transcript_1.deduplicateTurns)(transcript.turns).sort((a, b) => (a.at ?? 0) - (b.at ?? 0));
+    const attribution = (0, attribution_1.attributeTurns)(turns), lastAttribution = attribution.turnAttributions.at(-1);
+    const byTurn = new Map(attribution.turnAttributions.map(turn => [turn.turnId, turn]));
+    const prices = turns.map(turn => (0, pricing_1.priceTurn)(turn, rates));
+    const mixedWriteAllocation = turns.some(turn => (turn.cacheWrite5mTokens ?? 0) > 0 && (turn.cacheWrite1hTokens ?? 0) > 0
+        && byTurn.get(turn.id).buckets.some(bucket => bucket.categories.cacheCreation > 0 && bucket.categories.cacheCreation < turn.cacheWriteTokens));
+    const totals = { input: 0, write: 0, read: 0, output: 0 };
+    turns.forEach(turn => { totals.input += turn.inputTokens; totals.write += turn.cacheWriteTokens; totals.read += turn.cacheReadTokens; totals.output += turn.outputTokens; });
+    const rows = types_1.INSIGHT_BUCKETS.map(bucket => {
+        const row = attribution.buckets.find(item => item.bucket === bucket);
+        const lastTokens = lastAttribution?.buckets.find(item => item.bucket === bucket).tokens ?? 0;
+        return [labels[bucket], count(row.tokens), (0, live_1.dollars)(sumPrices(turns.map(turn => bucketPrice(turn, byTurn.get(turn.id).buckets.find(item => item.bucket === bucket), rates)))),
+            `${(attribution.totalTokens ? row.tokens / attribution.totalTokens * 100 : 0).toFixed(1)}%`,
+            `${(lastAttribution?.totalTokens ? lastTokens / lastAttribution.totalTokens * 100 : 0).toFixed(1)}%`];
+    });
+    const unknownModels = [...new Set(prices.filter(price => price.usd === null).map(price => price.model ?? 'missing model id'))];
+    return [
+        `AgentGuard why: ${transcript.sessionId}`,
+        `${turns.length} assistant responses | ${count(attribution.totalTokens)} tokens | ${(0, live_1.dollars)(sumPrices(prices.map(price => price.usd)))} API list equivalent`,
+        `Usage: input ${count(totals.input)}, cache creation ${count(totals.write)}, cache read ${count(totals.read)}, output ${count(totals.output)}.`,
+        '', table(['Bucket', 'Tokens', 'List USD', 'Session tokens', 'Last turn tokens'], rows), '',
+        'Token shares partition recorded usage; byte sizes only split measured token increments and are never converted into tokens.',
+        `Shared event increments: ${attribution.sharedTurns}. Prefix rebaselines: ${attribution.prefixRebaselines}. Prior output retained in unattributed input: ${count(attribution.previousOutputTokensReserved)} tokens.`,
+        `Observed calls: ${transcript.observations.readCalls} reads of ${transcript.observations.uniqueReadFiles} paths, ${transcript.observations.repeatedReadCalls} repeated reads, ${transcript.observations.spawnCalls} spawns, ${transcript.observations.toolResultRecords} tool results.`,
+        '', 'Method',
+        'Instruction stack + system: the first response context sets a fixed-prefix baseline including initial user content, later cached prefix is counted up to it, and prefix-change rewrites reset it with any history then present.',
+        'History re-sent: each response contributes cache-read tokens above its session fixed-prefix baseline, floored at zero.',
+        'Re-read files: the measured input and cache-creation increment after prior output subtraction is split by result bytes, with repeated Read paths assigned here.',
+        'Subagent fan-out: child transcripts contribute their measured input categories after rewrite allocation.',
+        'Tool output: the same measured increment is split by result bytes among other tool results.',
+        'Conversation: user-message bytes receive their share of that measured increment, with mixed user and tool intervals marked shared.',
+        'Full-prefix rewrites: qualifying turns contribute their measured cache-creation tokens and are excluded from event-increment allocation.',
+        'Output: every response contributes its recorded generated output tokens once.',
+        'Unattributed: residual measured usage includes prior output deducted from arriving-content increments and intervals without usable event evidence.',
+        ...(turns.some(turn => turn.explicitAttribution.length > 0) ? ['Explicit host token attribution takes precedence over the delta method for responses that provide it.'] : []),
+        ...(unknownModels.length ? [`Tokens only for unpriced models: ${unknownModels.join(', ')}. No verified exact model rate is available for at least one token category.`] : []),
+        ...(prices.some(price => price.unknownCacheWriteTokens > 0) ? ['Cache TTL is missing for some writes; their dollars span the verified five-minute and one-hour rates.'] : []),
+        ...(mixedWriteAllocation ? ['Some bucket cache-write costs are ranges because mixed cache lifetimes are not attributed to individual buckets. Range endpoints are not additive across buckets.'] : []),
+        `Usage records de-duplicated: ${transcript.diagnostics.duplicateUsageRecords}. Malformed lines skipped: ${transcript.diagnostics.malformedLines}.`,
+    ].join('\n');
+}
+function rewriteReport(transcripts, rates = {}) {
+    const grouped = new Map();
+    for (const turn of (0, transcript_1.deduplicateTurns)(transcripts.flatMap(transcript => transcript.turns)))
+        grouped.set(turn.sessionId, [...grouped.get(turn.sessionId) ?? [], turn]);
+    const sessions = [...grouped].map(([sessionId, turns]) => {
+        const records = turns.flatMap(turn => {
+            const rewrite = (0, attribution_1.classifyRewrite)(turn);
+            return rewrite ? [{ ...rewrite, sessionId, at: turn.at, model: turn.model,
+                    usd: (0, pricing_1.priceTurn)({ ...turn, inputTokens: 0, cacheReadTokens: 0, outputTokens: 0 }, rates).usd }] : [];
+        });
+        return { sessionId, records };
+    });
+    return { sessions, total: sessions.reduce((sum, session) => sum + session.records.length, 0),
+        excludedUnknownHistories: transcripts.filter(transcript => transcript.state.forkHistoryBoundaryUnknown).length,
+        idleOver60Minutes: sessions.reduce((sum, session) => sum + session.records.filter(record => record.idleOver60Minutes).length, 0) };
+}
+function renderRewrites(transcripts, rates = {}) {
+    const report = rewriteReport(transcripts, rates);
+    const rows = [];
+    const totals = new Map();
+    for (const session of report.sessions) {
+        const groups = new Map();
+        session.records.forEach(record => {
+            groups.set(record.cause, [...groups.get(record.cause) ?? [], record]);
+            totals.set(record.cause, [...totals.get(record.cause) ?? [], record]);
+        });
+        for (const [cause, records] of groups)
+            rows.push([session.sessionId, cause, String(records.length), count(records.reduce((sum, record) => sum + record.cacheWriteTokens, 0)), (0, live_1.dollars)(sumPrices(records.map(record => record.usd)))]);
+    }
+    for (const [cause, records] of totals)
+        rows.push(['ALL', cause, String(records.length), count(records.reduce((sum, record) => sum + record.cacheWriteTokens, 0)), (0, live_1.dollars)(sumPrices(records.map(record => record.usd)))]);
+    return [`AgentGuard rewrites: ${report.total}; ${report.idleOver60Minutes} followed an idle gap over 60 minutes.`,
+        table(['Session', 'Cause', 'Count', 'Write tokens', 'List USD'], rows),
+        ...(transcripts.some(transcript => transcript.state.forkHistoryBoundaryUnknown) ? [`Excluded ${transcripts.filter(transcript => transcript.state.forkHistoryBoundaryUnknown).length} Codex histories whose inherited usage boundary is unknown. Counts are incomplete.`] : []),
+        'Expiration is inferred from observed idle time and known TTL. Prefix change is the residual explanation; absent TTL remains unknown.'].join('\n');
+}
+function renderPricing(overrides = {}) {
+    const rows = Object.entries({ ...pricing_1.MODEL_PRICING, ...overrides }).map(([model, rate]) => [model, String(rate.input), String(rate.cacheRead), String(rate.cacheWrite5m), String(rate.cacheWrite1h), String(rate.output), rate.verifiedAt, rate.sourceUrl]);
+    return 'USD per million tokens. API list equivalents, not subscription charges.\n' + table(['Model', 'Input', 'Read', 'Write 5m', 'Write 1h', 'Output', 'Verified', 'Source'], rows);
+}

package/dist/src/insights/sessions.d.ts

@@ -0,0 +1,12 @@
+export interface TranscriptLocation {
+    path: string;
+    host: 'claude' | 'codex';
+    sessionId: string;
+    modifiedAt: number;
+}
+/** Local locators only. Never follows directory symlinks or reads message content. */
+export declare function discoverInsightTranscripts(roots?: {
+    claude: string;
+    codex: string;
+}): TranscriptLocation[];
+export declare function selectInsightTranscript(session?: string, locations?: TranscriptLocation[]): TranscriptLocation;