@agent-finops/core 0.5.8 → 0.5.9

package/dist/schema.d.ts

@@ -20,6 +20,37 @@ export declare const spendSourceSchema: z.ZodObject<{
     observedFrom: z.ZodString;
 }, z.core.$strip>;
 export type SpendSource = z.infer<typeof spendSourceSchema>;
+/**
+ * What one normalized usage record represents.
+ *
+ * Only `call` and `invocation` are precise enough to support per-workload
+ * counterfactuals such as model routing, result caching, Batch API moves, or
+ * prompt trimming. The remaining values are still useful financial evidence,
+ * but must never be silently treated as individual calls.
+ */
+export declare const usageGranularityValues: readonly ["call", "invocation", "session", "daily_aggregate", "usage_bucket", "billing_bucket", "seat", "user_aggregate"];
+export declare const usageGranularitySchema: z.ZodEnum<{
+    call: "call";
+    invocation: "invocation";
+    session: "session";
+    daily_aggregate: "daily_aggregate";
+    usage_bucket: "usage_bucket";
+    billing_bucket: "billing_bucket";
+    seat: "seat";
+    user_aggregate: "user_aggregate";
+}>;
+export type UsageGranularity = z.infer<typeof usageGranularitySchema>;
+/**
+ * Explicit adapter attestations for workload-specific optimization advice.
+ * These fields are intentionally absent by default: an operation label alone
+ * does not prove identical inputs, latency tolerance, or downgrade safety.
+ */
+export declare const workloadSemanticsSchema: z.ZodObject<{
+    stableInputFingerprint: z.ZodOptional<z.ZodString>;
+    batchEligible: z.ZodOptional<z.ZodBoolean>;
+    downgradeSafe: z.ZodOptional<z.ZodBoolean>;
+}, z.core.$strict>;
+export type WorkloadSemantics = z.infer<typeof workloadSemanticsSchema>;
 export declare const usageRecordSchema: z.ZodObject<{
     id: z.ZodString;
     timestamp: z.ZodString;
@@ -54,14 +85,57 @@ export declare const usageRecordSchema: z.ZodObject<{
     quantity: z.ZodOptional<z.ZodNumber>;
     agentId: z.ZodOptional<z.ZodString>;
     operation: z.ZodOptional<z.ZodString>;
+    usageGranularity: z.ZodOptional<z.ZodEnum<{
+        call: "call";
+        invocation: "invocation";
+        session: "session";
+        daily_aggregate: "daily_aggregate";
+        usage_bucket: "usage_bucket";
+        billing_bucket: "billing_bucket";
+        seat: "seat";
+        user_aggregate: "user_aggregate";
+    }>>;
+    workloadSemantics: z.ZodOptional<z.ZodObject<{
+        stableInputFingerprint: z.ZodOptional<z.ZodString>;
+        batchEligible: z.ZodOptional<z.ZodBoolean>;
+        downgradeSafe: z.ZodOptional<z.ZodBoolean>;
+    }, z.core.$strict>>;
 }, z.core.$strip>;
 export type UsageRecord = z.infer<typeof usageRecordSchema>;
+/**
+ * True only when a record can honestly ground a modeled workload change.
+ *
+ * A provider billing row, usage bucket, seat, user total, or unlabelled legacy
+ * row may describe real spend, but it does not prove that one row was one
+ * optimizable call. Requiring both explicit call/invocation provenance and a
+ * named operation keeps aggregate connector data in accounting views without
+ * manufacturing per-call savings advice from it.
+ */
+export declare function hasModeledWorkloadEvidence(record: UsageRecord): boolean;
+/** Explicit one-call / one-model-invocation provenance, never inferred. */
+export declare function hasCallLevelProvenance(record: UsageRecord): boolean;
+/** A positive priced observation from which a dollar counterfactual can be modeled. */
+export declare function hasPricedEvidence(record: UsageRecord): boolean;
+/**
+ * Recognize the bundled demo records written by releases that predate the
+ * persisted `mode` field. The marker is deliberately narrow: every record
+ * must come from the shipped sample CSV and use a sample source identifier.
+ * This lets newer clients recover the demo boundary without guessing that an
+ * arbitrary unlabeled state is real local or connected evidence.
+ */
+export declare function isBundledSampleUsage(records: UsageRecord[]): boolean;
+/**
+ * Stable financial cohort for period-over-period comparisons. Missing shape
+ * provenance returns `undefined`; unknown rows must not be pooled into a fake
+ * comparable series.
+ */
+export declare function spendComparisonKey(record: UsageRecord): string | undefined;
 export declare const attributionCandidateSchema: z.ZodObject<{
     entityType: z.ZodEnum<{
-        user: "user";
-        project: "project";
         client: "client";
+        project: "project";
         agent: "agent";
+        user: "user";
         workspace: "workspace";
         api_key: "api_key";
     }>;
@@ -74,10 +148,10 @@ export declare const attributionMappingSchema: z.ZodObject<{
     usageRecordId: z.ZodString;
     candidates: z.ZodArray<z.ZodObject<{
         entityType: z.ZodEnum<{
-            user: "user";
-            project: "project";
             client: "client";
+            project: "project";
             agent: "agent";
+            user: "user";
             workspace: "workspace";
             api_key: "api_key";
         }>;
@@ -87,10 +161,10 @@ export declare const attributionMappingSchema: z.ZodObject<{
     }, z.core.$strip>>;
     selected: z.ZodOptional<z.ZodObject<{
         entityType: z.ZodEnum<{
-            user: "user";
-            project: "project";
             client: "client";
+            project: "project";
             agent: "agent";
+            user: "user";
             workspace: "workspace";
             api_key: "api_key";
         }>;
@@ -99,10 +173,10 @@ export declare const attributionMappingSchema: z.ZodObject<{
         evidence: z.ZodArray<z.ZodString>;
     }, z.core.$strip>>;
     status: z.ZodEnum<{
-        unmapped: "unmapped";
         auto_mapped: "auto_mapped";
         needs_confirmation: "needs_confirmation";
         needs_question: "needs_question";
+        unmapped: "unmapped";
     }>;
     evidence: z.ZodArray<z.ZodString>;
 }, z.core.$strip>;
@@ -125,6 +199,7 @@ export declare const spendAnomalySchema: z.ZodObject<{
         week_over_week_spike: "week_over_week_spike";
     }>;
     key: z.ZodString;
+    comparisonKey: z.ZodOptional<z.ZodString>;
     previousAmountUsd: z.ZodNumber;
     currentAmountUsd: z.ZodNumber;
     multiplier: z.ZodNumber;
@@ -355,6 +430,7 @@ export declare const spendSummarySchema: z.ZodObject<{
             week_over_week_spike: "week_over_week_spike";
         }>;
         key: z.ZodString;
+        comparisonKey: z.ZodOptional<z.ZodString>;
         previousAmountUsd: z.ZodNumber;
         currentAmountUsd: z.ZodNumber;
         multiplier: z.ZodNumber;

package/dist/schema.js

@@ -13,6 +13,35 @@ export const spendSourceSchema = z.object({
     confidence: costConfidenceSchema,
     observedFrom: z.string().min(1)
 });
+/**
+ * What one normalized usage record represents.
+ *
+ * Only `call` and `invocation` are precise enough to support per-workload
+ * counterfactuals such as model routing, result caching, Batch API moves, or
+ * prompt trimming. The remaining values are still useful financial evidence,
+ * but must never be silently treated as individual calls.
+ */
+export const usageGranularityValues = [
+    "call",
+    "invocation",
+    "session",
+    "daily_aggregate",
+    "usage_bucket",
+    "billing_bucket",
+    "seat",
+    "user_aggregate"
+];
+export const usageGranularitySchema = z.enum(usageGranularityValues);
+/**
+ * Explicit adapter attestations for workload-specific optimization advice.
+ * These fields are intentionally absent by default: an operation label alone
+ * does not prove identical inputs, latency tolerance, or downgrade safety.
+ */
+export const workloadSemanticsSchema = z.object({
+    stableInputFingerprint: z.string().min(8).max(128).regex(/^[a-zA-Z0-9:_-]+$/).optional(),
+    batchEligible: z.boolean().optional(),
+    downgradeSafe: z.boolean().optional()
+}).strict();
 export const usageRecordSchema = z.object({
     id: z.string().min(1),
     timestamp: z.string().datetime({ offset: true }),
@@ -30,7 +59,9 @@ export const usageRecordSchema = z.object({
     providerCostType: z.string().min(1).optional(),
     quantity: z.number().nonnegative().optional(),
     agentId: z.string().min(1).optional(),
-    operation: z.string().min(1).optional()
+    operation: z.string().min(1).optional(),
+    usageGranularity: usageGranularitySchema.optional(),
+    workloadSemantics: workloadSemanticsSchema.optional()
 }).superRefine((record, context) => {
     if (record.costConfidence === "missing" && record.amountUsd !== null) {
         context.addIssue({
@@ -47,6 +78,58 @@ export const usageRecordSchema = z.object({
         });
     }
 });
+/**
+ * True only when a record can honestly ground a modeled workload change.
+ *
+ * A provider billing row, usage bucket, seat, user total, or unlabelled legacy
+ * row may describe real spend, but it does not prove that one row was one
+ * optimizable call. Requiring both explicit call/invocation provenance and a
+ * named operation keeps aggregate connector data in accounting views without
+ * manufacturing per-call savings advice from it.
+ */
+export function hasModeledWorkloadEvidence(record) {
+    return (hasCallLevelProvenance(record) &&
+        typeof record.operation === "string" &&
+        record.operation.trim().length > 0 &&
+        hasPricedEvidence(record));
+}
+/** Explicit one-call / one-model-invocation provenance, never inferred. */
+export function hasCallLevelProvenance(record) {
+    return record.usageGranularity === "call" || record.usageGranularity === "invocation";
+}
+/** A positive priced observation from which a dollar counterfactual can be modeled. */
+export function hasPricedEvidence(record) {
+    return (typeof record.amountUsd === "number" &&
+        record.amountUsd > 0 &&
+        record.costConfidence !== "missing");
+}
+/**
+ * Recognize the bundled demo records written by releases that predate the
+ * persisted `mode` field. The marker is deliberately narrow: every record
+ * must come from the shipped sample CSV and use a sample source identifier.
+ * This lets newer clients recover the demo boundary without guessing that an
+ * arbitrary unlabeled state is real local or connected evidence.
+ */
+export function isBundledSampleUsage(records) {
+    return records.length > 0 && records.every((record) => record.source.observedFrom === "sample_csv" &&
+        /(?:^|-)sample$/i.test(record.source.id));
+}
+/**
+ * Stable financial cohort for period-over-period comparisons. Missing shape
+ * provenance returns `undefined`; unknown rows must not be pooled into a fake
+ * comparable series.
+ */
+export function spendComparisonKey(record) {
+    if (!record.providerCostType || !record.usageGranularity) {
+        return undefined;
+    }
+    return [
+        record.source.id,
+        record.source.provider,
+        record.providerCostType,
+        record.usageGranularity
+    ].map((part) => encodeURIComponent(part)).join("|");
+}
 export const attributionCandidateSchema = z.object({
     entityType: z.enum(["client", "project", "agent", "user", "workspace", "api_key"]),
     entityId: z.string().min(1),
@@ -69,6 +152,7 @@ export const spendBreakdownEntrySchema = z.object({
 export const spendAnomalySchema = z.object({
     kind: z.enum(["day_over_day_spike", "week_over_week_spike"]),
     key: z.string().min(1),
+    comparisonKey: z.string().min(1).optional(),
     previousAmountUsd: z.number().nonnegative(),
     currentAmountUsd: z.number().nonnegative(),
     multiplier: z.number().nonnegative(),

package/dist/toolInvocations.d.ts

@@ -23,6 +23,20 @@ export type ToolInvocationCount = {
     name: string;
     count: number;
 };
+export type HostInvocationEvidence = {
+    sessions: number;
+    totalAssistantTurns: number;
+    sessionTurnCounts: number[];
+    invokedMcpTools: string[];
+    invokedSkills: string[];
+    invokedSubagents: string[];
+    invokedCommands: string[];
+};
+export type NestedSessionMetadata = {
+    sessionId?: string;
+    isSubagent: boolean;
+    parentSessionId?: string;
+};
 export type SessionContextSignal = {
     agent: "claude-code" | "codex";
     sessionId?: string;
@@ -38,6 +52,8 @@ export type SessionContextSignal = {
     /** Whether this transcript is a Claude sidechain/subagent transcript. */
     isSubagent: boolean;
     parentSessionId?: string;
+    /** Embedded/fork-history metadata, kept separate from this file's root identity. */
+    nestedSessions?: NestedSessionMetadata[];
     /**
      * Coverage is intentionally narrow. Shell commands are not parsed as file
      * reads because doing so would turn arbitrary command text into a heuristic.
@@ -55,7 +71,7 @@ export type InvocationSummary = {
     invokedSubagents: string[];
     /** distinct slash-command names invoked, if detectable; else [] */
     invokedCommands: string[];
-    /** number of transcript files parsed (≈ sessions) */
+    /** transcript files with at least one assistant turn in the selected window */
     sessions: number;
     /** total assistant turns across all sessions (post-dedupe) */
     totalAssistantTurns: number;
@@ -66,9 +82,24 @@ export type InvocationSummary = {
         claudeCode: number;
         codex: number;
     };
+    /** Host-isolated coverage and matchable invocation evidence. */
+    byHost?: {
+        "claude-code": HostInvocationEvidence;
+        codex: HostInvocationEvidence;
+    };
     /** Per-transcript compaction/read evidence used by Context Health. */
     sessionSignals?: SessionContextSignal[];
 };
+/** Privacy-safe per-file result; it never contains prompt text or local paths. */
+export type ParsedInvocationFile = {
+    invocations: ToolInvocationCount[];
+    invokedMcpTools: string[];
+    invokedSkills: string[];
+    invokedSubagents: string[];
+    invokedCommands: string[];
+    assistantTurns: number;
+    contextSignal: SessionContextSignal;
+};
 export type ToolInvocationOptions = {
     /** default: join(homedir(), ".claude", "projects") */
     claudeProjectsDir?: string;
@@ -76,26 +107,24 @@ export type ToolInvocationOptions = {
     codexSessionsDir?: string;
     /** optional: only count turns at/after this time */
     sinceIso?: string;
+    /**
+     * Fresh Codex summaries collected while usage parsed the same files. Supplying
+     * these skips a second rollout read/JSON parse in the same command. The
+     * summaries contain counts and basenames only, never raw transcript text.
+     */
+    codexInvocationFiles?: ParsedInvocationFile[];
 };
 /** Parse ONE transcript's content. Exported for tests. Returns the per-file pieces the aggregator needs. */
-export declare function parseClaudeCodeInvocations(content: string, sinceMs?: number): {
-    invocations: ToolInvocationCount[];
-    invokedMcpTools: string[];
-    invokedSkills: string[];
-    invokedSubagents: string[];
-    invokedCommands: string[];
-    assistantTurns: number;
-    contextSignal: SessionContextSignal;
-};
+export declare function parseClaudeCodeInvocations(content: string, sinceMs?: number): ParsedInvocationFile;
 /** Parse ONE Codex rollout's tool/skill/subagent invocations. */
-export declare function parseCodexInvocations(content: string, sinceMs?: number): {
-    invocations: ToolInvocationCount[];
-    invokedMcpTools: string[];
-    invokedSkills: string[];
-    invokedSubagents: string[];
-    invokedCommands: string[];
-    assistantTurns: number;
-    contextSignal: SessionContextSignal;
+export declare function parseCodexInvocations(content: string, sinceMs?: number): ParsedInvocationFile;
+/**
+ * Stateful Codex invocation parser used to share localAgentLogs' JSONL pass.
+ * One collector is created per rollout file and discarded after `finish()`.
+ */
+export declare function createCodexInvocationCollector(sinceMs?: number): {
+    consume: (entry: Record<string, unknown>) => void;
+    finish: () => ParsedInvocationFile;
 };
 /** Scan this machine's Claude Code + Codex transcripts and aggregate invocations. */
 export declare function loadToolInvocations(options?: ToolInvocationOptions): Promise<InvocationSummary>;