@agent-finops/core 0.1.0

package/dist/cutList.js

@@ -0,0 +1,201 @@
+const confidenceRank = {
+    verified: 0,
+    estimated: 1,
+    detected_unverified: 2,
+    missing: 3
+};
+const downgradeRules = [
+    { match: /^gpt-4\.1$/i, target: "gpt-4.1-mini", costRetained: 0.2 },
+    { match: /^gpt-4o$/i, target: "gpt-4o-mini", costRetained: 0.18 },
+    { match: /^gpt-4-turbo$/i, target: "gpt-4o-mini", costRetained: 0.12 },
+    { match: /^o3$/i, target: "o4-mini", costRetained: 0.25 },
+    { match: /^claude-sonnet-4(?:[.-].*)?$/i, target: "claude-haiku-4", costRetained: 0.25 },
+    { match: /^claude-opus-4(?:[.-].*)?$/i, target: "claude-sonnet-4", costRetained: 0.3 },
+    { match: /^claude-3-5-sonnet.*$/i, target: "claude-3-5-haiku", costRetained: 0.25 }
+];
+/**
+ * Operations that are usually quality-safe to run on a cheaper tier
+ * (extraction, triage, drafting, summarization). Used to gate model
+ * downgrade suggestions so we don't recommend downgrading high-stakes work.
+ */
+const downgradeSafeOperation = /triage|extract|classif|summary|summari|draft|reply|tag|label|categor/i;
+/**
+ * Operations that read as offline/asynchronous (nobody is waiting on the
+ * response), so they can move to the providers' Batch APIs — a flat 50%
+ * discount at both OpenAI and Anthropic. Deliberately narrower than
+ * downgradeSafeOperation: drafting/replying is interactive, summarizing a
+ * backlog is not.
+ */
+const batchSafeOperation = /summar|extract|classif|embed|enrich|index|backfill|digest|report|translat|transcri|batch/i;
+/** Fraction of cost retained on the Batch API (both providers price it at 50%). */
+const batchCostRetained = 0.5;
+export function generateCutList(records) {
+    const actions = [
+        ...modelDowngradeActions(records),
+        ...contextTrimActions(records),
+        ...cacheActions(records),
+        ...batchActions(records)
+    ];
+    return actions
+        .filter((action) => action.estimatedMonthlySavingsUsd >= 0.5)
+        .sort((left, right) => right.estimatedMonthlySavingsUsd - left.estimatedMonthlySavingsUsd ||
+        left.id.localeCompare(right.id));
+}
+/** Sum of all per-action estimated monthly savings. */
+export function totalEstimatedMonthlySavingsUsd(actions) {
+    return roundMoney(actions.reduce((total, action) => total + action.estimatedMonthlySavingsUsd, 0));
+}
+function modelDowngradeActions(records) {
+    const window = windowDays(records);
+    const groups = new Map();
+    for (const record of records) {
+        const rule = downgradeRules.find((candidate) => candidate.match.test(record.model));
+        if (!rule) {
+            continue;
+        }
+        const operation = record.operation ?? "general";
+        // Only suggest downgrades for clearly downgrade-safe operations, OR when
+        // the operation is unknown (we still flag it, but caveat via confidence).
+        if (record.operation && !downgradeSafeOperation.test(operation)) {
+            continue;
+        }
+        const key = `${record.model}::${operation}::${rule.target}`;
+        groups.set(key, [...(groups.get(key) ?? []), record]);
+    }
+    const actions = [];
+    for (const [key, groupRecords] of groups) {
+        const [model, operation, target] = key.split("::");
+        const rule = downgradeRules.find((candidate) => candidate.match.test(model));
+        const affectedSpendUsd = roundMoney(sumRecords(groupRecords));
+        const windowSavings = affectedSpendUsd * (1 - rule.costRetained);
+        const monthlySavings = roundMoney(toMonthly(windowSavings, window));
+        actions.push({
+            id: `downgrade-${slug(model)}-${slug(operation)}`,
+            title: `Move ${model} ${operation} calls to ${target}`,
+            action: `Route ${groupRecords.length} ${operation} call${groupRecords.length === 1 ? "" : "s"} from ${model} to ${target} (keep ${model} only when output is rejected).`,
+            estimatedMonthlySavingsUsd: monthlySavings,
+            affectedSpendUsd,
+            recordCount: groupRecords.length,
+            confidence: combinedConfidence(groupRecords.map((record) => record.costConfidence)),
+            kind: "model_downgrade"
+        });
+    }
+    return actions;
+}
+function contextTrimActions(records) {
+    const window = windowDays(records);
+    const heavy = records.filter((record) => record.inputTokens >= 100_000);
+    if (heavy.length === 0) {
+        return [];
+    }
+    const byOperation = new Map();
+    for (const record of heavy) {
+        const operation = record.operation ?? "large-context calls";
+        byOperation.set(operation, [...(byOperation.get(operation) ?? []), record]);
+    }
+    const actions = [];
+    for (const [operation, groupRecords] of byOperation) {
+        const affectedSpendUsd = roundMoney(sumRecords(groupRecords));
+        // Trimming oversized retrieval/context conservatively recovers ~25% of the
+        // input-token cost on these large calls.
+        const windowSavings = affectedSpendUsd * 0.25;
+        const monthlySavings = roundMoney(toMonthly(windowSavings, window));
+        actions.push({
+            id: `trim-${slug(operation)}`,
+            title: `Trim oversized context on ${operation}`,
+            action: `Cap retrieval/prompt size on ${groupRecords.length} large ${operation} call${groupRecords.length === 1 ? "" : "s"} (>=100k input tokens) before they fan out.`,
+            estimatedMonthlySavingsUsd: monthlySavings,
+            affectedSpendUsd,
+            recordCount: groupRecords.length,
+            confidence: combinedConfidence(groupRecords.map((record) => record.costConfidence)),
+            kind: "context_trim"
+        });
+    }
+    return actions;
+}
+function cacheActions(records) {
+    const window = windowDays(records);
+    const counts = new Map();
+    for (const record of records) {
+        if (!record.operation) {
+            continue;
+        }
+        counts.set(record.operation, [...(counts.get(record.operation) ?? []), record]);
+    }
+    const actions = [];
+    for (const [operation, groupRecords] of counts) {
+        if (groupRecords.length < 3) {
+            continue;
+        }
+        const affectedSpendUsd = roundMoney(sumRecords(groupRecords));
+        // Caching repeated identical-ish operations conservatively recovers ~20%.
+        const windowSavings = affectedSpendUsd * 0.2;
+        const monthlySavings = roundMoney(toMonthly(windowSavings, window));
+        actions.push({
+            id: `cache-${slug(operation)}`,
+            title: `Cache repeated ${operation} calls`,
+            action: `Add a result cache for ${operation} (${groupRecords.length} repeated call${groupRecords.length === 1 ? "" : "s"}) so identical inputs do not re-bill.`,
+            estimatedMonthlySavingsUsd: monthlySavings,
+            affectedSpendUsd,
+            recordCount: groupRecords.length,
+            confidence: combinedConfidence(groupRecords.map((record) => record.costConfidence)),
+            kind: "cache"
+        });
+    }
+    return actions;
+}
+function batchActions(records) {
+    const window = windowDays(records);
+    const byOperation = new Map();
+    for (const record of records) {
+        if (!record.operation || !batchSafeOperation.test(record.operation)) {
+            continue;
+        }
+        byOperation.set(record.operation, [...(byOperation.get(record.operation) ?? []), record]);
+    }
+    const actions = [];
+    for (const [operation, groupRecords] of byOperation) {
+        if (groupRecords.length < 3) {
+            continue;
+        }
+        const affectedSpendUsd = roundMoney(sumRecords(groupRecords));
+        const windowSavings = affectedSpendUsd * (1 - batchCostRetained);
+        const monthlySavings = roundMoney(toMonthly(windowSavings, window));
+        actions.push({
+            id: `batch-${slug(operation)}`,
+            title: `Move ${operation} calls to the Batch API`,
+            action: `Submit ${groupRecords.length} ${operation} call${groupRecords.length === 1 ? "" : "s"} through the provider's Batch API (flat 50% off; results within 24h, fine for offline work).`,
+            estimatedMonthlySavingsUsd: monthlySavings,
+            affectedSpendUsd,
+            recordCount: groupRecords.length,
+            confidence: combinedConfidence(groupRecords.map((record) => record.costConfidence)),
+            kind: "batch"
+        });
+    }
+    return actions;
+}
+/** Number of distinct calendar days the records span (min 1). */
+function windowDays(records) {
+    const days = new Set(records.map((record) => record.timestamp.slice(0, 10)));
+    return Math.max(1, days.size);
+}
+/** Project a window's savings to a 30-day month. */
+function toMonthly(windowSavings, windowDayCount) {
+    return (windowSavings / windowDayCount) * 30;
+}
+function sumRecords(records) {
+    return records.reduce((total, record) => total + (record.amountUsd ?? 0), 0);
+}
+function combinedConfidence(confidences) {
+    if (confidences.length === 0) {
+        return "missing";
+    }
+    return confidences.reduce((lowest, current) => confidenceRank[current] > confidenceRank[lowest] ? current : lowest);
+}
+function slug(value) {
+    return value.toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-|-$/g, "") || "x";
+}
+function roundMoney(value) {
+    return Math.round(value * 100) / 100;
+}
+//# sourceMappingURL=cutList.js.map

package/dist/discovery.d.ts

@@ -0,0 +1,19 @@
+export type UsageSignalKind = "dependency" | "config" | "environment" | "source_code" | "provider_export" | "invoice";
+export type UsageSignal = {
+    provider: string;
+    kind: UsageSignalKind;
+    filePath: string;
+    evidence: string;
+    confidence: number;
+};
+export type LocalDiscoveryResult = {
+    rootPath: string;
+    scannedFiles: number;
+    skippedDirectories: string[];
+    signals: UsageSignal[];
+    secretsDetected: string[];
+    redactedEvidence: string[];
+};
+export declare function scanLocalUsageSignals(rootPath: string): Promise<LocalDiscoveryResult>;
+export declare function redactSecrets(text: string): string;
+//# sourceMappingURL=discovery.d.ts.map

package/dist/discovery.js

@@ -0,0 +1,176 @@
+import { readdir, readFile, stat } from "node:fs/promises";
+import { basename, join, relative } from "node:path";
+const skippedDirectoryNames = new Set([
+    ".git",
+    "node_modules",
+    "dist",
+    "build",
+    ".next",
+    ".turbo",
+    "coverage",
+    ".ssh",
+    "Keychains"
+]);
+const maxFileBytes = 512_000;
+const providerRules = [
+    { provider: "anthropic", kind: "dependency", patterns: [/@anthropic-ai\/sdk/, /anthropic/i], confidence: 0.9 },
+    { provider: "langfuse", kind: "dependency", patterns: [/langfuse/i], confidence: 0.82 },
+    { provider: "openai", kind: "dependency", patterns: [/"openai"\s*:/, /from\s+["']openai["']/, /OPENAI_API_KEY/], confidence: 0.9 },
+    { provider: "vercel-ai-sdk", kind: "dependency", patterns: [/"ai"\s*:/, /from\s+["']ai["']/], confidence: 0.78 },
+    { provider: "litellm", kind: "config", patterns: [/litellm/i, /model_list:/], confidence: 0.84 },
+    { provider: "helicone", kind: "environment", patterns: [/HELICONE_API_KEY/, /helicone/i], confidence: 0.8 },
+    { provider: "cursor", kind: "invoice", patterns: [/cursor/i], confidence: 0.76 },
+    { provider: "replit", kind: "invoice", patterns: [/replit/i], confidence: 0.72 }
+];
+const secretAssignmentPattern = /\b([A-Z][A-Z0-9_]*(?:API_KEY|TOKEN|SECRET|PASSWORD))\s*=\s*([^\s#"']+)/g;
+const providerSecretPatterns = [
+    /sk-proj-[A-Za-z0-9_-]{20,}/g,
+    /sk-ant-api\d{2}-[A-Za-z0-9_-]{20,}/g,
+    /sk-[A-Za-z0-9_-]{20,}/g,
+    /helicone_[A-Za-z0-9_-]{16,}/gi
+];
+export async function scanLocalUsageSignals(rootPath) {
+    const result = {
+        rootPath,
+        scannedFiles: 0,
+        skippedDirectories: [],
+        signals: [],
+        secretsDetected: [],
+        redactedEvidence: []
+    };
+    const secrets = new Set();
+    const skipped = new Set();
+    await walk(rootPath, async (path) => {
+        const fileInfo = await stat(path);
+        if (fileInfo.size > maxFileBytes || !isInterestingFile(path)) {
+            return;
+        }
+        const raw = await readFile(path, "utf8");
+        const redacted = redactSecrets(raw);
+        const relativePath = relative(rootPath, path) || basename(path);
+        result.scannedFiles += 1;
+        for (const name of detectSecretNames(raw)) {
+            secrets.add(name);
+            result.redactedEvidence.push(`${relativePath}: ${name}=[REDACTED]`);
+        }
+        for (const signal of detectExportSignals(relativePath, redacted)) {
+            result.signals.push(signal);
+        }
+        for (const rule of providerRules) {
+            const matchedPattern = rule.patterns.find((pattern) => pattern.test(redacted));
+            if (!matchedPattern) {
+                continue;
+            }
+            const evidence = buildEvidence(relativePath, rule.provider, redacted);
+            result.signals.push({
+                provider: rule.provider,
+                kind: inferKind(path, rule.kind),
+                filePath: relativePath,
+                evidence,
+                confidence: rule.confidence
+            });
+        }
+    }, skipped);
+    result.skippedDirectories = Array.from(skipped).sort();
+    result.secretsDetected = Array.from(secrets).sort();
+    result.signals = dedupeSignals(result.signals).sort((left, right) => {
+        const provider = left.provider.localeCompare(right.provider);
+        return provider === 0 ? left.filePath.localeCompare(right.filePath) : provider;
+    });
+    result.redactedEvidence = Array.from(new Set(result.redactedEvidence)).sort();
+    return result;
+}
+export function redactSecrets(text) {
+    let redacted = text.replace(secretAssignmentPattern, (_match, key) => `${key}=[REDACTED]`);
+    for (const pattern of providerSecretPatterns) {
+        redacted = redacted.replace(pattern, "[REDACTED]");
+    }
+    return redacted;
+}
+function detectSecretNames(text) {
+    const names = new Set();
+    let match;
+    const pattern = new RegExp(secretAssignmentPattern.source, secretAssignmentPattern.flags);
+    while ((match = pattern.exec(text)) !== null) {
+        names.add(match[1]);
+    }
+    return Array.from(names);
+}
+async function walk(rootPath, visit, skipped) {
+    const entries = await readdir(rootPath, { withFileTypes: true });
+    for (const entry of entries) {
+        const path = join(rootPath, entry.name);
+        if (entry.isDirectory()) {
+            if (skippedDirectoryNames.has(entry.name)) {
+                skipped.add(entry.name);
+                continue;
+            }
+            await walk(path, visit, skipped);
+            continue;
+        }
+        if (entry.isFile()) {
+            await visit(path);
+        }
+    }
+}
+function isInterestingFile(path) {
+    const name = basename(path);
+    return (name === "package.json" ||
+        name === ".env" ||
+        name.startsWith(".env.") ||
+        /\.(ts|tsx|js|jsx|mjs|cjs|json|csv|ya?ml|toml|py|md|txt)$/i.test(name));
+}
+function inferKind(path, fallback) {
+    const name = basename(path);
+    if (name === ".env" || name.startsWith(".env.")) {
+        return "environment";
+    }
+    if (/\.(ya?ml|toml)$/i.test(name)) {
+        return "config";
+    }
+    if (/invoice|receipt|billing/i.test(name)) {
+        return "invoice";
+    }
+    if (/usage|export|cost|spend/i.test(name) && /\.(csv|json)$/i.test(name)) {
+        return "provider_export";
+    }
+    return fallback;
+}
+function detectExportSignals(filePath, redacted) {
+    const lowerPath = filePath.toLowerCase();
+    const lowerText = redacted.toLowerCase();
+    const providers = ["openai", "anthropic", "cursor", "helicone", "langfuse", "gemini", "google", "replit"];
+    const provider = providers.find((candidate) => lowerPath.includes(candidate) || lowerText.includes(candidate));
+    if (!provider) {
+        return [];
+    }
+    const isExport = /usage|export|cost|spend/.test(lowerPath) || /cost_usd|amount_usd|total_usd|input_tokens|output_tokens/.test(lowerText);
+    const isInvoice = /invoice|receipt|billing/.test(lowerPath) || /total due|amount due|invoice/.test(lowerText);
+    if (!isExport && !isInvoice) {
+        return [];
+    }
+    const normalizedProvider = provider === "google" ? "gemini" : provider;
+    const kind = isInvoice ? "invoice" : "provider_export";
+    return [{
+            provider: normalizedProvider,
+            kind,
+            filePath,
+            evidence: `${filePath}: detected ${normalizedProvider} ${kind.replace("_", " ")}`,
+            confidence: isInvoice ? 0.82 : 0.88
+        }];
+}
+function buildEvidence(filePath, provider, redacted) {
+    const line = redacted.split(/\r?\n/).find((candidate) => candidate.toLowerCase().includes(provider.split("-")[0]));
+    return line ? `${filePath}: ${line.trim()}` : `${filePath}: detected ${provider} usage signal`;
+}
+function dedupeSignals(signals) {
+    const byKey = new Map();
+    for (const signal of signals) {
+        const key = `${signal.provider}:${signal.filePath}:${signal.kind}`;
+        if (!byKey.has(key)) {
+            byKey.set(key, signal);
+        }
+    }
+    return Array.from(byKey.values());
+}
+//# sourceMappingURL=discovery.js.map

package/dist/index.d.ts

@@ -0,0 +1,14 @@
+export * from "./analyze.js";
+export * from "./attribution.js";
+export * from "./credentialDetection.js";
+export * from "./cutList.js";
+export * from "./discovery.js";
+export * from "./insights.js";
+export * from "./localAgentLogs.js";
+export * from "./modelPricing.js";
+export * from "./planMath.js";
+export * from "./sampleData.js";
+export * from "./schema.js";
+export * from "./sourceRegistry.js";
+export * from "./providerConnectors.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/index.js

@@ -0,0 +1,14 @@
+export * from "./analyze.js";
+export * from "./attribution.js";
+export * from "./credentialDetection.js";
+export * from "./cutList.js";
+export * from "./discovery.js";
+export * from "./insights.js";
+export * from "./localAgentLogs.js";
+export * from "./modelPricing.js";
+export * from "./planMath.js";
+export * from "./sampleData.js";
+export * from "./schema.js";
+export * from "./sourceRegistry.js";
+export * from "./providerConnectors.js";
+//# sourceMappingURL=index.js.map

package/dist/insights.d.ts

@@ -0,0 +1,3 @@
+import { type SpendInsight, type SpendSummary, type UsageRecord } from "./schema.js";
+export declare function generateSpendInsights(records: UsageRecord[], summary: SpendSummary): SpendInsight[];
+//# sourceMappingURL=insights.d.ts.map

package/dist/insights.js

@@ -0,0 +1,183 @@
+import { spendInsightSchema } from "./schema.js";
+const confidenceRank = {
+    verified: 0,
+    estimated: 1,
+    detected_unverified: 2,
+    missing: 3
+};
+const severityRank = {
+    critical: 0,
+    high: 1,
+    medium: 2,
+    low: 3
+};
+export function generateSpendInsights(records, summary) {
+    const insights = [
+        ...spikeInsights(records, summary),
+        ...agentCostDriverInsights(records, summary),
+        ...contextBloatInsights(records)
+    ];
+    return insights
+        .map((insight) => spendInsightSchema.parse(insight))
+        .sort((left, right) => severityRank[left.severity] - severityRank[right.severity] ||
+        right.estimatedImpactUsd - left.estimatedImpactUsd ||
+        left.id.localeCompare(right.id));
+}
+function spikeInsights(records, summary) {
+    return summary.anomalies.map((anomaly) => {
+        const currentRecords = records.filter((record) => record.timestamp.slice(0, 10) === anomaly.key);
+        const topAgent = topBreakdown(currentRecords, (record) => record.agentId);
+        const topClient = topBreakdown(currentRecords, (record) => record.clientId);
+        const topProject = topBreakdown(currentRecords, (record) => record.projectId);
+        const topModels = breakdown(currentRecords, (record) => record.model).slice(0, 2).map((entry) => entry.key);
+        const deltaUsd = roundMoney(anomaly.currentAmountUsd - anomaly.previousAmountUsd);
+        const likelyDriver = topAgent?.key ?? topProject?.key ?? topClient?.key ?? "unmapped usage";
+        return {
+            id: `spike-${anomaly.key}`,
+            kind: "spike_explanation",
+            severity: deltaUsd >= 25 || anomaly.multiplier >= 3 ? "critical" : "high",
+            title: `Spend spike on ${anomaly.key} needs owner review`,
+            summary: `${anomaly.key} spend rose ${formatMultiplier(anomaly.multiplier)} day over day, from ${formatUsd(anomaly.previousAmountUsd)} to ${formatUsd(anomaly.currentAmountUsd)}. The likely driver is ${likelyDriver}, so this needs owner review before the pattern repeats.`,
+            evidence: compactEvidence([
+                { label: "Previous day spend", value: formatUsd(anomaly.previousAmountUsd) },
+                { label: "Current day spend", value: formatUsd(anomaly.currentAmountUsd) },
+                { label: "Increase", value: formatUsd(deltaUsd), detail: `${formatMultiplier(anomaly.multiplier)} day-over-day multiplier` },
+                topAgent ? { label: "Likely driver", value: topAgent.key, detail: `${formatUsd(topAgent.amountUsd)} across ${topAgent.recordCount} records` } : undefined,
+                topClient ? { label: "Client concentration", value: topClient.key, detail: `${formatUsd(topClient.amountUsd)} on spike day` } : undefined,
+                topModels.length > 0 ? { label: "Dominant models", value: topModels.join(", ") } : undefined
+            ]),
+            affectedClients: keysFrom(currentRecords, (record) => record.clientId),
+            affectedProjects: keysFrom(currentRecords, (record) => record.projectId),
+            affectedAgents: keysFrom(currentRecords, (record) => record.agentId),
+            affectedModels: keysFrom(currentRecords, (record) => record.model),
+            estimatedImpactUsd: deltaUsd,
+            confidence: anomaly.confidence,
+            recommendedAction: `Review the ${likelyDriver} runs from ${anomaly.key}, set a temporary warning threshold for this owner, and pause expansion until the largest calls have an expected budget range.`,
+            verificationNeeded: "Verify the spike against the provider billing export before treating the dollar amount as finance-grade."
+        };
+    });
+}
+function agentCostDriverInsights(records, summary) {
+    const topAgent = summary.byAgent[0];
+    if (!topAgent || topAgent.key === "unmapped" || topAgent.amountUsd < 25 || summary.totalUsd === 0) {
+        return [];
+    }
+    const agentRecords = records.filter((record) => record.agentId === topAgent.key);
+    const share = topAgent.amountUsd / summary.totalUsd;
+    if (share < 0.35) {
+        return [];
+    }
+    const topOperation = topBreakdown(agentRecords, (record) => record.operation);
+    const topModel = topBreakdown(agentRecords, (record) => record.model);
+    const estimatedImpactUsd = roundMoney(topAgent.amountUsd * 0.15);
+    return [{
+            id: `agent-cost-driver-${topAgent.key}`,
+            kind: "agent_runaway",
+            severity: share >= 0.5 ? "high" : "medium",
+            title: `${topAgent.key} is the dominant autonomous spend driver`,
+            summary: `${topAgent.key} accounts for ${formatPercent(share)} of tracked spend. That is the agent to cap first because one runaway workflow can consume budget before invoice review.`,
+            evidence: compactEvidence([
+                { label: "Agent spend", value: formatUsd(topAgent.amountUsd), detail: `${topAgent.recordCount} records` },
+                { label: "Share of tracked spend", value: formatPercent(share) },
+                topModel ? { label: "Dominant model", value: topModel.key, detail: `${formatUsd(topModel.amountUsd)} inside this agent` } : undefined,
+                topOperation ? { label: "Dominant operation", value: topOperation.key, detail: `${formatUsd(topOperation.amountUsd)} inside this agent` } : undefined
+            ]),
+            affectedClients: keysFrom(agentRecords, (record) => record.clientId),
+            affectedProjects: keysFrom(agentRecords, (record) => record.projectId),
+            affectedAgents: [topAgent.key],
+            affectedModels: keysFrom(agentRecords, (record) => record.model),
+            estimatedImpactUsd,
+            confidence: topAgent.confidence,
+            recommendedAction: `Set a local warning threshold and hard cap for ${topAgent.key}, then require approval when a run exceeds its expected spend range.`,
+            verificationNeeded: "Confirm whether this agent has an approved budget owner and expected daily range."
+        }];
+}
+function contextBloatInsights(records) {
+    const highInputRecords = records.filter((record) => record.inputTokens >= 100_000);
+    if (highInputRecords.length === 0) {
+        return [];
+    }
+    const topOperation = topBreakdown(highInputRecords, (record) => record.operation);
+    const scopedRecords = topOperation
+        ? highInputRecords.filter((record) => record.operation === topOperation.key)
+        : highInputRecords;
+    const operationLabel = topOperation?.key ?? "large-context calls";
+    const totalInputTokens = scopedRecords.reduce((total, record) => total + record.inputTokens, 0);
+    const scopedSpend = roundMoney(sumRecords(scopedRecords));
+    if (scopedSpend < 20) {
+        return [];
+    }
+    return [{
+            id: `context-bloat-${slug(operationLabel)}`,
+            kind: "context_bloat",
+            severity: scopedSpend >= 60 ? "high" : "medium",
+            title: `${operationLabel} is carrying oversized context`,
+            summary: `${operationLabel} includes ${scopedRecords.length} high-input calls and ${formatNumber(totalInputTokens)} input tokens. This is a strong signal that retrieval or prompt context can be trimmed without changing the product surface.`,
+            evidence: [
+                { label: "High-input calls", value: String(scopedRecords.length), detail: "Calls at or above 100,000 input tokens" },
+                { label: "Input tokens", value: formatNumber(totalInputTokens) },
+                { label: "Spend attached to large context", value: formatUsd(scopedSpend) },
+                { label: "Dominant operation", value: operationLabel }
+            ],
+            affectedClients: keysFrom(scopedRecords, (record) => record.clientId),
+            affectedProjects: keysFrom(scopedRecords, (record) => record.projectId),
+            affectedAgents: keysFrom(scopedRecords, (record) => record.agentId),
+            affectedModels: keysFrom(scopedRecords, (record) => record.model),
+            estimatedImpactUsd: roundMoney(scopedSpend * 0.18),
+            confidence: combinedConfidence(scopedRecords.map((record) => record.costConfidence)),
+            recommendedAction: `Sample the largest ${operationLabel} prompts, cap retrieved chunks, and require justification before agents include full documents or long histories.`,
+            verificationNeeded: "Inspect representative prompts locally to confirm whether the large context is necessary for output quality."
+        }];
+}
+function topBreakdown(records, select) {
+    return breakdown(records, select)[0];
+}
+function breakdown(records, select) {
+    const groups = new Map();
+    for (const record of records) {
+        const key = select(record) ?? "unmapped";
+        groups.set(key, [...(groups.get(key) ?? []), record]);
+    }
+    return Array.from(groups.entries())
+        .map(([key, groupRecords]) => ({
+        key,
+        amountUsd: roundMoney(sumRecords(groupRecords)),
+        recordCount: groupRecords.length,
+        confidence: combinedConfidence(groupRecords.map((record) => record.costConfidence))
+    }))
+        .sort((left, right) => right.amountUsd - left.amountUsd || left.key.localeCompare(right.key));
+}
+function keysFrom(records, select) {
+    return Array.from(new Set(records.map(select).filter((value) => value !== undefined)));
+}
+function compactEvidence(items) {
+    return items.filter((item) => item !== undefined);
+}
+function sumRecords(records) {
+    return records.reduce((total, record) => total + (record.amountUsd ?? 0), 0);
+}
+function combinedConfidence(confidences) {
+    if (confidences.length === 0) {
+        return "missing";
+    }
+    return confidences.reduce((lowest, current) => confidenceRank[current] > confidenceRank[lowest] ? current : lowest);
+}
+function formatUsd(value) {
+    return `$${value.toFixed(2)}`;
+}
+function formatMultiplier(value) {
+    return `${(Math.round(value * 10) / 10).toFixed(1)}x`;
+}
+function formatPercent(value) {
+    return `${Math.round(value * 100)}%`;
+}
+function formatNumber(value) {
+    return new Intl.NumberFormat("en-US").format(value);
+}
+function slug(value) {
+    return value.toLowerCase().replace(/[^a-z0-9_]+/g, "-").replace(/^-|-$/g, "") || "unknown";
+}
+function roundMoney(value) {
+    return Math.round(value * 100) / 100;
+}
+//# sourceMappingURL=insights.js.map

package/dist/localAgentLogs.d.ts

@@ -0,0 +1,53 @@
+import { type TokenUsage } from "./modelPricing.js";
+import type { UsageRecord } from "./schema.js";
+/**
+ * Local agent-session log ingestion: turns the transcript files that coding
+ * agents already write on this machine into UsageRecords, priced at
+ * API-equivalent rates ("estimated" confidence).
+ *
+ * Why this exists: subscription usage (Claude Max, ChatGPT plans) has NO
+ * billing API — local logs are the only place that spend is visible. This is
+ * also what makes the zero-key first run show REAL numbers.
+ *
+ * Supported agents:
+ *  - Claude Code: ~/.claude/projects/** /*.jsonl — one JSON object per line;
+ *    assistant messages carry message.usage token counts.
+ *  - Codex CLI: ~/.codex/sessions/YYYY/MM/DD/rollout-*.jsonl — event stream;
+ *    the LAST event_msg/token_count carries the session's cumulative
+ *    total_token_usage (earlier ones are running updates — never summed).
+ */
+export type LocalAgentCall = {
+    agent: "claude-code" | "codex";
+    model: string;
+    /** ISO timestamp of the call (or session start for session-level entries). */
+    timestamp: string;
+    /** Project attribution derived from the session's working directory. */
+    project?: string;
+    usage: TokenUsage;
+    sessionId?: string;
+};
+export type LocalAgentLogOptions = {
+    /** Default: ~/.claude/projects */
+    claudeProjectsDir?: string;
+    /** Default: ~/.codex/sessions */
+    codexSessionsDir?: string;
+    /** Only include calls at/after this ISO timestamp. */
+    sinceIso?: string;
+};
+export type LocalAgentLogResult = {
+    records: UsageRecord[];
+    /** Per-call entries before aggregation (for drill-down/debugging). */
+    calls: LocalAgentCall[];
+    filesParsed: number;
+    /** Which agents actually had data on this machine. */
+    agentsDetected: string[];
+};
+/** Parse one Claude Code transcript (JSONL). Exported for tests. */
+export declare function parseClaudeCodeTranscript(content: string, filePath?: string): LocalAgentCall[];
+/** Parse one Codex rollout file (JSONL event stream). Exported for tests. */
+export declare function parseCodexRollout(content: string): LocalAgentCall[];
+/** Scan this machine's agent logs and return aggregated UsageRecords. */
+export declare function loadLocalAgentUsage(options?: LocalAgentLogOptions): Promise<LocalAgentLogResult>;
+/** Aggregate per-call usage into one UsageRecord per day+agent+model+project. */
+export declare function aggregateCalls(calls: LocalAgentCall[]): UsageRecord[];
+//# sourceMappingURL=localAgentLogs.d.ts.map