@agent-finops/core 0.1.0 → 0.1.3

package/dist/providerConnectors.js

@@ -1,4 +1,5 @@
 import { createProviderConnectorStub, slugifySourceId } from "./sourceRegistry.js";
+import { redactSecrets } from "./discovery.js";
 export function normalizeOpenAiCostResponse(response, options) {
     const data = isObject(response) && Array.isArray(response.data) ? response.data : [];
     const records = [];
@@ -257,12 +258,15 @@ export function normalizeCursorSpendResponse(response, options) {
         return [{
                 id: slugifySourceId(["cursor-spend", options.accountId, userId].filter(Boolean).join("-")),
                 timestamp,
-                source: { id: options.sourceId, name: "Cursor Admin API", provider: "cursor", confidence: "verified", observedFrom: options.observedFrom },
+                // The Cursor connector is spec-built and not yet live-verified (beta),
+                // so its dollars are labeled estimated until reconciled against a real
+                // team's invoice. Never stamp "verified" on data we haven't verified.
+                source: { id: options.sourceId, name: "Cursor Admin API", provider: "cursor", confidence: "estimated", observedFrom: options.observedFrom },
                 model: "cursor-team-usage",
                 inputTokens: 0,
                 outputTokens: 0,
                 amountUsd: cents / 100,
-                costConfidence: "verified",
+                costConfidence: "estimated",
                 userId,
                 projectId: options.accountId,
                 providerCostType: "cursor_spend",
@@ -299,7 +303,7 @@ async function fetchOpenAi(input, token, fetcher, sourceId) {
         ...costFetch.pages.flatMap((page) => normalizeOpenAiCostResponse(page, { sourceId, observedFrom: "OpenAI organization costs API" })),
         ...usageFetch.pages.flatMap((page) => normalizeOpenAiUsageResponse(page, { sourceId, observedFrom: "OpenAI organization usage API" }))
     ];
-    return providerResult("openai", sourceId, input.authReference, records, "verified", qaSummary("openai", [costFetch, usageFetch]));
+    return providerResult("openai", sourceId, input.authReference, records, qaSummary("openai", [costFetch, usageFetch]));
 }
 async function fetchAnthropic(input, token, fetcher, sourceId) {
     const costRequest = {
@@ -312,7 +316,7 @@ async function fetchAnthropic(input, token, fetcher, sourceId) {
         ...costFetch.pages.flatMap((page) => normalizeAnthropicCostResponse(page, { sourceId, observedFrom: "Anthropic Admin Cost Report" })),
         ...claudeCodeFetches.flatMap((fetchResult) => fetchResult.pages.flatMap((page) => normalizeAnthropicClaudeCodeUsageResponse(page, { sourceId, observedFrom: "Anthropic Claude Code Usage Report", accountId: input.accountId })))
     ];
-    return providerResult("anthropic", sourceId, input.authReference, records, "verified", qaSummary("anthropic", [costFetch, ...claudeCodeFetches]));
+    return providerResult("anthropic", sourceId, input.authReference, records, qaSummary("anthropic", [costFetch, ...claudeCodeFetches]));
 }
 async function fetchGitHubCopilot(input, token, fetcher, sourceId) {
     const accountId = input.org ?? input.enterprise;
@@ -326,7 +330,7 @@ async function fetchGitHubCopilot(input, token, fetcher, sourceId) {
     const seatFetch = input.org ? await fetchPaginatedJson(fetcher, buildGitHubCopilotSeatsUrl(input.org), request, "github-copilot", "GitHub Copilot seats") : undefined;
     const metricsRecords = metricsFetch.pages.flatMap((page) => normalizeGitHubCopilotMetricsResponse(page, { sourceId, observedFrom: "GitHub Copilot metrics API", accountId }));
     const seatRecords = seatFetch ? seatFetch.pages.flatMap((page) => normalizeGitHubCopilotSeatResponse(page, { sourceId, observedFrom: "GitHub Copilot billing seats API", accountId })) : [];
-    return providerResult("github-copilot", sourceId, input.authReference, [...metricsRecords, ...seatRecords], "verified", qaSummary("github-copilot", [metricsFetch, ...(seatFetch ? [seatFetch] : [])]));
+    return providerResult("github-copilot", sourceId, input.authReference, [...metricsRecords, ...seatRecords], qaSummary("github-copilot", [metricsFetch, ...(seatFetch ? [seatFetch] : [])]));
 }
 async function fetchCursor(input, token, fetcher, sourceId) {
     const accountId = input.accountId ?? input.org ?? "cursor-team";
@@ -337,13 +341,21 @@ async function fetchCursor(input, token, fetcher, sourceId) {
     }, "cursor", "Cursor Admin API spend");
     const page = response.payload;
     const records = normalizeCursorSpendResponse(page, { sourceId, observedFrom: "Cursor Admin API", accountId });
+    // The Cursor connector is matched to the published spec but not live-verified.
+    // If the API answered with content but no spend fields we recognize, say so
+    // loudly rather than silently report $0 (which reads as "you spent nothing").
+    if (records.length === 0 && isRecord(page) && Object.keys(page).length > 0) {
+        throw new Error("Cursor returned data but no spend fields this connector recognizes " +
+            `(saw: ${Object.keys(page).slice(0, 8).join(", ")}). The Cursor connector is beta — ` +
+            "please open an issue with this field list so we can map it: https://github.com/futurastudio/ai-spend-agent/issues");
+    }
     const singleFetch = {
         pages: [page],
         pagination: { label: "Cursor Admin API spend", pagesFetched: 1, stoppedBecause: "complete", maxPages: 1 },
         rateLimits: response.rateLimit ? [response.rateLimit] : [],
         responseDrift: detectResponseDrift(page, "cursor", "Cursor Admin API spend")
     };
-    return providerResult("cursor", sourceId, input.authReference, records, "verified", qaSummary("cursor", [singleFetch]));
+    return providerResult("cursor", sourceId, input.authReference, records, qaSummary("cursor", [singleFetch]));
 }
 async function fetchPaginatedJson(fetcher, initialUrl, request, provider, label) {
     const pages = [];
@@ -351,9 +363,24 @@ async function fetchPaginatedJson(fetcher, initialUrl, request, provider, label)
     const responseDrift = [];
     let nextUrl = initialUrl;
     let stoppedBecause = "complete";
+    let note;
     const maxPages = 50;
     for (let pageCount = 0; nextUrl && pageCount < maxPages; pageCount += 1) {
-        const response = await fetchJsonOrThrow(fetcher, nextUrl, request, provider, label);
+        let response;
+        try {
+            response = await fetchJsonOrThrow(fetcher, nextUrl, request, provider, label);
+        }
+        catch (error) {
+            // A mid-pagination failure (after retries) must not discard the pages
+            // already fetched — return partial results with an explicit QA note.
+            // A failure on the FIRST page (auth, bad scope) still throws.
+            if (pages.length === 0)
+                throw error;
+            stoppedBecause = "fetch_error";
+            note = `Stopped after ${pages.length} page(s): ${error instanceof Error ? error.message : String(error)}`;
+            nextUrl = undefined;
+            break;
+        }
         const page = response.payload;
         pages.push(page);
         if (response.rateLimit)
@@ -380,7 +407,7 @@ async function fetchPaginatedJson(fetcher, initialUrl, request, provider, label)
     }
     return {
         pages,
-        pagination: { label, pagesFetched: pages.length, stoppedBecause, maxPages, limitPerPage: limitPerPageFromUrl(initialUrl) },
+        pagination: { label, pagesFetched: pages.length, stoppedBecause, maxPages, limitPerPage: limitPerPageFromUrl(initialUrl), ...(note ? { note } : {}) },
         rateLimits,
         responseDrift
     };
@@ -390,17 +417,60 @@ async function fetchDateRangeJson(fetcher, buildUrl, startTime, endTime, request
     const daySeconds = 24 * 60 * 60;
     const finalTime = endTime ?? startTime;
     for (let cursor = startTime, count = 0; cursor <= finalTime && count < 370; cursor += daySeconds, count += 1) {
-        results.push(await fetchPaginatedJson(fetcher, buildUrl(cursor), request, provider, label));
+        try {
+            results.push(await fetchPaginatedJson(fetcher, buildUrl(cursor), request, provider, label));
+        }
+        catch (error) {
+            // Persistent failure mid-range: keep the days already fetched and note
+            // where the sync stopped instead of discarding everything. First-day
+            // failures (bad auth/scope) still throw so the user sees the real error.
+            if (results.length === 0)
+                throw error;
+            results.push({
+                pages: [],
+                pagination: {
+                    label,
+                    pagesFetched: 0,
+                    stoppedBecause: "fetch_error",
+                    maxPages: 50,
+                    note: `Day range stopped early after ${results.length} day(s): ${error instanceof Error ? error.message : String(error)}`
+                },
+                rateLimits: [],
+                responseDrift: []
+            });
+            break;
+        }
     }
     return results;
 }
+/** Retries per request on 429/5xx before giving up (initial try + retries). */
+const maxFetchRetries = 2;
+/** Cap on how long a retry-after header can make us wait, per attempt. */
+const maxRetryDelayMs = 30_000;
 async function fetchJsonOrThrow(fetcher, url, request, provider, label) {
-    const response = await fetcher(url, request);
-    const payload = await response.json().catch(() => undefined);
-    if (!response.ok) {
-        throw new Error(providerPermissionPrompt(provider, label, response, payload));
+    let lastError;
+    for (let attempt = 0; attempt <= maxFetchRetries; attempt += 1) {
+        const response = await fetcher(url, request);
+        const payload = await response.json().catch(() => undefined);
+        if (response.ok) {
+            return { payload, rateLimit: rateLimitFromHeaders(label, response.headers), headers: response.headers };
+        }
+        lastError = new Error(providerPermissionPrompt(provider, label, response, payload));
+        // 429 and 5xx are transient: honor retry-after when present, otherwise
+        // back off briefly and try again. 4xx auth/scope errors fail immediately.
+        const retryable = response.status === 429 || response.status >= 500;
+        if (!retryable || attempt === maxFetchRetries) {
+            break;
+        }
+        const retryAfterSeconds = headerNumber(response.headers, "retry-after");
+        const delayMs = typeof retryAfterSeconds === "number"
+            ? Math.min(Math.max(retryAfterSeconds, 0) * 1000, maxRetryDelayMs)
+            : 500 * 2 ** attempt;
+        if (delayMs > 0) {
+            await new Promise((resolveDelay) => setTimeout(resolveDelay, delayMs));
+        }
     }
-    return { payload, rateLimit: rateLimitFromHeaders(label, response.headers), headers: response.headers };
+    throw lastError ?? new Error(`${label} request failed.`);
 }
 function nextPageFromPayload(payload) {
     if (!isRecord(payload))
@@ -479,13 +549,31 @@ function walkProviderFields(value, path, visit) {
     }
 }
 function knownProviderFields(provider, label) {
-    const common = ["data", "data[]", "has_more", "hasMore", "next_page", "nextPage"];
+    // Every provider MUST enumerate the fields its normalizer consumes; a
+    // fall-through to `common` alone flags every legitimate field of every page
+    // as drift, burying real drift signals in thousands of false positives.
+    const common = ["data", "data[]", "has_more", "hasMore", "next_page", "nextPage", "object", "links", "links.next"];
     if (provider === "openai" && label.includes("costs")) {
         return new Set([...common, "data[].object", "data[].start_time", "data[].end_time", "data[].results", "data[].results[]", "data[].results[].object", "data[].results[].amount", "data[].results[].amount.value", "data[].results[].amount.currency", "data[].results[].line_item", "data[].results[].project_id", "data[].results[].api_key_id", "data[].results[].quantity"]);
     }
     if (provider === "openai" && label.includes("usage")) {
         return new Set([...common, "data[].object", "data[].start_time", "data[].end_time", "data[].results", "data[].results[]", "data[].results[].object", "data[].results[].input_tokens", "data[].results[].output_tokens", "data[].results[].input_cached_tokens", "data[].results[].input_audio_tokens", "data[].results[].output_audio_tokens", "data[].results[].num_model_requests", "data[].results[].project_id", "data[].results[].user_id", "data[].results[].api_key_id", "data[].results[].model"]);
     }
+    if (provider === "anthropic" && label.toLowerCase().includes("cost")) {
+        return new Set([...common, "data[].starting_at", "data[].ending_at", "data[].results", "data[].results[]", "data[].results[].amount", "data[].results[].currency", "data[].results[].cost_type", "data[].results[].description", "data[].results[].model", "data[].results[].workspace_id", "data[].results[].token_type", "data[].results[].service_tier", "data[].results[].context_window"]);
+    }
+    if (provider === "anthropic" && label.toLowerCase().includes("claude code")) {
+        return new Set([...common, "data[].date", "data[].actor", "data[].actor.email_address", "data[].actor.api_key_name", "data[].actor.id", "data[].actor.type", "data[].organization_id", "data[].customer_type", "data[].terminal_type", "data[].subscription_type", "data[].core_metrics", "data[].core_metrics.num_sessions", "data[].core_metrics.lines_of_code", "data[].core_metrics.lines_of_code.added", "data[].core_metrics.lines_of_code.removed", "data[].core_metrics.commits_by_claude_code", "data[].core_metrics.pull_requests_by_claude_code", "data[].model_breakdown", "data[].model_breakdown[]", "data[].model_breakdown[].model", "data[].model_breakdown[].tokens", "data[].model_breakdown[].tokens.input", "data[].model_breakdown[].tokens.output", "data[].model_breakdown[].tokens.cache_read", "data[].model_breakdown[].tokens.cache_creation", "data[].model_breakdown[].estimated_cost", "data[].model_breakdown[].estimated_cost.currency", "data[].model_breakdown[].estimated_cost.amount", "data[].tool_actions", "data[].tool_actions[]"]);
+    }
+    if (provider === "github-copilot" && label.toLowerCase().includes("metrics")) {
+        return new Set([...common, "day_totals", "day_totals[]", "day_totals[].day", "day_totals[].daily_active_users", "day_totals[].totals_by_model_feature", "day_totals[].totals_by_model_feature[]", "day_totals[].totals_by_model_feature[].model", "day_totals[].totals_by_model_feature[].feature", "day_totals[].totals_by_model_feature[].engaged_users", "day_totals[].totals_by_model_feature[].total_requests", "day_totals[].totals_by_model_feature[].user_initiated_interaction_count", "day_totals[].totals_by_cli", "day_totals[].totals_by_cli.request_count", "day_totals[].totals_by_cli.token_usage", "day_totals[].totals_by_cli.token_usage.prompt_tokens_sum", "day_totals[].totals_by_cli.token_usage.output_tokens_sum", "day_totals[].totals_by_cli.engaged_users", "day_totals[].totals_by_cli.total_requests", "report_start_day", "report_end_day", "generated_at"]);
+    }
+    if (provider === "github-copilot" && label.toLowerCase().includes("seats")) {
+        return new Set([...common, "total_seats", "plan_type", "seats", "seats[]", "seats[].created_at", "seats[].updated_at", "seats[].pending_cancellation_date", "seats[].last_activity_at", "seats[].last_activity_editor", "seats[].plan_type", "seats[].login", "seats[].id", "seats[].assignee", "seats[].assignee.login", "seats[].assignee.email", "seats[].assignee.id", "seats[].assignee.node_id", "seats[].assignee.avatar_url", "seats[].assignee.html_url", "seats[].assignee.type", "seats[].assignee.site_admin", "seats[].assigning_team", "seats[].organization"]);
+    }
+    if (provider === "cursor") {
+        return new Set([...common, "users", "users[]", "users[].email", "users[].emailAddress", "users[].userId", "users[].id", "users[].name", "users[].role", "users[].spendCents", "users[].usageBasedCents", "users[].chargedCents", "users[].fastPremiumRequests", "users[].hardLimitOverrideDollars", "data[].email", "data[].emailAddress", "data[].userId", "data[].id", "data[].name", "data[].role", "data[].spendCents", "data[].usageBasedCents", "data[].chargedCents", "subscriptionCycleStart", "totalMembers", "totalPages"]);
+    }
     return new Set([...common]);
 }
 function qaSummary(provider, fetches) {
@@ -551,29 +639,48 @@ function extractProviderMessage(payload) {
     return stringValue(error?.message) ?? stringValue(payload.message) ?? "";
 }
 function sanitizeProviderMessage(message) {
-    return message.replace(/sk-[A-Za-z0-9_-]+/g, "[REDACTED]").replace(/gh[pousr]_[A-Za-z0-9_]+/g, "[REDACTED]");
+    // One redaction implementation for the whole product (discovery.ts owns it).
+    return redactSecrets(message).replace(/sk-[A-Za-z0-9_-]+/g, "[REDACTED]").replace(/gh[pousr]_[A-Za-z0-9_]+/g, "[REDACTED]");
+}
+/**
+ * Result-level completeness is DERIVED from record-level confidence, never
+ * hardcoded: the label on the whole pull is the weakest confidence among the
+ * records that actually carry dollars (worst-wins, matching analyze.ts).
+ * Copilot seats and Cursor spend are estimated, so their results say so.
+ */
+function completenessFromRecords(records) {
+    const rank = { verified: 0, estimated: 1, detected_unverified: 2, missing: 3 };
+    const costBearing = records.filter((record) => typeof record.amountUsd === "number");
+    if (costBearing.length === 0) {
+        return "missing";
+    }
+    return costBearing
+        .map((record) => record.costConfidence)
+        .reduce((worst, current) => (rank[current] > rank[worst] ? current : worst));
 }
-function providerResult(provider, sourceId, authReference, records, fallbackCompleteness, qa) {
+function providerResult(provider, sourceId, authReference, records, qa) {
     const totalUsd = records.reduce((sum, record) => sum + (record.amountUsd ?? 0), 0);
+    const completeness = completenessFromRecords(records);
     return {
         provider,
-        source: createProviderConnection({ provider, sourceId, authReference, verifiedRecordCount: records.length, totalUsd }),
+        source: createProviderConnection({ provider, sourceId, authReference, verifiedRecordCount: records.length, totalUsd, completeness }),
         records,
         fetchedAt: new Date().toISOString(),
-        completeness: records.length > 0 ? fallbackCompleteness : "missing",
+        completeness,
         qa: qa ?? qaSummary(provider, [])
     };
 }
 export function createProviderConnection(input) {
     const source = createProviderConnectorStub(input.provider, "provider_api", input.fetchedAt);
     const total = `$${input.totalUsd.toFixed(2)}`;
+    const verification = input.completeness ?? "verified";
     return {
         ...source,
         id: input.sourceId ?? source.id,
-        verification: "verified",
+        verification,
         authReference: input.authReference,
         fieldsMissing: [],
-        scope: `${source.scope} Last successful pull produced ${input.verifiedRecordCount} verified records totaling ${total}.`
+        scope: `${source.scope} Last successful pull produced ${input.verifiedRecordCount} ${verification} records totaling ${total}.`
     };
 }
 export function resolveTokenReference(reference, env = process.env) {

package/dist/scanGuard.d.ts

@@ -0,0 +1,8 @@
+export declare class UnsafeScanRootError extends Error {
+    readonly rootPath: string;
+    constructor(rootPath: string, reason: string);
+}
+export declare function unsafeScanRootReason(rootPath: string, home?: string): string | undefined;
+/** Throws a typed error when the root is unsafe; callers map it to their UX. */
+export declare function assertSafeScanRoot(rootPath: string, home?: string): void;
+//# sourceMappingURL=scanGuard.d.ts.map

package/dist/scanGuard.js

@@ -0,0 +1,65 @@
+import { homedir } from "node:os";
+import { resolve, sep } from "node:path";
+/**
+ * Shared unsafe-scan-root policy for EVERY scan entrypoint (CLI `scan`, MCP
+ * `scan_ai_spend`, and any future surface). Scanning the home directory, the
+ * filesystem root, or a system directory is refused: the product's consent
+ * model is "one explicitly approved project folder", and anything broader can
+ * pull unrelated personal files into evidence output.
+ *
+ * Keep this the ONLY implementation — a CLI/MCP divergence here is exactly the
+ * class of bug that let MCP scan `~` while the CLI refused.
+ */
+const systemRootDirectories = new Set([
+    "/etc",
+    "/usr",
+    "/bin",
+    "/sbin",
+    "/var",
+    "/opt",
+    "/private",
+    "/Library",
+    "/System",
+    "/Applications",
+    "/Volumes",
+    "/proc",
+    "/sys",
+    "/dev"
+]);
+export class UnsafeScanRootError extends Error {
+    rootPath;
+    constructor(rootPath, reason) {
+        super(`Refusing to scan ${rootPath}: ${reason}. Choose a narrower approved folder.`);
+        this.name = "UnsafeScanRootError";
+        this.rootPath = rootPath;
+    }
+}
+export function unsafeScanRootReason(rootPath, home = homedir()) {
+    const resolved = resolve(rootPath);
+    const resolvedHome = resolve(home);
+    if (resolved === "/" || /^[A-Za-z]:[\\/]?$/.test(resolved)) {
+        return "the filesystem root is too broad for approved-source scanning";
+    }
+    if (resolved === resolvedHome) {
+        return "the home directory is too broad for approved-source scanning";
+    }
+    if (isAncestorPath(resolved, resolvedHome)) {
+        return "this directory contains your home directory and is too broad for approved-source scanning";
+    }
+    if (systemRootDirectories.has(resolved)) {
+        return "system directories are not valid approved-source scan targets";
+    }
+    return undefined;
+}
+/** Throws a typed error when the root is unsafe; callers map it to their UX. */
+export function assertSafeScanRoot(rootPath, home = homedir()) {
+    const reason = unsafeScanRootReason(rootPath, home);
+    if (reason) {
+        throw new UnsafeScanRootError(resolve(rootPath), reason);
+    }
+}
+function isAncestorPath(candidateAncestor, path) {
+    const normalizedAncestor = candidateAncestor.endsWith(sep) ? candidateAncestor : candidateAncestor + sep;
+    return path.startsWith(normalizedAncestor);
+}
+//# sourceMappingURL=scanGuard.js.map

package/dist/schema.d.ts

@@ -1,8 +1,8 @@
 import { z } from "zod";
 export declare const costConfidenceValues: readonly ["verified", "estimated", "detected_unverified", "missing"];
 export declare const costConfidenceSchema: z.ZodEnum<{
-    verified: "verified";
     estimated: "estimated";
+    verified: "verified";
     detected_unverified: "detected_unverified";
     missing: "missing";
 }>;
@@ -12,8 +12,8 @@ export declare const spendSourceSchema: z.ZodObject<{
     name: z.ZodString;
     provider: z.ZodString;
     confidence: z.ZodEnum<{
-        verified: "verified";
         estimated: "estimated";
+        verified: "verified";
         detected_unverified: "detected_unverified";
         missing: "missing";
     }>;
@@ -28,8 +28,8 @@ export declare const usageRecordSchema: z.ZodObject<{
         name: z.ZodString;
         provider: z.ZodString;
         confidence: z.ZodEnum<{
-            verified: "verified";
             estimated: "estimated";
+            verified: "verified";
             detected_unverified: "detected_unverified";
             missing: "missing";
         }>;
@@ -40,8 +40,8 @@ export declare const usageRecordSchema: z.ZodObject<{
     outputTokens: z.ZodNumber;
     amountUsd: z.ZodNullable<z.ZodNumber>;
     costConfidence: z.ZodEnum<{
-        verified: "verified";
         estimated: "estimated";
+        verified: "verified";
         detected_unverified: "detected_unverified";
         missing: "missing";
     }>;
@@ -58,10 +58,10 @@ export declare const usageRecordSchema: z.ZodObject<{
 export type UsageRecord = z.infer<typeof usageRecordSchema>;
 export declare const attributionCandidateSchema: z.ZodObject<{
     entityType: z.ZodEnum<{
-        client: "client";
+        user: "user";
         project: "project";
+        client: "client";
         agent: "agent";
-        user: "user";
         workspace: "workspace";
         api_key: "api_key";
     }>;
@@ -74,10 +74,10 @@ export declare const attributionMappingSchema: z.ZodObject<{
     usageRecordId: z.ZodString;
     candidates: z.ZodArray<z.ZodObject<{
         entityType: z.ZodEnum<{
-            client: "client";
+            user: "user";
             project: "project";
+            client: "client";
             agent: "agent";
-            user: "user";
             workspace: "workspace";
             api_key: "api_key";
         }>;
@@ -87,10 +87,10 @@ export declare const attributionMappingSchema: z.ZodObject<{
     }, z.core.$strip>>;
     selected: z.ZodOptional<z.ZodObject<{
         entityType: z.ZodEnum<{
-            client: "client";
+            user: "user";
             project: "project";
+            client: "client";
             agent: "agent";
-            user: "user";
             workspace: "workspace";
             api_key: "api_key";
         }>;
@@ -112,8 +112,8 @@ export declare const spendBreakdownEntrySchema: z.ZodObject<{
     amountUsd: z.ZodNumber;
     recordCount: z.ZodNumber;
     confidence: z.ZodEnum<{
-        verified: "verified";
         estimated: "estimated";
+        verified: "verified";
         detected_unverified: "detected_unverified";
         missing: "missing";
     }>;
@@ -129,8 +129,8 @@ export declare const spendAnomalySchema: z.ZodObject<{
     currentAmountUsd: z.ZodNumber;
     multiplier: z.ZodNumber;
     confidence: z.ZodEnum<{
-        verified: "verified";
         estimated: "estimated";
+        verified: "verified";
         detected_unverified: "detected_unverified";
         missing: "missing";
     }>;
@@ -146,8 +146,8 @@ export declare const workflowWatchEntrySchema: z.ZodObject<{
     shareOfSpend: z.ZodNumber;
     recordCount: z.ZodNumber;
     confidence: z.ZodEnum<{
-        verified: "verified";
         estimated: "estimated";
+        verified: "verified";
         detected_unverified: "detected_unverified";
         missing: "missing";
     }>;
@@ -171,8 +171,8 @@ export declare const recommendationSchema: z.ZodObject<{
     }>;
     estimatedImpactUsd: z.ZodNumber;
     confidence: z.ZodEnum<{
-        verified: "verified";
         estimated: "estimated";
+        verified: "verified";
         detected_unverified: "detected_unverified";
         missing: "missing";
     }>;
@@ -216,8 +216,8 @@ export declare const spendInsightSchema: z.ZodObject<{
     affectedModels: z.ZodArray<z.ZodString>;
     estimatedImpactUsd: z.ZodNumber;
     confidence: z.ZodEnum<{
-        verified: "verified";
         estimated: "estimated";
+        verified: "verified";
         detected_unverified: "detected_unverified";
         missing: "missing";
     }>;
@@ -229,14 +229,14 @@ export declare const spendSummarySchema: z.ZodObject<{
     totalUsd: z.ZodNumber;
     recordCount: z.ZodNumber;
     confidence: z.ZodEnum<{
-        verified: "verified";
         estimated: "estimated";
+        verified: "verified";
         detected_unverified: "detected_unverified";
         missing: "missing";
     }>;
     confidenceBreakdown: z.ZodRecord<z.ZodEnum<{
-        verified: "verified";
         estimated: "estimated";
+        verified: "verified";
         detected_unverified: "detected_unverified";
         missing: "missing";
     }>, z.ZodNumber>;
@@ -245,8 +245,8 @@ export declare const spendSummarySchema: z.ZodObject<{
         amountUsd: z.ZodNumber;
         recordCount: z.ZodNumber;
         confidence: z.ZodEnum<{
-            verified: "verified";
             estimated: "estimated";
+            verified: "verified";
             detected_unverified: "detected_unverified";
             missing: "missing";
         }>;
@@ -256,8 +256,8 @@ export declare const spendSummarySchema: z.ZodObject<{
         amountUsd: z.ZodNumber;
         recordCount: z.ZodNumber;
         confidence: z.ZodEnum<{
-            verified: "verified";
             estimated: "estimated";
+            verified: "verified";
             detected_unverified: "detected_unverified";
             missing: "missing";
         }>;
@@ -267,8 +267,8 @@ export declare const spendSummarySchema: z.ZodObject<{
         amountUsd: z.ZodNumber;
         recordCount: z.ZodNumber;
         confidence: z.ZodEnum<{
-            verified: "verified";
             estimated: "estimated";
+            verified: "verified";
             detected_unverified: "detected_unverified";
             missing: "missing";
         }>;
@@ -278,8 +278,8 @@ export declare const spendSummarySchema: z.ZodObject<{
         amountUsd: z.ZodNumber;
         recordCount: z.ZodNumber;
         confidence: z.ZodEnum<{
-            verified: "verified";
             estimated: "estimated";
+            verified: "verified";
             detected_unverified: "detected_unverified";
             missing: "missing";
         }>;
@@ -289,8 +289,8 @@ export declare const spendSummarySchema: z.ZodObject<{
         amountUsd: z.ZodNumber;
         recordCount: z.ZodNumber;
         confidence: z.ZodEnum<{
-            verified: "verified";
             estimated: "estimated";
+            verified: "verified";
             detected_unverified: "detected_unverified";
             missing: "missing";
         }>;
@@ -300,8 +300,8 @@ export declare const spendSummarySchema: z.ZodObject<{
         amountUsd: z.ZodNumber;
         recordCount: z.ZodNumber;
         confidence: z.ZodEnum<{
-            verified: "verified";
             estimated: "estimated";
+            verified: "verified";
             detected_unverified: "detected_unverified";
             missing: "missing";
         }>;
@@ -311,8 +311,8 @@ export declare const spendSummarySchema: z.ZodObject<{
         amountUsd: z.ZodNumber;
         recordCount: z.ZodNumber;
         confidence: z.ZodEnum<{
-            verified: "verified";
             estimated: "estimated";
+            verified: "verified";
             detected_unverified: "detected_unverified";
             missing: "missing";
         }>;
@@ -322,8 +322,8 @@ export declare const spendSummarySchema: z.ZodObject<{
         amountUsd: z.ZodNumber;
         recordCount: z.ZodNumber;
         confidence: z.ZodEnum<{
-            verified: "verified";
             estimated: "estimated";
+            verified: "verified";
             detected_unverified: "detected_unverified";
             missing: "missing";
         }>;
@@ -338,8 +338,8 @@ export declare const spendSummarySchema: z.ZodObject<{
         shareOfSpend: z.ZodNumber;
         recordCount: z.ZodNumber;
         confidence: z.ZodEnum<{
-            verified: "verified";
             estimated: "estimated";
+            verified: "verified";
             detected_unverified: "detected_unverified";
             missing: "missing";
         }>;
@@ -359,8 +359,8 @@ export declare const spendSummarySchema: z.ZodObject<{
         currentAmountUsd: z.ZodNumber;
         multiplier: z.ZodNumber;
         confidence: z.ZodEnum<{
-            verified: "verified";
             estimated: "estimated";
+            verified: "verified";
             detected_unverified: "detected_unverified";
             missing: "missing";
         }>;
@@ -378,8 +378,8 @@ export declare const spendSummarySchema: z.ZodObject<{
         }>;
         estimatedImpactUsd: z.ZodNumber;
         confidence: z.ZodEnum<{
-            verified: "verified";
             estimated: "estimated";
+            verified: "verified";
             detected_unverified: "detected_unverified";
             missing: "missing";
         }>;
@@ -416,8 +416,8 @@ export declare const spendSummarySchema: z.ZodObject<{
         affectedModels: z.ZodArray<z.ZodString>;
         estimatedImpactUsd: z.ZodNumber;
         confidence: z.ZodEnum<{
-            verified: "verified";
             estimated: "estimated";
+            verified: "verified";
             detected_unverified: "detected_unverified";
             missing: "missing";
         }>;

package/dist/toolInvocations.d.ts

@@ -0,0 +1,61 @@
+/**
+ * Read-only ingestion of which tools were actually INVOKED in Claude Code
+ * sessions, plus session/turn counts for cache-aware pricing.
+ *
+ * This is the counterpart to agentInventory.ts (what's LOADED into context):
+ * comparing loaded-but-never-invoked tools against this "actually invoked" set
+ * is the "dead-context cost" signal.
+ *
+ * Transcript format (~/.claude/projects/** /*.jsonl, one JSON object per line):
+ *  - type:"assistant" lines carry message.content = array of blocks; blocks
+ *    with type:"tool_use" have `name` (the invoked tool) and `input`.
+ *  - Built-ins: Read/Edit/Bash/Glob/Grep/...; MCP: "mcp__<server>__<tool>".
+ *  - The `Skill` tool's input.skill names the invoked skill.
+ *  - The `Agent` (or `Task`) tool's input.subagent_type names the subagent.
+ *  - Slash commands surface in type:"user" lines as
+ *    "<command-name>/foo</command-name>".
+ *
+ * A "turn" = one assistant message that produced an API call, deduped by
+ * message.id + requestId (streaming/retries write the same response on
+ * multiple lines), matching parseClaudeCodeTranscript in localAgentLogs.ts.
+ */
+export type ToolInvocationCount = {
+    name: string;
+    count: number;
+};
+export type InvocationSummary = {
+    /** aggregated counts by raw tool name across all parsed transcripts */
+    invocations: ToolInvocationCount[];
+    /** distinct mcp tool names invoked, formatted "mcp__<server>__<tool>" */
+    invokedMcpTools: string[];
+    /** distinct skill names invoked (resolved from the Skill tool input) */
+    invokedSkills: string[];
+    /** distinct subagent types invoked (resolved from Task/Agent input) */
+    invokedSubagents: string[];
+    /** distinct slash-command names invoked, if detectable; else [] */
+    invokedCommands: string[];
+    /** number of transcript files parsed (≈ sessions) */
+    sessions: number;
+    /** total assistant turns across all sessions (post-dedupe) */
+    totalAssistantTurns: number;
+    /** assistant-turn count per session, for cache-read pricing */
+    sessionTurnCounts: number[];
+};
+export type ToolInvocationOptions = {
+    /** default: join(homedir(), ".claude", "projects") */
+    claudeProjectsDir?: string;
+    /** optional: only count turns at/after this time */
+    sinceIso?: string;
+};
+/** Parse ONE transcript's content. Exported for tests. Returns the per-file pieces the aggregator needs. */
+export declare function parseClaudeCodeInvocations(content: string, sinceMs?: number): {
+    invocations: ToolInvocationCount[];
+    invokedMcpTools: string[];
+    invokedSkills: string[];
+    invokedSubagents: string[];
+    invokedCommands: string[];
+    assistantTurns: number;
+};
+/** Scan this machine's Claude Code transcripts and aggregate tool invocations. */
+export declare function loadToolInvocations(options?: ToolInvocationOptions): Promise<InvocationSummary>;
+//# sourceMappingURL=toolInvocations.d.ts.map