@agent-finops/core 0.1.0

package/dist/localAgentLogs.js

@@ -0,0 +1,243 @@
+import { readdir, readFile, stat } from "node:fs/promises";
+import { basename, join } from "node:path";
+import { homedir } from "node:os";
+import { estimateTokenCostUsd } from "./modelPricing.js";
+/** Parse one Claude Code transcript (JSONL). Exported for tests. */
+export function parseClaudeCodeTranscript(content, filePath = "") {
+    const calls = [];
+    const seen = new Set();
+    for (const line of content.split("\n")) {
+        if (!line.trim())
+            continue;
+        let entry;
+        try {
+            entry = JSON.parse(line);
+        }
+        catch {
+            continue;
+        }
+        if (!isRecord(entry) || entry.type !== "assistant")
+            continue;
+        const message = isRecord(entry.message) ? entry.message : undefined;
+        const usage = message && isRecord(message.usage) ? message.usage : undefined;
+        if (!message || !usage)
+            continue;
+        // "<synthetic>" marks Claude Code internal placeholder messages, not API calls.
+        if (stringOf(message.model) === "<synthetic>")
+            continue;
+        // Streaming/retries can write the same API response on multiple lines.
+        const dedupeKey = `${stringOf(message.id) ?? ""}:${stringOf(entry.requestId) ?? ""}`;
+        if (dedupeKey !== ":" && seen.has(dedupeKey))
+            continue;
+        seen.add(dedupeKey);
+        const cacheCreation = isRecord(usage.cache_creation) ? usage.cache_creation : undefined;
+        const write5m = numberOf(cacheCreation?.ephemeral_5m_input_tokens);
+        const write1h = numberOf(cacheCreation?.ephemeral_1h_input_tokens);
+        const writeTotal = numberOf(usage.cache_creation_input_tokens) ?? 0;
+        calls.push({
+            agent: "claude-code",
+            model: stringOf(message.model) ?? "claude-code",
+            timestamp: toIso(stringOf(entry.timestamp)) ?? new Date(0).toISOString(),
+            project: projectFromCwd(stringOf(entry.cwd)) ?? projectFromTranscriptPath(filePath),
+            sessionId: stringOf(entry.sessionId),
+            usage: {
+                inputTokens: numberOf(usage.input_tokens) ?? 0,
+                outputTokens: numberOf(usage.output_tokens) ?? 0,
+                cacheReadTokens: numberOf(usage.cache_read_input_tokens) ?? 0,
+                // Prefer the 5m/1h breakdown; fall back to the total as 5m (cheaper bound).
+                cacheWrite5mTokens: write5m ?? writeTotal,
+                cacheWrite1hTokens: write1h ?? 0
+            }
+        });
+    }
+    return calls;
+}
+/** Parse one Codex rollout file (JSONL event stream). Exported for tests. */
+export function parseCodexRollout(content) {
+    let model;
+    let cwd;
+    let sessionId;
+    let timestamp;
+    let lastTotal;
+    for (const line of content.split("\n")) {
+        if (!line.trim())
+            continue;
+        let entry;
+        try {
+            entry = JSON.parse(line);
+        }
+        catch {
+            continue;
+        }
+        if (!isRecord(entry))
+            continue;
+        const payload = isRecord(entry.payload) ? entry.payload : undefined;
+        if (entry.type === "session_meta" && payload) {
+            sessionId = stringOf(payload.id) ?? sessionId;
+            cwd = stringOf(payload.cwd) ?? cwd;
+            timestamp = toIso(stringOf(payload.timestamp) ?? stringOf(entry.timestamp)) ?? timestamp;
+        }
+        if (entry.type === "turn_context" && payload) {
+            model = stringOf(payload.model) ?? model;
+            cwd = stringOf(payload.cwd) ?? cwd;
+        }
+        if (entry.type === "event_msg" && payload?.type === "token_count") {
+            const info = isRecord(payload.info) ? payload.info : undefined;
+            const total = info && isRecord(info.total_token_usage) ? info.total_token_usage : undefined;
+            if (total) {
+                lastTotal = total;
+                timestamp = timestamp ?? toIso(stringOf(entry.timestamp));
+            }
+        }
+    }
+    if (!lastTotal)
+        return [];
+    const input = numberOf(lastTotal.input_tokens) ?? 0;
+    const cached = numberOf(lastTotal.cached_input_tokens) ?? 0;
+    return [{
+            agent: "codex",
+            model: model ?? "codex",
+            timestamp: timestamp ?? new Date(0).toISOString(),
+            project: projectFromCwd(cwd),
+            sessionId,
+            usage: {
+                // Codex input_tokens INCLUDES cached tokens; split them out.
+                inputTokens: Math.max(0, input - cached),
+                outputTokens: numberOf(lastTotal.output_tokens) ?? 0,
+                cacheReadTokens: cached
+            }
+        }];
+}
+/** Scan this machine's agent logs and return aggregated UsageRecords. */
+export async function loadLocalAgentUsage(options = {}) {
+    const home = homedir();
+    const claudeDir = options.claudeProjectsDir ?? join(home, ".claude", "projects");
+    const codexDir = options.codexSessionsDir ?? join(home, ".codex", "sessions");
+    const calls = [];
+    let filesParsed = 0;
+    for (const file of await listJsonlFiles(claudeDir)) {
+        const content = await readFile(file, "utf8").catch(() => "");
+        if (!content)
+            continue;
+        filesParsed += 1;
+        calls.push(...parseClaudeCodeTranscript(content, file));
+    }
+    for (const file of await listJsonlFiles(codexDir)) {
+        if (!basename(file).startsWith("rollout-"))
+            continue;
+        const content = await readFile(file, "utf8").catch(() => "");
+        if (!content)
+            continue;
+        filesParsed += 1;
+        calls.push(...parseCodexRollout(content));
+    }
+    const since = options.sinceIso ? Date.parse(options.sinceIso) : undefined;
+    const filtered = typeof since === "number" && Number.isFinite(since)
+        ? calls.filter((call) => Date.parse(call.timestamp) >= since)
+        : calls;
+    return {
+        records: aggregateCalls(filtered),
+        calls: filtered,
+        filesParsed,
+        agentsDetected: [...new Set(filtered.map((call) => call.agent))]
+    };
+}
+/** Aggregate per-call usage into one UsageRecord per day+agent+model+project. */
+export function aggregateCalls(calls) {
+    const groups = new Map();
+    for (const call of calls) {
+        const day = call.timestamp.slice(0, 10);
+        const key = [day, call.agent, call.model, call.project ?? "unattributed"].join("|");
+        groups.set(key, [...(groups.get(key) ?? []), call]);
+    }
+    const records = [];
+    for (const [key, groupCalls] of groups) {
+        const [day, agent, model, project] = key.split("|");
+        const usage = {
+            inputTokens: sum(groupCalls, (c) => c.usage.inputTokens),
+            outputTokens: sum(groupCalls, (c) => c.usage.outputTokens),
+            cacheReadTokens: sum(groupCalls, (c) => c.usage.cacheReadTokens ?? 0),
+            cacheWrite5mTokens: sum(groupCalls, (c) => c.usage.cacheWrite5mTokens ?? 0),
+            cacheWrite1hTokens: sum(groupCalls, (c) => c.usage.cacheWrite1hTokens ?? 0)
+        };
+        const amountUsd = estimateTokenCostUsd(model, usage);
+        const priced = typeof amountUsd === "number";
+        records.push({
+            id: slug(["local", agent, day, model, project].join("-")),
+            timestamp: new Date(`${day}T00:00:00Z`).toISOString(),
+            source: {
+                id: "local-agent-logs",
+                name: "Local agent session logs",
+                provider: agent === "claude-code" ? "anthropic" : "openai",
+                confidence: "estimated",
+                observedFrom: `${agent} transcript JSONL (this machine)`
+            },
+            model,
+            inputTokens: usage.inputTokens + (usage.cacheReadTokens ?? 0) + (usage.cacheWrite5mTokens ?? 0) + (usage.cacheWrite1hTokens ?? 0),
+            outputTokens: usage.outputTokens,
+            amountUsd: priced ? amountUsd : null,
+            costConfidence: priced ? "estimated" : "missing",
+            projectId: project === "unattributed" ? undefined : project,
+            agentId: agent,
+            providerCostType: "local_agent_logs",
+            quantity: groupCalls.length,
+            operation: `${agent} sessions`
+        });
+    }
+    return records.sort((left, right) => left.id.localeCompare(right.id));
+}
+async function listJsonlFiles(root) {
+    const exists = await stat(root).then((s) => s.isDirectory()).catch(() => false);
+    if (!exists)
+        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() && entry.name.endsWith(".jsonl"))
+                out.push(path);
+        }
+    }
+    return out;
+}
+function projectFromCwd(cwd) {
+    if (!cwd)
+        return undefined;
+    const name = basename(cwd);
+    return name.length > 0 ? name : undefined;
+}
+/** Claude Code encodes the project path into the transcript's parent dir name. */
+function projectFromTranscriptPath(filePath) {
+    if (!filePath)
+        return undefined;
+    const parent = basename(join(filePath, ".."));
+    const tail = parent.split("-").filter(Boolean).pop();
+    return tail && tail.length > 0 ? tail : undefined;
+}
+function toIso(value) {
+    if (!value)
+        return undefined;
+    const parsed = Date.parse(value);
+    return Number.isFinite(parsed) ? new Date(parsed).toISOString() : undefined;
+}
+function sum(calls, pick) {
+    return calls.reduce((total, call) => total + pick(call), 0);
+}
+function numberOf(value) {
+    return typeof value === "number" && Number.isFinite(value) ? value : undefined;
+}
+function stringOf(value) {
+    return typeof value === "string" && value.length > 0 ? value : undefined;
+}
+function isRecord(value) {
+    return typeof value === "object" && value !== null;
+}
+function slug(value) {
+    return value.toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-|-$/g, "") || "x";
+}
+//# sourceMappingURL=localAgentLogs.js.map

package/dist/modelPricing.d.ts

@@ -0,0 +1,35 @@
+/**
+ * Published per-token API prices (mid-2026) used to estimate the
+ * API-equivalent dollar value of locally observed usage (e.g. Claude Code /
+ * Codex session logs, where the provider never reports a price).
+ *
+ * Estimates only — always surfaced with costConfidence "estimated". Rules are
+ * matched top-down; first match wins. Unknown models return undefined so
+ * callers can label the record "missing" instead of inventing a number.
+ */
+export type TokenUsage = {
+    /** Billable, uncached input tokens. */
+    inputTokens: number;
+    outputTokens: number;
+    cacheReadTokens?: number;
+    cacheWrite5mTokens?: number;
+    cacheWrite1hTokens?: number;
+};
+type PricingRule = {
+    match: RegExp;
+    /** USD per million tokens. */
+    inputPerM: number;
+    outputPerM: number;
+    /** Defaults: cache read 0.1x input; 5m cache write 1.25x; 1h write 2x. */
+    cacheReadPerM?: number;
+    cacheWrite5mPerM?: number;
+    cacheWrite1hPerM?: number;
+};
+export declare function findPricingRule(model: string): PricingRule | undefined;
+/**
+ * API-equivalent USD for a usage slice, or undefined when the model has no
+ * published price we recognize.
+ */
+export declare function estimateTokenCostUsd(model: string, usage: TokenUsage): number | undefined;
+export {};
+//# sourceMappingURL=modelPricing.d.ts.map

package/dist/modelPricing.js

@@ -0,0 +1,45 @@
+const pricingRules = [
+    // Anthropic
+    { match: /^claude-fable-5/i, inputPerM: 10, outputPerM: 50 },
+    { match: /^claude-opus-4-[5-9]/i, inputPerM: 5, outputPerM: 25 },
+    { match: /^claude-opus-4(-[01])?$/i, inputPerM: 15, outputPerM: 75 },
+    { match: /^claude-sonnet-4/i, inputPerM: 3, outputPerM: 15 },
+    { match: /^claude-haiku-4/i, inputPerM: 1, outputPerM: 5 },
+    { match: /^claude-3-7-sonnet|^claude-3-5-sonnet/i, inputPerM: 3, outputPerM: 15 },
+    { match: /^claude-3-5-haiku/i, inputPerM: 0.8, outputPerM: 4 },
+    // OpenAI (codex CLI models first — more specific)
+    { match: /^gpt-5(\.\d+)?-codex/i, inputPerM: 1.25, outputPerM: 10, cacheReadPerM: 0.125 },
+    { match: /^gpt-5/i, inputPerM: 1.25, outputPerM: 10, cacheReadPerM: 0.125 },
+    { match: /^gpt-4\.1-nano/i, inputPerM: 0.1, outputPerM: 0.4 },
+    { match: /^gpt-4\.1-mini/i, inputPerM: 0.4, outputPerM: 1.6 },
+    { match: /^gpt-4\.1/i, inputPerM: 2, outputPerM: 8, cacheReadPerM: 0.5 },
+    { match: /^gpt-4o-mini/i, inputPerM: 0.15, outputPerM: 0.6 },
+    { match: /^gpt-4o/i, inputPerM: 2.5, outputPerM: 10 },
+    { match: /^o3$/i, inputPerM: 2, outputPerM: 8 },
+    { match: /^o4-mini/i, inputPerM: 1.1, outputPerM: 4.4 },
+    { match: /codex/i, inputPerM: 1.25, outputPerM: 10, cacheReadPerM: 0.125 }
+];
+export function findPricingRule(model) {
+    return pricingRules.find((rule) => rule.match.test(model));
+}
+/**
+ * API-equivalent USD for a usage slice, or undefined when the model has no
+ * published price we recognize.
+ */
+export function estimateTokenCostUsd(model, usage) {
+    const rule = findPricingRule(model);
+    if (!rule) {
+        return undefined;
+    }
+    const cacheRead = rule.cacheReadPerM ?? rule.inputPerM * 0.1;
+    const write5m = rule.cacheWrite5mPerM ?? rule.inputPerM * 1.25;
+    const write1h = rule.cacheWrite1hPerM ?? rule.inputPerM * 2;
+    const usd = (usage.inputTokens * rule.inputPerM +
+        usage.outputTokens * rule.outputPerM +
+        (usage.cacheReadTokens ?? 0) * cacheRead +
+        (usage.cacheWrite5mTokens ?? 0) * write5m +
+        (usage.cacheWrite1hTokens ?? 0) * write1h) /
+        1_000_000;
+    return Math.round(usd * 10_000) / 10_000;
+}
+//# sourceMappingURL=modelPricing.js.map

package/dist/planMath.d.ts

@@ -0,0 +1,42 @@
+import type { UsageRecord } from "./schema.js";
+/**
+ * Plan-price math: compares API-equivalent usage (from local agent logs)
+ * against published subscription plan prices — the arbitrage check no
+ * provider will ever show, because it's the math that tells you to pay
+ * them less.
+ *
+ * Prices are mid-2026 list prices. As of 2026-06-15, programmatic/Agent-SDK
+ * usage on Claude plans is metered against a separate monthly credit pool at
+ * API rates ($20 Pro / $100 Max 5x / $200 Max 20x) — which makes the
+ * API-equivalent dollar figure the number that matters on both paths.
+ */
+export type SubscriptionPlan = {
+    id: string;
+    provider: "anthropic" | "openai";
+    agent: "claude-code" | "codex";
+    name: string;
+    monthlyUsd: number;
+    /** Rough API-equivalent monthly usage this plan comfortably covers. */
+    coversUpToUsd: number;
+};
+export declare const subscriptionPlans: SubscriptionPlan[];
+export type PlanCheck = {
+    agent: "claude-code" | "codex";
+    /** 30-day projection of API-equivalent spend observed in local logs. */
+    apiEquivalentMonthlyUsd: number;
+    /** Distinct days of observed usage the projection is based on. */
+    windowDays: number;
+    /** Cheapest plan that comfortably covers the projected usage (if any). */
+    suggestedPlan?: SubscriptionPlan;
+    /** apiEquivalentMonthlyUsd - plan price, when positive. */
+    monthlySavingsVsApiUsd?: number;
+    /** One-line, render-ready verdict. */
+    headline: string;
+};
+/**
+ * Compute per-agent plan checks from usage records. Only records that came
+ * from local agent logs participate (billing-API records already have real
+ * prices and a real plan behind them).
+ */
+export declare function computePlanChecks(records: UsageRecord[]): PlanCheck[];
+//# sourceMappingURL=planMath.d.ts.map

package/dist/planMath.js

@@ -0,0 +1,58 @@
+export const subscriptionPlans = [
+    { id: "claude-pro", provider: "anthropic", agent: "claude-code", name: "Claude Pro", monthlyUsd: 20, coversUpToUsd: 50 },
+    { id: "claude-max-5x", provider: "anthropic", agent: "claude-code", name: "Claude Max 5x", monthlyUsd: 100, coversUpToUsd: 250 },
+    { id: "claude-max-20x", provider: "anthropic", agent: "claude-code", name: "Claude Max 20x", monthlyUsd: 200, coversUpToUsd: 1000 },
+    { id: "chatgpt-plus", provider: "openai", agent: "codex", name: "ChatGPT Plus", monthlyUsd: 20, coversUpToUsd: 60 },
+    { id: "chatgpt-pro", provider: "openai", agent: "codex", name: "ChatGPT Pro", monthlyUsd: 200, coversUpToUsd: 1000 }
+];
+const localLogCostType = "local_agent_logs";
+/**
+ * Compute per-agent plan checks from usage records. Only records that came
+ * from local agent logs participate (billing-API records already have real
+ * prices and a real plan behind them).
+ */
+export function computePlanChecks(records) {
+    const localRecords = records.filter((record) => record.providerCostType === localLogCostType &&
+        (record.agentId === "claude-code" || record.agentId === "codex") &&
+        typeof record.amountUsd === "number");
+    if (localRecords.length === 0) {
+        return [];
+    }
+    const byAgent = new Map();
+    for (const record of localRecords) {
+        const agent = record.agentId;
+        byAgent.set(agent, [...(byAgent.get(agent) ?? []), record]);
+    }
+    const checks = [];
+    for (const [agent, agentRecords] of byAgent) {
+        const windowDays = Math.max(1, new Set(agentRecords.map((record) => record.timestamp.slice(0, 10))).size);
+        const windowUsd = agentRecords.reduce((total, record) => total + (record.amountUsd ?? 0), 0);
+        const monthly = roundMoney((windowUsd / windowDays) * 30);
+        const candidates = subscriptionPlans.filter((plan) => plan.agent === agent);
+        const suggested = candidates.find((plan) => monthly <= plan.coversUpToUsd) ?? candidates[candidates.length - 1];
+        const savings = suggested ? roundMoney(monthly - suggested.monthlyUsd) : undefined;
+        let headline;
+        if (!suggested) {
+            headline = `${agent}: ~$${monthly.toFixed(2)}/mo at API rates.`;
+        }
+        else if (typeof savings === "number" && savings > 0) {
+            headline = `${agent}: ~$${monthly.toFixed(2)}/mo at API rates — ${suggested.name} ($${suggested.monthlyUsd}/mo) likely covers this, ~$${savings.toFixed(2)}/mo cheaper than paying per token.`;
+        }
+        else {
+            headline = `${agent}: ~$${monthly.toFixed(2)}/mo at API rates — within ${suggested.name} ($${suggested.monthlyUsd}/mo); pay-as-you-go API could be cheaper if you drop the subscription.`;
+        }
+        checks.push({
+            agent,
+            apiEquivalentMonthlyUsd: monthly,
+            windowDays,
+            suggestedPlan: suggested,
+            monthlySavingsVsApiUsd: typeof savings === "number" && savings > 0 ? savings : undefined,
+            headline
+        });
+    }
+    return checks.sort((left, right) => right.apiEquivalentMonthlyUsd - left.apiEquivalentMonthlyUsd);
+}
+function roundMoney(value) {
+    return Math.round(value * 100) / 100;
+}
+//# sourceMappingURL=planMath.js.map

package/dist/providerConnectors.d.ts

@@ -0,0 +1,88 @@
+import type { ApprovedSource } from "./sourceRegistry.js";
+import type { UsageRecord } from "./schema.js";
+type ProviderResponse = {
+    ok: boolean;
+    status: number;
+    statusText?: string;
+    headers?: Record<string, string | undefined> | {
+        get: (name: string) => string | null;
+    };
+    json: () => Promise<unknown>;
+};
+export type ProviderQaPagination = {
+    label: string;
+    pagesFetched: number;
+    stoppedBecause: "complete" | "missing_cursor" | "max_pages";
+    maxPages: number;
+    limitPerPage?: number;
+};
+export type ProviderQaRateLimit = {
+    label: string;
+    remainingRequests?: number;
+    retryAfterSeconds?: number;
+};
+export type ProviderQaDriftIssue = {
+    label: string;
+    field: string;
+    issue: string;
+};
+export type ProviderQaSummary = {
+    provider: string;
+    requestedEndpoints: string[];
+    pagination: ProviderQaPagination[];
+    rateLimits: ProviderQaRateLimit[];
+    responseDrift: ProviderQaDriftIssue[];
+    instructions: string[];
+};
+export type ProviderId = "openai" | "anthropic" | "github-copilot" | "cursor" | string;
+export type ProviderConnectorInput = {
+    provider: ProviderId;
+    sourceId?: string;
+    authReference: string;
+    startTime: number;
+    endTime?: number;
+    org?: string;
+    enterprise?: string;
+    accountId?: string;
+    fetcher?: Fetcher;
+    tokenResolver?: TokenResolver;
+};
+export type ProviderConnectorResult = {
+    provider: string;
+    source: ApprovedSource;
+    records: UsageRecord[];
+    fetchedAt: string;
+    completeness: "verified" | "estimated" | "detected_unverified" | "missing";
+    qa: ProviderQaSummary;
+};
+export type CreateProviderConnectionInput = {
+    provider: ProviderId;
+    sourceId?: string;
+    authReference: string;
+    verifiedRecordCount: number;
+    totalUsd: number;
+    fetchedAt?: Date;
+};
+export type TokenResolver = (reference: string) => string;
+export type Fetcher = (url: string, init?: {
+    method?: string;
+    headers?: Record<string, string>;
+    body?: string;
+}) => Promise<ProviderResponse>;
+type NormalizerOptions = {
+    sourceId: string;
+    observedFrom: string;
+    accountId?: string;
+};
+export declare function normalizeOpenAiCostResponse(response: unknown, options: NormalizerOptions): UsageRecord[];
+export declare function normalizeOpenAiUsageResponse(response: unknown, options: NormalizerOptions): UsageRecord[];
+export declare function normalizeAnthropicClaudeCodeUsageResponse(response: unknown, options: NormalizerOptions): UsageRecord[];
+export declare function normalizeGitHubCopilotSeatResponse(response: unknown, options: NormalizerOptions): UsageRecord[];
+export declare function normalizeAnthropicCostResponse(response: unknown, options: NormalizerOptions): UsageRecord[];
+export declare function normalizeGitHubCopilotMetricsResponse(response: unknown, options: NormalizerOptions): UsageRecord[];
+export declare function normalizeCursorSpendResponse(response: unknown, options: NormalizerOptions): UsageRecord[];
+export declare function fetchProviderUsageRecords(input: ProviderConnectorInput): Promise<ProviderConnectorResult>;
+export declare function createProviderConnection(input: CreateProviderConnectionInput): ApprovedSource;
+export declare function resolveTokenReference(reference: string, env?: Record<string, string | undefined>): string;
+export {};
+//# sourceMappingURL=providerConnectors.d.ts.map