@agent-finops/core 0.1.1 → 0.1.3

package/dist/deadContext.d.ts

@@ -0,0 +1,72 @@
+import { type AgentInventoryOptions, type InventoryItem } from "./agentInventory.js";
+import { type InvocationSummary, type ToolInvocationOptions } from "./toolInvocations.js";
+import type { CutAction } from "./cutList.js";
+export type DeadContextItem = {
+    kind: InventoryItem["kind"];
+    name: string;
+    alwaysLoadedTokens: number;
+    weightConfidence: InventoryItem["weightConfidence"];
+};
+export type DeadContextResult = {
+    /** True when we found inventory + transcripts AND at least one dead item. */
+    hasData: boolean;
+    /** True when these are illustrative sample numbers, not the user's real data. */
+    isSample?: boolean;
+    /** Prunable inventory items considered (built-ins excluded upstream). */
+    loadedCount: number;
+    /** Items never invoked across the parsed window (the defensible headline). */
+    deadCount: number;
+    /** Dead items whose token weight we MEASURED (skills/subagents/commands). */
+    measuredDeadCount: number;
+    /** Dead items whose weight we could NOT measure (MCP servers, no schemas). */
+    unmeasuredDeadCount: number;
+    /** Measured-only always-loaded tokens across dead items (per turn). */
+    deadTokens: number;
+    /** Measured-only dead tokens loaded into context over a month (projected). */
+    monthlyDeadTokens: number;
+    /** deadCount / loadedCount, 0..1. */
+    wastePercent: number;
+    /** Cache-aware monthly $, MEASURED items only (0 when only MCP is dead). */
+    monthlyUsd: number;
+    /** Upper bound (no prompt caching), measured items only. */
+    monthlyUsdUpperBound: number;
+    /** The never-used items, heaviest first. */
+    deadItems: DeadContextItem[];
+    sessions: number;
+    totalTurns: number;
+    /** Model whose rates priced the measured estimate. */
+    pricingModel: string;
+    /** Days the parsed transcripts were assumed to represent. */
+    windowDays: number;
+};
+export type DeadContextOptions = AgentInventoryOptions & ToolInvocationOptions & {
+    /** Days the parsed transcripts represent (for the /mo projection). Default 30. */
+    windowDays?: number;
+    /** Representative model for cache/input rates. Default claude-sonnet-4. */
+    pricingModel?: string;
+    /** Inject inventory/invocations (tests); otherwise loaded from disk. */
+    inventory?: {
+        items: InventoryItem[];
+    };
+    invocations?: InvocationSummary;
+};
+/** Load inventory + invocations from disk (or use injected ones) and price the waste. */
+export declare function loadDeadContext(options?: DeadContextOptions): Promise<DeadContextResult>;
+/**
+ * Illustrative dead-context numbers for the first-run / demo card, so the
+ * feature is always visible even when a user has nothing loaded yet. Clearly
+ * flagged isSample. Shows the measured-skills case (count + a small honest $).
+ */
+export declare function sampleDeadContext(): DeadContextResult;
+/** Pure core: compare inventory vs. invocations; count all dead, price only measured. */
+export declare function computeDeadContext(items: InventoryItem[], invocations: InvocationSummary, config: {
+    windowDays: number;
+    pricingModel: string;
+}): DeadContextResult;
+/**
+ * Adapt a dead-context result to a {@link CutAction} so it can flow into the
+ * ranked cut list / AI Receipt. Returns null unless there is MEASURED waste
+ * worth a dollar figure (MCP-only waste is shown as a count, not a cut $).
+ */
+export declare function deadContextCutAction(result: DeadContextResult): CutAction | null;
+//# sourceMappingURL=deadContext.d.ts.map

package/dist/deadContext.js

@@ -0,0 +1,174 @@
+import { loadAgentInventory } from "./agentInventory.js";
+import { findPricingRule } from "./modelPricing.js";
+import { loadToolInvocations } from "./toolInvocations.js";
+/**
+ * Dead-context: the tools an agent LOADS into context but NEVER calls. Compares
+ * the local Claude Code inventory (skills, subagents, slash commands, MCP
+ * servers — {@link loadAgentInventory}) against what real transcripts show was
+ * invoked ({@link loadToolInvocations}).
+ *
+ * ACCURACY CONTRACT (this is the credibility lever — read before changing):
+ *  - The COUNT + utilization % is always defensible and is the headline.
+ *  - A token/$ magnitude is ONLY computed from items whose weight we actually
+ *    MEASURED — skill/subagent/command frontmatter (weightConfidence
+ *    "estimated"). We never price items whose weight we could not measure.
+ *  - MCP servers have NO readable schemas in local config, so their real
+ *    weight is unknown. They are COUNTED as dead but NEVER assigned a $/token
+ *    figure — to size them we'd have to query each server's tools/list. They
+ *    surface as `unmeasuredDeadCount` so the renderer can say "not measurable".
+ *  - Pricing is cache-aware (one cache write/session + a read/turn), never the
+ *    inflated full-input-rate-every-turn number.
+ */
+const DEFAULT_WINDOW_DAYS = 30;
+/**
+ * Representative model for pricing measured dead context. Claude Code runs
+ * Anthropic models; Sonnet rates are a conservative middle. Always "estimated".
+ */
+const DEFAULT_PRICING_MODEL = "claude-sonnet-4";
+/** Load inventory + invocations from disk (or use injected ones) and price the waste. */
+export async function loadDeadContext(options = {}) {
+    const inventory = options.inventory ?? (await loadAgentInventory(options));
+    const invocations = options.invocations ?? (await loadToolInvocations(options));
+    return computeDeadContext(inventory.items, invocations, {
+        windowDays: options.windowDays ?? DEFAULT_WINDOW_DAYS,
+        pricingModel: options.pricingModel ?? DEFAULT_PRICING_MODEL
+    });
+}
+/**
+ * Illustrative dead-context numbers for the first-run / demo card, so the
+ * feature is always visible even when a user has nothing loaded yet. Clearly
+ * flagged isSample. Shows the measured-skills case (count + a small honest $).
+ */
+export function sampleDeadContext() {
+    const loadedCount = 38;
+    const deadCount = 29;
+    return {
+        hasData: true,
+        isSample: true,
+        loadedCount,
+        deadCount,
+        measuredDeadCount: deadCount,
+        unmeasuredDeadCount: 0,
+        deadTokens: 80,
+        monthlyDeadTokens: 120_000,
+        wastePercent: deadCount / loadedCount,
+        monthlyUsd: 0.4,
+        monthlyUsdUpperBound: 2.4,
+        deadItems: [],
+        sessions: 120,
+        totalTurns: 1500,
+        pricingModel: DEFAULT_PRICING_MODEL,
+        windowDays: 30
+    };
+}
+/** Pure core: compare inventory vs. invocations; count all dead, price only measured. */
+export function computeDeadContext(items, invocations, config) {
+    const windowDays = Math.max(1, config.windowDays);
+    const sessions = invocations.sessions;
+    const totalTurns = invocations.totalAssistantTurns;
+    const usedSkills = new Set(invocations.invokedSkills);
+    const usedSubagents = new Set(invocations.invokedSubagents);
+    const usedCommands = new Set(invocations.invokedCommands);
+    const usedMcpTools = new Set(invocations.invokedMcpTools);
+    // An MCP server counts as "used" if any invoked mcp tool belongs to it.
+    const usedMcpServers = new Set(invocations.invokedMcpTools.map((tool) => tool.split("__")[1]).filter((id) => Boolean(id)));
+    const dead = [];
+    let loadedCount = 0;
+    for (const item of items) {
+        loadedCount += 1;
+        if (!isDead(item, { usedSkills, usedSubagents, usedCommands, usedMcpTools, usedMcpServers })) {
+            continue;
+        }
+        dead.push({
+            kind: item.kind,
+            name: item.name,
+            alwaysLoadedTokens: item.alwaysLoadedTokens,
+            weightConfidence: item.weightConfidence
+        });
+    }
+    dead.sort((a, b) => b.alwaysLoadedTokens - a.alwaysLoadedTokens);
+    // Only items whose weight we actually measured get a $/token figure. MCP
+    // servers (weight unknown without querying tools/list) are counted, not priced.
+    const measuredDead = dead.filter((item) => item.weightConfidence === "estimated");
+    const unmeasuredDead = dead.filter((item) => item.weightConfidence !== "estimated");
+    const measuredTokens = measuredDead.reduce((total, item) => total + item.alwaysLoadedTokens, 0);
+    const hasData = items.length > 0 && sessions > 0 && dead.length > 0;
+    const rates = pricingRates(config.pricingModel);
+    // Cached: one cache write per session + a cache read on every later turn.
+    const cacheReads = Math.max(0, totalTurns - sessions);
+    const windowCachedUsd = (measuredTokens * (sessions * rates.write5mPerM + cacheReads * rates.cacheReadPerM)) / 1_000_000;
+    const windowUncachedUsd = (measuredTokens * totalTurns * rates.inputPerM) / 1_000_000;
+    const monthFactor = DEFAULT_WINDOW_DAYS / windowDays;
+    return {
+        hasData,
+        loadedCount,
+        deadCount: dead.length,
+        measuredDeadCount: measuredDead.length,
+        unmeasuredDeadCount: unmeasuredDead.length,
+        deadTokens: measuredTokens,
+        monthlyDeadTokens: Math.round(measuredTokens * totalTurns * monthFactor),
+        wastePercent: loadedCount > 0 ? dead.length / loadedCount : 0,
+        monthlyUsd: roundMoney(windowCachedUsd * monthFactor),
+        monthlyUsdUpperBound: roundMoney(windowUncachedUsd * monthFactor),
+        deadItems: dead,
+        sessions,
+        totalTurns,
+        pricingModel: config.pricingModel,
+        windowDays
+    };
+}
+/**
+ * Adapt a dead-context result to a {@link CutAction} so it can flow into the
+ * ranked cut list / AI Receipt. Returns null unless there is MEASURED waste
+ * worth a dollar figure (MCP-only waste is shown as a count, not a cut $).
+ */
+export function deadContextCutAction(result) {
+    if (!result.hasData || result.measuredDeadCount === 0 || result.monthlyUsd < 0.5) {
+        return null;
+    }
+    const pct = Math.round(result.wastePercent * 100);
+    return {
+        id: "dead-context",
+        title: `Trim ${result.measuredDeadCount} loaded tool${result.measuredDeadCount === 1 ? "" : "s"} your agent never calls`,
+        action: `Remove or lazy-load ${result.deadCount} of ${result.loadedCount} loaded item${result.loadedCount === 1 ? "" : "s"} ` +
+            `(${pct}% never invoked) to reclaim ~${result.deadTokens.toLocaleString("en-US")} tokens of dead context per turn.`,
+        estimatedMonthlySavingsUsd: result.monthlyUsd,
+        affectedSpendUsd: result.monthlyUsd,
+        recordCount: result.deadCount,
+        // Dead-context savings come from inventory, not priced usage records, so
+        // there are no record IDs to dedupe against the spend-based cut actions.
+        recordIds: [],
+        confidence: "estimated",
+        kind: "context_trim"
+    };
+}
+function isDead(item, used) {
+    switch (item.kind) {
+        case "skill":
+            return !used.usedSkills.has(item.name);
+        case "subagent":
+            return !used.usedSubagents.has(item.name);
+        case "command":
+            return !used.usedCommands.has(item.name);
+        case "mcp_tool":
+            return !used.usedMcpTools.has(item.name);
+        case "mcp_server":
+            return !used.usedMcpServers.has(item.name);
+        default:
+            return false;
+    }
+}
+function pricingRates(model) {
+    const rule = findPricingRule(model) ?? findPricingRule(DEFAULT_PRICING_MODEL);
+    // Fallback to Sonnet-class numbers if even the default is somehow unmatched.
+    const inputPerM = rule?.inputPerM ?? 3;
+    return {
+        inputPerM,
+        cacheReadPerM: rule?.cacheReadPerM ?? inputPerM * 0.1,
+        write5mPerM: rule?.cacheWrite5mPerM ?? inputPerM * 1.25
+    };
+}
+function roundMoney(value) {
+    return Math.round(value * 100) / 100;
+}
+//# sourceMappingURL=deadContext.js.map

package/dist/discovery.d.ts

@@ -10,6 +10,8 @@ export type LocalDiscoveryResult = {
     rootPath: string;
     scannedFiles: number;
     skippedDirectories: string[];
+    /** Paths that could not be read (permissions, dangling symlinks, non-UTF8) — skipped, never fatal. */
+    unreadablePaths: string[];
     signals: UsageSignal[];
     secretsDetected: string[];
     redactedEvidence: string[];

package/dist/discovery.js

@@ -22,30 +22,66 @@ const providerRules = [
     { 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;
+// Name-based redaction: any UPPER_SNAKE env-style assignment whose name ends
+// in a secret-ish suffix. `KEY` deliberately subsumes API_KEY/ADMIN_KEY/etc —
+// over-redacting a public key is harmless; leaking a private one is not.
+const secretAssignmentPattern = /\b([A-Z][A-Z0-9_]*(?:KEY|TOKEN|SECRET|PASSWORD|PASSWD|CREDENTIALS?|AUTH))\s*=\s*([^\s#"']+)/g;
+// Value-based redaction: known secret shapes regardless of how they're named.
 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
+    /helicone_[A-Za-z0-9_-]{16,}/gi,
+    // GitHub tokens: classic PATs, OAuth, server/user/refresh, fine-grained.
+    /\bgh[pousr]_[A-Za-z0-9]{20,}\b/g,
+    /\bgithub_pat_[A-Za-z0-9_]{20,}\b/g,
+    // Google API keys.
+    /\bAIza[0-9A-Za-z_-]{30,}\b/g,
+    // JWTs (three base64url segments).
+    /\beyJ[A-Za-z0-9_-]{8,}\.[A-Za-z0-9_-]{8,}\.[A-Za-z0-9_-]{8,}\b/g,
+    // Slack tokens.
+    /\bxox[baprs]-[A-Za-z0-9-]{10,}\b/g,
+    // AWS access key IDs.
+    /\bAKIA[0-9A-Z]{16}\b/g,
+    // GitLab PATs and npm tokens.
+    /\bglpat-[A-Za-z0-9_-]{16,}\b/g,
+    /\bnpm_[A-Za-z0-9]{30,}\b/g
 ];
 export async function scanLocalUsageSignals(rootPath) {
     const result = {
         rootPath,
         scannedFiles: 0,
         skippedDirectories: [],
+        unreadablePaths: [],
         signals: [],
         secretsDetected: [],
         redactedEvidence: []
     };
     const secrets = new Set();
     const skipped = new Set();
+    const unreadable = new Set();
     await walk(rootPath, async (path) => {
-        const fileInfo = await stat(path);
+        // A dangling symlink, permission-denied entry, or unreadable file must
+        // never reject the whole scan — real machines are messy. Skip and report.
+        let fileInfo;
+        try {
+            fileInfo = await stat(path);
+        }
+        catch {
+            unreadable.add(path);
+            return;
+        }
         if (fileInfo.size > maxFileBytes || !isInterestingFile(path)) {
             return;
         }
-        const raw = await readFile(path, "utf8");
+        let raw;
+        try {
+            raw = await readFile(path, "utf8");
+        }
+        catch {
+            unreadable.add(path);
+            return;
+        }
         const redacted = redactSecrets(raw);
         const relativePath = relative(rootPath, path) || basename(path);
         result.scannedFiles += 1;
@@ -70,8 +106,11 @@ export async function scanLocalUsageSignals(rootPath) {
                 confidence: rule.confidence
             });
         }
-    }, skipped);
+    }, skipped, unreadable);
     result.skippedDirectories = Array.from(skipped).sort();
+    result.unreadablePaths = Array.from(unreadable)
+        .map((path) => relative(rootPath, path) || basename(path))
+        .sort();
     result.secretsDetected = Array.from(secrets).sort();
     result.signals = dedupeSignals(result.signals).sort((left, right) => {
         const provider = left.provider.localeCompare(right.provider);
@@ -96,8 +135,16 @@ function detectSecretNames(text) {
     }
     return Array.from(names);
 }
-async function walk(rootPath, visit, skipped) {
-    const entries = await readdir(rootPath, { withFileTypes: true });
+async function walk(rootPath, visit, skipped, unreadable) {
+    let entries;
+    try {
+        entries = await readdir(rootPath, { withFileTypes: true });
+    }
+    catch {
+        // Permission-denied or vanished directory: skip it, keep scanning.
+        unreadable.add(rootPath);
+        return;
+    }
     for (const entry of entries) {
         const path = join(rootPath, entry.name);
         if (entry.isDirectory()) {
@@ -105,10 +152,10 @@ async function walk(rootPath, visit, skipped) {
                 skipped.add(entry.name);
                 continue;
             }
-            await walk(path, visit, skipped);
+            await walk(path, visit, skipped, unreadable);
             continue;
         }
-        if (entry.isFile()) {
+        if (entry.isFile() || entry.isSymbolicLink()) {
             await visit(path);
         }
     }

package/dist/index.d.ts

@@ -1,13 +1,17 @@
 export * from "./analyze.js";
+export * from "./agentInventory.js";
 export * from "./attribution.js";
 export * from "./credentialDetection.js";
 export * from "./cutList.js";
+export * from "./deadContext.js";
 export * from "./discovery.js";
+export * from "./toolInvocations.js";
 export * from "./insights.js";
 export * from "./localAgentLogs.js";
 export * from "./modelPricing.js";
 export * from "./planMath.js";
 export * from "./sampleData.js";
+export * from "./scanGuard.js";
 export * from "./schema.js";
 export * from "./sourceRegistry.js";
 export * from "./providerConnectors.js";

package/dist/index.js

@@ -1,13 +1,17 @@
 export * from "./analyze.js";
+export * from "./agentInventory.js";
 export * from "./attribution.js";
 export * from "./credentialDetection.js";
 export * from "./cutList.js";
+export * from "./deadContext.js";
 export * from "./discovery.js";
+export * from "./toolInvocations.js";
 export * from "./insights.js";
 export * from "./localAgentLogs.js";
 export * from "./modelPricing.js";
 export * from "./planMath.js";
 export * from "./sampleData.js";
+export * from "./scanGuard.js";
 export * from "./schema.js";
 export * from "./sourceRegistry.js";
 export * from "./providerConnectors.js";

package/dist/providerConnectors.d.ts

@@ -12,9 +12,11 @@ type ProviderResponse = {
 export type ProviderQaPagination = {
     label: string;
     pagesFetched: number;
-    stoppedBecause: "complete" | "missing_cursor" | "max_pages";
+    stoppedBecause: "complete" | "missing_cursor" | "max_pages" | "fetch_error";
     maxPages: number;
     limitPerPage?: number;
+    /** Present when stoppedBecause is "fetch_error": the sanitized reason the fetch stopped early. */
+    note?: string;
 };
 export type ProviderQaRateLimit = {
     label: string;
@@ -62,6 +64,8 @@ export type CreateProviderConnectionInput = {
     verifiedRecordCount: number;
     totalUsd: number;
     fetchedAt?: Date;
+    /** Record-derived completeness; the source's verification label mirrors it. */
+    completeness?: ProviderConnectorResult["completeness"];
 };
 export type TokenResolver = (reference: string) => string;
 export type Fetcher = (url: string, init?: {