@agent-finops/core 0.7.0 → 0.7.2

package/dist/contextHealth.js

@@ -1,5 +1,6 @@
 import { loadAgentInventory } from "./agentInventory.js";
 import { computeDeadContext } from "./deadContext.js";
+import { localAgentFormatSupports } from "./localAgentFormats/registry.js";
 import { loadToolInvocations } from "./toolInvocations.js";
 const DAY_MS = 24 * 60 * 60 * 1_000;
 const DEFAULT_WINDOW_DAYS = 30;
@@ -30,7 +31,8 @@ export async function loadContextHealth(calls, options = {}) {
 /** Pure Context Health contract builder for deterministic tests and adapters. */
 export function buildContextHealth(input = {}) {
     const now = input.now ?? new Date();
-    const calls = input.calls ?? [];
+    const calls = (input.calls ?? [])
+        .filter((call) => localAgentFormatSupports(call.agent, "contextHealth"));
     const items = input.inventory?.items ?? [];
     const invocations = input.invocations ?? emptyInvocations();
     const windowDays = input.windowDays ?? input.deadContext?.windowDays ?? DEFAULT_WINDOW_DAYS;

package/dist/glance.js

@@ -2,6 +2,7 @@ import { dedupeCumulativeSessionCalls, sanitizeLocalActivityText } from "./local
 import { estimateTokenCostUsd, PRICING_TABLE_AS_OF } from "./modelPricing.js";
 import { subscriptionPlans } from "./planMath.js";
 import { buildContextHealth } from "./contextHealth.js";
+import { localAgentFormatDescriptors, localAgentFormatSupports } from "./localAgentFormats/registry.js";
 const HOUR_MS = 60 * 60 * 1_000;
 const DAY_MS = 24 * HOUR_MS;
 /**
@@ -16,7 +17,9 @@ export function buildUsageGlance(calls, options = {}) {
     // defense-in-depth to every string-bearing transcript/context field before
     // any calculation so secrets cannot survive in a nested session-health or
     // provenance field even if an upstream parser missed them.
-    const safeCalls = dedupeCumulativeSessionCalls(sanitizeStringMetadata(calls));
+    const supportedFormats = localAgentFormatDescriptors.filter((descriptor) => (descriptor.capabilities.glance));
+    const safeCalls = dedupeCumulativeSessionCalls(sanitizeStringMetadata(calls))
+        .filter((call) => localAgentFormatSupports(call.agent, "glance"));
     const suppliedContextHealth = options.contextHealth
         ? sanitizeStringMetadata(options.contextHealth)
         : undefined;
@@ -40,7 +43,8 @@ export function buildUsageGlance(calls, options = {}) {
     const plan = currentSession
         ? toGlancePlan(currentSession.agent, safeDetectedPlans)
         : null;
-    const limitCalls = sanitizeStringMetadata(options.limitCalls ?? safeCalls);
+    const limitCalls = sanitizeStringMetadata(options.limitCalls ?? safeCalls)
+        .filter((call) => localAgentFormatSupports(call.agent, "rateLimits"));
     const limits = latestLimits(limitCalls, now).map(({ agent, window, observedAt }) => toGlanceLimit(agent, window, observedAt));
     const windowStart = now.getTime() - focusWindowDays * DAY_MS;
     const windowCalls = safeCalls.filter((call) => Date.parse(call.timestamp) >= windowStart);
@@ -62,7 +66,8 @@ export function buildUsageGlance(calls, options = {}) {
         generatedAt: now.toISOString(),
         filesParsed: options.filesParsed ?? 0
     });
-    const detectedAgents = options.detectedAgents ?? uniqueAgents(safeCalls);
+    const detectedAgents = (options.detectedAgents ?? uniqueAgents(safeCalls))
+        .filter((agent) => localAgentFormatSupports(agent, "glance"));
     const agentsWithLimits = new Set(limits.map((limit) => limit.agent));
     const limitAgents = uniqueAgents(limitCalls.filter((call) => call.rateLimits));
     const reportedWindows = (agent) => ([...new Set(limits
@@ -82,20 +87,15 @@ export function buildUsageGlance(calls, options = {}) {
         generatedAt: now.toISOString(),
         coverage: {
             filesParsed: options.filesParsed ?? 0,
-            supportedTranscriptAgents: ["claude-code", "codex"],
+            supportedTranscriptAgents: supportedFormats.map((descriptor) => descriptor.id),
             detectedAgents,
-            rateLimitMetadata: [
-                {
-                    agent: "claude-code",
-                    status: "not_reported_by_transcript",
-                    windowsReported: reportedWindows("claude-code")
-                },
-                {
-                    agent: "codex",
-                    status: agentsWithLimits.has("codex") ? "reported" : "not_seen",
-                    windowsReported: reportedWindows("codex")
-                }
-            ],
+            rateLimitMetadata: supportedFormats.map((descriptor) => ({
+                agent: descriptor.id,
+                status: descriptor.capabilities.rateLimits
+                    ? agentsWithLimits.has(descriptor.id) ? "reported" : "not_seen"
+                    : "not_reported_by_transcript",
+                windowsReported: reportedWindows(descriptor.id)
+            })),
             providerConnectionRequired: ["cursor", "github-copilot"]
         },
         provenance: {

package/dist/index.d.ts

@@ -1,5 +1,6 @@
 export * from "./analyze.js";
 export * from "./agentInventory.js";
+export * from "./agentEconomicsReceipt.js";
 export * from "./activitySnapshot.js";
 export * from "./activitySnapshotCache.js";
 export * from "./attribution.js";
@@ -11,7 +12,10 @@ export * from "./discovery.js";
 export * from "./glance.js";
 export * from "./toolInvocations.js";
 export * from "./insights.js";
-export * from "./localAgentLogs.js";
+export { aggregateCalls, dedupeCumulativeSessionCalls, latestObservedWorkingDirectory, loadLocalAgentFinancialUsage, loadLocalAgentUsage, parseClaudeCodeTranscript, parseCodexRollout, sanitizeLocalActivityText } from "./localAgentLogs.js";
+export type { LocalAgentActivity, LocalAgentCall, LocalAgentFinancialLogOptions, LocalAgentLogDiagnostic, LocalAgentLogDiagnosticCode, LocalAgentLogOptions, LocalAgentLogResult, LocalAgentRateLimitSnapshot, LocalAgentRateLimitWindow, LocalAgentSourceScan, LocalAgentTurnUsage } from "./localAgentLogs.js";
+export * from "./localAgentFormats/registry.js";
+export type * from "./localAgentFormats/types.js";
 export * from "./modelPricing.js";
 export * from "./planDetection.js";
 export * from "./planMath.js";

package/dist/index.js

@@ -1,5 +1,6 @@
 export * from "./analyze.js";
 export * from "./agentInventory.js";
+export * from "./agentEconomicsReceipt.js";
 export * from "./activitySnapshot.js";
 export * from "./activitySnapshotCache.js";
 export * from "./attribution.js";
@@ -11,7 +12,8 @@ export * from "./discovery.js";
 export * from "./glance.js";
 export * from "./toolInvocations.js";
 export * from "./insights.js";
-export * from "./localAgentLogs.js";
+export { aggregateCalls, dedupeCumulativeSessionCalls, latestObservedWorkingDirectory, loadLocalAgentFinancialUsage, loadLocalAgentUsage, parseClaudeCodeTranscript, parseCodexRollout, sanitizeLocalActivityText } from "./localAgentLogs.js";
+export * from "./localAgentFormats/registry.js";
 export * from "./modelPricing.js";
 export * from "./planDetection.js";
 export * from "./planMath.js";

package/dist/localAgentFormats/registry.d.ts

@@ -0,0 +1,8 @@
+import type { LocalAgentFormatDescriptor, LocalAgentFormatId } from "./types.js";
+export declare const localAgentFormatDescriptors: readonly LocalAgentFormatDescriptor[];
+export declare function localAgentFormatDescriptor(id: LocalAgentFormatId): LocalAgentFormatDescriptor | undefined;
+export declare function localAgentFormatLabel(id: LocalAgentFormatId): string;
+export declare function localAgentFormatSupports(id: LocalAgentFormatId, capability: keyof LocalAgentFormatDescriptor["capabilities"]): boolean;
+export declare function matchesLocalAgentFormatFile(descriptor: LocalAgentFormatDescriptor, filePath: string): boolean;
+export declare function validateLocalAgentFormatDescriptors(registry?: readonly LocalAgentFormatDescriptor[]): void;
+//# sourceMappingURL=registry.d.ts.map

package/dist/localAgentFormats/registry.js

@@ -0,0 +1,219 @@
+import { basename } from "node:path";
+const descriptors = [
+    {
+        schemaVersion: 1,
+        id: "claude-code",
+        order: 10,
+        label: "Claude Code",
+        provider: "anthropic",
+        defaultHomeRelative: [".claude", "projects"],
+        legacyDirectoryOption: "claudeProjectsDir",
+        discovery: { extension: ".jsonl" },
+        confidenceDefaults: {
+            validationCoverage: "live_verified",
+            pricedFinancialEvidence: "estimated",
+            unpricedFinancialEvidence: "missing",
+            sourceConfidence: "estimated"
+        },
+        sourceRecord: {
+            id: "local-agent-logs",
+            name: "Local agent session logs",
+            observedFrom: "claude-code transcript JSONL (this machine)",
+            providerCostType: "local_agent_logs",
+            usageGranularity: "daily_aggregate",
+            operation: "claude-code sessions"
+        },
+        capabilities: {
+            activity: true,
+            contextHealth: true,
+            financialFastPath: true,
+            glance: true,
+            invocationEvidence: false,
+            planContext: true,
+            rateLimits: false
+        },
+        financialRead: "full_jsonl",
+        validationNote: "Local transcript parsing is exercised against live logs; dollar values remain API-rate estimates.",
+        docs: {
+            format: "JSON Lines under ~/.claude/projects/**/*.jsonl",
+            howRead: [
+                "Read one JSON object per line and keep assistant records with message.usage.",
+                "Ignore <synthetic> placeholder models and deduplicate streaming/retry rewrites by message and request identity.",
+                "Treat each retained assistant usage record as turn-scoped evidence."
+            ],
+            fieldsRead: [
+                "timestamp, model, and token-usage components",
+                "session and working-directory metadata for local deduplication and attribution",
+                "human-prompt and tool metadata for privacy-reduced local activity summaries"
+            ],
+            verified: [
+                "The reader and its failure paths have been exercised against live local Claude Code logs.",
+                "Synthetic recorded fixtures lock the supported JSONL shapes and normalized output."
+            ],
+            estimated: [
+                "Supported token components are priced at published API rates as API-equivalent value."
+            ],
+            notVerified: [
+                "API-equivalent value is not billed spend, subscription cost, savings, or ROI.",
+                "Claude Code transcripts do not provide account-plan headroom; missing limits are not inferred."
+            ],
+            privacy: [
+                "Parsing and aggregation run locally; raw prompts and responses are not returned by the parser registry.",
+                "aibill never sits in the inference path and never stores, prints, or proxies provider credentials."
+            ],
+            limitations: [
+                "Malformed lines are skipped and reported.",
+                "Incomplete token shapes remain unpriced with missing financial evidence instead of becoming $0."
+            ]
+        },
+        fixtures: ["claude-code-v1"]
+    },
+    {
+        schemaVersion: 1,
+        id: "codex",
+        order: 20,
+        label: "Codex",
+        provider: "openai",
+        defaultHomeRelative: [".codex", "sessions"],
+        legacyDirectoryOption: "codexSessionsDir",
+        discovery: { extension: ".jsonl", basenamePrefix: "rollout-" },
+        confidenceDefaults: {
+            validationCoverage: "live_verified",
+            pricedFinancialEvidence: "estimated",
+            unpricedFinancialEvidence: "missing",
+            sourceConfidence: "estimated"
+        },
+        sourceRecord: {
+            id: "local-agent-logs",
+            name: "Local agent session logs",
+            observedFrom: "codex transcript JSONL (this machine)",
+            providerCostType: "local_agent_logs",
+            usageGranularity: "daily_aggregate",
+            operation: "codex sessions"
+        },
+        capabilities: {
+            activity: true,
+            contextHealth: true,
+            financialFastPath: true,
+            glance: true,
+            invocationEvidence: true,
+            planContext: true,
+            rateLimits: true
+        },
+        financialRead: "bounded_event_jsonl",
+        validationNote: "Local parsing was replayed against live logs; total-only token shapes and unknown aliases remain missing rather than becoming estimated $0.",
+        docs: {
+            format: "JSON Lines under ~/.codex/sessions/YYYY/MM/DD/rollout-*.jsonl",
+            howRead: [
+                "Read the Codex event stream and retain the root session identity, model, and latest cumulative event_msg/token_count evidence.",
+                "Never sum earlier running token counters; forked sessions subtract a supported inherited cumulative baseline.",
+                "Use a bounded proof-based financial reader for init/cache while the full reader retains privacy-reduced activity and optional invocation evidence."
+            ],
+            fieldsRead: [
+                "session metadata, timestamps, model, and cumulative/last-turn token usage",
+                "transcript-reported rate-limit windows when present",
+                "tool-call metadata for local attribution and optional privacy-safe invocation counts"
+            ],
+            verified: [
+                "The full and optimized financial readers have been replayed against live local Codex logs.",
+                "Synthetic recorded fixtures lock cumulative, last-turn, and rate-limit normalization."
+            ],
+            estimated: [
+                "Supported token components are priced at published API rates as API-equivalent value."
+            ],
+            notVerified: [
+                "API-equivalent value is not billed spend, subscription cost, savings, or ROI.",
+                "A transcript-reported limit is plan-capacity evidence, not a provider invoice."
+            ],
+            privacy: [
+                "Parsing and aggregation run locally; raw prompts and responses are not returned by the parser registry.",
+                "aibill never sits in the inference path and never stores, prints, or proxies provider credentials."
+            ],
+            limitations: [
+                "Only rollout-*.jsonl files are parsed as Codex sessions.",
+                "Incomplete, regressing, or total-only token shapes remain unpriced with missing financial evidence."
+            ]
+        },
+        fixtures: ["codex-v1"]
+    }
+];
+export const localAgentFormatDescriptors = Object.freeze([...descriptors]
+    .sort((left, right) => left.order - right.order)
+    .map(freezeDescriptor));
+export function localAgentFormatDescriptor(id) {
+    return localAgentFormatDescriptors.find((descriptor) => descriptor.id === id);
+}
+export function localAgentFormatLabel(id) {
+    return localAgentFormatDescriptor(id)?.label ?? id;
+}
+export function localAgentFormatSupports(id, capability) {
+    return localAgentFormatDescriptor(id)?.capabilities[capability] === true;
+}
+export function matchesLocalAgentFormatFile(descriptor, filePath) {
+    const name = basename(filePath);
+    if (descriptor.discovery.extension && !name.endsWith(descriptor.discovery.extension))
+        return false;
+    if (descriptor.discovery.basename && name !== descriptor.discovery.basename)
+        return false;
+    if (descriptor.discovery.basenamePrefix && !name.startsWith(descriptor.discovery.basenamePrefix))
+        return false;
+    return true;
+}
+export function validateLocalAgentFormatDescriptors(registry = localAgentFormatDescriptors) {
+    const ids = new Set();
+    const orders = new Set();
+    for (const descriptor of registry) {
+        if (descriptor.schemaVersion !== 1)
+            throw new Error(`Unsupported local-agent format schema for ${descriptor.id}.`);
+        if (!descriptor.id || !descriptor.label || !descriptor.provider)
+            throw new Error("Local-agent format identity is incomplete.");
+        if (!/^[a-z0-9]+(?:-[a-z0-9]+)*$/.test(descriptor.id) ||
+            !/^[a-z0-9]+(?:-[a-z0-9]+)*$/.test(descriptor.provider)) {
+            throw new Error(`Unsafe local-agent format identity for ${descriptor.id}.`);
+        }
+        if (ids.has(descriptor.id))
+            throw new Error(`Duplicate local-agent format id: ${descriptor.id}.`);
+        if (orders.has(descriptor.order))
+            throw new Error(`Duplicate local-agent format order: ${descriptor.order}.`);
+        if (descriptor.defaultHomeRelative.length === 0 || descriptor.defaultHomeRelative.some((part) => (!part || part === "." || part === ".." || /[\\/\u0000]/.test(part)))) {
+            throw new Error(`Unsafe default local-agent root for ${descriptor.id}.`);
+        }
+        const discovery = descriptor.discovery;
+        if (!discovery.extension && !discovery.basename && !discovery.basenamePrefix) {
+            throw new Error(`Local-agent format ${descriptor.id} must declare a bounded file rule.`);
+        }
+        if (discovery.extension && !/^\.[A-Za-z0-9]+$/.test(discovery.extension)) {
+            throw new Error(`Unsafe discovery extension for ${descriptor.id}.`);
+        }
+        for (const value of [discovery.basename, discovery.basenamePrefix]) {
+            if (value && (!/^[A-Za-z0-9][A-Za-z0-9._-]*$/.test(value) || /[\\/\u0000]/.test(value))) {
+                throw new Error(`Unsafe discovery filename rule for ${descriptor.id}.`);
+            }
+        }
+        if (descriptor.confidenceDefaults.pricedFinancialEvidence !== "estimated" ||
+            descriptor.confidenceDefaults.unpricedFinancialEvidence !== "missing" ||
+            descriptor.confidenceDefaults.sourceConfidence !== "estimated") {
+            throw new Error(`Local transcript format ${descriptor.id} must default to estimated/missing financial evidence.`);
+        }
+        if (descriptor.fixtures.length === 0 || descriptor.fixtures.some((fixture) => (!/^[a-z0-9]+(?:-[a-z0-9]+)*-v[1-9][0-9]*$/.test(fixture)))) {
+            throw new Error(`Local-agent format ${descriptor.id} has an unsafe or missing recorded fixture.`);
+        }
+        ids.add(descriptor.id);
+        orders.add(descriptor.order);
+    }
+}
+function freezeDescriptor(descriptor) {
+    Object.freeze(descriptor.defaultHomeRelative);
+    Object.freeze(descriptor.discovery);
+    Object.freeze(descriptor.confidenceDefaults);
+    Object.freeze(descriptor.sourceRecord);
+    Object.freeze(descriptor.capabilities);
+    for (const values of Object.values(descriptor.docs)) {
+        if (Array.isArray(values))
+            Object.freeze(values);
+    }
+    Object.freeze(descriptor.docs);
+    Object.freeze(descriptor.fixtures);
+    return Object.freeze(descriptor);
+}
+//# sourceMappingURL=registry.js.map

package/dist/localAgentFormats/runtimeRegistry.d.ts

@@ -0,0 +1,4 @@
+import type { LocalAgentFormatRuntime } from "./types.js";
+export declare const localAgentFormatRuntimeRegistry: readonly LocalAgentFormatRuntime[];
+export declare function validateLocalAgentFormatRuntimeRegistry(registry?: readonly LocalAgentFormatRuntime[], descriptors?: readonly import("./types.js").LocalAgentFormatDescriptor[]): void;
+//# sourceMappingURL=runtimeRegistry.d.ts.map

package/dist/localAgentFormats/runtimeRegistry.js

@@ -0,0 +1,55 @@
+import { parseClaudeCodeTranscript, parseCodexRollout, readClaudeCodeFinancialFileForRegistry, readCodexFinancialFileForRegistry } from "../localAgentLogs.js";
+import { createCodexInvocationCollector } from "../toolInvocations.js";
+import { localAgentFormatDescriptors, validateLocalAgentFormatDescriptors } from "./registry.js";
+const byId = new Map(localAgentFormatDescriptors.map((descriptor) => [descriptor.id, descriptor]));
+const claudeCode = byId.get("claude-code");
+const codex = byId.get("codex");
+if (!claudeCode || !codex) {
+    throw new Error("Built-in local-agent format descriptors are incomplete.");
+}
+validateLocalAgentFormatDescriptors();
+const runtimes = [
+    {
+        descriptor: claudeCode,
+        parseFull: ({ content, filePath, sinceMs, onDiagnostic }) => ({
+            calls: parseClaudeCodeTranscript(content, filePath, sinceMs, onDiagnostic)
+        }),
+        parseFinancialFile: readClaudeCodeFinancialFileForRegistry
+    },
+    {
+        descriptor: codex,
+        parseFull: ({ content, sinceMs, collectInvocationEvidence, onDiagnostic }) => {
+            const collector = collectInvocationEvidence
+                ? createCodexInvocationCollector(sinceMs)
+                : undefined;
+            return {
+                calls: parseCodexRollout(content, collector?.consume, onDiagnostic),
+                ...(collector ? { invocationFile: collector.finish() } : {})
+            };
+        },
+        parseFinancialFile: readCodexFinancialFileForRegistry
+    }
+];
+export const localAgentFormatRuntimeRegistry = Object.freeze(runtimes.map((runtime) => Object.freeze(runtime)));
+export function validateLocalAgentFormatRuntimeRegistry(registry = localAgentFormatRuntimeRegistry, descriptors = localAgentFormatDescriptors) {
+    validateLocalAgentFormatDescriptors(registry.map((entry) => entry.descriptor));
+    const expected = [...registry].sort((left, right) => (left.descriptor.order - right.descriptor.order));
+    if (expected.some((entry, index) => entry !== registry[index])) {
+        throw new Error("Local-agent runtime registry must be ordered by descriptor order.");
+    }
+    for (const entry of registry) {
+        if (typeof entry.parseFull !== "function" || typeof entry.parseFinancialFile !== "function") {
+            throw new Error(`Local-agent format ${entry.descriptor.id} is missing a runtime parser.`);
+        }
+    }
+    const runtimeIds = registry.map((entry) => entry.descriptor.id);
+    const descriptorIds = descriptors.map((descriptor) => descriptor.id);
+    if (JSON.stringify(runtimeIds) !== JSON.stringify(descriptorIds)) {
+        throw new Error(`Local-agent runtime registry must exactly match descriptor order: ${descriptorIds.join(", ")}.`);
+    }
+    if (registry.some((entry, index) => entry.descriptor !== descriptors[index])) {
+        throw new Error("Local-agent runtime entries must use the canonical descriptor objects.");
+    }
+}
+validateLocalAgentFormatRuntimeRegistry();
+//# sourceMappingURL=runtimeRegistry.js.map

package/dist/localAgentFormats/types.d.ts

@@ -0,0 +1,84 @@
+import type { LocalAgentCall, LocalAgentLogDiagnostic, LocalAgentSourceScan } from "../localAgentLogs.js";
+import type { ParsedInvocationFile } from "../toolInvocations.js";
+/**
+ * Public format identity contract. Add future parser IDs here as part of the
+ * registry-owned change so existing exhaustive consumers do not see an
+ * unbounded `string` in a patch release.
+ */
+export type LocalAgentFormatId = "claude-code" | "codex";
+export type LocalAgentFormatDescriptor = {
+    readonly schemaVersion: 1;
+    readonly id: LocalAgentFormatId;
+    readonly order: number;
+    readonly label: string;
+    readonly provider: string;
+    readonly defaultHomeRelative: readonly string[];
+    readonly legacyDirectoryOption?: "claudeProjectsDir" | "codexSessionsDir";
+    readonly discovery: {
+        readonly extension?: string;
+        readonly basename?: string;
+        readonly basenamePrefix?: string;
+    };
+    readonly confidenceDefaults: {
+        readonly validationCoverage: "live_verified" | "fixture_verified" | "untested" | "failed";
+        readonly pricedFinancialEvidence: "estimated";
+        readonly unpricedFinancialEvidence: "missing";
+        readonly sourceConfidence: "estimated";
+    };
+    readonly sourceRecord: {
+        readonly id: "local-agent-logs";
+        readonly name: "Local agent session logs";
+        readonly observedFrom: string;
+        readonly providerCostType: "local_agent_logs";
+        readonly usageGranularity: "daily_aggregate";
+        readonly operation: string;
+    };
+    readonly capabilities: {
+        readonly activity: boolean;
+        readonly contextHealth: boolean;
+        readonly financialFastPath: boolean;
+        readonly glance: boolean;
+        readonly invocationEvidence: boolean;
+        readonly planContext: boolean;
+        readonly rateLimits: boolean;
+    };
+    readonly financialRead: "full_jsonl" | "bounded_event_jsonl";
+    readonly validationNote: string;
+    readonly docs: {
+        readonly format: string;
+        readonly howRead: readonly string[];
+        readonly fieldsRead: readonly string[];
+        readonly verified: readonly string[];
+        readonly estimated: readonly string[];
+        readonly notVerified: readonly string[];
+        readonly privacy: readonly string[];
+        readonly limitations: readonly string[];
+    };
+    readonly fixtures: readonly string[];
+};
+export type LocalAgentFormatParseContext = {
+    content: string;
+    filePath: string;
+    sinceMs?: number;
+    collectInvocationEvidence: boolean;
+    onDiagnostic: (diagnostic: {
+        code: "malformed_jsonl" | "unsupported_token_shape";
+        count: number;
+    }) => void;
+};
+export type LocalAgentFormatParseResult = {
+    calls: LocalAgentCall[];
+    invocationFile?: ParsedInvocationFile;
+};
+export type LocalAgentFormatFinancialFileContext = {
+    filePath: string;
+    sinceMs?: number;
+    scan: LocalAgentSourceScan;
+    diagnostics: LocalAgentLogDiagnostic[];
+};
+export type LocalAgentFormatRuntime = {
+    descriptor: LocalAgentFormatDescriptor;
+    parseFull: (context: LocalAgentFormatParseContext) => LocalAgentFormatParseResult;
+    parseFinancialFile: (context: LocalAgentFormatFinancialFileContext) => Promise<LocalAgentCall[]>;
+};
+//# sourceMappingURL=types.d.ts.map

package/dist/localAgentFormats/types.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=types.js.map

package/dist/localAgentLogs.d.ts

@@ -1,6 +1,7 @@
 import { type TokenUsage } from "./modelPricing.js";
 import type { UsageRecord } from "./schema.js";
-import { type ParsedInvocationFile } from "./toolInvocations.js";
+import type { ParsedInvocationFile } from "./toolInvocations.js";
+import type { LocalAgentFormatDescriptor, LocalAgentFormatFinancialFileContext, LocalAgentFormatId, LocalAgentFormatRuntime } from "./localAgentFormats/types.js";
 /**
  * Local agent-session log ingestion: turns the transcript files that coding
  * agents already write on this machine into UsageRecords, priced at
@@ -18,7 +19,7 @@ import { type ParsedInvocationFile } from "./toolInvocations.js";
  *    total_token_usage (earlier ones are running updates — never summed).
  */
 export type LocalAgentCall = {
-    agent: "claude-code" | "codex";
+    agent: LocalAgentFormatId;
     model: string;
     /** ISO timestamp of this call, or the latest cumulative usage event. */
     timestamp: string;
@@ -104,6 +105,8 @@ export type LocalAgentLogOptions = {
     claudeProjectsDir?: string;
     /** Default: ~/.codex/sessions */
     codexSessionsDir?: string;
+    /** Registry-native source-root overrides, keyed by format id. */
+    sourceDirectories?: Readonly<Partial<Record<LocalAgentFormatId, string>>>;
     /** Only include calls at/after this ISO timestamp. */
     sinceIso?: string;
     /** Collect privacy-safe Codex invocation summaries during the same JSON pass. */
@@ -178,6 +181,12 @@ export declare function parseClaudeCodeTranscript(content: string, filePath?: st
 export declare function parseCodexRollout(content: string, onEntry?: (entry: Record<string, unknown>) => void, onDiagnostic?: TranscriptParseDiagnosticHandler): LocalAgentCall[];
 /** Scan this machine's agent logs and return aggregated UsageRecords. */
 export declare function loadLocalAgentUsage(options?: LocalAgentLogOptions): Promise<LocalAgentLogResult>;
+/**
+ * Registry-driven ingestion engine. Exported from this module for registry
+ * contract tests and format modules, but intentionally omitted from the
+ * package-root API.
+ */
+export declare function loadLocalAgentUsageWithFormats(registry: readonly LocalAgentFormatRuntime[], options?: LocalAgentLogOptions): Promise<LocalAgentLogResult>;
 /**
  * Stream only the financial evidence required by init/status snapshots.
  *
@@ -189,8 +198,16 @@ export declare function loadLocalAgentUsage(options?: LocalAgentLogOptions): Pro
  * tool-workdir inference remains exclusive to the full qualitative loader.
  */
 export declare function loadLocalAgentFinancialUsage(options?: LocalAgentFinancialLogOptions): Promise<LocalAgentLogResult>;
+/** Registry-driven financial-only engine; package-root exports stay unchanged. */
+export declare function loadLocalAgentFinancialUsageWithFormats(registry: readonly LocalAgentFormatRuntime[], options?: LocalAgentFinancialLogOptions): Promise<LocalAgentLogResult>;
+/** @internal Runtime hook owned by the Claude Code registry entry. */
+export declare function readClaudeCodeFinancialFileForRegistry(context: LocalAgentFormatFinancialFileContext): Promise<LocalAgentCall[]>;
+/** @internal Runtime hook owned by the Codex registry entry. */
+export declare function readCodexFinancialFileForRegistry(context: LocalAgentFormatFinancialFileContext): Promise<LocalAgentCall[]>;
 /** Aggregate per-call usage into one UsageRecord per day+agent+model+project. */
 export declare function aggregateCalls(calls: LocalAgentCall[]): UsageRecord[];
+/** @internal Registry-aware aggregation used by the extensible ingestion engine. */
+export declare function aggregateCallsForFormats(calls: LocalAgentCall[], descriptors: readonly LocalAgentFormatDescriptor[]): UsageRecord[];
 /**
  * Remove known and assignment-shaped credentials from metadata before it can
  * become a topic, title, Glance field, MCP result, or copy-ready handoff.