sidekick-shared 0.28.3 → 0.29.1

package/dist/turns/assistantTurn.js

@@ -6,12 +6,12 @@ exports.segmentAssistantTurn = segmentAssistantTurn;
 exports.assistantTurnEventsFromSessionEvents = assistantTurnEventsFromSessionEvents;
 exports.extractTurnSubagents = extractTurnSubagents;
 const toolSummary_1 = require("../formatters/toolSummary");
+const subagentSpawn_1 = require("../subagentSpawn");
 const DEFAULT_NARRATION_CHARS = 4000;
 const DEFAULT_REASONING_CHARS = 8000;
 const DEFAULT_PROCESS_STEPS = 60;
 const DEFAULT_REASONING_BLOCKS = 24;
 const DEFAULT_TOOL_INPUT_CHARS = 200;
-const SUBAGENT_TOOL_NAMES = new Set(['Task']);
 const LABEL_MAX = 80;
 const TITLE_RE = /^\s*\*\*([^*\n]+)\*\*[ \t]*(?:\n+([\s\S]*))?$/;
 const TITLE_MAX = 100;
@@ -29,8 +29,9 @@ function reasoningSummary(text) {
     }
     return { title: null, body: trimmed };
 }
+/** Whether a tool call spawns a subagent (`Agent`, or its earlier name `Task`). */
 function isAssistantTurnSubagentTool(toolName) {
-    return toolName != null && SUBAGENT_TOOL_NAMES.has(toolName);
+    return (0, subagentSpawn_1.isSubagentSpawnTool)(toolName);
 }
 function segmentAssistantTurn(events, options = {}) {
     const maxNarrationChars = options.maxNarrationChars ?? DEFAULT_NARRATION_CHARS;

package/dist/types/opencode.d.ts

@@ -42,6 +42,8 @@ export interface OpenCodeMessage {
         cacheRead?: number;
         cacheWrite?: number;
         reasoning?: number;
+        /** Provider-reported total; tells OpenCode's token layouts apart (see `normalizeOpenCodeUsage`). */
+        total?: number;
     };
     time: {
         created: string | number;

package/dist/usage/claudeUsageDedupe.d.ts

@@ -22,6 +22,24 @@ import type { SessionEvent } from '../types/sessionEvent';
 export declare const SYNTHETIC_MODEL = "<synthetic>";
 /** Attach Anthropic-semantics normalized usage and Claude Code provenance to an event. */
 export declare function normalizeClaudeUsage(event: SessionEvent): SessionEvent;
+/** Tokens a {@link ClaudeUsageDeduper} has already counted for one message id. */
+export interface ClaudeUsageDedupeBuckets {
+    input: number;
+    cacheRead: number;
+    cacheWrite: number;
+    output: number;
+    reasoning: number;
+}
+/**
+ * JSON-serializable state of a {@link ClaudeUsageDeduper}, from
+ * `exportState()`, for `importState()` in a reader resumed at the same
+ * position (for example from a persisted session snapshot).
+ */
+export interface ClaudeUsageDedupeState {
+    version: 1;
+    /** `[message id, counted tokens]` pairs, oldest first. */
+    entries: Array<[string, ClaudeUsageDedupeBuckets]>;
+}
 /**
  * Per-reader dedupe state. Split lines of one response are adjacent, so a
  * bounded map (oldest keys evicted first) is enough.
@@ -40,6 +58,19 @@ export declare class ClaudeUsageDeduper {
     /** Whether a message id has already been counted by this deduper. */
     has(id: string): boolean;
     reset(): void;
+    /**
+     * The most recent `limit` message ids and the tokens counted for each,
+     * oldest first. Split lines of one response are adjacent, so a reader
+     * resumed at the position this was taken at needs only the last few.
+     */
+    exportState(limit?: number): ClaudeUsageDedupeState;
+    /**
+     * Replaces this deduper's state with one from {@link exportState}. Returns
+     * false, changing nothing, when `state` is not a valid version-1 state
+     * (wrong shape, empty ids, or counts that are not finite non-negative
+     * numbers). Entries beyond this deduper's capacity drop oldest first.
+     */
+    importState(state: unknown): boolean;
     private remember;
 }
 /**

package/dist/usage/claudeUsageDedupe.js

@@ -64,6 +64,25 @@ function normalizeClaudeUsage(event) {
         },
     };
 }
+const BUCKET_KEYS = ['input', 'cacheRead', 'cacheWrite', 'output', 'reasoning'];
+/** Entries {@link ClaudeUsageDeduper.exportState} keeps by default. */
+const DEFAULT_EXPORT_LIMIT = 256;
+function isCount(value) {
+    return typeof value === 'number' && Number.isFinite(value) && value >= 0;
+}
+function bucketsFrom(value) {
+    if (!value || typeof value !== 'object' || Array.isArray(value))
+        return null;
+    const record = value;
+    const buckets = {};
+    for (const key of BUCKET_KEYS) {
+        const count = record[key];
+        if (!isCount(count))
+            return null;
+        buckets[key] = count;
+    }
+    return buckets;
+}
 function bucketsOf(usage) {
     return {
         input: usage.uncachedInputTokens,
@@ -168,6 +187,55 @@ class ClaudeUsageDeduper {
     reset() {
         this.seen.clear();
     }
+    /**
+     * The most recent `limit` message ids and the tokens counted for each,
+     * oldest first. Split lines of one response are adjacent, so a reader
+     * resumed at the position this was taken at needs only the last few.
+     */
+    exportState(limit = DEFAULT_EXPORT_LIMIT) {
+        const count = limit >= 0 ? Math.min(this.seen.size, Math.floor(limit)) : 0;
+        const entries = [];
+        if (count > 0) {
+            let skip = this.seen.size - count;
+            for (const [id, buckets] of this.seen) {
+                if (skip > 0) {
+                    skip -= 1;
+                    continue;
+                }
+                entries.push([id, { ...buckets }]);
+            }
+        }
+        return { version: 1, entries };
+    }
+    /**
+     * Replaces this deduper's state with one from {@link exportState}. Returns
+     * false, changing nothing, when `state` is not a valid version-1 state
+     * (wrong shape, empty ids, or counts that are not finite non-negative
+     * numbers). Entries beyond this deduper's capacity drop oldest first.
+     */
+    importState(state) {
+        if (!state || typeof state !== 'object')
+            return false;
+        const { version, entries } = state;
+        if (version !== 1 || !Array.isArray(entries))
+            return false;
+        const parsed = [];
+        for (const entry of entries) {
+            if (!Array.isArray(entry) || entry.length !== 2)
+                return false;
+            const [id, value] = entry;
+            if (typeof id !== 'string' || id.length === 0)
+                return false;
+            const buckets = bucketsFrom(value);
+            if (!buckets)
+                return false;
+            parsed.push([id, buckets]);
+        }
+        this.seen.clear();
+        for (const [id, buckets] of parsed)
+            this.remember(id, buckets);
+        return true;
+    }
     remember(id, buckets) {
         this.seen.delete(id);
         this.seen.set(id, buckets);

package/dist/usage/usageEvents.d.ts

@@ -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.
  *
@@ -25,9 +35,11 @@ import type { PricingProvenance } from '../usageNormalization';
 /**
  * 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 declare const USAGE_CACHE_VERSION = 2;
+export declare 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
@@ -47,11 +59,43 @@ export interface UsageEventRecord {
     /** Four buckets plus the provider-semantics-aware total. */
     tokens: TokenTotals & {
         totalTokens: number;
+        /**
+         * Reasoning tokens the provider reported, when any. Informational, never
+         * added to a total: Codex counts them inside `outputTokens`; OpenCode
+         * reports them apart, inside `totalTokens` but not `outputTokens`.
+         */
+        reasoningTokens?: number;
     };
     costUsd: number | null;
     costProvenance: PricingProvenance;
     /** Session file the event came from; tells apart two files with one session id. */
     filePath?: string;
+    /**
+     * Ordinal of the human prompt this call followed: the highest ordinal among
+     * the session's prompts timestamped at or before the event, as
+     * `collectPromptHistory()` numbers them with default bounds. Claude Code
+     * subagent calls map to the parent session's prompts. `null` when no prompt
+     * precedes the call, or the session has none (a Codex subagent or fork is a
+     * session of its own without human prompts). Absent when
+     * unknown: a provider without prompt history (OpenCode), or a cache entry
+     * written before prompt ordinals were recorded.
+     */
+    promptOrdinal?: number | null;
+    /**
+     * The provider's message id for the call (Claude Code, OpenCode). Absent for
+     * Codex, whose `token_count` lines carry no request id (the reader's
+     * timestamp-derived placeholder is not passed through).
+     */
+    requestId?: string;
+    /**
+     * Set when a subagent made the call. Claude Code: the agent id from its
+     * transcript name (`agent-<id>.jsonl`), parent = this session. Codex: the
+     * forked or spawned rollout's own session id and the session it came from.
+     */
+    subagent?: {
+        agentId: string;
+        parentSessionId: string;
+    };
 }
 /** One session that contributed events. */
 export interface UsageSessionRecord {
@@ -111,7 +155,11 @@ export interface CollectUsageEventsResult {
     roots?: string[];
 }
 export declare function getUsageCacheDir(): string;
-/** 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 declare function pruneUsageCache(keep?: number, dir?: string): number;
 /**
  * Collect priced usage events for every session touched in the window.

package/dist/usage/usageEvents.js

@@ -12,9 +12,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.
  *
@@ -60,7 +70,10 @@ exports.pruneUsageCache = pruneUsageCache;
 exports.collectUsageEvents = collectUsageEvents;
 const fs = __importStar(require("fs"));
 const path = __importStar(require("path"));
+const codexRolloutOrigin_1 = require("../parsers/codexRolloutOrigin");
 const paths_1 = require("../paths");
+const promptHistory_1 = require("../promptHistory");
+const codexRollouts_1 = require("../providers/codexRollouts");
 const sessionPreviews_1 = require("../sessionPreviews");
 const usageNormalization_1 = require("../usageNormalization");
 const atomic_1 = require("../writers/atomic");
@@ -68,9 +81,11 @@ const workspaceRoots_1 = require("../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`).
  */
-exports.USAGE_CACHE_VERSION = 2;
+exports.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
@@ -81,9 +96,15 @@ exports.MAX_USAGE_CACHE_FILES = 5000;
 function getUsageCacheDir() {
     return path.join((0, paths_1.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${exports.USAGE_CACHE_VERSION}.json`);
 }
 function toMs(value, label) {
     if (value === undefined)
@@ -114,7 +135,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.
+ */
 function pruneUsageCache(keep = exports.MAX_USAGE_CACHE_FILES, dir = getUsageCacheDir()) {
     try {
         const entries = fs
@@ -147,7 +172,7 @@ function pruneUsageCache(keep = exports.MAX_USAGE_CACHE_FILES, dir = getUsageCac
         return 0;
     }
 }
-function cachedEventFromUsage(usage, timestamp, model) {
+function cachedEventFromUsage(usage, timestamp, model, messageId, agentId) {
     const record = {
         t: timestamp,
         m: model,
@@ -160,16 +185,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,
@@ -181,6 +219,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,
@@ -193,13 +234,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')
@@ -219,6 +266,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,
             });
@@ -235,7 +283,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();
@@ -257,12 +305,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);
@@ -272,10 +322,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 (0, promptHistory_1.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 (0, codexRollouts_1.readFirstLineAsync)(preview.filePath);
+    if (!line)
+        return undefined;
+    let first;
+    try {
+        first = JSON.parse(line);
+    }
+    catch {
+        return undefined;
+    }
+    const origin = (0, codexRolloutOrigin_1.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));
 }
@@ -315,12 +430,14 @@ 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;
@@ -344,7 +461,10 @@ 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: exports.USAGE_CACHE_VERSION,
                     provider: preview.provider,
@@ -352,6 +472,7 @@ async function collectUsageEvents(options) {
                     fingerprint,
                     project,
                     events: cachedEvents,
+                    ...(sessionSubagent ? { subagent: sessionSubagent } : {}),
                 };
                 try {
                     await (0, atomic_1.atomicWriteJson)(filePath, record);
@@ -371,7 +492,7 @@ 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;
@@ -400,6 +521,14 @@ 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/usage/usageReports.d.ts

@@ -10,8 +10,11 @@ import type { ProviderId } from '../providers/types';
 import type { TokenTotals } from '../types/historicalData';
 import type { UsageEventRecord } from './usageEvents';
 export type UsageGranularity = 'day' | 'week' | 'month' | 'session';
-/** Extra dimensions a bucket is split by, beyond the time key. */
-export type UsageGroupDimension = 'provider' | 'project' | 'model';
+/**
+ * Extra dimensions a bucket is split by, beyond the time key. `session`
+ * splits each time bucket per session (rows then carry `sessionId`).
+ */
+export type UsageGroupDimension = 'provider' | 'project' | 'model' | 'session';
 export interface BucketUsageOptions {
     granularity: UsageGranularity;
     /** Key by the UTC calendar instead of the local calendar (default false). */
@@ -20,6 +23,19 @@ export interface BucketUsageOptions {
     weekStartsOn?: 0 | 1;
     /** Dimensions to group by in addition to the time key (default `['provider']`). */
     groupBy?: readonly UsageGroupDimension[];
+    /**
+     * Drop events whose model is Claude Code's `<synthetic>` placeholder
+     * (`SYNTHETIC_MODEL`: locally generated, unbilled messages). Default false.
+     */
+    excludeSynthetic?: boolean;
+    /**
+     * How model ids are keyed in `model` rows and the `models` list. `'raw'`
+     * (default) keeps each id as recorded; `'canonical'` merges spellings of one
+     * model (date suffixes, provider/region prefixes, Bedrock forms) through
+     * `canonicalModelId()`, so `claude-opus-5-5-20261001` and `claude-opus-5-5`
+     * share a row. Pricing is unaffected: events arrive already priced.
+     */
+    modelKey?: 'raw' | 'canonical';
 }
 export interface UsageBucketRow {
     /** `YYYY-MM-DD` for days and week starts, `YYYY-MM` for months, the session id for sessions. */
@@ -29,7 +45,7 @@ export interface UsageBucketRow {
     project: string | null;
     /** Set when grouping by model; null for rows spanning every model. */
     model: string | null;
-    /** Session id for `session` rows; null otherwise. */
+    /** Session id for `session` rows and rows grouped by `session`; null otherwise. */
     sessionId: string | null;
     /** Models seen in the row, most tokens first. */
     models: string[];
@@ -41,8 +57,18 @@ export interface UsageBucketRow {
     totalTokens: number;
     /** Priced portion of the cost; read `costProvenance` before labelling it. */
     costUsd: number;
+    /**
+     * Sum of the priced calls' costs, or null when no call in the row was
+     * priced (where `costUsd` reads 0).
+     */
+    pricedCostUsd: number | null;
     costProvenance: AggregatedCostProvenance;
     unpricedCalls: number;
+    /**
+     * Reasoning tokens reported by the row's calls. Informational, already
+     * inside the token buckets and `totalTokens`. Always set by `bucketUsage`.
+     */
+    reasoningTokens?: number;
     /** First and last event in the row, ms since epoch. */
     firstTimestamp: number;
     lastTimestamp: number;
@@ -53,8 +79,12 @@ export interface UsageTotals {
     tokens: TokenTotals;
     totalTokens: number;
     costUsd: number;
+    /** Sum of the rows' priced costs, or null when no row had a priced call. */
+    pricedCostUsd: number | null;
     costProvenance: AggregatedCostProvenance;
     unpricedCalls: number;
+    /** Sum of the rows' `reasoningTokens`. Always set by `summarizeUsageRows`. */
+    reasoningTokens?: number;
 }
 /** The `YYYY-MM-DD` key of the week containing `ms`, starting on `weekStartsOn`. */
 export declare function weekKey(ms: number, options?: {
@@ -65,7 +95,8 @@ export declare function weekKey(ms: number, options?: {
 export declare function usageBucketKey(event: Pick<UsageEventRecord, 'timestamp' | 'sessionId'>, options: BucketUsageOptions): string;
 /**
  * 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 declare function bucketUsage(events: readonly UsageEventRecord[], options: BucketUsageOptions): UsageBucketRow[];
 /**