@agent-finops/core 0.9.8 → 0.9.10

package/dist/localAgentLogs.js

@@ -1351,6 +1351,8 @@ export async function loadLocalAgentFinancialUsageWithFormats(registry, options
     const home = homedir();
     const since = options.sinceIso ? Date.parse(options.sinceIso) : undefined;
     const sinceMs = typeof since === "number" && Number.isFinite(since) ? since : undefined;
+    const until = options.workspaceDailyFacts && options.untilIso ? Date.parse(options.untilIso) : undefined;
+    const untilMs = typeof until === "number" && Number.isFinite(until) ? until : undefined;
     const scanned = await Promise.all(registry.map(async (runtime) => {
         const { descriptor } = runtime;
         const diagnostics = [];
@@ -1422,7 +1424,7 @@ export async function loadLocalAgentFinancialUsageWithFormats(registry, options
             const diagnosticsBefore = diagnostics.length;
             const unreadableBefore = scan.unreadableFiles;
             const filesParsedBefore = scan.filesParsed;
-            const context = { filePath: file, sinceMs, scan, diagnostics };
+            const context = { filePath: file, sinceMs, untilMs, scan, diagnostics };
             const parsedCalls = options.workspaceDailyFacts && descriptor.id === "codex"
                 ? await readCodexDailyFinancialFile(context)
                 : options.workspaceDailyFacts && descriptor.id === "claude-code"
@@ -1453,8 +1455,12 @@ export async function loadLocalAgentFinancialUsageWithFormats(registry, options
     }));
     // Sources scan concurrently, but flatten in registry order to preserve the
     // long-standing Claude-then-Codex output and diagnostic contract.
+    const inWorkspaceWindow = (call) => {
+        const timestamp = Date.parse(call.timestamp);
+        return (sinceMs === undefined || timestamp >= sinceMs) && (untilMs === undefined || timestamp < untilMs);
+    };
     const calls = scanned.flatMap((entry) => entry.calls);
-    const normalizedCalls = dedupeCumulativeSessionCalls(calls, (agent) => {
+    const normalizedCalls = dedupeCumulativeSessionCalls(options.workspaceDailyFacts ? calls.filter(inWorkspaceWindow) : calls, (agent) => {
         const source = scanned.find((entry) => entry.scan.agent === agent);
         if (source) {
             recordParseDiagnostic(agent, source.scan, source.diagnostics, {
@@ -1463,9 +1469,7 @@ export async function loadLocalAgentFinancialUsageWithFormats(registry, options
             });
         }
     });
-    const filtered = typeof sinceMs === "number"
-        ? normalizedCalls.filter((call) => Date.parse(call.timestamp) >= sinceMs)
-        : normalizedCalls;
+    const filtered = normalizedCalls.filter(inWorkspaceWindow);
     return {
         records: aggregateCallsForFormats(filtered, registry.map((entry) => entry.descriptor)),
         calls: filtered,
@@ -1610,7 +1614,7 @@ function codexHeaderAttribution(header) {
 }
 /** @internal Runtime hook owned by the Claude Code registry entry. */
 export async function readClaudeCodeFinancialFileForRegistry(context, workspaceDailyFacts = false) {
-    const { filePath, sinceMs, scan, diagnostics } = context;
+    const { filePath, sinceMs, untilMs, scan, diagnostics } = context;
     if (!await shouldStreamFile(filePath, sinceMs, "claude-code", scan, diagnostics)) {
         return [];
     }
@@ -1620,11 +1624,21 @@ export async function readClaudeCodeFinancialFileForRegistry(context, workspaceD
     let streamed;
     try {
         streamed = await streamJsonlRecords(filePath, (entry) => {
+            if (workspaceDailyFacts && entry.type === "assistant" && isRecord(entry.message)
+                && isRecord(entry.message.usage) && stringOf(entry.message.model) !== "<synthetic>"
+                && !toIso(stringOf(entry.timestamp))) {
+                fileDiagnostics.push({ code: "unsupported_token_shape", count: 1, workspaceReason: "missing_identity" });
+                return;
+            }
+            const timestamp = toIso(stringOf(entry.timestamp));
+            if (workspaceDailyFacts && timestamp && untilMs !== undefined && Date.parse(timestamp) >= untilMs)
+                return;
+            const entryDiagnostics = [];
             const call = parseClaudeFinancialEntry(entry, filePath, 
-            // Window-blind on purpose: cached values must contain the complete
-            // file so a narrow-window run can never truncate a wider one. The
-            // loader's final timestamp filter performs all narrowing.
-            undefined, seen, (diagnostic) => fileDiagnostics.push(diagnostic));
+            // Workspace mode disables the cumulative cache, so dated historical
+            // events outside its window must not contribute diagnostics. Ordinary
+            // financial cache parses remain window-blind.
+            workspaceDailyFacts ? sinceMs : undefined, seen, (diagnostic) => entryDiagnostics.push(diagnostic));
             if (call) {
                 if (workspaceDailyFacts) {
                     const nativeAgent = stringOf(entry.agentId);
@@ -1635,7 +1649,12 @@ export async function readClaudeCodeFinancialFileForRegistry(context, workspaceD
                 }
                 calls.push(call);
             }
-        });
+            for (const diagnostic of entryDiagnostics) {
+                fileDiagnostics.push(workspaceDailyFacts && call?.sessionId && timestamp
+                    && call.usageSupport === "unsupported_token_shape" && diagnostic.code === "unsupported_token_shape"
+                    ? { ...diagnostic, workspaceFactCoverage: "unknown_tokens" } : diagnostic);
+            }
+        }, workspaceDailyFacts);
     }
     catch (error) {
         recordUnreadableFile("claude-code", scan, diagnostics, error);
@@ -1697,13 +1716,42 @@ export async function readCodexFinancialFileForRegistry(context) {
     });
     return call ? [call] : [];
 }
+/** Privacy-safe explanation only. This never changes whether a counter is supported. */
+function workspaceCounterFailureReason(current, baseline) {
+    const input = tokenComponentOf(current.input_tokens), output = tokenComponentOf(current.output_tokens);
+    const cached = optionalTokenComponent(current, "cached_input_tokens");
+    const total = optionalTokenComponent(current, "total_tokens");
+    if (input === undefined || output === undefined || cached.present && cached.value === undefined
+        || total.present && total.value === undefined)
+        return "missing_or_invalid_components";
+    if ((cached.value ?? 0) > input)
+        return "cache_exceeds_input";
+    if (total.value !== undefined && total.value < input + output)
+        return "total_below_components";
+    if ((total.value ?? 0) > 0 && input === 0 && output === 0)
+        return "positive_total_without_components";
+    if (baseline) {
+        if (!parseCodexCumulativeUsage(baseline).supported)
+            return "invalid_baseline";
+        const priorInput = tokenComponentOf(baseline.input_tokens);
+        const priorOutput = tokenComponentOf(baseline.output_tokens);
+        const priorCached = optionalTokenComponent(baseline, "cached_input_tokens").value ?? 0;
+        const priorTotal = optionalTokenComponent(baseline, "total_tokens").value;
+        if (input < priorInput || output < priorOutput || (cached.value ?? 0) < priorCached
+            || input - (cached.value ?? 0) < priorInput - priorCached
+            || total.value !== undefined && priorTotal !== undefined && total.value < priorTotal)
+            return "counter_decreased";
+    }
+    return "unsupported_components";
+}
 /** Workspace-only event deltas. The existing snapshot reader remains cumulative. */
 async function readCodexDailyFinancialFile(context) {
-    const { filePath, sinceMs, scan, diagnostics } = context;
+    const { filePath, sinceMs, untilMs, scan, diagnostics } = context;
     if (!await shouldStreamFile(filePath, sinceMs, "codex", scan, diagnostics))
         return [];
     const state = createCodexFinancialStreamState(), calls = [];
-    const report = () => recordParseDiagnostic("codex", scan, diagnostics, { code: "unsupported_token_shape", count: 1 });
+    const report = (workspaceReason, markerBacked = false) => recordParseDiagnostic("codex", scan, diagnostics, { code: "unsupported_token_shape", count: 1, workspaceReason,
+        ...(markerBacked ? { workspaceFactCoverage: "unknown_tokens" } : {}) });
     let priorEventAt;
     try {
         const streamed = await streamJsonlRecords(filePath, entry => {
@@ -1713,18 +1761,21 @@ async function readCodexDailyFinancialFile(context) {
             if (entry.type !== "event_msg" || payload?.type !== "token_count"
                 || state.hasInheritedHistory && !state.rootTaskStarted)
                 return;
+            const timestamp = toIso(stringOf(entry.timestamp));
+            const inWindow = !timestamp || (sinceMs === undefined || Date.parse(timestamp) >= sinceMs)
+                && (untilMs === undefined || Date.parse(timestamp) < untilMs);
             const info = isRecord(payload.info) ? payload.info : undefined;
             const total = info && isRecord(info.total_token_usage) ? info.total_token_usage : undefined;
             if (!total) {
                 // A usage-bearing event without its cumulative endpoint cannot be
                 // placed safely: a later counter may span this event's UTC day.
-                if (info && isRecord(info.last_token_usage))
-                    report();
+                if (inWindow && info && isRecord(info.last_token_usage))
+                    report("missing_endpoint");
                 return;
             }
-            const timestamp = toIso(stringOf(entry.timestamp));
             if (!timestamp || !state.sessionId) {
-                report();
+                if (inWindow)
+                    report("missing_identity");
                 return;
             }
             const parsed = parseCodexCumulativeUsage(total, previousTotal);
@@ -1740,8 +1791,6 @@ async function readCodexDailyFinancialFile(context) {
             if (supported && previousTotal && parsed.usage.inputTokens === 0 && parsed.usage.outputTokens === 0
                 && (parsed.usage.cacheReadTokens ?? 0) === 0 && (parsed.reportedTotalTokens ?? 0) === 0)
                 return;
-            if (!supported)
-                report();
             const workingDirectory = absoluteWorkingDirectory(state.rootCwd);
             // The cumulative endpoint fingerprint is stable across copies of a
             // rollout. Different deltas for that same endpoint become a conflict in
@@ -1756,7 +1805,10 @@ async function readCodexDailyFinancialFile(context) {
                 usage: parsed.usage,
                 ...(supported && parsed.tokenComponentEvidence ? { tokenComponentEvidence: parsed.tokenComponentEvidence } : {}),
                 ...(parsed.reportedTotalTokens !== undefined ? { reportedTotalTokens: parsed.reportedTotalTokens } : {}) });
-        });
+            if (inWindow && !supported)
+                report(!chronological ? "nonchronological" : !firstDayKnown ? "first_day_unknown"
+                    : !cachedShapeStable ? "cache_shape" : workspaceCounterFailureReason(total, previousTotal), chronological);
+        }, true);
         if (streamed.hadContent)
             scan.filesParsed++;
         if (streamed.malformedLines)
@@ -2840,14 +2892,93 @@ function financialSourceScan(descriptor) {
     scan.jsonlValidationCoverage = "complete";
     return scan;
 }
-async function streamJsonlRecords(file, onRecord) {
+/** Re-encode literal control characters inside JSON strings without changing their value.
+ * Ordinary readers stay strict; this compatibility path is reserved for Workspace facts. */
+function parseWorkspaceJsonRecord(text) {
+    try {
+        return { value: JSON.parse(text) };
+    }
+    catch { /* Try a lossless string encoding repair. */ }
+    let quoted = false, escaped = false, normalized = "";
+    for (const character of text) {
+        if (quoted && character.charCodeAt(0) < 32) {
+            // An existing escape before a raw control character has no unambiguous
+            // JSON interpretation. Do not guess its intended value.
+            if (escaped)
+                return undefined;
+            normalized += `\\u${character.charCodeAt(0).toString(16).padStart(4, "0")}`;
+            continue;
+        }
+        normalized += character;
+        if (escaped) {
+            escaped = false;
+            continue;
+        }
+        if (quoted && character === "\\") {
+            escaped = true;
+            continue;
+        }
+        if (character === '"')
+            quoted = !quoted;
+    }
+    try {
+        return { value: JSON.parse(normalized) };
+    }
+    catch {
+        return undefined;
+    }
+}
+async function streamJsonlRecords(file, onRecord, workspaceCompatibility = false) {
     const input = createReadStream(file, { encoding: "utf8" });
     const lines = createInterface({ input, crlfDelay: Infinity });
     let hadContent = false;
     let malformedLines = 0;
+    let pending = [], pendingBytes = 0;
+    const accept = (value) => { if (isRecord(value))
+        onRecord(value); };
     try {
         for await (const line of lines) {
             hadContent = true;
+            if (workspaceCompatibility) {
+                if (!pending.length && !line.trim())
+                    continue;
+                if (pending.length) {
+                    pendingBytes += Buffer.byteLength(line, "utf8") + 1;
+                    if (pending.length < 256 && pendingBytes <= 32 * 1024 * 1024) {
+                        const combined = parseWorkspaceJsonRecord([...pending, line].join("\n"));
+                        if (combined) {
+                            accept(combined.value);
+                            pending = [];
+                            pendingBytes = 0;
+                            continue;
+                        }
+                    }
+                    // A complete following record is a boundary. Never let a damaged
+                    // preceding record swallow otherwise readable financial evidence.
+                    const standalone = parseWorkspaceJsonRecord(line);
+                    if (standalone) {
+                        malformedLines += pending.length;
+                        pending = [];
+                        pendingBytes = 0;
+                        accept(standalone.value);
+                        continue;
+                    }
+                    if (pending.length >= 256 || pendingBytes > 32 * 1024 * 1024) {
+                        malformedLines += pending.length;
+                        pending = [];
+                        pendingBytes = 0;
+                    }
+                }
+                const parsed = parseWorkspaceJsonRecord(line);
+                if (parsed) {
+                    accept(parsed.value);
+                    continue;
+                }
+                pending.push(line);
+                if (pending.length === 1)
+                    pendingBytes = Buffer.byteLength(line, "utf8");
+                continue;
+            }
             if (!line.trim())
                 continue;
             let entry;
@@ -2858,12 +2989,9 @@ async function streamJsonlRecords(file, onRecord) {
                 malformedLines += 1;
                 continue;
             }
-            // Parsed event type is checked before any deeper traversal. This keeps
-            // qualitative payloads out of the fast path while still validating
-            // every JSONL line and reporting malformed coverage honestly.
-            if (isRecord(entry))
-                onRecord(entry);
+            accept(entry);
         }
+        malformedLines += pending.length;
     }
     finally {
         lines.close();
@@ -3639,6 +3767,8 @@ function recordParseDiagnostic(agent, scan, diagnostics, diagnostic) {
         agent,
         code: diagnostic.code,
         severity: "warning",
+        ...(diagnostic.workspaceReason ? { workspaceReason: diagnostic.workspaceReason } : {}),
+        ...(diagnostic.workspaceFactCoverage ? { workspaceFactCoverage: diagnostic.workspaceFactCoverage } : {}),
         message: `${diagnostic.count} ${agentLabel(agent)} token snapshot(s) lacked the complete, internally consistent fields required for safe normalization and pricing.`,
         count: diagnostic.count
     });

package/dist/projectIndexStore.d.ts

@@ -150,9 +150,9 @@ declare const documentSchema: z.ZodObject<{
                     tool: z.ZodOptional<z.ZodNumber>;
                     total: z.ZodOptional<z.ZodNumber>;
                     cacheAccounting: z.ZodEnum<{
-                        unknown: "unknown";
                         included: "included";
                         none: "none";
+                        unknown: "unknown";
                     }>;
                 }, z.core.$strict>>;
                 usage: z.ZodObject<{
@@ -189,8 +189,8 @@ declare const documentSchema: z.ZodObject<{
                 activity: z.ZodOptional<z.ZodObject<{
                     summary: z.ZodString;
                     kind: z.ZodEnum<{
-                        project: "project";
                         agent: "agent";
+                        project: "project";
                         file: "file";
                         task: "task";
                         automation: "automation";
@@ -369,9 +369,9 @@ declare const documentSchema: z.ZodObject<{
                     tool: z.ZodOptional<z.ZodNumber>;
                     total: z.ZodOptional<z.ZodNumber>;
                     cacheAccounting: z.ZodEnum<{
-                        unknown: "unknown";
                         included: "included";
                         none: "none";
+                        unknown: "unknown";
                     }>;
                 }, z.core.$strict>>;
                 usage: z.ZodObject<{
@@ -408,8 +408,8 @@ declare const documentSchema: z.ZodObject<{
                 activity: z.ZodOptional<z.ZodObject<{
                     summary: z.ZodString;
                     kind: z.ZodEnum<{
-                        project: "project";
                         agent: "agent";
+                        project: "project";
                         file: "file";
                         task: "task";
                         automation: "automation";

package/dist/qualitativeIndexCache.d.ts

@@ -121,9 +121,9 @@ declare const valueSchema: z.ZodObject<{
             tool: z.ZodOptional<z.ZodNumber>;
             total: z.ZodOptional<z.ZodNumber>;
             cacheAccounting: z.ZodEnum<{
-                unknown: "unknown";
                 included: "included";
                 none: "none";
+                unknown: "unknown";
             }>;
         }, z.core.$strict>>;
         usage: z.ZodObject<{
@@ -160,8 +160,8 @@ declare const valueSchema: z.ZodObject<{
         activity: z.ZodOptional<z.ZodObject<{
             summary: z.ZodString;
             kind: z.ZodEnum<{
-                project: "project";
                 agent: "agent";
+                project: "project";
                 file: "file";
                 task: "task";
                 automation: "automation";
@@ -347,9 +347,9 @@ export declare const qualitativeEntryValueSchema: z.ZodObject<{
             tool: z.ZodOptional<z.ZodNumber>;
             total: z.ZodOptional<z.ZodNumber>;
             cacheAccounting: z.ZodEnum<{
-                unknown: "unknown";
                 included: "included";
                 none: "none";
+                unknown: "unknown";
             }>;
         }, z.core.$strict>>;
         usage: z.ZodObject<{
@@ -386,8 +386,8 @@ export declare const qualitativeEntryValueSchema: z.ZodObject<{
         activity: z.ZodOptional<z.ZodObject<{
             summary: z.ZodString;
             kind: z.ZodEnum<{
-                project: "project";
                 agent: "agent";
+                project: "project";
                 file: "file";
                 task: "task";
                 automation: "automation";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agent-finops/core",
-  "version": "0.9.8",
+  "version": "0.9.10",
   "funding": "https://asktilden.com",
   "type": "module",
   "main": "./dist/index.js",