@agent-finops/core 0.5.8 → 0.5.9

package/dist/localAgentLogs.js

@@ -3,15 +3,64 @@ import { basename, isAbsolute, join, resolve, sep } from "node:path";
 import { homedir } from "node:os";
 import { estimateTokenCostUsd } from "./modelPricing.js";
 import { redactSecrets } from "./discovery.js";
+import { createCodexInvocationCollector } from "./toolInvocations.js";
+/**
+ * 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 function latestObservedWorkingDirectory(calls) {
+    return calls
+        .filter((call) => call.workingDirectory)
+        .sort((left, right) => right.timestamp.localeCompare(left.timestamp))[0]
+        ?.workingDirectory;
+}
+/**
+ * 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 function dedupeCumulativeSessionCalls(calls) {
+    const retained = [];
+    const cumulative = new Map();
+    for (const call of calls) {
+        if (call.usageScope !== "session_cumulative" || !call.sessionId) {
+            retained.push(call);
+            continue;
+        }
+        const key = `${call.agent}:${call.sessionId}`;
+        const prior = cumulative.get(key);
+        if (!prior || isLaterCumulativeSnapshot(call, prior)) {
+            cumulative.set(key, call);
+        }
+    }
+    return [...retained, ...cumulative.values()];
+}
+function isLaterCumulativeSnapshot(candidate, prior) {
+    const timestampOrder = candidate.timestamp.localeCompare(prior.timestamp);
+    if (timestampOrder !== 0)
+        return timestampOrder > 0;
+    return totalUsageTokens(candidate.usage) > totalUsageTokens(prior.usage);
+}
+function totalUsageTokens(usage) {
+    return usage.inputTokens +
+        usage.outputTokens +
+        (usage.cacheReadTokens ?? 0) +
+        (usage.cacheWrite5mTokens ?? 0) +
+        (usage.cacheWrite1hTokens ?? 0);
+}
 /** Parse one Claude Code transcript (JSONL). Exported for tests. */
-export function parseClaudeCodeTranscript(content, filePath = "") {
+export function parseClaudeCodeTranscript(content, filePath = "", sinceMs) {
     const calls = [];
     const seen = new Set();
-    const prompts = [];
-    const fileCounts = new Map();
+    const pendingPrompts = [];
+    const activityEvidence = new Map();
     let title;
     let lastPrompt;
-    let toolCallCount = 0;
+    let latestActivityKey;
     let isSubagent = filePath.split(sep).includes("subagents");
     let parentSessionId;
     for (const line of content.split("\n")) {
@@ -39,15 +88,7 @@ export function parseClaudeCodeTranscript(content, filePath = "") {
         if (entry.type === "user" && message) {
             for (const prompt of textValues(message.content)) {
                 if (isHumanPrompt(prompt))
-                    prompts.push(prompt);
-            }
-        }
-        if (entry.type === "assistant" && message) {
-            for (const item of recordValues(message.content)) {
-                if (item.type !== "tool_use")
-                    continue;
-                toolCallCount += 1;
-                collectToolFiles(item.input, fileCounts);
+                    pendingPrompts.push(prompt);
             }
         }
         if (entry.type !== "assistant")
@@ -63,51 +104,97 @@ export function parseClaudeCodeTranscript(content, filePath = "") {
         if (dedupeKey !== ":" && seen.has(dedupeKey))
             continue;
         seen.add(dedupeKey);
+        const timestamp = toIso(stringOf(entry.timestamp)) ?? new Date(0).toISOString();
+        if (typeof sinceMs === "number" && Date.parse(timestamp) < sinceMs) {
+            // These prompts led to a call outside the selected evidence window. Do
+            // not let them become the focus of a later in-window project/call.
+            pendingPrompts.length = 0;
+            continue;
+        }
         const cacheCreation = isRecord(usage.cache_creation) ? usage.cache_creation : undefined;
         const write5m = numberOf(cacheCreation?.ephemeral_5m_input_tokens);
         const write1h = numberOf(cacheCreation?.ephemeral_1h_input_tokens);
         const writeTotal = numberOf(usage.cache_creation_input_tokens) ?? 0;
-        calls.push({
+        const parsedUsage = {
+            inputTokens: numberOf(usage.input_tokens) ?? 0,
+            outputTokens: numberOf(usage.output_tokens) ?? 0,
+            cacheReadTokens: numberOf(usage.cache_read_input_tokens) ?? 0,
+            // Prefer the 5m/1h breakdown; fall back to the total as 5m (cheaper bound).
+            cacheWrite5mTokens: write5m ?? writeTotal,
+            cacheWrite1hTokens: write1h ?? 0
+        };
+        const workingDirectory = absoluteWorkingDirectory(stringOf(entry.cwd));
+        const project = projectFromCwd(workingDirectory) ?? projectFromTranscriptPath(filePath);
+        const sessionId = stringOf(entry.sessionId);
+        const call = {
             agent: "claude-code",
             model: stringOf(message.model) ?? "claude-code",
-            timestamp: toIso(stringOf(entry.timestamp)) ?? new Date(0).toISOString(),
-            project: projectFromCwd(stringOf(entry.cwd)) ?? projectFromTranscriptPath(filePath),
-            sessionId: stringOf(entry.sessionId),
-            usage: {
-                inputTokens: numberOf(usage.input_tokens) ?? 0,
-                outputTokens: numberOf(usage.output_tokens) ?? 0,
-                cacheReadTokens: numberOf(usage.cache_read_input_tokens) ?? 0,
-                // Prefer the 5m/1h breakdown; fall back to the total as 5m (cheaper bound).
-                cacheWrite5mTokens: write5m ?? writeTotal,
-                cacheWrite1hTokens: write1h ?? 0
-            }
-        });
+            timestamp,
+            project,
+            workingDirectory,
+            sessionId,
+            latestTurnUsage: toTurnUsage(parsedUsage, "assistant_message_usage"),
+            usageScope: "turn",
+            usage: parsedUsage
+        };
+        calls.push(call);
+        const activityKey = localActivityScopeKey(sessionId, workingDirectory, project);
+        const evidence = activityEvidence.get(activityKey) ?? {
+            prompts: [],
+            files: new Map(),
+            toolCallCount: 0
+        };
+        evidence.prompts.push(...pendingPrompts);
+        pendingPrompts.length = 0;
+        for (const item of recordValues(message.content)) {
+            if (item.type !== "tool_use")
+                continue;
+            evidence.toolCallCount += 1;
+            collectToolFiles(item.input, evidence.files);
+        }
+        activityEvidence.set(activityKey, evidence);
+        latestActivityKey = activityKey;
     }
     const fallbackPrompt = lastPrompt && isHumanPrompt(lastPrompt) ? lastPrompt : undefined;
-    const activity = buildLocalAgentActivity({
-        title,
-        prompts: prompts.length > 0 ? prompts : fallbackPrompt ? [fallbackPrompt] : [],
-        files: fileCounts,
-        toolCallCount,
-        project: calls[0]?.project ?? projectFromTranscriptPath(filePath),
-        isSubagent,
-        parentSessionId
-    });
-    if (activity) {
-        for (const call of calls)
-            call.activity = activity;
+    const activities = new Map();
+    for (const [activityKey, evidence] of activityEvidence) {
+        const matchingCall = calls.find((call) => (localActivityScopeKey(call.sessionId, call.workingDirectory, call.project) === activityKey));
+        const isLatest = activityKey === latestActivityKey;
+        const activity = buildLocalAgentActivity({
+            title: isLatest ? title : undefined,
+            prompts: evidence.prompts.length > 0
+                ? evidence.prompts
+                : isLatest && fallbackPrompt
+                    ? [fallbackPrompt]
+                    : [],
+            files: evidence.files,
+            toolCallCount: evidence.toolCallCount,
+            project: matchingCall?.project ?? projectFromTranscriptPath(filePath),
+            isSubagent,
+            parentSessionId
+        });
+        if (activity)
+            activities.set(activityKey, activity);
+    }
+    for (const call of calls) {
+        call.activity = activities.get(localActivityScopeKey(call.sessionId, call.workingDirectory, call.project));
     }
     return calls;
 }
 /** Parse one Codex rollout file (JSONL event stream). Exported for tests. */
-export function parseCodexRollout(content) {
+export function parseCodexRollout(content, onEntry) {
     let model;
-    let cwd;
+    let rootCwd;
     const toolWorkdirs = new Map();
     let sessionId;
+    let rootSessionMetaSeen = false;
     let startedAt;
+    let rootStartedAtMs;
+    let rootTaskStarted = false;
+    let inheritedUsageBaseline;
     let lastActivityAt;
     let lastTotal;
+    let lastTurn;
     let lastRateLimits;
     const prompts = [];
     const fileCounts = new Map();
@@ -126,17 +213,45 @@ export function parseCodexRollout(content) {
         }
         if (!isRecord(entry))
             continue;
+        onEntry?.(entry);
         const payload = isRecord(entry.payload) ? entry.payload : undefined;
-        if (entry.type === "session_meta" && payload) {
-            sessionId = stringOf(payload.id) ?? sessionId;
-            cwd = stringOf(payload.cwd) ?? cwd;
-            startedAt = toIso(stringOf(payload.timestamp) ?? stringOf(entry.timestamp)) ?? startedAt;
+        if (entry.type === "session_meta" && payload && !rootSessionMetaSeen) {
+            // A forked/subagent rollout can embed the parent transcript, including
+            // many later session_meta records. The first metadata record belongs to
+            // this rollout file; later records are nested/history evidence and must
+            // never replace the financial session identity or root cwd.
+            rootSessionMetaSeen = true;
+            sessionId = stringOf(payload.id);
+            rootCwd = stringOf(payload.cwd);
+            startedAt = toIso(stringOf(payload.timestamp) ?? stringOf(entry.timestamp));
+            rootStartedAtMs = timestampMilliseconds(payload.timestamp ?? entry.timestamp);
             isSubagent = stringOf(payload.thread_source) === "subagent" || isRecord(payload.source) && "subagent" in payload.source;
-            parentSessionId = stringOf(payload.parent_thread_id) ?? parentSessionId;
+            parentSessionId = stringOf(payload.parent_thread_id);
         }
         if (entry.type === "turn_context" && payload) {
             model = stringOf(payload.model) ?? model;
-            cwd = stringOf(payload.cwd) ?? cwd;
+            rootCwd ??= stringOf(payload.cwd);
+        }
+        if (isSubagent &&
+            !rootTaskStarted &&
+            payload?.type === "task_started" &&
+            isRootSpecificTaskStart(payload.started_at, rootStartedAtMs)) {
+            // Forked Codex rollouts copy the parent's complete event history after
+            // the child's root session_meta. The cumulative counter immediately
+            // before the child's first task is the inherited baseline, not child
+            // usage. Reset qualitative evidence at the same boundary so parent
+            // prompts/files cannot become the child's focus.
+            inheritedUsageBaseline = lastTotal;
+            lastTotal = undefined;
+            rootTaskStarted = true;
+            prompts.length = 0;
+            fileCounts.clear();
+            toolWorkdirs.clear();
+            toolCallCount = 0;
+            model = undefined;
+            lastTurn = undefined;
+            lastRateLimits = undefined;
+            lastActivityAt = toIso(stringOf(entry.timestamp)) ?? startedAt;
         }
         if (payload?.type === "function_call" || payload?.type === "custom_tool_call") {
             toolCallCount += 1;
@@ -165,21 +280,39 @@ export function parseCodexRollout(content) {
             const eventTimestamp = toIso(stringOf(entry.timestamp)) ?? lastActivityAt ?? startedAt;
             const info = isRecord(payload.info) ? payload.info : undefined;
             const total = info && isRecord(info.total_token_usage) ? info.total_token_usage : undefined;
+            const turn = info && isRecord(info.last_token_usage) ? info.last_token_usage : undefined;
             if (total) {
                 lastTotal = total;
                 lastActivityAt = eventTimestamp;
             }
+            if (turn) {
+                lastTurn = turn;
+                lastActivityAt = eventTimestamp;
+            }
             const rateLimits = parseCodexRateLimits(payload.rate_limits, eventTimestamp);
             if (rateLimits) {
                 lastRateLimits = rateLimits;
             }
         }
     }
-    if (!lastTotal)
+    // A fork without a recognized root-task boundary is ambiguous: older Codex
+    // formats may contain only inherited parent history. Omitting that child is
+    // safer than charging the parent cumulative counter again. Likewise, a
+    // recognized boundary with no later total_token_usage is not a financial
+    // call yet.
+    if (!lastTotal || isSubagent && !rootTaskStarted)
         return [];
-    const input = numberOf(lastTotal.input_tokens) ?? 0;
-    const cached = numberOf(lastTotal.cached_input_tokens) ?? 0;
-    const project = projectFromCwd(dominantCodexCwd(cwd, toolWorkdirs));
+    const input = Math.max(0, (numberOf(lastTotal.input_tokens) ?? 0) -
+        (numberOf(inheritedUsageBaseline?.input_tokens) ?? 0));
+    const cached = Math.max(0, (numberOf(lastTotal.cached_input_tokens) ?? 0) -
+        (numberOf(inheritedUsageBaseline?.cached_input_tokens) ?? 0));
+    const output = Math.max(0, (numberOf(lastTotal.output_tokens) ?? 0) -
+        (numberOf(inheritedUsageBaseline?.output_tokens) ?? 0));
+    const latestTurnUsage = lastTurn
+        ? codexTurnUsage(lastTurn)
+        : undefined;
+    const workingDirectory = absoluteWorkingDirectory(dominantCodexCwd(rootCwd, toolWorkdirs));
+    const project = projectFromCwd(workingDirectory);
     const activity = buildLocalAgentActivity({
         prompts,
         files: fileCounts,
@@ -194,13 +327,16 @@ export function parseCodexRollout(content) {
             timestamp: lastActivityAt ?? startedAt ?? new Date(0).toISOString(),
             startedAt,
             project,
+            workingDirectory,
             sessionId,
             rateLimits: lastRateLimits,
             activity,
+            latestTurnUsage,
+            usageScope: "session_cumulative",
             usage: {
                 // Codex input_tokens INCLUDES cached tokens; split them out.
                 inputTokens: Math.max(0, input - cached),
-                outputTokens: numberOf(lastTotal.output_tokens) ?? 0,
+                outputTokens: output,
                 cacheReadTokens: cached
             }
         }];
@@ -275,13 +411,18 @@ export async function loadLocalAgentUsage(options = {}) {
     const claudeDir = options.claudeProjectsDir ?? join(home, ".claude", "projects");
     const codexDir = options.codexSessionsDir ?? join(home, ".codex", "sessions");
     const calls = [];
+    const codexInvocationFiles = options.collectCodexInvocationEvidence
+        ? []
+        : undefined;
     let filesParsed = 0;
+    const since = options.sinceIso ? Date.parse(options.sinceIso) : undefined;
+    const sinceMs = typeof since === "number" && Number.isFinite(since) ? since : undefined;
     for (const file of await listJsonlFiles(claudeDir)) {
         const content = await readFile(file, "utf8").catch(() => "");
         if (!content)
             continue;
         filesParsed += 1;
-        calls.push(...parseClaudeCodeTranscript(content, file));
+        calls.push(...parseClaudeCodeTranscript(content, file, sinceMs));
     }
     for (const file of await listJsonlFiles(codexDir)) {
         if (!basename(file).startsWith("rollout-"))
@@ -290,23 +431,29 @@ export async function loadLocalAgentUsage(options = {}) {
         if (!content)
             continue;
         filesParsed += 1;
-        calls.push(...parseCodexRollout(content));
+        const collector = codexInvocationFiles
+            ? createCodexInvocationCollector(sinceMs)
+            : undefined;
+        calls.push(...parseCodexRollout(content, collector?.consume));
+        if (collector)
+            codexInvocationFiles.push(collector.finish());
     }
-    const since = options.sinceIso ? Date.parse(options.sinceIso) : undefined;
-    const filtered = typeof since === "number" && Number.isFinite(since)
-        ? calls.filter((call) => Date.parse(call.timestamp) >= since)
-        : calls;
+    const normalizedCalls = dedupeCumulativeSessionCalls(calls);
+    const filtered = typeof sinceMs === "number"
+        ? normalizedCalls.filter((call) => Date.parse(call.timestamp) >= sinceMs)
+        : normalizedCalls;
     return {
         records: aggregateCalls(filtered),
         calls: filtered,
         filesParsed,
-        agentsDetected: [...new Set(filtered.map((call) => call.agent))]
+        agentsDetected: [...new Set(filtered.map((call) => call.agent))],
+        ...(codexInvocationFiles ? { codexInvocationFiles } : {})
     };
 }
 /** Aggregate per-call usage into one UsageRecord per day+agent+model+project. */
 export function aggregateCalls(calls) {
     const groups = new Map();
-    for (const call of calls) {
+    for (const call of dedupeCumulativeSessionCalls(calls)) {
         const day = call.timestamp.slice(0, 10);
         const key = [day, call.agent, call.model, call.project ?? "unattributed"].join("|");
         groups.set(key, [...(groups.get(key) ?? []), call]);
@@ -344,6 +491,7 @@ export function aggregateCalls(calls) {
             projectId: project === "unattributed" || project === "(home)" ? undefined : project,
             agentId: agent,
             providerCostType: "local_agent_logs",
+            usageGranularity: "daily_aggregate",
             quantity: groupCalls.length,
             operation: `${agent} sessions`
         });
@@ -379,6 +527,9 @@ function projectFromCwd(cwd) {
     const name = basename(cwd);
     return name.length > 0 ? name : undefined;
 }
+function absoluteWorkingDirectory(cwd) {
+    return cwd && isAbsolute(cwd) ? resolve(cwd) : undefined;
+}
 /**
  * Codex can be launched from HOME and do nearly all of its work through tools
  * that declare a more specific working directory. Prefer that observed
@@ -412,12 +563,18 @@ function projectFromTranscriptPath(filePath) {
     const tail = parent.split("-").filter(Boolean).pop();
     return tail && tail.length > 0 ? tail : undefined;
 }
+function localActivityScopeKey(sessionId, workingDirectory, project) {
+    // The absolute cwd stays inside this ephemeral parser key and is never
+    // persisted or rendered. It prevents one transcript that changes projects
+    // from attaching Project A's prompt/file evidence to Project B's calls.
+    return [sessionId ?? "unknown-session", workingDirectory ?? project ?? "unattributed"].join("\u0000");
+}
 const FOCUS_STOP_WORDS = new Set([
-    "about", "after", "again", "also", "and", "are", "at", "been", "being", "but",
+    "about", "above", "after", "again", "also", "and", "are", "at", "been", "being", "but",
     "can", "check", "could", "did", "does", "doing", "dont", "every", "from",
     "for", "have", "here", "how", "in", "into", "its", "just", "like", "make", "more",
     "need", "not", "now", "on", "only", "other", "our", "please", "really", "should",
-    "something", "sure", "than", "that", "the", "their", "them", "then", "there",
+    "earlier", "is", "mentioned", "one", "something", "sure", "than", "that", "the", "their", "them", "then", "there",
     "these", "they", "thing", "think", "this", "through", "to", "too", "use", "user",
     "users", "want", "was", "way", "we", "what", "when", "where", "which", "while",
     "who", "why", "will", "with", "work", "working", "would", "you", "your",
@@ -493,12 +650,49 @@ function focusTopic(prompts) {
     if (prompts.length === 0)
         return undefined;
     const recent = prompts.slice(-12);
-    const observedTopicTokens = new Set(recent.flatMap((prompt) => (topicTokens(prompt).filter((token) => !FOCUS_STOP_WORDS.has(token)))));
+    const promptTokenSets = recent.map((prompt) => (new Set(topicTokens(prompt).filter((token) => !FOCUS_STOP_WORDS.has(token)))));
+    const observedTopicTokens = new Set(promptTokenSets.flatMap((tokens) => [...tokens]));
+    // Recognized product/work concepts are meaningful even in one prompt. Generic
+    // tokens must repeat across distinct prompts below; that keeps attachment
+    // prose and one-off screenshot filenames from becoming a confident topic.
+    if (observedTopicTokens.has("aibill") && observedTopicTokens.has("prompt")) {
+        return "aibill prompt";
+    }
+    if (observedTopicTokens.has("glance") && observedTopicTokens.has("hover")) {
+        return observedTopicTokens.has("ui") ? "Glance hover UI" : "Glance hover";
+    }
+    if (observedTopicTokens.has("glance") &&
+        ["action", "agent", "handoff", "prompt"].some((token) => observedTopicTokens.has(token))) {
+        return "Glance agent handoff";
+    }
+    if (observedTopicTokens.has("landing") && observedTopicTokens.has("page"))
+        return "landing page";
+    if (observedTopicTokens.has("hover")) {
+        return observedTopicTokens.has("ui") ? "hover UI" : "hover interaction";
+    }
+    if (observedTopicTokens.has("mcp")) {
+        return observedTopicTokens.has("feature") ? "MCP feature" : "MCP";
+    }
+    if (observedTopicTokens.has("seo")) {
+        return observedTopicTokens.has("strategy") ? "SEO strategy" : "SEO";
+    }
+    const promptOccurrences = new Map();
+    for (const tokens of promptTokenSets) {
+        for (const token of tokens) {
+            promptOccurrences.set(token, (promptOccurrences.get(token) ?? 0) + 1);
+        }
+    }
+    const repeatedTokens = new Set([...promptOccurrences.entries()]
+        .filter(([, count]) => count >= 2)
+        .map(([token]) => token));
+    if (repeatedTokens.size === 0)
+        return undefined;
     const tokenScores = new Map();
     const pairScores = new Map();
     recent.forEach((prompt, index) => {
         const weight = 1 + index / Math.max(1, recent.length - 1);
-        const tokens = topicTokens(prompt).filter((token) => !FOCUS_STOP_WORDS.has(token));
+        const tokens = topicTokens(prompt)
+            .filter((token) => !FOCUS_STOP_WORDS.has(token) && repeatedTokens.has(token));
         const unique = [...new Set(tokens)];
         for (const token of unique) {
             tokenScores.set(token, (tokenScores.get(token) ?? 0) + weight);
@@ -526,22 +720,9 @@ function focusTopic(prompts) {
     if (candidateTokens.size === 0)
         return undefined;
     const tokens = [...candidateTokens].slice(0, 3);
-    if (tokens.includes("glance") && tokens.includes("hover")) {
-        return tokens.includes("ui") ? "Glance hover UI" : "Glance hover";
-    }
-    if (observedTopicTokens.has("glance") &&
-        ["action", "agent", "handoff", "prompt"].some((token) => observedTopicTokens.has(token))) {
-        return "Glance agent handoff";
-    }
     if (tokens.includes("hover")) {
         return tokens.includes("ui") ? "hover UI" : "hover interaction";
     }
-    if (tokens.includes("landing") && tokens.includes("page"))
-        return "landing page";
-    if (tokens.includes("mcp"))
-        return tokens.includes("feature") ? "MCP feature" : "MCP";
-    if (tokens.includes("seo"))
-        return tokens.includes("strategy") ? "SEO strategy" : "SEO";
     return tokens.map(displayToken).join(" ");
 }
 function inferAction(prompts, title) {
@@ -619,9 +800,36 @@ function topicTokens(value) {
     // Absolute paths often appear in attached-image metadata and tool-oriented
     // prompts. They are machine context, not the user's work topic, and can
     // otherwise outrank meaningful words when only one recent prompt exists.
-    const withoutAbsolutePaths = value.replace(/(^|[\s("'=:])(?:file:\/\/)?\/[^\s)"']+/g, "$1");
+    const withoutAbsolutePaths = value.replace(/(^|[\s("'=:])(?:file:\/\/)?\/[^\s)"']+/g, "$1")
+        .replace(/\b[^\s/\\]+\.(?:png|jpe?g|gif|webp|heic|svg|pdf|mov|mp4)\b/gi, " ")
+        .replace(/\b(?:attached|attachment|clipboard|image|images|photo|picture|screenshot|screenshots)\b/gi, " ");
     return promptTokens(sanitizeLocalActivityText(withoutAbsolutePaths));
 }
+function codexTurnUsage(value) {
+    const rawInput = numberOf(value.input_tokens) ?? 0;
+    const cached = Math.min(rawInput, numberOf(value.cached_input_tokens) ?? 0);
+    const output = numberOf(value.output_tokens) ?? 0;
+    return {
+        inputTokens: Math.max(0, rawInput - cached),
+        outputTokens: output,
+        cacheReadTokens: cached,
+        contextTokens: rawInput,
+        totalTokens: numberOf(value.total_tokens) ?? rawInput + output,
+        source: "transcript_last_token_usage"
+    };
+}
+function toTurnUsage(usage, source) {
+    const contextTokens = usage.inputTokens +
+        (usage.cacheReadTokens ?? 0) +
+        (usage.cacheWrite5mTokens ?? 0) +
+        (usage.cacheWrite1hTokens ?? 0);
+    return {
+        ...usage,
+        contextTokens,
+        totalTokens: contextTokens + usage.outputTokens,
+        source
+    };
+}
 /**
  * Remove known and assignment-shaped credentials from metadata before it can
  * become a topic, title, Glance field, MCP result, or copy-ready handoff.
@@ -698,6 +906,26 @@ function toIso(value) {
     const parsed = Date.parse(value);
     return Number.isFinite(parsed) ? new Date(parsed).toISOString() : undefined;
 }
+const ROOT_TASK_CLOCK_TOLERANCE_MS = 5_000;
+function isRootSpecificTaskStart(value, rootStartedAtMs) {
+    const taskStartedAtMs = timestampMilliseconds(value);
+    return typeof rootStartedAtMs === "number" &&
+        typeof taskStartedAtMs === "number" &&
+        taskStartedAtMs >= rootStartedAtMs - ROOT_TASK_CLOCK_TOLERANCE_MS;
+}
+function timestampMilliseconds(value) {
+    if (typeof value === "number" && Number.isFinite(value)) {
+        return value < 1_000_000_000_000 ? value * 1_000 : value;
+    }
+    if (typeof value !== "string" || value.length === 0)
+        return undefined;
+    const numeric = Number(value);
+    if (Number.isFinite(numeric)) {
+        return numeric < 1_000_000_000_000 ? numeric * 1_000 : numeric;
+    }
+    const parsed = Date.parse(value);
+    return Number.isFinite(parsed) ? parsed : undefined;
+}
 function sum(calls, pick) {
     return calls.reduce((total, call) => total + pick(call), 0);
 }

package/dist/providerConnectors.js

@@ -35,6 +35,7 @@ export function normalizeOpenAiCostResponse(response, options) {
                 projectId,
                 apiKeyId,
                 providerCostType: "openai_cost",
+                usageGranularity: "billing_bucket",
                 quantity: typeof result.quantity === "number" ? result.quantity : undefined,
                 operation: lineItem
             });
@@ -74,6 +75,7 @@ export function normalizeOpenAiUsageResponse(response, options) {
                 userId,
                 apiKeyId,
                 providerCostType: "openai_usage_evidence",
+                usageGranularity: "usage_bucket",
                 quantity: numberValue(result.num_model_requests),
                 operation: "OpenAI completions usage evidence"
             });
@@ -121,6 +123,7 @@ export function normalizeAnthropicClaudeCodeUsageResponse(response, options) {
                 userId,
                 projectId: organizationId,
                 providerCostType: "anthropic_claude_code_usage",
+                usageGranularity: "daily_aggregate",
                 quantity: sessions,
                 operation: `Claude Code sessions: ${sessions}; LOC +${added}/-${removed}; commits ${commits}; PRs ${prs}`
             });
@@ -153,6 +156,7 @@ export function normalizeGitHubCopilotSeatResponse(response, options) {
                 userId,
                 projectId: options.accountId,
                 providerCostType: "copilot_seat_reconciliation",
+                usageGranularity: "seat",
                 quantity: 1,
                 operation: `GitHub Copilot ${plan} seat; ${lastActivity ? `last activity ${lastActivity}` : "no recent activity reported"}`
             }];
@@ -191,6 +195,7 @@ export function normalizeAnthropicCostResponse(response, options) {
                 projectId: workspaceId,
                 workspaceId,
                 providerCostType: result.cost_type ?? "anthropic_cost",
+                usageGranularity: "billing_bucket",
                 operation: description
             });
         }
@@ -222,6 +227,7 @@ export function normalizeGitHubCopilotMetricsResponse(response, options) {
                 costConfidence: "missing",
                 projectId: options.accountId,
                 providerCostType: "copilot_usage_metrics",
+                usageGranularity: "daily_aggregate",
                 operation: feature
             });
         }
@@ -239,6 +245,7 @@ export function normalizeGitHubCopilotMetricsResponse(response, options) {
                 costConfidence: "missing",
                 projectId: options.accountId,
                 providerCostType: "copilot_cli_metrics",
+                usageGranularity: "daily_aggregate",
                 operation: "CLI requests"
             });
         }
@@ -270,6 +277,7 @@ export function normalizeCursorSpendResponse(response, options) {
                 userId,
                 projectId: options.accountId,
                 providerCostType: "cursor_spend",
+                usageGranularity: "user_aggregate",
                 operation: "Cursor team spend"
             }];
     });

package/dist/sampleData.js

@@ -49,11 +49,38 @@ export function parseUsageCsv(contents) {
             userId: optionalValue(row.user_id),
             workspaceId: optionalValue(row.workspace_id),
             apiKeyId: optionalValue(row.api_key_id),
-            operation: optionalValue(row.operation)
+            providerCostType: optionalValue(row.provider_cost_type),
+            operation: optionalValue(row.operation),
+            usageGranularity: optionalValue(row.usage_granularity),
+            workloadSemantics: workloadSemantics(row)
         });
     });
 }
 function optionalValue(value) {
     return value === "" ? undefined : value;
 }
+function workloadSemantics(row) {
+    const stableInputFingerprint = optionalValue(row.stable_input_fingerprint);
+    const batchEligible = optionalBoolean(row.batch_eligible);
+    const downgradeSafe = optionalBoolean(row.downgrade_safe);
+    if (stableInputFingerprint === undefined &&
+        batchEligible === undefined &&
+        downgradeSafe === undefined) {
+        return undefined;
+    }
+    return {
+        ...(stableInputFingerprint ? { stableInputFingerprint } : {}),
+        ...(batchEligible !== undefined ? { batchEligible } : {}),
+        ...(downgradeSafe !== undefined ? { downgradeSafe } : {})
+    };
+}
+function optionalBoolean(value) {
+    if (value === undefined || value === "")
+        return undefined;
+    if (value === "true")
+        return true;
+    if (value === "false")
+        return false;
+    throw new Error(`Expected true/false CSV value, received ${JSON.stringify(value)}.`);
+}
 //# sourceMappingURL=sampleData.js.map