@agent-finops/core 0.7.2 → 0.8.0

package/README.md

@@ -2,12 +2,45 @@
 
 The canonical local-first evidence and decision engine for
 [aibill](https://github.com/futurastudio/ai-spend-agent): Claude Code/Codex
-activity ingestion, provider cost semantics, attribution, provenance, runway,
-Context Health, and the shared Glance contract.
+activity ingestion, experimental Gemini CLI financial ingestion, provider cost
+semantics, attribution, provenance, runway, Context Health, and the shared
+Glance contract. Gemini support is fixture-verified and does not enter the
+Glance/status-line or Context Health contracts.
 
 Most users should run `npx aibill`. This package is for integrations that
 need the same evidence-labeled calculations as the CLI and MCP server.
 
+## Supported library preview
+
+Use Node.js 22+ ESM and import only from the package root:
+
+```ts
+import { analyzeSpend, parseUsageRecord } from "@agent-finops/core";
+```
+
+The supported 0.x subset covers usage-record validation/parsing,
+`analyzeSpend`, Receipt v0 creation/parsing, opaque source-record references,
+and the explicitly version-pinned FOCUS, OpenTelemetry GenAI, and Tokenomics
+projections. Tokenomics remains a `not_published`, zero-row tracking stub.
+
+An explicit export map blocks unsupported deep imports. Other historical root
+exports remain available for compatibility but are not stabilized by this
+narrow preview. See the complete
+[library contract](https://github.com/futurastudio/ai-spend-agent/blob/main/docs/LIBRARY.md),
+including the runnable JavaScript/TypeScript example and 0.x deprecation
+policy.
+
+The supported functions are local, deterministic operations on caller-supplied
+objects for a given package version. Importing this package does not read
+transcripts or credentials, write state, call a provider, upload evidence, or
+send telemetry.
+
+Schema parsing checks structure and internal consistency; it does not
+authenticate a source, verify a price, or reconcile an invoice. Callers must
+keep provenance and confidence labels truthful: reserve `verified` for
+official provider-reported financial evidence, keep modeled/local value
+`estimated` or `missing`, and leave unvalidated adapters `untested`.
+
 This is the open foundation for aibill's financial-accountability mission. It
 does not yet implement company-wide ownership, accepted outcomes, approvals,
 invoice reconciliation, or ROI.

package/dist/activitySnapshot.d.ts

@@ -4,8 +4,8 @@ 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 LocalAgentFormatId[];
-export type ActivitySnapshotAgent = LocalAgentFormatId;
+export type ActivitySnapshotAgent = Extract<LocalAgentFormatId, "claude-code" | "codex">;
+export declare const activitySnapshotAgentValues: readonly ActivitySnapshotAgent[];
 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"];
@@ -178,7 +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.ZodString & z.ZodType<LocalAgentFormatId, string, z.core.$ZodTypeInternals<LocalAgentFormatId, string>>;
+    agent: z.ZodString & z.ZodType<ActivitySnapshotAgent, string, z.core.$ZodTypeInternals<ActivitySnapshotAgent, string>>;
     billing: z.ZodLiteral<"subscription">;
     planId: z.ZodNullable<z.ZodEnum<{
         "claude-max-20x": "claude-max-20x";
@@ -258,7 +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.ZodString & z.ZodType<LocalAgentFormatId, string, z.core.$ZodTypeInternals<LocalAgentFormatId, string>>;
+        agent: z.ZodString & z.ZodType<ActivitySnapshotAgent, string, z.core.$ZodTypeInternals<ActivitySnapshotAgent, string>>;
         directoryStatus: z.ZodEnum<{
             missing: "missing";
             readable: "readable";
@@ -349,7 +349,7 @@ export declare const activitySnapshotSchema: z.ZodObject<{
     }>;
     subscription: z.ZodNullable<z.ZodObject<{
         agents: z.ZodArray<z.ZodObject<{
-            agent: z.ZodString & z.ZodType<LocalAgentFormatId, string, z.core.$ZodTypeInternals<LocalAgentFormatId, string>>;
+            agent: z.ZodString & z.ZodType<ActivitySnapshotAgent, string, z.core.$ZodTypeInternals<ActivitySnapshotAgent, string>>;
             billing: z.ZodLiteral<"subscription">;
             planId: z.ZodNullable<z.ZodEnum<{
                 "claude-max-20x": "claude-max-20x";
@@ -420,7 +420,7 @@ export declare const activitySnapshotSchema: z.ZodObject<{
     }, z.core.$strict>>;
     metered: z.ZodNullable<z.ZodObject<{
         agents: z.ZodArray<z.ZodObject<{
-            agent: z.ZodString & z.ZodType<LocalAgentFormatId, string, z.core.$ZodTypeInternals<LocalAgentFormatId, string>>;
+            agent: z.ZodString & z.ZodType<ActivitySnapshotAgent, string, z.core.$ZodTypeInternals<ActivitySnapshotAgent, string>>;
             billing: z.ZodLiteral<"api_key">;
             planId: z.ZodNullable<z.ZodEnum<{
                 "claude-max-20x": "claude-max-20x";
@@ -521,7 +521,7 @@ export declare const activitySnapshotSchema: z.ZodObject<{
     }, z.core.$strict>>;
     unresolved: z.ZodNullable<z.ZodObject<{
         agents: z.ZodArray<z.ZodObject<{
-            agent: z.ZodString & z.ZodType<LocalAgentFormatId, string, z.core.$ZodTypeInternals<LocalAgentFormatId, string>>;
+            agent: z.ZodString & z.ZodType<ActivitySnapshotAgent, string, z.core.$ZodTypeInternals<ActivitySnapshotAgent, string>>;
             billing: z.ZodLiteral<"unknown">;
             planId: z.ZodNullable<z.ZodEnum<{
                 "claude-max-20x": "claude-max-20x";
@@ -586,7 +586,7 @@ export declare const activitySnapshotSchema: z.ZodObject<{
     }, z.core.$strict>>;
     coverage: z.ZodObject<{
         agents: z.ZodArray<z.ZodObject<{
-            agent: z.ZodString & z.ZodType<LocalAgentFormatId, string, z.core.$ZodTypeInternals<LocalAgentFormatId, string>>;
+            agent: z.ZodString & z.ZodType<ActivitySnapshotAgent, string, z.core.$ZodTypeInternals<ActivitySnapshotAgent, string>>;
             directoryStatus: z.ZodEnum<{
                 missing: "missing";
                 readable: "readable";

package/dist/activitySnapshot.js

@@ -1,11 +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 { canPriceTokenUsageAtScope, 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 = Object.freeze(localAgentFormatDescriptors.map((descriptor) => descriptor.id));
+export const activitySnapshotAgentValues = Object.freeze(localAgentFormatDescriptors
+    .filter((descriptor) => descriptor.capabilities.statuslineSnapshot)
+    .map((descriptor) => descriptor.id));
 const activitySnapshotAgentValueSet = new Set(activitySnapshotAgentValues);
 const activitySnapshotAgentLimit = activitySnapshotAgentValues.length;
 export const activitySnapshotPlanIdValues = [
@@ -459,7 +461,12 @@ export function buildActivitySnapshot(input) {
     const horizonStartMs = asOfMs - 30 * DAY_MS;
     // Horizon filtering must precede ID conflict detection: stale history must
     // neither activate a cohort nor suppress a current row that reused an ID.
-    const horizonRecords = input.records.filter((record) => validRecordTimestampInHorizon(record, horizonStartMs, asOfMs));
+    const horizonRecords = input.records.filter((record) => validRecordTimestampInHorizon(record, horizonStartMs, asOfMs) &&
+        // The statusline cache is a deliberately narrower contract than the full
+        // parser registry. Registry-native sources join only after their snapshot
+        // capability has its own host/UI verification.
+        (record.providerCostType !== "local_agent_logs" ||
+            record.agentId === undefined || isSnapshotAgent(record.agentId)));
     const deduplicated = deduplicateRecords(horizonRecords);
     const classified = deduplicated.records
         .map((record) => ({
@@ -468,10 +475,10 @@ export function buildActivitySnapshot(input) {
     }));
     // Keep later same-day calls available only for proportionally splitting a
     // daily aggregate at asOf; activity and limit selection remain <= asOf.
-    const allCalls = dedupeCumulativeSessionCalls([...(input.calls ?? [])].filter((call) => 
-    // One preceding bucket is needed to preserve the denominator when a
-    // daily aggregate straddles the 30-day cutoff.
-    validCallAtOrAfter(call, horizonStartMs - DAY_MS)));
+    const allCalls = dedupeCumulativeSessionCalls([...(input.calls ?? [])].filter((call) => isSnapshotAgent(call.agent) &&
+        // One preceding bucket is needed to preserve the denominator when a
+        // daily aggregate straddles the 30-day cutoff.
+        validCallAtOrAfter(call, horizonStartMs - DAY_MS)));
     const calls = allCalls.filter((call) => validCallAtOrBefore(call, asOfMs));
     const subscriptionAgents = activitySubscriptionAgents(classified, calls, allCalls, plans, scans, trustedIds, asOfMs);
     const meteredApiRecords = classified
@@ -794,10 +801,14 @@ function apiEquivalentObservations(records, calls, trustedProviderIds) {
 function allocateAggregateAmount(amountUsd, calls) {
     if (amountUsd === null)
         return calls.map(() => null);
+    const priceable = calls.map((call) => canPriceTokenUsageAtScope(call.model, call.usage, call.usageScope === "turn" ? "request" : "aggregate") && estimateTokenCostUsd(call.model, call.usage) !== undefined);
+    if (priceable.some((supported) => !supported))
+        return calls.map(() => null);
     const weights = calls.map((call) => estimateTokenCostUsd(call.model, call.usage) ?? 0);
     const totalWeight = weights.reduce((sum, weight) => sum + weight, 0);
-    if (totalWeight <= 0)
-        return calls.map(() => amountUsd / calls.length);
+    if (totalWeight <= 0) {
+        return amountUsd === 0 ? calls.map(() => 0) : calls.map(() => null);
+    }
     return weights.map((weight) => amountUsd * weight / totalWeight);
 }
 function observationsForWindow(observations, asOfMs, days) {

package/dist/cutList.js

@@ -1,4 +1,5 @@
 import { hasCallLevelProvenance, hasModeledWorkloadEvidence, hasPricedEvidence } from "./schema.js";
+import { localAgentFormatSupports } from "./localAgentFormats/registry.js";
 /**
  * Select a non-overlapping subset of cut actions, highest-savings first. An
  * action is added only if none of its records were already claimed by a
@@ -76,7 +77,7 @@ export function generateCutList(records) {
     // Local transcript aggregates remain eligible only for the observed-only
     // context exposure path below; they never earn a modeled savings number.
     const callLevelRecords = records.filter(hasModeledWorkloadEvidence);
-    const contextEvidenceRecords = records.filter((record) => isLocalAgentRecord(record) || (hasCallLevelProvenance(record) && hasPricedEvidence(record)));
+    const contextEvidenceRecords = records.filter((record) => (hasPricedEvidence(record) && (isActionPlanningLocalAgentRecord(record) || hasCallLevelProvenance(record))));
     const actions = [
         ...modelDowngradeActions(callLevelRecords),
         ...contextTrimActions(contextEvidenceRecords),
@@ -90,6 +91,13 @@ export function generateCutList(records) {
         right.affectedSpendUsd - left.affectedSpendUsd ||
         left.id.localeCompare(right.id));
 }
+function isActionPlanningLocalAgentRecord(record) {
+    if (!isLocalAgentRecord(record))
+        return false;
+    // Preserve old local caches that predate agentId, but make every registered
+    // source opt into recommendation/Apply semantics explicitly.
+    return !record.agentId || localAgentFormatSupports(record.agentId, "actionPlanning");
+}
 /** Sum of all per-action estimated monthly savings. */
 export function totalEstimatedMonthlySavingsUsd(actions) {
     return roundMoney(actions.reduce((total, action) => total + action.estimatedMonthlySavingsUsd, 0));

package/dist/glance.js

@@ -1,5 +1,5 @@
 import { dedupeCumulativeSessionCalls, sanitizeLocalActivityText } from "./localAgentLogs.js";
-import { estimateTokenCostUsd, PRICING_TABLE_AS_OF } from "./modelPricing.js";
+import { canPriceTokenUsageAtScope, 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";
@@ -612,6 +612,8 @@ function limitActionName(limit) {
 function callCost(call) {
     if (call.usageSupport === "unsupported_token_shape")
         return undefined;
+    if (!canPriceTokenUsageAtScope(call.model, call.usage, call.usageScope === "turn" ? "request" : "aggregate"))
+        return undefined;
     return estimateTokenCostUsd(call.model, call.usage);
 }
 function inputSideTokens(call) {

package/dist/localAgentFormats/gemini.d.ts

@@ -0,0 +1,55 @@
+import type { TokenUsage } from "../modelPricing.js";
+export type GeminiCacheAccounting = "included" | "none" | "unknown";
+export type GeminiTokenEvidence = {
+    /** Raw provider fields. Invalid or absent fields remain absent. */
+    readonly input?: number;
+    readonly output?: number;
+    readonly cached?: number;
+    readonly thoughts?: number;
+    readonly tool?: number;
+    readonly total?: number;
+    /** Whether the reported input count includes the cached count. */
+    readonly cacheAccounting: GeminiCacheAccounting;
+};
+/**
+ * Structural call type that can be wired into LocalAgentCall once the Gemini
+ * registry descriptor is enabled. It deliberately exposes no prompt content
+ * or raw project hash.
+ */
+export type GeminiParsedCall = {
+    readonly agent: "gemini-cli";
+    readonly callId: string;
+    readonly model: string;
+    readonly timestamp: string;
+    readonly startedAt?: string;
+    readonly project?: string;
+    readonly workingDirectory?: string;
+    readonly sessionId?: string;
+    readonly usageScope: "turn";
+    readonly usageSupport: "complete" | "unsupported_token_shape";
+    readonly reportedTotalTokens?: number;
+    readonly sourceVersion?: string;
+    readonly usage: TokenUsage;
+    readonly geminiTokenEvidence: GeminiTokenEvidence;
+};
+export type GeminiParseDiagnosticCode = "malformed_json" | "malformed_jsonl" | "unsupported_token_shape" | "missing_timestamp";
+export type GeminiParseDiagnostic = {
+    readonly code: GeminiParseDiagnosticCode;
+    readonly count: number;
+};
+export type GeminiParseOptions = {
+    /** Caller-supplied path, including recursive chats/subagent paths. */
+    readonly filePath: string;
+    readonly sinceMs?: number;
+};
+export type GeminiParseResult = {
+    readonly calls: GeminiParsedCall[];
+    readonly diagnostics: GeminiParseDiagnostic[];
+};
+/** Parse a Gemini chat file according to its caller-supplied extension. */
+export declare function parseGeminiSession(content: string, options: GeminiParseOptions): GeminiParseResult;
+/** Parse the legacy whole-conversation JSON representation. */
+export declare function parseGeminiJsonSession(content: string, options: GeminiParseOptions): GeminiParseResult;
+/** Parse the append-only current JSONL message representation. */
+export declare function parseGeminiJsonlSession(content: string, options: GeminiParseOptions): GeminiParseResult;
+//# sourceMappingURL=gemini.d.ts.map