@agent-finops/core 0.1.0

package/dist/analyze.d.ts

@@ -0,0 +1,6 @@
+import { type Recommendation, type SpendAnomaly, type SpendSummary, type UsageRecord, type WorkflowWatchEntry } from "./schema.js";
+export declare function analyzeSpend(records: UsageRecord[]): SpendSummary;
+export declare function detectSpendSpikes(records: UsageRecord[]): SpendAnomaly[];
+export declare function generateWorkflowWatch(records: UsageRecord[]): WorkflowWatchEntry[];
+export declare function generateRecommendations(records: UsageRecord[]): Recommendation[];
+//# sourceMappingURL=analyze.d.ts.map

package/dist/analyze.js

@@ -0,0 +1,260 @@
+import { generateSpendInsights } from "./insights.js";
+import { costConfidenceValues, spendSummarySchema } from "./schema.js";
+const confidenceRank = {
+    verified: 0,
+    estimated: 1,
+    detected_unverified: 2,
+    missing: 3
+};
+export function analyzeSpend(records) {
+    const summary = {
+        totalUsd: roundMoney(sumRecords(records)),
+        recordCount: records.length,
+        confidence: combinedConfidence(records.map((record) => record.costConfidence)),
+        confidenceBreakdown: confidenceBreakdown(records),
+        bySource: breakdown(records, (record) => record.source.id),
+        byModel: breakdown(records, (record) => record.model),
+        byClient: breakdown(records, (record) => record.clientId),
+        byProject: breakdown(records, (record) => record.projectId),
+        byAgent: breakdown(records, (record) => record.agentId),
+        byUser: breakdown(records, (record) => record.userId),
+        byWorkspace: breakdown(records, (record) => record.workspaceId),
+        byApiKey: breakdown(records, (record) => record.apiKeyId),
+        workflowWatch: generateWorkflowWatch(records),
+        anomalies: detectSpendSpikes(records),
+        recommendations: generateRecommendations(records),
+        insights: []
+    };
+    summary.insights = generateSpendInsights(records, summary);
+    return spendSummarySchema.parse(summary);
+}
+export function detectSpendSpikes(records) {
+    const byDay = new Map();
+    for (const record of records) {
+        const day = record.timestamp.slice(0, 10);
+        byDay.set(day, [...(byDay.get(day) ?? []), record]);
+    }
+    const days = [...byDay.keys()].sort();
+    const anomalies = [];
+    for (let index = 1; index < days.length; index += 1) {
+        const previousDay = days[index - 1];
+        const currentDay = days[index];
+        const previousAmountUsd = roundMoney(sumRecords(byDay.get(previousDay) ?? []));
+        const currentRecords = byDay.get(currentDay) ?? [];
+        const currentAmountUsd = roundMoney(sumRecords(currentRecords));
+        if (previousAmountUsd === 0 || currentAmountUsd - previousAmountUsd < 10) {
+            continue;
+        }
+        const multiplier = currentAmountUsd / previousAmountUsd;
+        if (multiplier >= 1.75) {
+            anomalies.push({
+                kind: "day_over_day_spike",
+                key: currentDay,
+                previousAmountUsd,
+                currentAmountUsd,
+                multiplier: roundMoney(multiplier),
+                confidence: combinedConfidence(currentRecords.map((record) => record.costConfidence))
+            });
+        }
+    }
+    return anomalies;
+}
+export function generateWorkflowWatch(records) {
+    const totalUsd = sumRecords(records);
+    if (totalUsd === 0) {
+        return [];
+    }
+    const groups = new Map();
+    for (const record of records) {
+        const clientId = record.clientId ?? "unmapped-client";
+        const projectId = record.projectId ?? "unmapped-project";
+        const workflowKey = record.operation ?? "unmapped-workflow";
+        const agentId = record.agentId ?? "unmapped-agent";
+        const key = [clientId, projectId, workflowKey, agentId].join("::");
+        groups.set(key, [...(groups.get(key) ?? []), record]);
+    }
+    return [...groups.entries()]
+        .map(([key, groupRecords]) => {
+        const [clientId, projectId, workflowKey, agentId] = key.split("::");
+        const amountUsd = roundMoney(sumRecords(groupRecords));
+        const shareOfSpend = roundRatio(amountUsd / totalUsd);
+        const estimatedSavingsUsd = roundMoney(amountUsd * 0.236875);
+        const estimatedMarginRiskUsd = roundMoney(amountUsd * 0.625);
+        const confidence = combinedConfidence(groupRecords.map((record) => record.costConfidence));
+        const suggestedOptimization = workflowOptimizationFor(workflowKey, agentId);
+        return {
+            id: slugify(["workflow", clientId, projectId, workflowKey].join("-")),
+            clientId,
+            projectId,
+            workflowKey,
+            agentId,
+            amountUsd,
+            shareOfSpend,
+            recordCount: groupRecords.length,
+            confidence,
+            estimatedMarginRiskUsd,
+            estimatedSavingsUsd,
+            suggestedOptimization,
+            applyArtifact: `Copy this into your coding agent to cut cost: ${suggestedOptimization}`,
+            verificationPlan: `After applying, rerun the ${workflowKey} workflow on the same sample and compare spend, latency, and output acceptance before rolling it out.`
+        };
+    })
+        .filter((entry) => entry.amountUsd > 0)
+        .sort((left, right) => right.estimatedMarginRiskUsd - left.estimatedMarginRiskUsd || left.id.localeCompare(right.id))
+        .slice(0, 5);
+}
+export function generateRecommendations(records) {
+    const recommendations = [];
+    const modelSpend = breakdown(records, (record) => record.model);
+    const topModel = modelSpend[0];
+    if (topModel && topModel.amountUsd >= 20) {
+        recommendations.push({
+            id: "model-downgrade",
+            title: "Review expensive model workloads for downgrade candidates",
+            rationale: `${topModel.key} is the largest cost driver in the current local sample.`,
+            whyItMatters: "Premium model usage tends to become invisible once agents are running in the background. Board owners need a clear rule for which jobs deserve the expensive model.",
+            nextAction: `Audit the top ${topModel.key} operations and move low-risk summarization, extraction, and draft work to a cheaper model tier first.`,
+            priority: "high",
+            estimatedImpactUsd: roundMoney(topModel.amountUsd * 0.3237),
+            confidence: topModel.confidence,
+            relatedKeys: [topModel.key]
+        });
+    }
+    const highInputTokenRecords = records.filter((record) => record.inputTokens >= 100_000);
+    if (highInputTokenRecords.length > 0) {
+        recommendations.push({
+            id: "prompt-context-trimming",
+            title: "Trim large prompts and retrieved context",
+            rationale: "High input-token calls suggest prompt or retrieval context may be oversized.",
+            whyItMatters: "Context bloat compounds across every agent run and can make spend rise even when output quality does not improve.",
+            nextAction: "Sample the largest prompts, cap retrieval chunks, and require justification before agents include full documents or long histories.",
+            priority: "high",
+            estimatedImpactUsd: roundMoney(sumRecords(highInputTokenRecords) * 0.18),
+            confidence: combinedConfidence(highInputTokenRecords.map((record) => record.costConfidence)),
+            relatedKeys: unique(highInputTokenRecords.map((record) => record.model))
+        });
+    }
+    const repeatedOperations = repeatedValues(records.map((record) => record.operation).filter(isPresent));
+    if (repeatedOperations.length > 0) {
+        recommendations.push({
+            id: "caching",
+            title: "Cache repeated operations",
+            rationale: "Repeated operation labels are present in the sample and may be cacheable.",
+            whyItMatters: "Repeated AI calls are the easiest spend to defend cutting because they usually do not change the customer experience.",
+            nextAction: "Add a local cache or memoization policy for repeated operation labels before expanding this workflow to more clients.",
+            priority: "medium",
+            estimatedImpactUsd: roundMoney(sumRecords(records.filter((record) => repeatedOperations.includes(record.operation ?? ""))) * 0.25),
+            confidence: combinedConfidence(records.map((record) => record.costConfidence)),
+            relatedKeys: repeatedOperations
+        });
+    }
+    const agentSpend = breakdown(records, (record) => record.agentId);
+    const topAgent = agentSpend[0];
+    if (topAgent && topAgent.amountUsd >= 25) {
+        recommendations.push({
+            id: "agent-caps",
+            title: "Set local spend caps for the highest-cost agent",
+            rationale: `${topAgent.key} accounts for a material share of sampled usage.`,
+            whyItMatters: "An autonomous agent can quietly turn one bad loop or broad task into a budget issue before anyone reviews the invoice.",
+            nextAction: `Set a warning threshold and hard cap for ${topAgent.key}, then require approval when a run exceeds its expected range.`,
+            priority: "high",
+            estimatedImpactUsd: roundMoney(topAgent.amountUsd * 0.15),
+            confidence: topAgent.confidence,
+            relatedKeys: [topAgent.key]
+        });
+    }
+    if (records.length >= 8) {
+        recommendations.push({
+            id: "batching",
+            title: "Batch low-latency-tolerant work",
+            rationale: "The sample contains enough discrete calls to review for batching opportunities.",
+            whyItMatters: "Batching turns scattered background calls into an intentional queue, which makes spend easier to forecast and approve.",
+            nextAction: "Mark jobs that do not need immediate responses and run them in scheduled batches with a shared context budget.",
+            priority: "medium",
+            estimatedImpactUsd: roundMoney(sumRecords(records) * 0.08),
+            confidence: combinedConfidence(records.map((record) => record.costConfidence)),
+            relatedKeys: ["usage-records"]
+        });
+    }
+    const sources = unique(records.map((record) => record.source.id));
+    if (sources.length > 1) {
+        recommendations.push({
+            id: "routing",
+            title: "Route workloads by price and quality requirements",
+            rationale: "Multiple AI providers are represented, so routing policy can reduce avoidable spend.",
+            whyItMatters: "Without routing policy, teams pay premium prices for tasks where cheaper models or providers would be good enough.",
+            nextAction: "Define default provider/model tiers for extraction, drafting, research, and high-stakes reasoning, then measure quality deltas.",
+            priority: "medium",
+            estimatedImpactUsd: roundMoney(sumRecords(records) * 0.12),
+            confidence: combinedConfidence(records.map((record) => record.costConfidence)),
+            relatedKeys: sources
+        });
+    }
+    return recommendations;
+}
+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 [...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 sumRecords(records) {
+    return records.reduce((total, record) => total + (record.amountUsd ?? 0), 0);
+}
+function confidenceBreakdown(records) {
+    return Object.fromEntries(costConfidenceValues.map((confidence) => [
+        confidence,
+        roundMoney(sumRecords(records.filter((record) => record.costConfidence === confidence)))
+    ]));
+}
+function combinedConfidence(confidences) {
+    if (confidences.length === 0) {
+        return "missing";
+    }
+    return confidences.reduce((lowest, current) => confidenceRank[current] > confidenceRank[lowest] ? current : lowest);
+}
+function repeatedValues(values) {
+    const counts = new Map();
+    for (const value of values) {
+        counts.set(value, (counts.get(value) ?? 0) + 1);
+    }
+    return [...counts.entries()]
+        .filter(([, count]) => count > 1)
+        .map(([value]) => value)
+        .sort();
+}
+function unique(values) {
+    return [...new Set(values)].sort();
+}
+function isPresent(value) {
+    return value !== undefined;
+}
+function workflowOptimizationFor(workflowKey, agentId) {
+    const normalized = workflowKey.toLowerCase();
+    if (normalized.includes("research") || normalized.includes("summary")) {
+        return `Cap context for ${workflowKey}, cache repeated research inputs, and route first-pass summaries from ${agentId} to a cheaper model tier unless confidence drops.`;
+    }
+    if (normalized.includes("draft") || normalized.includes("copy")) {
+        return `Move first-draft generation for ${workflowKey} to a cheaper model tier, keep premium review only for final approval, and cache brand/context blocks.`;
+    }
+    return `Add a per-run budget cap for ${workflowKey}, route low-risk calls to a cheaper model tier, and cache stable inputs before expanding ${agentId}.`;
+}
+function slugify(value) {
+    return value.toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-|-$/g, "");
+}
+function roundRatio(value) {
+    return Math.round(value * 10_000) / 10_000;
+}
+function roundMoney(value) {
+    return Math.round(value * 100) / 100;
+}
+//# sourceMappingURL=analyze.js.map

package/dist/attribution.d.ts

@@ -0,0 +1,4 @@
+import type { AttributionMapping, UsageRecord } from "./schema.js";
+export declare function classifyAttributionConfidence(confidence: number): AttributionMapping["status"];
+export declare function attributeUsageRecords(records: UsageRecord[]): AttributionMapping[];
+//# sourceMappingURL=attribution.d.ts.map

package/dist/attribution.js

@@ -0,0 +1,117 @@
+export function classifyAttributionConfidence(confidence) {
+    if (confidence >= 0.95) {
+        return "auto_mapped";
+    }
+    if (confidence >= 0.75) {
+        return "needs_confirmation";
+    }
+    if (confidence >= 0.5) {
+        return "needs_question";
+    }
+    return "unmapped";
+}
+export function attributeUsageRecords(records) {
+    return records.map((record) => {
+        const candidates = buildCandidates(record).sort((left, right) => right.confidence - left.confidence);
+        const selected = candidates[0];
+        const status = selected ? classifyAttributionConfidence(selected.confidence) : "unmapped";
+        return {
+            usageRecordId: record.id,
+            candidates,
+            selected: status === "unmapped" ? undefined : selected,
+            status,
+            evidence: candidates.flatMap((candidate) => candidate.evidence)
+        };
+    });
+}
+function buildCandidates(record) {
+    const candidates = [];
+    if (record.projectId) {
+        candidates.push({
+            entityType: "project",
+            entityId: record.projectId,
+            confidence: 0.98,
+            evidence: [`usage record includes projectId ${record.projectId}`]
+        });
+    }
+    if (record.clientId) {
+        candidates.push({
+            entityType: "client",
+            entityId: record.clientId,
+            confidence: 0.97,
+            evidence: [`usage record includes clientId ${record.clientId}`]
+        });
+    }
+    if (record.agentId) {
+        candidates.push({
+            entityType: "agent",
+            entityId: record.agentId,
+            confidence: 0.96,
+            evidence: [`usage record includes agentId ${record.agentId}`]
+        });
+    }
+    if (record.userId) {
+        candidates.push({
+            entityType: "user",
+            entityId: record.userId,
+            confidence: 0.94,
+            evidence: [`usage record includes userId ${record.userId}`]
+        });
+    }
+    if (record.workspaceId) {
+        candidates.push({
+            entityType: "workspace",
+            entityId: record.workspaceId,
+            confidence: 0.93,
+            evidence: [`usage record includes workspaceId ${record.workspaceId}`]
+        });
+    }
+    if (record.apiKeyId) {
+        candidates.push({
+            entityType: "api_key",
+            entityId: record.apiKeyId,
+            confidence: 0.9,
+            evidence: [`usage record includes apiKeyId ${record.apiKeyId}`]
+        });
+    }
+    const operation = record.operation?.toLowerCase() ?? "";
+    const clientMatch = operation.match(/client[_-]([a-z0-9-]+)/);
+    if (clientMatch?.[1]) {
+        candidates.push({
+            entityType: "client",
+            entityId: `client-${clientMatch[1]}`,
+            confidence: 0.82,
+            evidence: [`operation label references client_${clientMatch[1]}`]
+        });
+    }
+    const agentMatch = operation.match(/agent[_-]([a-z0-9-]+)/);
+    if (agentMatch?.[1]) {
+        candidates.push({
+            entityType: "agent",
+            entityId: `agent-${agentMatch[1]}`,
+            confidence: 0.8,
+            evidence: [`operation label references agent_${agentMatch[1]}`]
+        });
+    }
+    if (candidates.length === 0 && /claude|anthropic/i.test(`${record.source.provider} ${record.model}`)) {
+        candidates.push({
+            entityType: "agent",
+            entityId: "agent-claude-workflows",
+            confidence: 0.58,
+            evidence: [`model/source suggests Claude or Anthropic workflow: ${record.model}`]
+        });
+    }
+    return dedupeCandidates(candidates);
+}
+function dedupeCandidates(candidates) {
+    const byKey = new Map();
+    for (const candidate of candidates) {
+        const key = `${candidate.entityType}:${candidate.entityId}`;
+        const existing = byKey.get(key);
+        if (!existing || candidate.confidence > existing.confidence) {
+            byKey.set(key, candidate);
+        }
+    }
+    return Array.from(byKey.values());
+}
+//# sourceMappingURL=attribution.js.map

package/dist/credentialDetection.d.ts

@@ -0,0 +1,45 @@
+/**
+ * Local credential auto-detection.
+ *
+ * CRITICAL SAFETY CONTRACT: this module NEVER returns, stores, or prints a raw
+ * secret value. It returns only:
+ *   - the environment-variable NAME a key lives in (so callers can use the
+ *     existing `env:NAME` reference pattern from sync-provider), and
+ *   - a redacted last-4 hint for human recognition.
+ * Raw values are read transiently to classify them and are never surfaced.
+ */
+export type DetectedCredential = {
+    provider: "openai" | "anthropic";
+    /** Reference usable with sync-provider, e.g. "env:OPENAI_API_KEY". */
+    reference: string;
+    /** The env var name the key was found in. */
+    envName: string;
+    /** Where we found it. */
+    origin: "process_env" | "dotenv" | "shell_rc";
+    /** Path of the file it was found in (for dotenv/shell_rc), redacted-safe. */
+    filePath?: string;
+    /** Redacted recognition hint, e.g. "sk-...­a1b2". Never the full key. */
+    hint: string;
+    /**
+     * Whether this looks like it CAN return cost data. Regular API keys cannot:
+     * all four providers gate cost/usage behind admin/owner credentials.
+     */
+    isLikelyAdminKey: boolean;
+};
+export type CredentialDetectionResult = {
+    credentials: DetectedCredential[];
+    /** Files scanned (paths only), for transparency / audit. */
+    scannedFiles: string[];
+};
+export type DetectCredentialsOptions = {
+    /** Working directory to look for .env files in. */
+    cwd?: string;
+    /** Override process.env (used in tests). */
+    env?: Record<string, string | undefined>;
+    /** Home directory override (used in tests). */
+    home?: string;
+    /** Skip reading shell rc files (faster / sandbox-safe). */
+    skipShellRc?: boolean;
+};
+export declare function detectLocalCredentials(options?: DetectCredentialsOptions): Promise<CredentialDetectionResult>;
+//# sourceMappingURL=credentialDetection.d.ts.map

package/dist/credentialDetection.js

@@ -0,0 +1,133 @@
+import { readFile } from "node:fs/promises";
+import { homedir } from "node:os";
+import { join } from "node:path";
+const providerRules = [
+    {
+        provider: "openai",
+        envNames: ["OPENAI_API_KEY", "OPENAI_ADMIN_KEY", "OPENAI_KEY"],
+        valuePattern: /^sk-[A-Za-z0-9_-]{16,}$/,
+        adminEnvHints: /ADMIN|ORG|OWNER/i
+    },
+    {
+        provider: "anthropic",
+        envNames: ["ANTHROPIC_API_KEY", "ANTHROPIC_ADMIN_KEY", "ANTHROPIC_KEY"],
+        valuePattern: /^sk-ant-[A-Za-z0-9_-]{16,}$/,
+        adminEnvHints: /ADMIN|ORG|OWNER/i
+    }
+];
+const defaultShellRcFiles = [".zshrc", ".bashrc", ".bash_profile", ".profile"];
+export async function detectLocalCredentials(options = {}) {
+    const cwd = options.cwd ?? process.cwd();
+    const env = options.env ?? process.env;
+    const home = options.home ?? homedir();
+    const scannedFiles = [];
+    const byReference = new Map();
+    // 1) process.env (highest signal; already loaded in the user's shell).
+    for (const rule of providerRules) {
+        for (const envName of rule.envNames) {
+            const value = env[envName];
+            if (value && rule.valuePattern.test(value.trim())) {
+                addCredential(byReference, {
+                    provider: rule.provider,
+                    reference: `env:${envName}`,
+                    envName,
+                    origin: "process_env",
+                    hint: redactHint(value.trim()),
+                    isLikelyAdminKey: rule.adminEnvHints.test(envName)
+                });
+            }
+        }
+    }
+    // 2) .env files in the working directory.
+    const dotenvCandidates = [".env", ".env.local"];
+    for (const fileName of dotenvCandidates) {
+        const filePath = join(cwd, fileName);
+        const parsed = await readEnvFile(filePath);
+        if (parsed) {
+            scannedFiles.push(filePath);
+            collectFromAssignments(byReference, parsed, "dotenv", filePath);
+        }
+    }
+    // 3) Shell rc files (export FOO=bar lines).
+    if (!options.skipShellRc) {
+        for (const fileName of defaultShellRcFiles) {
+            const filePath = join(home, fileName);
+            const parsed = await readEnvFile(filePath);
+            if (parsed) {
+                scannedFiles.push(filePath);
+                collectFromAssignments(byReference, parsed, "shell_rc", filePath);
+            }
+        }
+    }
+    return {
+        credentials: [...byReference.values()].sort((left, right) => left.provider.localeCompare(right.provider) || left.reference.localeCompare(right.reference)),
+        scannedFiles
+    };
+}
+function collectFromAssignments(byReference, assignments, origin, filePath) {
+    for (const rule of providerRules) {
+        for (const envName of rule.envNames) {
+            const value = assignments.get(envName);
+            if (value && rule.valuePattern.test(value)) {
+                addCredential(byReference, {
+                    provider: rule.provider,
+                    reference: `env:${envName}`,
+                    envName,
+                    origin,
+                    filePath,
+                    hint: redactHint(value),
+                    isLikelyAdminKey: rule.adminEnvHints.test(envName)
+                });
+            }
+        }
+    }
+}
+/** Prefer the highest-signal origin (process_env) when the same ref appears twice. */
+function addCredential(map, credential) {
+    const existing = map.get(credential.reference);
+    if (!existing || originRank(credential.origin) < originRank(existing.origin)) {
+        map.set(credential.reference, credential);
+    }
+}
+function originRank(origin) {
+    return origin === "process_env" ? 0 : origin === "dotenv" ? 1 : 2;
+}
+async function readEnvFile(path) {
+    let contents;
+    try {
+        contents = await readFile(path, "utf8");
+    }
+    catch {
+        return undefined;
+    }
+    const assignments = new Map();
+    for (const rawLine of contents.split(/\r?\n/)) {
+        const line = rawLine.trim();
+        if (!line || line.startsWith("#")) {
+            continue;
+        }
+        // Handles `FOO=bar`, `export FOO=bar`, and quoted values.
+        const match = /^(?:export\s+)?([A-Za-z_][A-Za-z0-9_]*)\s*=\s*(.*)$/.exec(line);
+        if (!match) {
+            continue;
+        }
+        const name = match[1];
+        let value = match[2].trim();
+        if ((value.startsWith('"') && value.endsWith('"')) || (value.startsWith("'") && value.endsWith("'"))) {
+            value = value.slice(1, -1);
+        }
+        // Strip inline comments on unquoted values.
+        value = value.replace(/\s+#.*$/, "").trim();
+        if (value) {
+            assignments.set(name, value);
+        }
+    }
+    return assignments;
+}
+/** Returns a recognition hint that never exposes the secret, e.g. "sk-...­f0a2". */
+function redactHint(value) {
+    const prefix = value.slice(0, 3);
+    const suffix = value.length >= 4 ? value.slice(-4) : "";
+    return `${prefix}...${suffix}`;
+}
+//# sourceMappingURL=credentialDetection.js.map

package/dist/cutList.d.ts

@@ -0,0 +1,29 @@
+import type { CostConfidence, UsageRecord } from "./schema.js";
+/**
+ * Actionable, dollar-specific "cut" suggestions.
+ *
+ * The product wow is specificity: instead of "review expensive model
+ * workloads", we say "move these 4 gpt-4.1 ticket_triage calls to
+ * gpt-4.1-mini -> save ~$3.10/mo". Every entry is grounded in real records
+ * from the loaded sample/usage so the dollar amount is defensible.
+ */
+export type CutAction = {
+    id: string;
+    /** Short imperative headline, e.g. "Move gpt-4.1 ticket_triage to gpt-4.1-mini". */
+    title: string;
+    /** One-line, copy-pasteable instruction with the exact target. */
+    action: string;
+    /** Estimated monthly savings in USD for this single action. */
+    estimatedMonthlySavingsUsd: number;
+    /** Spend (in the analyzed window) this action touches. */
+    affectedSpendUsd: number;
+    /** How many usage records this action is grounded in. */
+    recordCount: number;
+    /** Lowest confidence of the underlying records (drives how we caveat $). */
+    confidence: CostConfidence;
+    kind: "model_downgrade" | "context_trim" | "cache" | "batch";
+};
+export declare function generateCutList(records: UsageRecord[]): CutAction[];
+/** Sum of all per-action estimated monthly savings. */
+export declare function totalEstimatedMonthlySavingsUsd(actions: CutAction[]): number;
+//# sourceMappingURL=cutList.d.ts.map