@agent-finops/core 0.7.1 → 0.7.2

package/dist/activitySnapshot.d.ts

@@ -1,10 +1,11 @@
 import { z } from "zod";
 import { type LocalAgentCall, type LocalAgentSourceScan } from "./localAgentLogs.js";
+import type { LocalAgentFormatId } from "./localAgentFormats/types.js";
 import type { DetectedPlan } from "./planDetection.js";
 import { type UsageRecord } from "./schema.js";
 import { type SourceValidationCoverage } from "./sourceStatus.js";
-export declare const activitySnapshotAgentValues: readonly ["claude-code", "codex"];
-export type ActivitySnapshotAgent = typeof activitySnapshotAgentValues[number];
+export declare const activitySnapshotAgentValues: readonly LocalAgentFormatId[];
+export type ActivitySnapshotAgent = LocalAgentFormatId;
 export declare const activitySnapshotPlanIdValues: readonly ["claude-pro", "claude-max-5x", "claude-max-20x", "chatgpt-plus", "chatgpt-pro"];
 export type ActivitySnapshotPlanId = typeof activitySnapshotPlanIdValues[number];
 export declare const activitySnapshotProviderValues: readonly ["openai", "anthropic", "cursor", "github-copilot", "other"];
@@ -177,10 +178,7 @@ export declare const activitySnapshotLimitSchema: z.ZodObject<{
 }, z.core.$strict>;
 export type ActivitySnapshotLimit = z.infer<typeof activitySnapshotLimitSchema>;
 export declare const activitySnapshotSubscriptionAgentSchema: z.ZodObject<{
-    agent: z.ZodEnum<{
-        "claude-code": "claude-code";
-        codex: "codex";
-    }>;
+    agent: z.ZodString & z.ZodType<LocalAgentFormatId, string, z.core.$ZodTypeInternals<LocalAgentFormatId, string>>;
     billing: z.ZodLiteral<"subscription">;
     planId: z.ZodNullable<z.ZodEnum<{
         "claude-max-20x": "claude-max-20x";
@@ -260,10 +258,7 @@ export declare const activitySnapshotOverageSchema: z.ZodObject<{
 export type ActivitySnapshotOverage = z.infer<typeof activitySnapshotOverageSchema>;
 export declare const activitySnapshotCoverageSchema: z.ZodObject<{
     agents: z.ZodArray<z.ZodObject<{
-        agent: z.ZodEnum<{
-            "claude-code": "claude-code";
-            codex: "codex";
-        }>;
+        agent: z.ZodString & z.ZodType<LocalAgentFormatId, string, z.core.$ZodTypeInternals<LocalAgentFormatId, string>>;
         directoryStatus: z.ZodEnum<{
             missing: "missing";
             readable: "readable";
@@ -314,8 +309,8 @@ export declare const activitySnapshotCoverageSchema: z.ZodObject<{
     recordsPriced: z.ZodNumber;
     recordsUnpriced: z.ZodNumber;
     validationStatus: z.ZodEnum<{
-        complete: "complete";
         failed: "failed";
+        complete: "complete";
         not_checked: "not_checked";
         partial: "partial";
     }>;
@@ -354,10 +349,7 @@ export declare const activitySnapshotSchema: z.ZodObject<{
     }>;
     subscription: z.ZodNullable<z.ZodObject<{
         agents: z.ZodArray<z.ZodObject<{
-            agent: z.ZodEnum<{
-                "claude-code": "claude-code";
-                codex: "codex";
-            }>;
+            agent: z.ZodString & z.ZodType<LocalAgentFormatId, string, z.core.$ZodTypeInternals<LocalAgentFormatId, string>>;
             billing: z.ZodLiteral<"subscription">;
             planId: z.ZodNullable<z.ZodEnum<{
                 "claude-max-20x": "claude-max-20x";
@@ -428,10 +420,7 @@ export declare const activitySnapshotSchema: z.ZodObject<{
     }, z.core.$strict>>;
     metered: z.ZodNullable<z.ZodObject<{
         agents: z.ZodArray<z.ZodObject<{
-            agent: z.ZodEnum<{
-                "claude-code": "claude-code";
-                codex: "codex";
-            }>;
+            agent: z.ZodString & z.ZodType<LocalAgentFormatId, string, z.core.$ZodTypeInternals<LocalAgentFormatId, string>>;
             billing: z.ZodLiteral<"api_key">;
             planId: z.ZodNullable<z.ZodEnum<{
                 "claude-max-20x": "claude-max-20x";
@@ -532,10 +521,7 @@ export declare const activitySnapshotSchema: z.ZodObject<{
     }, z.core.$strict>>;
     unresolved: z.ZodNullable<z.ZodObject<{
         agents: z.ZodArray<z.ZodObject<{
-            agent: z.ZodEnum<{
-                "claude-code": "claude-code";
-                codex: "codex";
-            }>;
+            agent: z.ZodString & z.ZodType<LocalAgentFormatId, string, z.core.$ZodTypeInternals<LocalAgentFormatId, string>>;
             billing: z.ZodLiteral<"unknown">;
             planId: z.ZodNullable<z.ZodEnum<{
                 "claude-max-20x": "claude-max-20x";
@@ -600,10 +586,7 @@ export declare const activitySnapshotSchema: z.ZodObject<{
     }, z.core.$strict>>;
     coverage: z.ZodObject<{
         agents: z.ZodArray<z.ZodObject<{
-            agent: z.ZodEnum<{
-                "claude-code": "claude-code";
-                codex: "codex";
-            }>;
+            agent: z.ZodString & z.ZodType<LocalAgentFormatId, string, z.core.$ZodTypeInternals<LocalAgentFormatId, string>>;
             directoryStatus: z.ZodEnum<{
                 missing: "missing";
                 readable: "readable";
@@ -654,8 +637,8 @@ export declare const activitySnapshotSchema: z.ZodObject<{
         recordsPriced: z.ZodNumber;
         recordsUnpriced: z.ZodNumber;
         validationStatus: z.ZodEnum<{
-            complete: "complete";
             failed: "failed";
+            complete: "complete";
             not_checked: "not_checked";
             partial: "partial";
         }>;

package/dist/activitySnapshot.js

@@ -1,10 +1,13 @@
 import { z } from "zod";
 import { aggregateCalls, dedupeCumulativeSessionCalls } from "./localAgentLogs.js";
+import { localAgentFormatDescriptors } from "./localAgentFormats/registry.js";
 import { estimateTokenCostUsd, PRICING_TABLE_AS_OF } from "./modelPricing.js";
 import { isBundledSampleUsage } from "./schema.js";
 import { sourceValidationCoverageValues } from "./sourceStatus.js";
 const DAY_MS = 24 * 60 * 60 * 1_000;
-export const activitySnapshotAgentValues = ["claude-code", "codex"];
+export const activitySnapshotAgentValues = Object.freeze(localAgentFormatDescriptors.map((descriptor) => descriptor.id));
+const activitySnapshotAgentValueSet = new Set(activitySnapshotAgentValues);
+const activitySnapshotAgentLimit = activitySnapshotAgentValues.length;
 export const activitySnapshotPlanIdValues = [
     "claude-pro",
     "claude-max-5x",
@@ -45,7 +48,9 @@ const isoTimestampSchema = z.string().datetime({ offset: true });
 const usdSchema = z.number().finite().nonnegative();
 const countSchema = z.number().int().nonnegative();
 const windowCoverageSchema = z.enum(["complete", "partial", "missing"]);
-const agentSchema = z.enum(activitySnapshotAgentValues);
+const agentSchema = z.string().refine(isSnapshotAgent, {
+    message: "Agent must be registered as a local-agent format."
+});
 const planIdSchema = z.enum(activitySnapshotPlanIdValues).nullable();
 export const activitySnapshotApiEquivalentWindowSchema = z.object({
     amountUsd: usdSchema.nullable(),
@@ -169,14 +174,14 @@ export const activitySnapshotSubscriptionAgentSchema = z.object({
     }
 });
 const activitySnapshotSubscriptionSchema = z.object({
-    agents: z.array(activitySnapshotSubscriptionAgentSchema).min(1).max(2)
+    agents: z.array(activitySnapshotSubscriptionAgentSchema).min(1).max(activitySnapshotAgentLimit)
 }).strict().superRefine(uniqueAgentEntries);
 const activitySnapshotMeteredSchema = z.object({
     agents: z.array(z.object({
         agent: agentSchema,
         billing: z.literal("api_key"),
         planId: planIdSchema
-    }).strict()).max(2),
+    }).strict()).max(activitySnapshotAgentLimit),
     apiEquivalent: activitySnapshotApiEquivalentWindowsSchema,
     providerBilled: activitySnapshotBilledWindowsSchema
 }).strict().superRefine((value, context) => {
@@ -196,7 +201,7 @@ const activitySnapshotUnresolvedSchema = z.object({
         agent: agentSchema,
         billing: z.literal("unknown"),
         planId: planIdSchema
-    }).strict()).max(2),
+    }).strict()).max(activitySnapshotAgentLimit),
     apiEquivalent: activitySnapshotApiEquivalentWindowsSchema
 }).strict().superRefine((value, context) => {
     uniqueAgentEntries(value, context);
@@ -290,7 +295,7 @@ const activitySnapshotProviderCoverageSchema = z.object({
     }
 });
 export const activitySnapshotCoverageSchema = z.object({
-    agents: z.array(activitySnapshotAgentCoverageSchema).max(2),
+    agents: z.array(activitySnapshotAgentCoverageSchema).max(activitySnapshotAgentLimit),
     providers: z.array(activitySnapshotProviderCoverageSchema).max(5),
     recordsParsed: countSchema,
     recordsPriced: countSchema,
@@ -483,8 +488,10 @@ export function buildActivitySnapshot(input) {
         if (isSnapshotAgent(entry.record.agentId))
             activeAgents.add(entry.record.agentId);
     }
-    for (const call of calls)
-        activeAgents.add(call.agent);
+    for (const call of calls) {
+        if (isSnapshotAgent(call.agent))
+            activeAgents.add(call.agent);
+    }
     const meteredAgents = [...activeAgents]
         .filter((agent) => plans.get(agent)?.billing === "api_key")
         .sort()
@@ -529,7 +536,7 @@ export function buildActivitySnapshot(input) {
     const subscription = hasSubscriptionActivity ? { agents: subscriptionAgents } : null;
     const metered = hasMeteredActivity ? {
         agents: meteredAgents,
-        apiEquivalent: buildApiWindows(meteredApiRecords, allCalls.filter((call) => plans.get(call.agent)?.billing === "api_key"), trustedIds, asOfMs, localCoverageForRecords(meteredApiRecords, scans, [...plans.entries()]
+        apiEquivalent: buildApiWindows(meteredApiRecords, allCalls.filter((call) => (isSnapshotAgent(call.agent) && plans.get(call.agent)?.billing === "api_key")), trustedIds, asOfMs, localCoverageForRecords(meteredApiRecords, scans, [...plans.entries()]
             .filter(([, plan]) => plan.billing === "api_key")
             .map(([agent]) => agent))),
         providerBilled: buildBilledWindows(meteredBilledRecords, asOfMs, providers)
@@ -537,6 +544,8 @@ export function buildActivitySnapshot(input) {
     const unresolved = hasUnresolvedActivity ? {
         agents: unresolvedAgents,
         apiEquivalent: buildApiWindows(unresolvedRecords, allCalls.filter((call) => {
+            if (!isSnapshotAgent(call.agent))
+                return false;
             const billing = plans.get(call.agent)?.billing;
             return billing !== "subscription" && billing !== "api_key";
         }), trustedIds, asOfMs, unresolvedCoverageForRecords(unresolvedRecords, scans, providers))
@@ -1200,7 +1209,7 @@ function inRollingWindow(timestamp, asOfMs, days) {
     return Number.isFinite(value) && value >= asOfMs - days * DAY_MS && value <= asOfMs;
 }
 function isSnapshotAgent(value) {
-    return typeof value === "string" && activitySnapshotAgentValues.includes(value);
+    return typeof value === "string" && activitySnapshotAgentValueSet.has(value);
 }
 function isKnownPlanId(value) {
     return typeof value === "string" && activitySnapshotPlanIdValues.includes(value);

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

@@ -12,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

@@ -12,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