@agent-finops/core 0.5.9 → 0.6.0

package/README.md

@@ -14,6 +14,12 @@ invoice reconciliation, or ROI.
 
 Local API-equivalent estimates, subscription context, and official
 provider-reported cost are separate concepts and must not be added together.
+Reader/connector validation (`live_verified`, `fixture_verified`, `untested`,
+or `failed`) is also separate from each number's financial evidence
+(`verified`, `estimated`, `detected_unverified`, or `missing`). A live-tested
+local reader still emits estimates or missing cost—not billed spend.
+Source-boundary approval is a third, permission-only field: approving a folder
+for read-only scanning never verifies any financial number inside it.
 
 MIT licensed. See the repository
 [README](https://github.com/futurastudio/ai-spend-agent#readme) and

package/dist/discovery.d.ts

@@ -2,6 +2,7 @@ export type UsageSignalKind = "dependency" | "config" | "environment" | "source_
 export type UsageSignal = {
     provider: string;
     kind: UsageSignalKind;
+    /** Deterministic opaque reference; never a repository-controlled filename. */
     filePath: string;
     /** Stable rule identity; present on scanner-produced signals. */
     ruleId?: string;
@@ -12,6 +13,7 @@ export type UsageSignal = {
     confidence: number;
 };
 export type UsageSignalEvidence = {
+    /** Same deterministic opaque reference as UsageSignal.filePath. */
     file: string;
     provider: string;
     signal: UsageSignalKind;
@@ -20,12 +22,14 @@ export type UsageSignalEvidence = {
 export type LocalDiscoveryResult = {
     rootPath: string;
     scannedFiles: number;
+    /** Deterministic opaque references for denied/heavy descendant directories. */
     skippedDirectories: string[];
-    /** Symbolic links found below the approved root. They are never followed. */
+    /** Opaque references for symbolic links below the approved root. They are never followed. */
     skippedSymlinks: string[];
-    /** Paths that could not be read (permissions, vanished entries, non-UTF8) — skipped, never fatal. */
+    /** Opaque references for unreadable descendants — skipped, never fatal. */
     unreadablePaths: string[];
     signals: UsageSignal[];
+    /** Deterministic opaque references for detected secret assignments. */
     secretsDetected: string[];
     redactedEvidence: string[];
 };

package/dist/discovery.js

@@ -1,5 +1,6 @@
 import { lstat, readdir, readFile } from "node:fs/promises";
-import { basename, join, relative } from "node:path";
+import { createHash } from "node:crypto";
+import { basename, join, relative, sep } from "node:path";
 import { resolveSafeScanRoot } from "./scanGuard.js";
 const skippedDirectoryNames = new Set([
     ".git",
@@ -93,13 +94,15 @@ export async function scanLocalUsageSignals(rootPath) {
             return;
         }
         const redacted = redactSecrets(raw);
-        const relativePath = relative(canonicalRoot, path) || basename(path);
+        const relativePath = relative(canonicalRoot, path) || ".";
+        const pathReference = opaquePathReference(relativePath);
         result.scannedFiles += 1;
         for (const name of detectSecretNames(raw)) {
-            secrets.add(name);
-            result.redactedEvidence.push(`${relativePath}: ${name}=[REDACTED]`);
+            const secretReference = opaqueSecretReference(name);
+            secrets.add(secretReference);
+            result.redactedEvidence.push(`${pathReference}: ${secretReference}=[REDACTED]`);
         }
-        for (const signal of detectExportSignals(relativePath, redacted)) {
+        for (const signal of detectExportSignals(relativePath, redacted, pathReference)) {
             result.signals.push(signal);
         }
         for (const rule of providerRules) {
@@ -108,11 +111,11 @@ export async function scanLocalUsageSignals(rootPath) {
                 continue;
             }
             const kind = inferKind(path, rule.kind);
-            const evidenceMeta = buildEvidence(relativePath, rule.provider, kind, rule.id);
+            const evidenceMeta = buildEvidence(pathReference, rule.provider, kind, rule.id);
             result.signals.push({
                 provider: rule.provider,
                 kind,
-                filePath: relativePath,
+                filePath: pathReference,
                 ruleId: rule.id,
                 evidenceMeta,
                 evidence: encodeEvidence(evidenceMeta),
@@ -120,12 +123,14 @@ export async function scanLocalUsageSignals(rootPath) {
             });
         }
     }, skipped, symlinks, unreadable);
-    result.skippedDirectories = Array.from(skipped).sort();
+    result.skippedDirectories = Array.from(skipped)
+        .map((path) => opaquePathReference(relative(canonicalRoot, path) || "."))
+        .sort();
     result.skippedSymlinks = Array.from(symlinks)
-        .map((path) => relative(canonicalRoot, path) || basename(path))
+        .map((path) => opaquePathReference(relative(canonicalRoot, path) || "."))
         .sort();
     result.unreadablePaths = Array.from(unreadable)
-        .map((path) => relative(canonicalRoot, path) || basename(path))
+        .map((path) => opaquePathReference(relative(canonicalRoot, path) || "."))
         .sort();
     result.secretsDetected = Array.from(secrets).sort();
     result.signals = dedupeSignals(result.signals).sort((left, right) => {
@@ -169,7 +174,7 @@ async function walk(rootPath, visit, skipped, symlinks, unreadable) {
         }
         if (entry.isDirectory()) {
             if (skippedDirectoryNames.has(entry.name)) {
-                skipped.add(entry.name);
+                skipped.add(path);
                 continue;
             }
             await walk(path, visit, skipped, symlinks, unreadable);
@@ -203,7 +208,7 @@ function inferKind(path, fallback) {
     }
     return fallback;
 }
-function detectExportSignals(filePath, redacted) {
+function detectExportSignals(filePath, redacted, pathReference) {
     const lowerPath = filePath.toLowerCase();
     const lowerText = redacted.toLowerCase();
     const providers = ["openai", "anthropic", "cursor", "helicone", "langfuse", "gemini", "google", "replit"];
@@ -219,11 +224,11 @@ function detectExportSignals(filePath, redacted) {
     const normalizedProvider = provider === "google" ? "gemini" : provider;
     const kind = isInvoice ? "invoice" : "provider_export";
     const ruleId = `export.${normalizedProvider}.${kind}`;
-    const evidenceMeta = buildEvidence(filePath, normalizedProvider, kind, ruleId);
+    const evidenceMeta = buildEvidence(pathReference, normalizedProvider, kind, ruleId);
     return [{
             provider: normalizedProvider,
             kind,
-            filePath,
+            filePath: pathReference,
             ruleId,
             evidenceMeta,
             evidence: encodeEvidence(evidenceMeta),
@@ -236,6 +241,23 @@ function buildEvidence(file, provider, signal, ruleId) {
 function encodeEvidence(evidence) {
     return JSON.stringify(evidence);
 }
+/**
+ * Repository-controlled descendant names are untrusted metadata. Discovery may
+ * use the real relative path internally for classification, but persisted and
+ * agent-facing output receives only this stable, non-semantic reference.
+ */
+function opaquePathReference(relativePath) {
+    // Normalize only the current platform's separator. A literal backslash is
+    // a valid POSIX filename character and must not alias a nested POSIX path.
+    const normalized = (relativePath || ".").split(sep).join("/");
+    const digest = createHash("sha256").update(normalized, "utf8").digest("hex").slice(0, 16);
+    return `path-${digest}`;
+}
+/** Repository-controlled environment names are untrusted metadata too. */
+function opaqueSecretReference(name) {
+    const digest = createHash("sha256").update(name, "utf8").digest("hex").slice(0, 16);
+    return `secret-${digest}`;
+}
 function dedupeSignals(signals) {
     const byKey = new Map();
     for (const signal of signals) {

package/dist/glance.d.ts

@@ -11,8 +11,12 @@ export type GlanceSession = {
     durationMinutes: number;
     apiEquivalentUsd: number | null;
     costConfidence: "estimated" | "missing";
-    inputTokens: number;
-    outputTokens: number;
+    /** Null when the transcript reports only a total and no priceable breakdown. */
+    inputTokens: number | null;
+    /** Null when the transcript reports only a total and no priceable breakdown. */
+    outputTokens: number | null;
+    /** Provider-reported total retained without inventing input/output components. */
+    reportedTotalTokens?: number;
 };
 export type GlanceLimit = {
     agent: LocalAgentCall["agent"];

package/dist/glance.js

@@ -193,6 +193,10 @@ function groupSessions(calls) {
         const last = ordered[ordered.length - 1];
         const costs = ordered.map(callCost);
         const costComplete = costs.every((cost) => typeof cost === "number");
+        const tokenComponentsComplete = ordered.every((call) => call.usageSupport !== "unsupported_token_shape");
+        const reportedTotalTokens = tokenComponentsComplete
+            ? undefined
+            : sessionReportedTotalTokens(ordered);
         const startedAt = ordered
             .map((call) => call.startedAt ?? call.timestamp)
             .sort()[0];
@@ -205,16 +209,13 @@ function groupSessions(calls) {
             startedAt,
             lastActivityAt: last.timestamp,
             apiEquivalentUsd: costComplete ? costs.reduce((total, cost) => total + cost, 0) : null,
-            inputTokens: sum(ordered, (call) => (call.usage.inputTokens +
-                (call.usage.cacheReadTokens ?? 0) +
-                (call.usage.cacheWrite5mTokens ?? 0) +
-                (call.usage.cacheWrite1hTokens ?? 0))),
-            outputTokens: sum(ordered, (call) => call.usage.outputTokens),
-            totalTokens: sum(ordered, (call) => (call.usage.inputTokens +
-                call.usage.outputTokens +
-                (call.usage.cacheReadTokens ?? 0) +
-                (call.usage.cacheWrite5mTokens ?? 0) +
-                (call.usage.cacheWrite1hTokens ?? 0))),
+            inputTokens: tokenComponentsComplete
+                ? sum(ordered, inputSideTokens)
+                : null,
+            outputTokens: tokenComponentsComplete
+                ? sum(ordered, (call) => call.usage.outputTokens)
+                : null,
+            ...(reportedTotalTokens !== undefined ? { reportedTotalTokens } : {}),
             activity: ordered
                 .slice()
                 .reverse()
@@ -237,7 +238,10 @@ function toGlanceSession(session, now, activeWithinMinutes) {
         apiEquivalentUsd: roundUsd(session.apiEquivalentUsd),
         costConfidence: session.apiEquivalentUsd === null ? "missing" : "estimated",
         inputTokens: session.inputTokens,
-        outputTokens: session.outputTokens
+        outputTokens: session.outputTokens,
+        ...(session.reportedTotalTokens !== undefined
+            ? { reportedTotalTokens: session.reportedTotalTokens }
+            : {})
     };
 }
 function latestLimits(calls, now) {
@@ -516,8 +520,11 @@ function buildPrimaryAction(input) {
         : input.limits.length > 0
             ? "No transcript-reported plan window is currently projected to exhaust before reset."
             : "Not available; no plan window was reported in the local transcript.";
+    const reportedTotalEvidence = input.currentSession?.reportedTotalTokens === undefined
+        ? ""
+        : `; provider-reported total tokens=${input.currentSession.reportedTotalTokens.toLocaleString("en-US")}; input/output breakdown unavailable`;
     const sessionEvidence = input.currentSession
-        ? `${input.currentSession.agent}; model=${input.currentSession.model}; status=${input.currentSession.status}; API-equivalent value=${input.currentSession.apiEquivalentUsd === null ? "unpriced" : `$${input.currentSession.apiEquivalentUsd.toFixed(2)}`} (${input.currentSession.costConfidence}, not billed spend)`
+        ? `${input.currentSession.agent}; model=${input.currentSession.model}; status=${input.currentSession.status}; API-equivalent value=${formatGlanceUsd(input.currentSession.apiEquivalentUsd)} (${input.currentSession.costConfidence}, not billed spend)${reportedTotalEvidence}`
         : "not available";
     const promptLines = [
         "Use this aibill Glance evidence to prepare a bounded session handoff.",
@@ -603,8 +610,37 @@ function limitActionName(limit) {
             : limit.name;
 }
 function callCost(call) {
+    if (call.usageSupport === "unsupported_token_shape")
+        return undefined;
     return estimateTokenCostUsd(call.model, call.usage);
 }
+function inputSideTokens(call) {
+    return call.usage.inputTokens +
+        (call.usage.cacheReadTokens ?? 0) +
+        (call.usage.cacheWrite5mTokens ?? 0) +
+        (call.usage.cacheWrite1hTokens ?? 0);
+}
+/**
+ * Preserve a provider-reported total when a session contains a total-only
+ * snapshot. Complete calls can be added from their real components; an
+ * unsupported call without a trustworthy total makes the aggregate unknown.
+ */
+function sessionReportedTotalTokens(calls) {
+    let total = 0;
+    for (const call of calls) {
+        if (call.usageSupport === "unsupported_token_shape") {
+            if (typeof call.reportedTotalTokens !== "number" ||
+                !Number.isFinite(call.reportedTotalTokens) ||
+                call.reportedTotalTokens < 0) {
+                return undefined;
+            }
+            total += call.reportedTotalTokens;
+            continue;
+        }
+        total += inputSideTokens(call) + call.usage.outputTokens;
+    }
+    return total;
+}
 function uniqueAgents(calls) {
     return [...new Set(calls.map((call) => call.agent))].sort();
 }
@@ -612,7 +648,20 @@ function sum(calls, pick) {
     return calls.reduce((total, call) => total + pick(call), 0);
 }
 function roundUsd(value) {
-    return value === null ? null : Math.round(value * 100) / 100;
+    if (value === null)
+        return null;
+    if (value > 0 && value < 0.01) {
+        const precise = Math.round(value * 1_000_000) / 1_000_000;
+        return precise === 0 ? value : precise;
+    }
+    return Math.round(value * 100) / 100;
+}
+function formatGlanceUsd(value) {
+    if (value === null)
+        return "unpriced";
+    if (value > 0 && value < 0.01)
+        return "<$0.01";
+    return `$${value.toFixed(2)}`;
 }
 function roundPercent(value) {
     return Math.round(value * 10) / 10;

package/dist/index.d.ts

@@ -17,5 +17,7 @@ export * from "./sampleData.js";
 export * from "./scanGuard.js";
 export * from "./schema.js";
 export * from "./sourceRegistry.js";
+export * from "./sourceStatus.js";
+export * from "./stateTrust.js";
 export * from "./providerConnectors.js";
 //# sourceMappingURL=index.d.ts.map

package/dist/index.js

@@ -17,5 +17,7 @@ export * from "./sampleData.js";
 export * from "./scanGuard.js";
 export * from "./schema.js";
 export * from "./sourceRegistry.js";
+export * from "./sourceStatus.js";
+export * from "./stateTrust.js";
 export * from "./providerConnectors.js";
 //# sourceMappingURL=index.js.map

package/dist/localAgentLogs.d.ts

@@ -41,6 +41,14 @@ export type LocalAgentCall = {
     latestTurnUsage?: LocalAgentTurnUsage;
     /** Whether `usage` is one model turn or the session's cumulative financial total. */
     usageScope?: "turn" | "session_cumulative";
+    /**
+     * Whether the transcript exposed the input/output components required for
+     * pricing. A total-only snapshot is still usage evidence, but pricing it as
+     * zero would be false precision.
+     */
+    usageSupport?: "complete" | "unsupported_token_shape";
+    /** Provider-reported total retained when component fields are unavailable. */
+    reportedTotalTokens?: number;
     usage: TokenUsage;
     sessionId?: string;
     /** Provider-reported plan windows embedded in the transcript, when present. */
@@ -101,6 +109,24 @@ export type LocalAgentLogOptions = {
     /** Collect privacy-safe Codex invocation summaries during the same JSON pass. */
     collectCodexInvocationEvidence?: boolean;
 };
+export type LocalAgentLogDiagnosticCode = "directory_missing" | "directory_unreadable" | "file_unreadable" | "malformed_jsonl" | "unsupported_token_shape";
+export type LocalAgentLogDiagnostic = {
+    agent: LocalAgentCall["agent"];
+    code: LocalAgentLogDiagnosticCode;
+    severity: "info" | "warning" | "error";
+    /** Privacy-safe summary; absolute local paths and transcript text are omitted. */
+    message: string;
+    count: number;
+};
+export type LocalAgentSourceScan = {
+    agent: LocalAgentCall["agent"];
+    directoryStatus: "readable" | "missing" | "unreadable";
+    filesDiscovered: number;
+    filesParsed: number;
+    malformedLines: number;
+    unreadableFiles: number;
+    unsupportedUsageSnapshots: number;
+};
 export type LocalAgentLogResult = {
     records: UsageRecord[];
     /** Per-call entries before aggregation (for drill-down/debugging). */
@@ -108,9 +134,18 @@ export type LocalAgentLogResult = {
     filesParsed: number;
     /** Which agents actually had data on this machine. */
     agentsDetected: Array<LocalAgentCall["agent"]>;
+    /** Per-source scan outcome, including honest empty and unsupported states. */
+    sourceScans: LocalAgentSourceScan[];
+    /** Structured, privacy-safe failures/warnings encountered during the scan. */
+    diagnostics: LocalAgentLogDiagnostic[];
     /** Present only when requested; contains counts/basenames, never raw text. */
     codexInvocationFiles?: ParsedInvocationFile[];
 };
+type TranscriptParseDiagnostic = {
+    code: "malformed_jsonl" | "unsupported_token_shape";
+    count: number;
+};
+type TranscriptParseDiagnosticHandler = (diagnostic: TranscriptParseDiagnostic) => void;
 /**
  * Codex rollout/compaction files can repeat the same session's cumulative
  * token counter. Keep only the latest snapshot per session so financial value,
@@ -119,9 +154,9 @@ export type LocalAgentLogResult = {
  */
 export declare function dedupeCumulativeSessionCalls(calls: LocalAgentCall[]): LocalAgentCall[];
 /** Parse one Claude Code transcript (JSONL). Exported for tests. */
-export declare function parseClaudeCodeTranscript(content: string, filePath?: string, sinceMs?: number): LocalAgentCall[];
+export declare function parseClaudeCodeTranscript(content: string, filePath?: string, sinceMs?: number, onDiagnostic?: TranscriptParseDiagnosticHandler): LocalAgentCall[];
 /** Parse one Codex rollout file (JSONL event stream). Exported for tests. */
-export declare function parseCodexRollout(content: string, onEntry?: (entry: Record<string, unknown>) => void): LocalAgentCall[];
+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>;
 /** Aggregate per-call usage into one UsageRecord per day+agent+model+project. */
@@ -132,4 +167,5 @@ export declare function aggregateCalls(calls: LocalAgentCall[]): UsageRecord[];
  * This intentionally favors dropping a suspicious token over displaying it.
  */
 export declare function sanitizeLocalActivityText(value: string): string;
+export {};
 //# sourceMappingURL=localAgentLogs.d.ts.map