@agent-finops/core 0.5.8 → 0.5.9

package/dist/insights.js

@@ -1,4 +1,4 @@
-import { spendInsightSchema } from "./schema.js";
+import { hasCallLevelProvenance, hasPricedEvidence, spendComparisonKey, spendInsightSchema } from "./schema.js";
 const confidenceRank = {
     verified: 0,
     estimated: 1,
@@ -25,24 +25,32 @@ export function generateSpendInsights(records, summary) {
 }
 function spikeInsights(records, summary) {
     return summary.anomalies.map((anomaly) => {
-        const currentRecords = records.filter((record) => record.timestamp.slice(0, 10) === anomaly.key);
+        const currentRecords = records.filter((record) => record.timestamp.slice(0, 10) === anomaly.key &&
+            (anomaly.comparisonKey === undefined || spendComparisonKey(record) === anomaly.comparisonKey));
         const topAgent = topBreakdown(currentRecords, (record) => record.agentId);
         const topClient = topBreakdown(currentRecords, (record) => record.clientId);
         const topProject = topBreakdown(currentRecords, (record) => record.projectId);
         const topModels = breakdown(currentRecords, (record) => record.model).slice(0, 2).map((entry) => entry.key);
         const deltaUsd = roundMoney(anomaly.currentAmountUsd - anomaly.previousAmountUsd);
-        const likelyDriver = topAgent?.key ?? topProject?.key ?? topClient?.key ?? "unmapped usage";
+        const likelyOwner = topAgent?.key ?? topProject?.key ?? topClient?.key ?? "an unassigned owner";
+        const cohortSuffix = stableSuffix(anomaly.comparisonKey ?? "legacy");
+        const isProviderBilledCost = currentRecords.length > 0 && currentRecords.every((record) => record.usageGranularity === "billing_bucket" &&
+            record.costConfidence === "verified");
+        const isAggregateCohort = currentRecords.some((record) => !hasCallLevelProvenance(record));
+        const evidenceLabel = isProviderBilledCost ? "Spend" : "Cost/value evidence";
+        const evidenceBasis = uniqueStrings(currentRecords.map((record) => `${record.source.provider} · ${record.providerCostType ?? "unclassified"} · ${record.usageGranularity ?? "unclassified"}`)).join(", ");
         return {
-            id: `spike-${anomaly.key}`,
+            id: `spike-${anomaly.key}-${cohortSuffix}`,
             kind: "spike_explanation",
             severity: deltaUsd >= 25 || anomaly.multiplier >= 3 ? "critical" : "high",
-            title: `Spend spike on ${anomaly.key} needs owner review`,
-            summary: `${anomaly.key} spend rose ${formatMultiplier(anomaly.multiplier)} day over day, from ${formatUsd(anomaly.previousAmountUsd)} to ${formatUsd(anomaly.currentAmountUsd)}. The likely driver is ${likelyDriver}, so this needs owner review before the pattern repeats.`,
+            title: `${evidenceLabel} spike on ${anomaly.key} needs owner review`,
+            summary: `${anomaly.key} ${evidenceLabel.toLowerCase()} in one comparable provider cohort rose ${formatMultiplier(anomaly.multiplier)} day over day, from ${formatUsd(anomaly.previousAmountUsd)} to ${formatUsd(anomaly.currentAmountUsd)}. ${likelyOwner} is the best available ownership lead; ${isAggregateCohort ? "this aggregate bucket does not identify causal runs" : "this cohort change does not by itself prove a cause"}.`,
             evidence: compactEvidence([
-                { label: "Previous day spend", value: formatUsd(anomaly.previousAmountUsd) },
-                { label: "Current day spend", value: formatUsd(anomaly.currentAmountUsd) },
-                { label: "Increase", value: formatUsd(deltaUsd), detail: `${formatMultiplier(anomaly.multiplier)} day-over-day multiplier` },
-                topAgent ? { label: "Likely driver", value: topAgent.key, detail: `${formatUsd(topAgent.amountUsd)} across ${topAgent.recordCount} records` } : undefined,
+                evidenceBasis ? { label: "Comparison basis", value: evidenceBasis } : undefined,
+                { label: `Previous cohort ${isProviderBilledCost ? "spend" : "value"}`, value: formatUsd(anomaly.previousAmountUsd) },
+                { label: `Current cohort ${isProviderBilledCost ? "spend" : "value"}`, value: formatUsd(anomaly.currentAmountUsd) },
+                { label: `${evidenceLabel} increase`, value: formatUsd(deltaUsd), detail: `${formatMultiplier(anomaly.multiplier)} day-over-day multiplier` },
+                topAgent ? { label: "Ownership lead", value: topAgent.key, detail: `${formatUsd(topAgent.amountUsd)} across ${topAgent.recordCount} cohort records` } : undefined,
                 topClient ? { label: "Client concentration", value: topClient.key, detail: `${formatUsd(topClient.amountUsd)} on spike day` } : undefined,
                 topModels.length > 0 ? { label: "Dominant models", value: topModels.join(", ") } : undefined
             ]),
@@ -52,8 +60,10 @@ function spikeInsights(records, summary) {
             affectedModels: keysFrom(currentRecords, (record) => record.model),
             estimatedImpactUsd: deltaUsd,
             confidence: anomaly.confidence,
-            recommendedAction: `Review the ${likelyDriver} runs from ${anomaly.key}, set a temporary warning threshold for this owner, and pause expansion until the largest calls have an expected budget range.`,
-            verificationNeeded: "Verify the spike against the provider billing export before treating the dollar amount as finance-grade."
+            recommendedAction: `Review and reconcile the provider-cohort records from ${anomaly.key}, confirm the accountable owner, and obtain run-level evidence before diagnosing behavior or changing a policy.`,
+            verificationNeeded: isAggregateCohort
+                ? "Verify both periods against the same provider report shape; aggregate buckets do not identify causal calls or savings."
+                : "Verify both periods use the same call-level schema and inspect the underlying workloads before attributing cause or savings."
         };
     });
 }
@@ -69,31 +79,33 @@ function agentCostDriverInsights(records, summary) {
     }
     const topOperation = topBreakdown(agentRecords, (record) => record.operation);
     const topModel = topBreakdown(agentRecords, (record) => record.model);
-    const estimatedImpactUsd = roundMoney(topAgent.amountUsd * 0.15);
+    const hasRunLevelEvidence = agentRecords.length > 0 && agentRecords.every(hasCallLevelProvenance);
     return [{
-            id: `agent-cost-driver-${topAgent.key}`,
-            kind: "agent_runaway",
-            severity: share >= 0.5 ? "high" : "medium",
-            title: `${topAgent.key} is the dominant autonomous spend driver`,
-            summary: `${topAgent.key} accounts for ${formatPercent(share)} of tracked spend. That is the agent to cap first because one runaway workflow can consume budget before invoice review.`,
+            id: `agent-spend-concentration-${topAgent.key}`,
+            kind: "optimization_opportunity",
+            severity: "medium",
+            title: `${topAgent.key} spend concentration needs owner and budget review`,
+            summary: `${topAgent.key} is attached to ${formatPercent(share)} of tracked spend. Concentration alone does not prove abnormal behavior or an avoidable dollar amount${hasRunLevelEvidence ? "." : "; the evidence is aggregate rather than run-level."}`,
             evidence: compactEvidence([
-                { label: "Agent spend", value: formatUsd(topAgent.amountUsd), detail: `${topAgent.recordCount} records` },
+                { label: "Attributed spend", value: formatUsd(topAgent.amountUsd), detail: `${topAgent.recordCount} ${hasRunLevelEvidence ? "call-level" : "aggregate"} record${topAgent.recordCount === 1 ? "" : "s"}` },
                 { label: "Share of tracked spend", value: formatPercent(share) },
-                topModel ? { label: "Dominant model", value: topModel.key, detail: `${formatUsd(topModel.amountUsd)} inside this agent` } : undefined,
-                topOperation ? { label: "Dominant operation", value: topOperation.key, detail: `${formatUsd(topOperation.amountUsd)} inside this agent` } : undefined
+                topModel ? { label: "Dominant model or billing label", value: topModel.key, detail: `${formatUsd(topModel.amountUsd)} in this concentration` } : undefined,
+                topOperation ? { label: "Operation label", value: topOperation.key, detail: hasRunLevelEvidence ? "Call-level attribution" : "Not verified as one call or run" } : undefined
             ]),
             affectedClients: keysFrom(agentRecords, (record) => record.clientId),
             affectedProjects: keysFrom(agentRecords, (record) => record.projectId),
             affectedAgents: [topAgent.key],
             affectedModels: keysFrom(agentRecords, (record) => record.model),
-            estimatedImpactUsd,
+            estimatedImpactUsd: 0,
             confidence: topAgent.confidence,
-            recommendedAction: `Set a local warning threshold and hard cap for ${topAgent.key}, then require approval when a run exceeds its expected spend range.`,
-            verificationNeeded: "Confirm whether this agent has an approved budget owner and expected daily range."
+            recommendedAction: `Confirm who owns ${topAgent.key}, reconcile the spend to its approved budget, and collect behavioral evidence before setting a cap or savings target.`,
+            verificationNeeded: "Confirm the budget owner and expected range; concentration alone is not behavioral evidence."
         }];
 }
 function contextBloatInsights(records) {
-    const highInputRecords = records.filter((record) => record.inputTokens >= 100_000);
+    const highInputRecords = records.filter((record) => hasCallLevelProvenance(record) &&
+        hasPricedEvidence(record) &&
+        record.inputTokens >= 100_000);
     if (highInputRecords.length === 0) {
         return [];
     }
@@ -111,8 +123,8 @@ function contextBloatInsights(records) {
             id: `context-bloat-${slug(operationLabel)}`,
             kind: "context_bloat",
             severity: scopedSpend >= 60 ? "high" : "medium",
-            title: `${operationLabel} is carrying oversized context`,
-            summary: `${operationLabel} includes ${scopedRecords.length} high-input calls and ${formatNumber(totalInputTokens)} input tokens. This is a strong signal that retrieval or prompt context can be trimmed without changing the product surface.`,
+            title: `${operationLabel} needs context inspection`,
+            summary: `${operationLabel} includes ${scopedRecords.length} high-input calls and ${formatNumber(totalInputTokens)} input tokens. This proves context exposure, not that any particular context is removable or that quality will hold after a cut.`,
             evidence: [
                 { label: "High-input calls", value: String(scopedRecords.length), detail: "Calls at or above 100,000 input tokens" },
                 { label: "Input tokens", value: formatNumber(totalInputTokens) },
@@ -123,10 +135,10 @@ function contextBloatInsights(records) {
             affectedProjects: keysFrom(scopedRecords, (record) => record.projectId),
             affectedAgents: keysFrom(scopedRecords, (record) => record.agentId),
             affectedModels: keysFrom(scopedRecords, (record) => record.model),
-            estimatedImpactUsd: roundMoney(scopedSpend * 0.18),
+            estimatedImpactUsd: 0,
             confidence: combinedConfidence(scopedRecords.map((record) => record.costConfidence)),
-            recommendedAction: `Sample the largest ${operationLabel} prompts, cap retrieved chunks, and require justification before agents include full documents or long histories.`,
-            verificationNeeded: "Inspect representative prompts locally to confirm whether the large context is necessary for output quality."
+            recommendedAction: `Inspect representative ${operationLabel} prompts locally and run a matched before/after with the same acceptance criteria before proposing one reversible context change.`,
+            verificationNeeded: "Measure token and quality deltas on matched calls; no savings counterfactual is present yet."
         }];
 }
 function topBreakdown(records, select) {
@@ -150,6 +162,9 @@ function breakdown(records, select) {
 function keysFrom(records, select) {
     return Array.from(new Set(records.map(select).filter((value) => value !== undefined)));
 }
+function uniqueStrings(values) {
+    return [...new Set(values)].sort();
+}
 function compactEvidence(items) {
     return items.filter((item) => item !== undefined);
 }
@@ -177,6 +192,14 @@ function formatNumber(value) {
 function slug(value) {
     return value.toLowerCase().replace(/[^a-z0-9_]+/g, "-").replace(/^-|-$/g, "") || "unknown";
 }
+function stableSuffix(value) {
+    let hash = 2_166_136_261;
+    for (let index = 0; index < value.length; index += 1) {
+        hash ^= value.charCodeAt(index);
+        hash = Math.imul(hash, 16_777_619);
+    }
+    return (hash >>> 0).toString(36);
+}
 function roundMoney(value) {
     return Math.round(value * 100) / 100;
 }

package/dist/localAgentLogs.d.ts

@@ -1,5 +1,6 @@
 import { type TokenUsage } from "./modelPricing.js";
 import type { UsageRecord } from "./schema.js";
+import { type ParsedInvocationFile } from "./toolInvocations.js";
 /**
  * Local agent-session log ingestion: turns the transcript files that coding
  * agents already write on this machine into UsageRecords, priced at
@@ -25,6 +26,21 @@ export type LocalAgentCall = {
     startedAt?: string;
     /** Project attribution derived from the session's working directory. */
     project?: string;
+    /**
+     * Internal absolute working directory observed in the local transcript.
+     * Renderers must not expose it; adapters use it only to scope local inventory
+     * reads to the same repository as the active session.
+     */
+    workingDirectory?: string;
+    /**
+     * Numeric-only usage for the latest observed model turn. Codex reports this
+     * separately from cumulative `total_token_usage`; Claude assistant-message
+     * usage is already turn-scoped. Context Health uses this field so a long
+     * session lifetime is never compared with a short session's final turn.
+     */
+    latestTurnUsage?: LocalAgentTurnUsage;
+    /** Whether `usage` is one model turn or the session's cumulative financial total. */
+    usageScope?: "turn" | "session_cumulative";
     usage: TokenUsage;
     sessionId?: string;
     /** Provider-reported plan windows embedded in the transcript, when present. */
@@ -35,6 +51,21 @@ export type LocalAgentCall = {
      */
     activity?: LocalAgentActivity;
 };
+/**
+ * Resolve the repository root most recently observed in transcript metadata.
+ *
+ * CLI, MCP, and Glance use this only to scope read-only project inventory when
+ * the caller did not explicitly choose a path. Absolute working directories
+ * never enter rendered output.
+ */
+export declare function latestObservedWorkingDirectory(calls: readonly LocalAgentCall[]): string | undefined;
+export type LocalAgentTurnUsage = TokenUsage & {
+    /** Input-side context observed for this turn, including cached/write tokens. */
+    contextTokens: number;
+    /** Context plus output tokens for this turn. */
+    totalTokens: number;
+    source: "assistant_message_usage" | "transcript_last_token_usage" | "call_usage";
+};
 export type LocalAgentActivity = {
     summary: string;
     kind: "task" | "automation" | "agent" | "file" | "project";
@@ -67,6 +98,8 @@ export type LocalAgentLogOptions = {
     codexSessionsDir?: string;
     /** Only include calls at/after this ISO timestamp. */
     sinceIso?: string;
+    /** Collect privacy-safe Codex invocation summaries during the same JSON pass. */
+    collectCodexInvocationEvidence?: boolean;
 };
 export type LocalAgentLogResult = {
     records: UsageRecord[];
@@ -75,11 +108,20 @@ export type LocalAgentLogResult = {
     filesParsed: number;
     /** Which agents actually had data on this machine. */
     agentsDetected: Array<LocalAgentCall["agent"]>;
+    /** Present only when requested; contains counts/basenames, never raw text. */
+    codexInvocationFiles?: ParsedInvocationFile[];
 };
+/**
+ * Codex rollout/compaction files can repeat the same session's cumulative
+ * token counter. Keep only the latest snapshot per session so financial value,
+ * Glance, and project totals never add cumulative checkpoints together.
+ * Turn-scoped Claude calls and calls without a stable session id are retained.
+ */
+export declare function dedupeCumulativeSessionCalls(calls: LocalAgentCall[]): LocalAgentCall[];
 /** Parse one Claude Code transcript (JSONL). Exported for tests. */
-export declare function parseClaudeCodeTranscript(content: string, filePath?: string): LocalAgentCall[];
+export declare function parseClaudeCodeTranscript(content: string, filePath?: string, sinceMs?: number): LocalAgentCall[];
 /** Parse one Codex rollout file (JSONL event stream). Exported for tests. */
-export declare function parseCodexRollout(content: string): LocalAgentCall[];
+export declare function parseCodexRollout(content: string, onEntry?: (entry: Record<string, unknown>) => void): LocalAgentCall[];
 /** Scan this machine's agent logs and return aggregated UsageRecords. */
 export declare function loadLocalAgentUsage(options?: LocalAgentLogOptions): Promise<LocalAgentLogResult>;
 /** Aggregate per-call usage into one UsageRecord per day+agent+model+project. */