sidekick-shared 0.28.3 → 0.29.1

package/dist/esm/usage/usageEvents.js

@@ -11,9 +11,19 @@
  * every hit and pruned least-recently-used, once per collection.
  *
  * A Claude Code session's subagents write their own transcripts under
- * `<sessionId>/subagents/`; their usage is attributed to the parent session
- * and their sizes and mtimes join the fingerprint. (Codex spawned subagents
- * are top-level rollouts, already listed as sessions of their own.)
+ * `<sessionId>/subagents/`; their usage is attributed to the parent session,
+ * tagged with the subagent, and their sizes and mtimes join the fingerprint.
+ * (Codex spawned subagents and forks are top-level rollouts, already listed
+ * as sessions of their own; their events are tagged with the parent read
+ * from the rollout's first line.)
+ *
+ * Each event also carries the ordinal of the human prompt it answered, from
+ * the same scanner as `collectPromptHistory()`, so usage joins prompt history
+ * on `(provider, sessionId, ordinal)`.
+ *
+ * Cache files are named per cache version (`<provider>--<session>.v3.json`)
+ * so readers of different versions sharing the directory never overwrite each
+ * other's files; pruning ages out every version's files alike.
  *
  * Node-only: reads session files and the cache directory.
  *
@@ -21,7 +31,10 @@
  */
 import * as fs from 'fs';
 import * as path from 'path';
+import { codexRolloutOrigin } from '../parsers/codexRolloutOrigin';
 import { getConfigDir } from '../paths';
+import { readPromptOrdinalMarks } from '../promptHistory';
+import { readFirstLineAsync } from '../providers/codexRollouts';
 import { listSessionPreviewsAsync } from '../sessionPreviews';
 import { calculateNormalizedUsageCost, extractNormalizedUsage } from '../usageNormalization';
 import { atomicWriteJson } from '../writers/atomic';
@@ -29,9 +42,11 @@ import { resolveWorkspaceRoots } from '../workspaceRoots';
 /**
  * Bump when the cached record shape or the counting rules change; older files
  * are re-read. v2: Claude split lines and duplicate Codex `token_count` events
- * are counted once, and Claude subagent transcripts are included.
+ * are counted once, and Claude subagent transcripts are included. v3: events
+ * keep reasoning tokens, prompt ordinal, message id, and subagent, and files
+ * move to a versioned name (`<provider>--<session>.v3.json`).
  */
-export const USAGE_CACHE_VERSION = 2;
+export const USAGE_CACHE_VERSION = 3;
 /**
  * Most-recently-used cache files kept on disk. Sized for a busy month of
  * sessions (files are a few KB each); a collection larger than this still
@@ -42,9 +57,15 @@ export const MAX_USAGE_CACHE_FILES = 5000;
 export function getUsageCacheDir() {
     return path.join(getConfigDir(), 'usage-cache');
 }
+/**
+ * Cache file of one session. The name carries the cache version, so a reader
+ * of another version sharing the directory (which rejects this version, and
+ * versions before 3 use the unversioned `<provider>--<session>.json`) never
+ * overwrites it, and this version never overwrites theirs.
+ */
 function cacheFilePath(dir, provider, sessionId) {
     const safe = sessionId.replace(/[^A-Za-z0-9._-]/g, '_');
-    return path.join(dir, `${provider}--${safe}.json`);
+    return path.join(dir, `${provider}--${safe}.v${USAGE_CACHE_VERSION}.json`);
 }
 function toMs(value, label) {
     if (value === undefined)
@@ -75,7 +96,11 @@ function readCache(filePath) {
         return null;
     }
 }
-/** Deletes all but the `keep` most recently used cache files (by mtime). Best-effort. */
+/**
+ * Deletes all but the `keep` most recently used cache files (by mtime), of
+ * every cache version alike, so files no reader touches any more age out.
+ * Best-effort.
+ */
 export function pruneUsageCache(keep = MAX_USAGE_CACHE_FILES, dir = getUsageCacheDir()) {
     try {
         const entries = fs
@@ -108,7 +133,7 @@ export function pruneUsageCache(keep = MAX_USAGE_CACHE_FILES, dir = getUsageCach
         return 0;
     }
 }
-function cachedEventFromUsage(usage, timestamp, model) {
+function cachedEventFromUsage(usage, timestamp, model, messageId, agentId) {
     const record = {
         t: timestamp,
         m: model,
@@ -121,16 +146,29 @@ function cachedEventFromUsage(usage, timestamp, model) {
     };
     if (usage.reportedCostUsd !== undefined)
         record.rc = usage.reportedCostUsd;
+    if (usage.reasoningTokens > 0)
+        record.rt = usage.reasoningTokens;
+    if (messageId && !messageId.startsWith('token-count-'))
+        record.rid = messageId;
+    if (agentId)
+        record.sa = agentId;
     return record;
 }
-/** Price a cached event with the current catalog (or its provider-reported cost). */
-function priceCachedEvent(cached, provider, sessionId, project, sessionFile) {
+/**
+ * Price a cached event with the current catalog (or its provider-reported
+ * cost). Output is priced from the billable output (`bo`), which already
+ * holds reasoning however the provider reports it, so restoring the reasoning
+ * count never changes the cost.
+ */
+function priceCachedEvent(cached, provider, sessionId, project, sessionFile, sessionSubagent) {
+    const reasoningTokens = typeof cached.rt === 'number' && cached.rt > 0 ? cached.rt : 0;
     const usage = {
         uncachedInputTokens: cached.i,
         cacheReadTokens: cached.cr,
         cacheWriteTokens: cached.cw,
         outputTokens: cached.o,
-        reasoningTokens: 0,
+        reasoningTokens,
+        // `bo` is already the billable output; nothing is added to it.
         reasoningIncludedInOutput: true,
         cacheInclusiveInputTokens: cached.i + cached.cr + cached.cw,
         billableOutputTokens: cached.bo,
@@ -142,6 +180,9 @@ function priceCachedEvent(cached, provider, sessionId, project, sessionFile) {
         usage,
         modelId: cached.m === 'unknown' ? undefined : cached.m,
     });
+    const subagent = typeof cached.sa === 'string' && cached.sa
+        ? { agentId: cached.sa, parentSessionId: sessionId }
+        : sessionSubagent;
     return {
         timestamp: cached.t,
         provider,
@@ -154,13 +195,19 @@ function priceCachedEvent(cached, provider, sessionId, project, sessionFile) {
             cacheWriteTokens: cached.cw,
             cacheReadTokens: cached.cr,
             totalTokens: cached.tt,
+            ...(reasoningTokens > 0 ? { reasoningTokens } : {}),
         },
         costUsd: priced.costUsd,
         costProvenance: priced.source,
         filePath: sessionFile,
+        ...(cached.po === null || (typeof cached.po === 'number' && Number.isInteger(cached.po))
+            ? { promptOrdinal: cached.po }
+            : {}),
+        ...(typeof cached.rid === 'string' ? { requestId: cached.rid } : {}),
+        ...(subagent ? { subagent: { ...subagent } } : {}),
     };
 }
-const CLAUDE_AGENT_FILE = /^agent-.+\.jsonl$/;
+const CLAUDE_AGENT_FILE = /^agent-(.+)\.jsonl$/;
 /** Claude Code subagent transcripts of a session, sorted by name. */
 function claudeSubagentFiles(preview) {
     if (preview.provider !== 'claude-code')
@@ -180,6 +227,7 @@ function claudeSubagentFiles(preview) {
             files.push({
                 path: path.join(dir, name),
                 name,
+                agentId: CLAUDE_AGENT_FILE.exec(name)?.[1] ?? name,
                 sizeBytes: stat.size,
                 modifiedAt: stat.mtimeMs,
             });
@@ -196,7 +244,7 @@ function sessionFingerprint(preview, subagents) {
         return base;
     return `${base}|${subagents.map((f) => `${f.name}:${f.sizeBytes}:${f.modifiedAt}`).join(',')}`;
 }
-function readTranscriptUsage(provider, filePath, cached) {
+function readTranscriptUsage(provider, filePath, cached, agentId) {
     const reader = provider.createReader(filePath);
     const events = reader.readAll();
     reader.flush();
@@ -218,12 +266,14 @@ function readTranscriptUsage(provider, filePath, cached) {
             target.cr += usage.cacheReadTokens;
             target.bo += usage.billableOutputTokens;
             target.tt += usage.totalTokens;
+            if (usage.reasoningTokens > 0)
+                target.rt = (target.rt ?? 0) + usage.reasoningTokens;
             continue;
         }
         const timestamp = Date.parse(event.timestamp);
         if (!Number.isFinite(timestamp))
             continue;
-        const record = cachedEventFromUsage(usage, timestamp, event.message?.model ?? usage.model ?? 'unknown');
+        const record = cachedEventFromUsage(usage, timestamp, event.message?.model ?? usage.model ?? 'unknown', messageId, agentId);
         cached.push(record);
         if (messageId)
             byMessageId.set(messageId, record);
@@ -233,10 +283,75 @@ function readSessionUsage(provider, preview, subagents) {
     const cached = [];
     readTranscriptUsage(provider, preview.filePath, cached);
     for (const file of subagents)
-        readTranscriptUsage(provider, file.path, cached);
+        readTranscriptUsage(provider, file.path, cached, file.agentId);
     cached.sort((a, b) => a.t - b.t);
     return cached;
 }
+/**
+ * Sets each event's `po` to the highest ordinal among the prompts timestamped
+ * at or before it, or null when none is. With prompts in time order (the
+ * usual case) that is the last prompt before the event.
+ */
+function assignPromptOrdinals(events, marks) {
+    const sorted = [...marks].sort((a, b) => a.timestampMs - b.timestampMs || a.ordinal - b.ordinal);
+    const highest = [];
+    let max = -1;
+    for (const mark of sorted) {
+        max = Math.max(max, mark.ordinal);
+        highest.push(max);
+    }
+    for (const event of events) {
+        let low = 0;
+        let high = sorted.length;
+        while (low < high) {
+            const middle = (low + high) >>> 1;
+            if (sorted[middle].timestampMs <= event.t)
+                low = middle + 1;
+            else
+                high = middle;
+        }
+        event.po = low === 0 ? null : highest[low - 1];
+    }
+}
+/**
+ * Prompt ordinals for a freshly read session, from its main transcript.
+ * Returns false when the transcript could not be scanned (the events then
+ * keep no ordinal and the session is not cached, so the next run retries).
+ */
+async function addPromptOrdinals(preview, events) {
+    if (preview.provider !== 'claude-code' && preview.provider !== 'codex')
+        return true;
+    let marks;
+    try {
+        marks = await readPromptOrdinalMarks(preview.provider, preview.sessionId, preview.filePath);
+    }
+    catch {
+        return false;
+    }
+    assignPromptOrdinals(events, marks);
+    return true;
+}
+/** Parent of a Codex rollout that is a fork or a spawned subagent, from its first line only. */
+async function codexSessionSubagent(preview) {
+    if (preview.provider !== 'codex')
+        return undefined;
+    const { line } = await readFirstLineAsync(preview.filePath);
+    if (!line)
+        return undefined;
+    let first;
+    try {
+        first = JSON.parse(line);
+    }
+    catch {
+        return undefined;
+    }
+    const origin = codexRolloutOrigin(first);
+    if (!origin.parentId || (!origin.isSubagent && !origin.forkedFromId))
+        return undefined;
+    if (origin.parentId === preview.sessionId)
+        return undefined;
+    return { agentId: preview.sessionId, parentSessionId: origin.parentId };
+}
 function yieldToEventLoop() {
     return new Promise((resolve) => setImmediate(resolve));
 }
@@ -276,12 +391,14 @@ export async function collectUsageEvents(options) {
         const fingerprint = sessionFingerprint(preview, subagentFiles);
         const filePath = cacheFilePath(cacheDir, preview.provider, preview.sessionId);
         let cachedEvents = null;
+        let sessionSubagent;
         let project = preview.workspacePath;
         let fromCache = false;
         if (useCache) {
             const cached = readCache(filePath);
             if (cached && cached.fingerprint === fingerprint && cached.sessionId === preview.sessionId) {
                 cachedEvents = cached.events;
+                sessionSubagent = validSubagent(cached.subagent);
                 project = project ?? cached.project;
                 fromCache = true;
                 cacheHits += 1;
@@ -305,7 +422,10 @@ export async function collectUsageEvents(options) {
                 options.onDiagnostic?.(diagnostic);
                 continue;
             }
-            if (useCache) {
+            // Ordinals and origin are best-effort: a failure costs only the cache write.
+            const ordinalsRead = await addPromptOrdinals(preview, cachedEvents);
+            sessionSubagent = await codexSessionSubagent(preview).catch(() => undefined);
+            if (useCache && ordinalsRead) {
                 const record = {
                     version: USAGE_CACHE_VERSION,
                     provider: preview.provider,
@@ -313,6 +433,7 @@ export async function collectUsageEvents(options) {
                     fingerprint,
                     project,
                     events: cachedEvents,
+                    ...(sessionSubagent ? { subagent: sessionSubagent } : {}),
                 };
                 try {
                     await atomicWriteJson(filePath, record);
@@ -332,7 +453,7 @@ export async function collectUsageEvents(options) {
                 continue;
             if (untilMs !== null && cached.t > untilMs)
                 continue;
-            events.push(priceCachedEvent(cached, preview.provider, preview.sessionId, project, preview.filePath));
+            events.push(priceCachedEvent(cached, preview.provider, preview.sessionId, project, preview.filePath, sessionSubagent));
             first = first === null ? cached.t : Math.min(first, cached.t);
             last = last === null ? cached.t : Math.max(last, cached.t);
             count += 1;
@@ -361,6 +482,14 @@ export async function collectUsageEvents(options) {
         ...(scope ? { roots: scope.roots } : {}),
     };
 }
+function validSubagent(value) {
+    if (typeof value !== 'object' || value === null)
+        return undefined;
+    const { agentId, parentSessionId } = value;
+    return typeof agentId === 'string' && typeof parentSessionId === 'string'
+        ? { agentId, parentSessionId }
+        : undefined;
+}
 /** The roots to list, or undefined for an unscoped (or legacy single-root) call. */
 function usageScope(options) {
     if (options.workspacePaths) {

package/dist/esm/usage/usageReports.js

@@ -7,6 +7,8 @@
  */
 import { classifyCostProvenance } from '../aggregation/costProvenance';
 import { formatLocalDateKey } from '../formatting';
+import { canonicalModelId } from '../modelInfo';
+import { SYNTHETIC_MODEL } from './claudeUsageDedupe';
 function dayParts(ms, utc) {
     const date = new Date(ms);
     return utc
@@ -69,7 +71,8 @@ function addTokens(target, source) {
 }
 /**
  * Group usage events into rows. Rows are sorted by key (sessions by first
- * event), then provider, project, and model, so tables read oldest first.
+ * event), then provider, project, and model, so tables read oldest first;
+ * rows grouped by `session` within one of those follow their first event.
  */
 export function bucketUsage(events, options) {
     const groupBy = new Set(options.groupBy ?? ['provider']);
@@ -77,13 +80,21 @@ export function bucketUsage(events, options) {
     const byProvider = isSession || groupBy.has('provider');
     const byProject = isSession || groupBy.has('project');
     const byModel = groupBy.has('model');
+    const bySession = isSession || groupBy.has('session');
+    const keyModel = options.modelKey === 'canonical'
+        ? (model) => (model === SYNTHETIC_MODEL ? model : canonicalModelId(model) || model)
+        : (model) => model;
     const buckets = new Map();
     for (const event of events) {
+        if (options.excludeSynthetic && event.model === SYNTHETIC_MODEL)
+            continue;
         const key = usageBucketKey(event, options);
         const provider = byProvider ? event.provider : null;
         const project = byProject ? event.project : null;
-        const model = byModel ? event.model : null;
-        const id = [key, provider ?? '', project ?? '', model ?? ''].join('|');
+        const eventModel = keyModel(event.model);
+        const model = byModel ? eventModel : null;
+        const sessionId = bySession ? event.sessionId : null;
+        const id = JSON.stringify([key, provider, project, model, sessionId]);
         let acc = buckets.get(id);
         if (!acc) {
             acc = {
@@ -93,15 +104,17 @@ export function bucketUsage(events, options) {
                     provider,
                     project,
                     model,
-                    sessionId: isSession ? event.sessionId : null,
+                    sessionId,
                     models: [],
                     calls: 0,
                     sessions: 0,
                     tokens: emptyTokens(),
                     totalTokens: 0,
                     costUsd: 0,
+                    pricedCostUsd: null,
                     costProvenance: 'none',
                     unpricedCalls: 0,
+                    reasoningTokens: 0,
                     firstTimestamp: event.timestamp,
                     lastTimestamp: event.timestamp,
                 },
@@ -116,12 +129,14 @@ export function bucketUsage(events, options) {
         row.calls += 1;
         addTokens(row.tokens, event.tokens);
         row.totalTokens += event.tokens.totalTokens;
+        row.reasoningTokens = (row.reasoningTokens ?? 0) + reasoningOf(event.tokens.reasoningTokens);
         row.firstTimestamp = Math.min(row.firstTimestamp, event.timestamp);
         row.lastTimestamp = Math.max(row.lastTimestamp, event.timestamp);
         acc.sessionIds.add(event.sessionId);
-        acc.modelTokens.set(event.model, (acc.modelTokens.get(event.model) ?? 0) + event.tokens.totalTokens);
+        acc.modelTokens.set(eventModel, (acc.modelTokens.get(eventModel) ?? 0) + event.tokens.totalTokens);
         if (event.costUsd !== null) {
             row.costUsd += event.costUsd;
+            row.pricedCostUsd = (row.pricedCostUsd ?? 0) + event.costUsd;
             if (event.costProvenance === 'provider-reported')
                 acc.reportedCalls += 1;
             else
@@ -147,7 +162,14 @@ export function bucketUsage(events, options) {
     return rows.sort((a, b) => (isSession ? a.firstTimestamp - b.firstTimestamp : a.key.localeCompare(b.key)) ||
         (a.provider ?? '').localeCompare(b.provider ?? '') ||
         (a.project ?? '').localeCompare(b.project ?? '') ||
-        (a.model ?? '').localeCompare(b.model ?? ''));
+        (a.model ?? '').localeCompare(b.model ?? '') ||
+        (bySession && !isSession
+            ? a.firstTimestamp - b.firstTimestamp ||
+                (a.sessionId ?? '').localeCompare(b.sessionId ?? '')
+            : 0));
+}
+function reasoningOf(value) {
+    return typeof value === 'number' && Number.isFinite(value) && value > 0 ? value : 0;
 }
 /**
  * Sum rows that do not overlap (for example every row of one `bucketUsage`
@@ -161,8 +183,10 @@ export function summarizeUsageRows(rows, events) {
         tokens: emptyTokens(),
         totalTokens: 0,
         costUsd: 0,
+        pricedCostUsd: null,
         costProvenance: 'none',
         unpricedCalls: 0,
+        reasoningTokens: 0,
     };
     let reportedCalls = 0;
     let estimatedCalls = 0;
@@ -172,6 +196,15 @@ export function summarizeUsageRows(rows, events) {
         addTokens(totals.tokens, row.tokens);
         totals.totalTokens += row.totalTokens;
         totals.costUsd += row.costUsd;
+        // Rows from before `pricedCostUsd` existed: any priced call means a priced cost.
+        const rowPriced = row.pricedCostUsd !== undefined
+            ? row.pricedCostUsd
+            : row.calls > row.unpricedCalls
+                ? row.costUsd
+                : null;
+        if (rowPriced !== null)
+            totals.pricedCostUsd = (totals.pricedCostUsd ?? 0) + rowPriced;
+        totals.reasoningTokens = (totals.reasoningTokens ?? 0) + reasoningOf(row.reasoningTokens);
         totals.unpricedCalls += row.unpricedCalls;
         const priced = row.calls - row.unpricedCalls;
         if (row.costProvenance === 'reported')

package/dist/esm/watchers/eventBridge.js

@@ -8,6 +8,7 @@
  * FollowEvent is a lossy summary for timeline display and CLI output.
  */
 import { formatToolSummary } from '../formatters/toolSummary';
+import { isTaskNotificationSystemEvent, taskNotificationFromEvent } from '../subagentSpawn';
 /**
  * Converts a single SessionEvent to one or more FollowEvents.
  *
@@ -148,6 +149,20 @@ export function toFollowEvents(event, providerId) {
             break;
         }
         case 'system': {
+            // A background task's notice (opt-in reader event): its summary, not the raw block.
+            const notification = isTaskNotificationSystemEvent(event)
+                ? taskNotificationFromEvent(event)
+                : null;
+            if (notification) {
+                events.push({
+                    providerId,
+                    type: 'system',
+                    timestamp: ts,
+                    summary: notification.summary ?? `Background task ${notification.status ?? 'finished'}`,
+                    raw: event,
+                });
+                break;
+            }
             const text = extractTextContent(event.message?.content);
             const label = event.message?.sourceLabel || event.message?.role || 'system';
             const summary = text ||

package/dist/esm/watchers/factory.js

@@ -41,13 +41,15 @@ export function resolveSessionPath(provider, workspacePath, sessionId) {
 export function createWatcher(options) {
     const { provider, workspacePath, sessionId, callbacks } = options;
     const sessionPath = resolveSessionPath(provider, workspacePath, sessionId);
-    const watcher = createWatcherForProvider(provider, sessionPath, callbacks);
+    const watcher = createWatcherForProvider(provider, sessionPath, callbacks, {
+        includeTaskNotifications: options.includeTaskNotifications === true,
+    });
     return { watcher, sessionPath };
 }
-function createWatcherForProvider(provider, sessionPath, callbacks) {
+function createWatcherForProvider(provider, sessionPath, callbacks, jsonlOptions) {
     switch (provider.id) {
         case 'claude-code':
-            return new JsonlSessionWatcher(provider.id, sessionPath, callbacks);
+            return new JsonlSessionWatcher(provider.id, sessionPath, callbacks, jsonlOptions);
         case 'codex':
             return new ProviderReaderSessionWatcher(provider, sessionPath, callbacks);
         case 'opencode': {