@agent-finops/core 0.1.0 → 0.1.3

package/dist/agentInventory.d.ts

@@ -0,0 +1,86 @@
+/**
+ * Agent context inventory: enumerate the Claude Code "inventory" that gets
+ * loaded into an agent's always-on context (skills, subagents, slash commands,
+ * MCP servers + their tools) and estimate how many tokens each item adds.
+ *
+ * This feeds a later "dead-context cost" feature that prices loaded-but-never-
+ * invoked tools. Every read here is read-only and missing dirs/files never throw.
+ *
+ * CRITICAL token-weight rules (these drive the honesty of the final $ number):
+ *  - Skills use *progressive disclosure*: only the YAML frontmatter (`name` +
+ *    `description`) is always loaded — the body loads only when invoked. So a
+ *    skill's alwaysLoadedTokens reflects ONLY name + description, never the body.
+ *  - MCP tools: the FULL tool definition (name + description + JSON input schema)
+ *    is always loaded — the heavy weight. Config (~/.claude.json) almost never
+ *    carries tool schemas, so MCP enumeration is usually limited to server names;
+ *    those items are flagged "estimated_understated" because the real weight is
+ *    larger than what we can see.
+ *  - Subagents / slash commands: estimate from their description/frontmatter line
+ *    only (what is surfaced in the always-loaded list), not the whole file body.
+ *  - Built-in tools (Read/Edit/Bash/Glob/Grep/etc.) are EXCLUDED entirely: always
+ *    loaded, not prunable, not "waste."
+ */
+export type InventoryKind = "skill" | "subagent" | "command" | "mcp_tool" | "mcp_server";
+export type InventoryItem = {
+    kind: InventoryKind;
+    /**
+     * Canonical matchable name. mcp tool: "mcp__<server>__<tool>"; mcp server:
+     * the server id; skill/subagent/command: their declared name.
+     */
+    name: string;
+    scope: "user" | "project";
+    /** e.g. mcp server name for an mcp_tool, plugin name for a plugin skill. */
+    group?: string;
+    alwaysLoadedTokens: number;
+    /** "estimated_understated" when an MCP tool schema is unavailable. */
+    weightConfidence: "estimated" | "estimated_understated";
+    path?: string;
+};
+export type AgentInventoryOptions = {
+    /** Default: ~/.claude */
+    claudeHomeDir?: string;
+    /** Default: ~/.claude.json */
+    claudeConfigPath?: string;
+    /** Default: process.cwd(); scans <projectDir>/.claude/**. */
+    projectDir?: string;
+    /**
+     * Include MCP servers from EVERY project in the config (not just projectDir).
+     * Used for the global "across your whole setup" dead-context view so the
+     * first run is populated from any directory. Default false (project-scoped).
+     */
+    includeAllProjectMcp?: boolean;
+};
+export type AgentInventoryResult = {
+    items: InventoryItem[];
+    scanned: {
+        skills: number;
+        subagents: number;
+        commands: number;
+        mcpServers: number;
+        mcpTools: number;
+    };
+};
+/** Token estimate: Math.ceil(chars / 4). Exported so the parent reuses it. */
+export declare function estimateTokensFromText(text: string): number;
+/**
+ * Conservative floor for an MCP server's always-loaded token weight when its
+ * tool schemas aren't readable from config. A single tool's
+ * name+description+JSON-schema is commonly ~300–800 tokens and servers usually
+ * expose several; 700 is a deliberately low estimate, always paired with
+ * weightConfidence "estimated_understated" so we under-claim, never over-claim.
+ */
+export declare const MCP_SERVER_TOKEN_FLOOR = 700;
+/** Scan this machine's (and the project's) agent inventory. Never throws. */
+export declare function loadAgentInventory(options?: AgentInventoryOptions): Promise<AgentInventoryResult>;
+type Frontmatter = {
+    name?: string;
+    description?: string;
+};
+/**
+ * Extract `name` and `description` from a leading `---` fenced YAML block.
+ * Handles quoted values and folded/multi-line descriptions (continuation lines
+ * are read until the next top-level `key:` or the closing fence).
+ */
+export declare function parseFrontmatter(content: string): Frontmatter;
+export {};
+//# sourceMappingURL=agentInventory.d.ts.map

package/dist/agentInventory.js

@@ -0,0 +1,324 @@
+import { readdir, readFile, stat } from "node:fs/promises";
+import { basename, join } from "node:path";
+import { homedir } from "node:os";
+/** Token estimate: Math.ceil(chars / 4). Exported so the parent reuses it. */
+export function estimateTokensFromText(text) {
+    return Math.ceil(text.length / 4);
+}
+/**
+ * Conservative floor for an MCP server's always-loaded token weight when its
+ * tool schemas aren't readable from config. A single tool's
+ * name+description+JSON-schema is commonly ~300–800 tokens and servers usually
+ * expose several; 700 is a deliberately low estimate, always paired with
+ * weightConfidence "estimated_understated" so we under-claim, never over-claim.
+ */
+export const MCP_SERVER_TOKEN_FLOOR = 700;
+/** Scan this machine's (and the project's) agent inventory. Never throws. */
+export async function loadAgentInventory(options = {}) {
+    const home = homedir();
+    const claudeHome = options.claudeHomeDir ?? join(home, ".claude");
+    const configPath = options.claudeConfigPath ?? join(home, ".claude.json");
+    const projectDir = options.projectDir ?? process.cwd();
+    const projectClaude = join(projectDir, ".claude");
+    const items = [];
+    const scanned = { skills: 0, subagents: 0, commands: 0, mcpServers: 0, mcpTools: 0 };
+    // --- Skills (user + project) ---
+    for (const { dir, scope } of [
+        { dir: join(claudeHome, "skills"), scope: "user" },
+        { dir: join(projectClaude, "skills"), scope: "project" }
+    ]) {
+        for (const file of await findFiles(dir, (name) => name === "SKILL.md")) {
+            const content = await readFile(file, "utf8").catch(() => "");
+            if (!content)
+                continue;
+            scanned.skills += 1;
+            const fm = parseFrontmatter(content);
+            const name = fm.name ?? skillNameFromPath(file, dir);
+            // Only frontmatter (name + description) is always loaded — progressive disclosure.
+            const loadedText = [
+                name ? `name: ${name}` : "",
+                fm.description ? `description: ${fm.description}` : ""
+            ]
+                .filter(Boolean)
+                .join("\n");
+            items.push({
+                kind: "skill",
+                name,
+                scope,
+                group: pluginGroupFromPath(file, dir),
+                alwaysLoadedTokens: estimateTokensFromText(loadedText),
+                weightConfidence: "estimated",
+                path: file
+            });
+        }
+    }
+    // --- Subagents (user + project) ---
+    for (const { dir, scope } of [
+        { dir: join(claudeHome, "agents"), scope: "user" },
+        { dir: join(projectClaude, "agents"), scope: "project" }
+    ]) {
+        for (const file of await findFiles(dir, (name) => name.endsWith(".md"))) {
+            const content = await readFile(file, "utf8").catch(() => "");
+            if (!content)
+                continue;
+            scanned.subagents += 1;
+            const fm = parseFrontmatter(content);
+            const name = fm.name ?? basename(file).replace(/\.md$/i, "");
+            // Only the surfaced description line is always loaded, not the body.
+            const loadedText = [
+                `name: ${name}`,
+                fm.description ? `description: ${fm.description}` : ""
+            ]
+                .filter(Boolean)
+                .join("\n");
+            items.push({
+                kind: "subagent",
+                name,
+                scope,
+                alwaysLoadedTokens: estimateTokensFromText(loadedText),
+                weightConfidence: "estimated",
+                path: file
+            });
+        }
+    }
+    // --- Slash commands (user + project) ---
+    for (const { dir, scope } of [
+        { dir: join(claudeHome, "commands"), scope: "user" },
+        { dir: join(projectClaude, "commands"), scope: "project" }
+    ]) {
+        for (const file of await findFiles(dir, (name) => name.endsWith(".md"))) {
+            const content = await readFile(file, "utf8").catch(() => "");
+            if (!content)
+                continue;
+            scanned.commands += 1;
+            const fm = parseFrontmatter(content);
+            const name = commandNameFromPath(file, dir);
+            // Commands surface a name + (optional) description line in the always-loaded list.
+            const loadedText = [
+                `/${name}`,
+                fm.description ?? firstNonFrontmatterLine(content) ?? ""
+            ]
+                .filter(Boolean)
+                .join(" ");
+            items.push({
+                kind: "command",
+                name,
+                scope,
+                alwaysLoadedTokens: estimateTokensFromText(loadedText),
+                weightConfidence: "estimated",
+                path: file
+            });
+        }
+    }
+    // --- MCP servers (from ~/.claude.json: top-level + per-project map) ---
+    const config = await readJson(configPath);
+    const serverScopes = collectMcpServers(config, projectDir, options.includeAllProjectMcp ?? false);
+    for (const { id, scope } of serverScopes) {
+        scanned.mcpServers += 1;
+        // We almost never have tool schemas from config, so we can't measure the
+        // real weight (full tool definitions). Use a conservative published-typical
+        // FLOOR per server instead of the bare id — a single MCP tool's
+        // name+description+JSON schema is commonly several hundred tokens, and
+        // servers usually expose multiple tools. Flagged "estimated_understated":
+        // the true weight is almost certainly higher, never lower.
+        items.push({
+            kind: "mcp_server",
+            name: id,
+            scope,
+            group: id,
+            alwaysLoadedTokens: MCP_SERVER_TOKEN_FLOOR,
+            weightConfidence: "estimated_understated",
+            path: configPath
+        });
+    }
+    return { items, scanned };
+}
+// --------------------------------------------------------------------------
+// MCP config extraction
+// --------------------------------------------------------------------------
+function collectMcpServers(config, projectDir, includeAllProjectMcp) {
+    if (!isRecord(config))
+        return [];
+    const out = [];
+    const seen = new Set();
+    const add = (id, scope) => {
+        // Dedupe by id across all scopes so a server configured in several projects
+        // is counted once in the global view.
+        const key = includeAllProjectMcp ? id : `${scope}:${id}`;
+        if (seen.has(key))
+            return;
+        seen.add(key);
+        out.push({ id, scope });
+    };
+    // Top-level mcpServers are user-scope (global).
+    if (isRecord(config.mcpServers)) {
+        for (const id of Object.keys(config.mcpServers))
+            add(id, "user");
+    }
+    // Per-project mcpServers live under projects[<absolute dir>].mcpServers.
+    // Global view: collect every project's servers; otherwise just this project's.
+    if (isRecord(config.projects)) {
+        const entries = includeAllProjectMcp
+            ? Object.values(config.projects)
+            : [config.projects[projectDir]];
+        for (const projectEntry of entries) {
+            if (isRecord(projectEntry) && isRecord(projectEntry.mcpServers)) {
+                for (const id of Object.keys(projectEntry.mcpServers))
+                    add(id, "project");
+            }
+        }
+    }
+    return out;
+}
+/**
+ * Extract `name` and `description` from a leading `---` fenced YAML block.
+ * Handles quoted values and folded/multi-line descriptions (continuation lines
+ * are read until the next top-level `key:` or the closing fence).
+ */
+export function parseFrontmatter(content) {
+    const lines = content.split(/\r?\n/);
+    if ((lines[0] ?? "").trim() !== "---")
+        return {};
+    let end = -1;
+    for (let i = 1; i < lines.length; i += 1) {
+        if (lines[i].trim() === "---") {
+            end = i;
+            break;
+        }
+    }
+    if (end === -1)
+        return {};
+    const fm = {};
+    for (let i = 1; i < end; i += 1) {
+        const line = lines[i];
+        const match = /^([A-Za-z0-9_-]+):\s?(.*)$/.exec(line);
+        if (!match)
+            continue;
+        const key = match[1].toLowerCase();
+        if (key !== "name" && key !== "description")
+            continue;
+        let value = match[2];
+        // Block scalar (| or >): gather indented continuation lines.
+        if (value.trim() === "|" || value.trim() === ">" || value.trim() === "") {
+            const collected = [];
+            for (let j = i + 1; j < end; j += 1) {
+                if (/^([A-Za-z0-9_-]+):\s?/.test(lines[j]) && !/^\s/.test(lines[j]))
+                    break;
+                collected.push(lines[j].trim());
+                i = j;
+            }
+            value = collected.join(" ").trim();
+        }
+        else {
+            // Plain/quoted scalar may wrap onto following indented (non-key) lines.
+            for (let j = i + 1; j < end; j += 1) {
+                if (/^([A-Za-z0-9_-]+):\s?/.test(lines[j]) && !/^\s/.test(lines[j]))
+                    break;
+                if (lines[j].trim() === "")
+                    break;
+                value += ` ${lines[j].trim()}`;
+                i = j;
+            }
+        }
+        fm[key] = unquote(value.trim());
+    }
+    return fm;
+}
+function firstNonFrontmatterLine(content) {
+    const lines = content.split(/\r?\n/);
+    let start = 0;
+    if ((lines[0] ?? "").trim() === "---") {
+        for (let i = 1; i < lines.length; i += 1) {
+            if (lines[i].trim() === "---") {
+                start = i + 1;
+                break;
+            }
+        }
+    }
+    for (let i = start; i < lines.length; i += 1) {
+        const trimmed = lines[i].trim().replace(/^#+\s*/, "");
+        if (trimmed)
+            return trimmed;
+    }
+    return undefined;
+}
+function unquote(value) {
+    if (value.length >= 2) {
+        const first = value[0];
+        const last = value[value.length - 1];
+        if ((first === '"' && last === '"') || (first === "'" && last === "'")) {
+            return value.slice(1, -1);
+        }
+    }
+    return value;
+}
+// --------------------------------------------------------------------------
+// Path / name helpers
+// --------------------------------------------------------------------------
+/** Skill name fallback: the directory that contains SKILL.md. */
+function skillNameFromPath(file, root) {
+    const parent = basename(join(file, ".."));
+    return parent && parent !== basename(root) ? parent : basename(file);
+}
+/** Plugin skills nest one level deeper (root/<plugin>/<skill>/SKILL.md). */
+function pluginGroupFromPath(file, root) {
+    const rel = relativeSegments(file, root);
+    // rel = [..., <plugin>, <skill>, "SKILL.md"] when nested under a plugin.
+    if (rel.length >= 3)
+        return rel[0];
+    return undefined;
+}
+/** Slash command name: path under commands/ joined by ":" (namespacing). */
+function commandNameFromPath(file, root) {
+    const rel = relativeSegments(file, root);
+    const parts = rel.map((s) => s).filter(Boolean);
+    const last = parts.pop() ?? basename(file);
+    const name = last.replace(/\.md$/i, "");
+    return parts.length > 0 ? `${parts.join(":")}:${name}` : name;
+}
+function relativeSegments(file, root) {
+    const normFile = file.replace(/\\/g, "/");
+    const normRoot = root.replace(/\\/g, "/").replace(/\/$/, "");
+    const rest = normFile.startsWith(normRoot + "/")
+        ? normFile.slice(normRoot.length + 1)
+        : basename(file);
+    return rest.split("/").filter(Boolean);
+}
+// --------------------------------------------------------------------------
+// Filesystem + typed helpers (style mirrors localAgentLogs.ts)
+// --------------------------------------------------------------------------
+/** Recursively collect files under `root` whose basename matches `match`. */
+async function findFiles(root, match) {
+    const isDir = await stat(root).then((s) => s.isDirectory()).catch(() => false);
+    if (!isDir)
+        return [];
+    const out = [];
+    const queue = [root];
+    while (queue.length > 0) {
+        const dir = queue.pop();
+        const entries = await readdir(dir, { withFileTypes: true }).catch(() => []);
+        for (const entry of entries) {
+            const path = join(dir, entry.name);
+            if (entry.isDirectory())
+                queue.push(path);
+            else if (entry.isFile() && match(entry.name))
+                out.push(path);
+        }
+    }
+    return out;
+}
+async function readJson(path) {
+    const content = await readFile(path, "utf8").catch(() => "");
+    if (!content)
+        return undefined;
+    try {
+        return JSON.parse(content);
+    }
+    catch {
+        return undefined;
+    }
+}
+function isRecord(value) {
+    return typeof value === "object" && value !== null;
+}
+//# sourceMappingURL=agentInventory.js.map

package/dist/analyze.js

@@ -6,6 +6,37 @@ const confidenceRank = {
     detected_unverified: 2,
     missing: 3
 };
+/**
+ * Planning ratios behind every "estimated impact/savings" figure this module
+ * emits. These are deliberately ROUND heuristics — orientation numbers for a
+ * first conversation, not measured savings — and every consumer labels them
+ * estimated. They are aligned with the documented per-model economics in
+ * cutList.ts (downgradeRules retain 20–50% of cost on downgrade-safe work;
+ * the Batch API retains 50%): applying those cuts to only the eligible slice
+ * of a workload typically lands in the 10–30% range below.
+ *
+ * If you change one, change the doc line with it. No undocumented multiplier
+ * may ever reach user-visible output — that is a product bug on an
+ * honest-numbers brand, not a style issue.
+ */
+const impactRatios = {
+    /** Portion of a workflow's spend typically cuttable via caps, caching, and tier routing. */
+    workflowSavings: 0.2,
+    /** Un-attributed workflow spend treated as margin-exposed until mapped to a client/project (coin-flip prior). */
+    workflowMarginRisk: 0.5,
+    /** Top-model spend recoverable by moving downgrade-safe work to a cheaper tier (see cutList.ts downgradeRules). */
+    modelDowngrade: 0.3,
+    /** Cost of oversized-context calls recoverable by trimming prompts/retrieval. */
+    promptTrimming: 0.15,
+    /** Spend on repeated identical operations recoverable via caching/memoization. */
+    caching: 0.25,
+    /** Top-agent spend avoidable with budget caps catching runaway loops. */
+    agentCaps: 0.15,
+    /** Total spend addressable by moving latency-tolerant work to Batch APIs (50% price × eligible slice). */
+    batching: 0.1,
+    /** Total spend addressable with price/quality routing across multiple providers. */
+    routing: 0.1
+};
 export function analyzeSpend(records) {
     const summary = {
         totalUsd: roundMoney(sumRecords(records)),
@@ -78,8 +109,8 @@ export function generateWorkflowWatch(records) {
         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 estimatedSavingsUsd = roundMoney(amountUsd * impactRatios.workflowSavings);
+        const estimatedMarginRiskUsd = roundMoney(amountUsd * impactRatios.workflowMarginRisk);
         const confidence = combinedConfidence(groupRecords.map((record) => record.costConfidence));
         const suggestedOptimization = workflowOptimizationFor(workflowKey, agentId);
         return {
@@ -115,7 +146,7 @@ export function generateRecommendations(records) {
             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),
+            estimatedImpactUsd: roundMoney(topModel.amountUsd * impactRatios.modelDowngrade),
             confidence: topModel.confidence,
             relatedKeys: [topModel.key]
         });
@@ -129,7 +160,7 @@ export function generateRecommendations(records) {
             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),
+            estimatedImpactUsd: roundMoney(sumRecords(highInputTokenRecords) * impactRatios.promptTrimming),
             confidence: combinedConfidence(highInputTokenRecords.map((record) => record.costConfidence)),
             relatedKeys: unique(highInputTokenRecords.map((record) => record.model))
         });
@@ -143,7 +174,7 @@ export function generateRecommendations(records) {
             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),
+            estimatedImpactUsd: roundMoney(sumRecords(records.filter((record) => repeatedOperations.includes(record.operation ?? ""))) * impactRatios.caching),
             confidence: combinedConfidence(records.map((record) => record.costConfidence)),
             relatedKeys: repeatedOperations
         });
@@ -158,7 +189,7 @@ export function generateRecommendations(records) {
             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),
+            estimatedImpactUsd: roundMoney(topAgent.amountUsd * impactRatios.agentCaps),
             confidence: topAgent.confidence,
             relatedKeys: [topAgent.key]
         });
@@ -171,7 +202,7 @@ export function generateRecommendations(records) {
             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),
+            estimatedImpactUsd: roundMoney(sumRecords(records) * impactRatios.batching),
             confidence: combinedConfidence(records.map((record) => record.costConfidence)),
             relatedKeys: ["usage-records"]
         });
@@ -185,7 +216,7 @@ export function generateRecommendations(records) {
             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),
+            estimatedImpactUsd: roundMoney(sumRecords(records) * impactRatios.routing),
             confidence: combinedConfidence(records.map((record) => record.costConfidence)),
             relatedKeys: sources
         });

package/dist/cutList.d.ts

@@ -22,8 +22,45 @@ export type CutAction = {
     /** Lowest confidence of the underlying records (drives how we caveat $). */
     confidence: CostConfidence;
     kind: "model_downgrade" | "context_trim" | "cache" | "batch";
+    /**
+     * IDs of the usage records this action's savings are computed from. Used to
+     * deduplicate overlapping recommendations so the same spend is never counted
+     * by two actions (see {@link buildRecommendedPlan}).
+     */
+    recordIds: string[];
 };
+/**
+ * A non-overlapping "recommended plan" plus the leftover overlapping
+ * opportunities. The recommended-plan total is the only savings number safe to
+ * present as a single figure: each underlying record is optimized by at most one
+ * action, so the total can never exceed the projected spend it draws from.
+ */
+export type RecommendedPlan = {
+    /** Actions chosen so their underlying records don't overlap. */
+    recommended: CutAction[];
+    /** Actions dropped because they target spend already claimed above. */
+    additional: CutAction[];
+    /** Deduplicated monthly savings — safe to display as one number. */
+    recommendedSavingsUsd: number;
+    /** Savings from the overlapping leftovers — NOT additive with the above. */
+    additionalSavingsUsd: number;
+    /** How the headline number was derived (for honest labeling). */
+    savingsMath: "deduplicated";
+};
+/**
+ * Select a non-overlapping subset of cut actions, highest-savings first. An
+ * action is added only if none of its records were already claimed by a
+ * previously selected action; otherwise it falls to {@link RecommendedPlan.additional}.
+ * This guarantees the recommended total never double-counts a dollar of spend.
+ */
+export declare function buildRecommendedPlan(actions: CutAction[]): RecommendedPlan;
 export declare function generateCutList(records: UsageRecord[]): CutAction[];
 /** Sum of all per-action estimated monthly savings. */
 export declare function totalEstimatedMonthlySavingsUsd(actions: CutAction[]): number;
+/**
+ * Public view of the observed window, so the renderer can caveat monthly
+ * projections honestly: a 30-day figure extrapolated from 1–2 days of data
+ * assumes the pattern repeats, which it may not.
+ */
+export declare function usageWindowDays(records: UsageRecord[]): number;
 //# sourceMappingURL=cutList.d.ts.map

package/dist/cutList.js

@@ -1,3 +1,33 @@
+/**
+ * Select a non-overlapping subset of cut actions, highest-savings first. An
+ * action is added only if none of its records were already claimed by a
+ * previously selected action; otherwise it falls to {@link RecommendedPlan.additional}.
+ * This guarantees the recommended total never double-counts a dollar of spend.
+ */
+export function buildRecommendedPlan(actions) {
+    const sorted = [...actions].sort((left, right) => right.estimatedMonthlySavingsUsd - left.estimatedMonthlySavingsUsd ||
+        left.id.localeCompare(right.id));
+    const claimed = new Set();
+    const recommended = [];
+    const additional = [];
+    for (const action of sorted) {
+        const overlaps = action.recordIds.some((id) => claimed.has(id));
+        if (overlaps) {
+            additional.push(action);
+            continue;
+        }
+        for (const id of action.recordIds)
+            claimed.add(id);
+        recommended.push(action);
+    }
+    return {
+        recommended,
+        additional,
+        recommendedSavingsUsd: roundMoney(recommended.reduce((total, a) => total + a.estimatedMonthlySavingsUsd, 0)),
+        additionalSavingsUsd: roundMoney(additional.reduce((total, a) => total + a.estimatedMonthlySavingsUsd, 0)),
+        savingsMath: "deduplicated"
+    };
+}
 const confidenceRank = {
     verified: 0,
     estimated: 1,
@@ -5,12 +35,17 @@ const confidenceRank = {
     missing: 3
 };
 const downgradeRules = [
+    // Frontier tiers (mid-2026): Fable 5 ($10/$50 per M) -> Opus 4.8 ($5/$25)
+    // retains ~50% of cost; GPT-5.x -> matching mini tier retains ~20%.
+    { match: /^claude-fable-5(?:[.-].*)?$/i, target: "claude-opus-4-8", costRetained: 0.5 },
+    { match: /^gpt-5\.5$/i, target: "gpt-5.5-mini", costRetained: 0.2 },
+    { match: /^gpt-5(\.\d+)?$/i, target: "gpt-5-mini", costRetained: 0.2 },
     { 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-sonnet-4(?:[.-].*)?$/i, target: "claude-haiku-4-5", costRetained: 0.25 },
+    { match: /^claude-opus-4(?:[.-].*)?$/i, target: "claude-sonnet-4-6", costRetained: 0.3 },
     { match: /^claude-3-5-sonnet.*$/i, target: "claude-3-5-haiku", costRetained: 0.25 }
 ];
 /**
@@ -76,6 +111,7 @@ function modelDowngradeActions(records) {
             estimatedMonthlySavingsUsd: monthlySavings,
             affectedSpendUsd,
             recordCount: groupRecords.length,
+            recordIds: groupRecords.map((record) => record.id),
             confidence: combinedConfidence(groupRecords.map((record) => record.costConfidence)),
             kind: "model_downgrade"
         });
@@ -107,6 +143,7 @@ function contextTrimActions(records) {
             estimatedMonthlySavingsUsd: monthlySavings,
             affectedSpendUsd,
             recordCount: groupRecords.length,
+            recordIds: groupRecords.map((record) => record.id),
             confidence: combinedConfidence(groupRecords.map((record) => record.costConfidence)),
             kind: "context_trim"
         });
@@ -138,6 +175,7 @@ function cacheActions(records) {
             estimatedMonthlySavingsUsd: monthlySavings,
             affectedSpendUsd,
             recordCount: groupRecords.length,
+            recordIds: groupRecords.map((record) => record.id),
             confidence: combinedConfidence(groupRecords.map((record) => record.costConfidence)),
             kind: "cache"
         });
@@ -168,6 +206,7 @@ function batchActions(records) {
             estimatedMonthlySavingsUsd: monthlySavings,
             affectedSpendUsd,
             recordCount: groupRecords.length,
+            recordIds: groupRecords.map((record) => record.id),
             confidence: combinedConfidence(groupRecords.map((record) => record.costConfidence)),
             kind: "batch"
         });
@@ -179,6 +218,14 @@ function windowDays(records) {
     const days = new Set(records.map((record) => record.timestamp.slice(0, 10)));
     return Math.max(1, days.size);
 }
+/**
+ * Public view of the observed window, so the renderer can caveat monthly
+ * projections honestly: a 30-day figure extrapolated from 1–2 days of data
+ * assumes the pattern repeats, which it may not.
+ */
+export function usageWindowDays(records) {
+    return windowDays(records);
+}
 /** Project a window's savings to a 30-day month. */
 function toMonthly(windowSavings, windowDayCount) {
     return (windowSavings / windowDayCount) * 30;