sidekick-shared 0.27.2 → 0.27.4

package/dist/report/htmlReportGenerator.js

@@ -8,6 +8,7 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.generateHtmlReport = generateHtmlReport;
 const costProvenance_1 = require("../aggregation/costProvenance");
 const tokenSummary_1 = require("../tokenSummary");
+const sessionTokenTotals_1 = require("../sessionTokenTotals");
 const htmlHelpers_1 = require("./htmlHelpers");
 const logo_1 = require("./logo");
 /**
@@ -16,7 +17,7 @@ const logo_1 = require("./logo");
 function generateHtmlReport(metrics, transcript, options = {}) {
     const { sessionFileName, includeThinking = true, includeToolDetail = true, theme = 'dark', } = options;
     const duration = (0, htmlHelpers_1.formatDuration)(metrics.sessionStartTime, metrics.lastEventTime);
-    const totalTokens = (0, tokenSummary_1.summarizeTokens)(metrics.tokens).total;
+    const tokens = (0, sessionTokenTotals_1.combineSessionTokenTotals)(metrics.tokens, options.subagents ?? []);
     return `<!DOCTYPE html>
 <html lang="en" data-theme="${theme}">
 <head>
@@ -27,7 +28,7 @@ ${generateStyles()}
 </head>
 <body>
 ${generateHeader(metrics, sessionFileName, duration)}
-${generateStatsCards(metrics, totalTokens, duration)}
+${generateStatsCards(metrics, tokens, duration)}
 ${generateModelBreakdown(metrics)}
 ${generateToolBreakdown(metrics)}
 ${generateTranscriptControls()}
@@ -422,7 +423,9 @@ function generateHeader(metrics, sessionFileName, duration) {
   </div>
 </div>`;
 }
-function generateStatsCards(metrics, totalTokens, duration) {
+function generateStatsCards(metrics, tokens, duration) {
+    const main = tokens.mainThread;
+    const hasSubagents = tokens.subagents.length > 0;
     const toolCount = metrics.toolStats.reduce((sum, t) => sum + t.successCount + t.failureCount, 0);
     const cards = [
         { label: 'Messages', value: String(metrics.messageCount), sub: `${metrics.eventCount} events` },
@@ -432,14 +435,28 @@ function generateStatsCards(metrics, totalTokens, duration) {
             sub: metrics.sessionStartTime ? (0, htmlHelpers_1.formatTimestamp)(metrics.sessionStartTime) + ' start' : '',
         },
         {
-            label: tokenSummary_1.TOKEN_TOTAL_LABEL,
-            value: (0, htmlHelpers_1.fmtTokens)(totalTokens),
-            sub: `${(0, htmlHelpers_1.fmtTokens)(metrics.tokens.inputTokens)} in / ${(0, htmlHelpers_1.fmtTokens)(metrics.tokens.outputTokens)} out`,
+            label: hasSubagents ? `${tokenSummary_1.TOKEN_MAIN_THREAD_LABEL} — ${tokenSummary_1.TOKEN_TOTAL_LABEL}` : tokenSummary_1.TOKEN_TOTAL_LABEL,
+            value: (0, htmlHelpers_1.fmtTokens)(main.total),
+            sub: `${(0, htmlHelpers_1.fmtTokens)(main.input)} in · ${(0, htmlHelpers_1.fmtTokens)(main.cacheRead)} cache read · ${(0, htmlHelpers_1.fmtTokens)(main.cacheWrite)} cache write · ${(0, htmlHelpers_1.fmtTokens)(main.output)} out${main.billedOutsideBuckets > 0 ? ` · ${(0, htmlHelpers_1.fmtTokens)(main.billedOutsideBuckets)} reasoning` : ''}`,
         },
+        ...(hasSubagents
+            ? [
+                {
+                    label: `${tokenSummary_1.TOKEN_SUBAGENTS_LABEL} (${tokens.subagents.length})`,
+                    value: (0, htmlHelpers_1.fmtTokens)(tokens.subagentTotal.total),
+                    sub: `${(0, htmlHelpers_1.fmtTokens)(tokens.subagentTotal.cacheRead)} cache read · ${(0, htmlHelpers_1.fmtTokens)(tokens.subagentTotal.output)} out`,
+                },
+                {
+                    label: tokenSummary_1.TOKEN_SESSION_TOTAL_LABEL,
+                    value: (0, htmlHelpers_1.fmtTokens)(tokens.combined.total),
+                    sub: 'main thread + subagents',
+                },
+            ]
+            : []),
         {
-            label: 'Cache',
-            value: (0, htmlHelpers_1.fmtTokens)(metrics.tokens.cacheReadTokens),
-            sub: `${(0, htmlHelpers_1.fmtTokens)(metrics.tokens.cacheWriteTokens)} written`,
+            label: 'Cache hit',
+            value: main.cacheHitRatio === null ? '—' : `${Math.round(main.cacheHitRatio * 100)}%`,
+            sub: `${(0, htmlHelpers_1.fmtTokens)(main.cacheRead)} of ${(0, htmlHelpers_1.fmtTokens)(main.context)} context tokens`,
         },
         {
             label: 'Tool Calls',
@@ -474,7 +491,7 @@ function generateModelBreakdown(metrics) {
     return `<div class="section">
 <div class="section-title">Model Breakdown</div>
 <table>
-<thead><tr><th>Model</th><th>Calls</th><th>Total Tokens</th><th>In / Out</th><th>Cost</th></tr></thead>
+<thead><tr><th>Model</th><th>Calls</th><th>${tokenSummary_1.TOKEN_TOTAL_LABEL}</th><th>In / Out</th><th>Cost</th></tr></thead>
 <tbody>${rows}</tbody>
 </table>
 </div>`;
@@ -534,7 +551,12 @@ function renderMessage(entry, includeThinking, includeToolDetail) {
         ? `<span class="message-model">${(0, htmlHelpers_1.escapeHtml)(entry.model)}</span>`
         : '';
     const tokenStr = entry.usage
-        ? `<span class="message-tokens">${(0, htmlHelpers_1.fmtTokens)(entry.usage.input_tokens + entry.usage.output_tokens)} tokens</span>`
+        ? `<span class="message-tokens">${(0, htmlHelpers_1.fmtTokens)((0, tokenSummary_1.summarizeTokens)({
+            inputTokens: entry.usage.input_tokens,
+            outputTokens: entry.usage.output_tokens,
+            cacheWriteTokens: entry.usage.cache_creation_input_tokens,
+            cacheReadTokens: entry.usage.cache_read_input_tokens,
+        }).total)} tokens incl. cache</span>`
         : '';
     const bodyParts = [];
     for (const block of entry.content) {

package/dist/report/sessionReportInputs.d.ts

@@ -10,7 +10,7 @@
  */
 import type { AggregatedMetrics } from '../aggregation/types';
 import type { SessionProviderBase } from '../providers/types';
-import type { SessionEvent } from '../types/sessionEvent';
+import type { SessionEvent, SubagentStats } from '../types/sessionEvent';
 import type { TranscriptEntry } from './types';
 export interface SessionReportInputs {
     sessionPath: string;
@@ -18,6 +18,8 @@ export interface SessionReportInputs {
     events: SessionEvent[];
     metrics: AggregatedMetrics;
     transcript: TranscriptEntry[];
+    /** The session's subagents; pass as `HtmlReportOptions.subagents` for the session total. */
+    subagents: SubagentStats[];
 }
 /** Read a session once and build the aggregator metrics and report transcript from it. */
 export declare function readSessionReportInputs(provider: SessionProviderBase, sessionPath: string): SessionReportInputs;

package/dist/report/sessionReportInputs.js

@@ -13,6 +13,7 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.readSessionReportInputs = readSessionReportInputs;
 const EventAggregator_1 = require("../aggregation/EventAggregator");
 const sessionStats_1 = require("../sessionStats");
+const sessionTokenTotals_1 = require("../sessionTokenTotals");
 const transcriptParser_1 = require("./transcriptParser");
 /** Read a session once and build the aggregator metrics and report transcript from it. */
 function readSessionReportInputs(provider, sessionPath) {
@@ -30,5 +31,6 @@ function readSessionReportInputs(provider, sessionPath) {
         events,
         metrics: aggregator.getMetrics(),
         transcript: (0, transcriptParser_1.parseTranscriptFromEvents)(events),
+        subagents: (0, sessionTokenTotals_1.scanSessionSubagents)(provider, sessionPath),
     };
 }

package/dist/report/types.d.ts

@@ -42,4 +42,9 @@ export interface HtmlReportOptions {
     includeToolDetail?: boolean;
     /** Color theme (default: 'dark'). */
     theme?: 'dark' | 'light';
+    /**
+     * The session's subagents (`provider.scanSubagents()`). Their tokens are
+     * reported beside the main thread and added to the session total.
+     */
+    subagents?: readonly import('../types/sessionEvent').SubagentStats[];
 }

package/dist/schemas/sessionEvent.d.ts

@@ -51,8 +51,12 @@ export declare const sessionMessageSchema: z.ZodObject<{
             source: z.ZodOptional<z.ZodString>;
         }, z.core.$strip>;
     }, z.core.$strip>>;
+    usageKind: z.ZodOptional<z.ZodEnum<{
+        call: "call";
+        correction: "correction";
+    }>>;
     content: z.ZodOptional<z.ZodUnknown>;
-    stop_reason: z.ZodOptional<z.ZodString>;
+    stop_reason: z.ZodPipe<z.ZodOptional<z.ZodNullable<z.ZodString>>, z.ZodTransform<string | undefined, string | null | undefined>>;
 }, z.core.$strip>;
 export declare const permissionModeSchema: z.ZodEnum<{
     default: "default";
@@ -141,8 +145,12 @@ export declare const userSessionEventSchema: z.ZodObject<{
                 source: z.ZodOptional<z.ZodString>;
             }, z.core.$strip>;
         }, z.core.$strip>>;
+        usageKind: z.ZodOptional<z.ZodEnum<{
+            call: "call";
+            correction: "correction";
+        }>>;
         content: z.ZodOptional<z.ZodUnknown>;
-        stop_reason: z.ZodOptional<z.ZodString>;
+        stop_reason: z.ZodPipe<z.ZodOptional<z.ZodNullable<z.ZodString>>, z.ZodTransform<string | undefined, string | null | undefined>>;
     }, z.core.$strip>;
 }, z.core.$strip>;
 export declare const assistantSessionEventSchema: z.ZodObject<{
@@ -226,8 +234,12 @@ export declare const assistantSessionEventSchema: z.ZodObject<{
                 source: z.ZodOptional<z.ZodString>;
             }, z.core.$strip>;
         }, z.core.$strip>>;
+        usageKind: z.ZodOptional<z.ZodEnum<{
+            call: "call";
+            correction: "correction";
+        }>>;
         content: z.ZodOptional<z.ZodUnknown>;
-        stop_reason: z.ZodOptional<z.ZodString>;
+        stop_reason: z.ZodPipe<z.ZodOptional<z.ZodNullable<z.ZodString>>, z.ZodTransform<string | undefined, string | null | undefined>>;
     }, z.core.$strip>;
 }, z.core.$strip>;
 export declare const summarySessionEventSchema: z.ZodType<SummarySessionEvent>;
@@ -312,8 +324,12 @@ export declare const systemSessionEventSchema: z.ZodObject<{
                 source: z.ZodOptional<z.ZodString>;
             }, z.core.$strip>;
         }, z.core.$strip>>;
+        usageKind: z.ZodOptional<z.ZodEnum<{
+            call: "call";
+            correction: "correction";
+        }>>;
         content: z.ZodOptional<z.ZodUnknown>;
-        stop_reason: z.ZodOptional<z.ZodString>;
+        stop_reason: z.ZodPipe<z.ZodOptional<z.ZodNullable<z.ZodString>>, z.ZodTransform<string | undefined, string | null | undefined>>;
     }, z.core.$strip>>;
 }, z.core.$strip>;
 export declare const toolUseSessionEventSchema: z.ZodObject<{
@@ -401,8 +417,12 @@ export declare const toolUseSessionEventSchema: z.ZodObject<{
                 source: z.ZodOptional<z.ZodString>;
             }, z.core.$strip>;
         }, z.core.$strip>>;
+        usageKind: z.ZodOptional<z.ZodEnum<{
+            call: "call";
+            correction: "correction";
+        }>>;
         content: z.ZodOptional<z.ZodUnknown>;
-        stop_reason: z.ZodOptional<z.ZodString>;
+        stop_reason: z.ZodPipe<z.ZodOptional<z.ZodNullable<z.ZodString>>, z.ZodTransform<string | undefined, string | null | undefined>>;
     }, z.core.$strip>>;
 }, z.core.$strip>;
 export declare const toolResultSessionEventSchema: z.ZodObject<{
@@ -491,8 +511,12 @@ export declare const toolResultSessionEventSchema: z.ZodObject<{
                 source: z.ZodOptional<z.ZodString>;
             }, z.core.$strip>;
         }, z.core.$strip>>;
+        usageKind: z.ZodOptional<z.ZodEnum<{
+            call: "call";
+            correction: "correction";
+        }>>;
         content: z.ZodOptional<z.ZodUnknown>;
-        stop_reason: z.ZodOptional<z.ZodString>;
+        stop_reason: z.ZodPipe<z.ZodOptional<z.ZodNullable<z.ZodString>>, z.ZodTransform<string | undefined, string | null | undefined>>;
     }, z.core.$strip>>;
 }, z.core.$strip>;
 export declare const sessionEventSchema: z.ZodType<SessionEvent>;

package/dist/schemas/sessionEvent.js

@@ -29,8 +29,14 @@ exports.sessionMessageSchema = zod_1.z.object({
     model: zod_1.z.string().optional(),
     usage: exports.messageUsageSchema.optional(),
     normalizedUsage: usageNormalization_1.normalizedUsageSchema.optional(),
+    usageKind: zod_1.z.enum(['call', 'correction']).optional(),
     content: zod_1.z.unknown().optional(),
-    stop_reason: zod_1.z.string().optional(),
+    // Streaming lines can carry `stop_reason: null`; rejecting it dropped the
+    // whole event (text, tools, and usage), so normalize it to absent.
+    stop_reason: zod_1.z
+        .string()
+        .nullish()
+        .transform((value) => value ?? undefined),
 });
 // ── PermissionMode ──
 exports.permissionModeSchema = zod_1.z.enum([

package/dist/schemas/stateFile.d.ts

@@ -58,6 +58,7 @@ export declare const stateFileContextSchema: z.ZodObject<{
     contextWindowSize: z.ZodNullable<z.ZodNumber>;
     totalInputTokens: z.ZodNullable<z.ZodNumber>;
     totalOutputTokens: z.ZodNullable<z.ZodNumber>;
+    totalTokens: z.ZodOptional<z.ZodNullable<z.ZodNumber>>;
 }, z.core.$strip>;
 export declare const stateFileSessionSchema: z.ZodObject<{
     sessionId: z.ZodNullable<z.ZodString>;
@@ -166,6 +167,7 @@ export declare const sidekickStateFileSchema: z.ZodObject<{
         contextWindowSize: z.ZodNullable<z.ZodNumber>;
         totalInputTokens: z.ZodNullable<z.ZodNumber>;
         totalOutputTokens: z.ZodNullable<z.ZodNumber>;
+        totalTokens: z.ZodOptional<z.ZodNullable<z.ZodNumber>>;
     }, z.core.$strip>>;
     session: z.ZodNullable<z.ZodObject<{
         sessionId: z.ZodNullable<z.ZodString>;

package/dist/schemas/stateFile.js

@@ -39,6 +39,7 @@ exports.stateFileContextSchema = zod_1.z.object({
     contextWindowSize: zod_1.z.number().nullable(),
     totalInputTokens: zod_1.z.number().nullable(),
     totalOutputTokens: zod_1.z.number().nullable(),
+    totalTokens: zod_1.z.number().nullable().optional(),
 });
 exports.stateFileSessionSchema = zod_1.z.object({
     sessionId: zod_1.z.string().nullable(),

package/dist/sessionTokenTotals.d.ts

@@ -0,0 +1,46 @@
+/**
+ * A session's token total, main thread plus subagents, in the shared
+ * `summarizeTokens` vocabulary.
+ *
+ * Subagents run in their own transcripts (Claude Code `subagents/agent-*.jsonl`,
+ * Codex spawned rollouts, OpenCode child sessions), so the main-thread reader
+ * never sees their usage. Every surface that shows "the session total" goes
+ * through this module so dump, report, and both dashboards agree.
+ *
+ * @module sessionTokenTotals
+ */
+import type { SessionProviderBase } from './providers/types';
+import type { SubagentStats } from './types/sessionEvent';
+import { type TokenSummary, type TokenTotalsLike } from './tokenSummary';
+export interface SubagentTokenSummary {
+    agentId: string;
+    agentType?: string;
+    description?: string;
+    summary: TokenSummary;
+}
+export interface SessionTokenTotals {
+    /** Tokens the session's own transcript billed. */
+    mainThread: TokenSummary;
+    /** One entry per subagent, in provider order. */
+    subagents: SubagentTokenSummary[];
+    /** All subagents together. */
+    subagentTotal: TokenSummary;
+    /** Main thread plus subagents. */
+    combined: TokenSummary;
+}
+/** Token record of one subagent, in `TokenTotalsLike` form. */
+export declare function subagentTokenTotals(stats: SubagentStats): TokenTotalsLike;
+/** Combine an already-known main-thread total with a session's subagent stats. */
+export declare function combineSessionTokenTotals(mainThread: TokenTotalsLike, subagents: readonly SubagentStats[]): SessionTokenTotals;
+/** Sum the usage a provider reader reports for one session transcript. */
+export declare function readMainThreadTokenTotals(provider: SessionProviderBase, sessionPath: string): TokenTotalsLike;
+/**
+ * Main thread plus subagents for one session. Pass `mainThread` when the
+ * caller already aggregated the transcript (an `EventAggregator`'s tokens) to
+ * skip re-reading it. Subagent discovery failures degrade to "no subagents".
+ */
+export declare function collectSessionTokenTotals(provider: SessionProviderBase, sessionPath: string, options?: {
+    mainThread?: TokenTotalsLike;
+}): SessionTokenTotals;
+/** A session's subagents by transcript path; discovery failures yield none. */
+export declare function scanSessionSubagents(provider: SessionProviderBase, sessionPath: string): SubagentStats[];

package/dist/sessionTokenTotals.js

@@ -0,0 +1,138 @@
+"use strict";
+/**
+ * A session's token total, main thread plus subagents, in the shared
+ * `summarizeTokens` vocabulary.
+ *
+ * Subagents run in their own transcripts (Claude Code `subagents/agent-*.jsonl`,
+ * Codex spawned rollouts, OpenCode child sessions), so the main-thread reader
+ * never sees their usage. Every surface that shows "the session total" goes
+ * through this module so dump, report, and both dashboards agree.
+ *
+ * @module sessionTokenTotals
+ */
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.subagentTokenTotals = subagentTokenTotals;
+exports.combineSessionTokenTotals = combineSessionTokenTotals;
+exports.readMainThreadTokenTotals = readMainThreadTokenTotals;
+exports.collectSessionTokenTotals = collectSessionTokenTotals;
+exports.scanSessionSubagents = scanSessionSubagents;
+const path = __importStar(require("path"));
+const usageNormalization_1 = require("./usageNormalization");
+const tokenSummary_1 = require("./tokenSummary");
+/** Token record of one subagent, in `TokenTotalsLike` form. */
+function subagentTokenTotals(stats) {
+    return {
+        inputTokens: stats.inputTokens,
+        outputTokens: stats.outputTokens,
+        cacheReadTokens: stats.cacheReadTokens,
+        cacheWriteTokens: stats.cacheWriteTokens,
+        reasoningTokens: stats.reasoningTokens,
+        ...(typeof stats.totalTokens === 'number' ? { totalTokens: stats.totalTokens } : {}),
+    };
+}
+/** Combine an already-known main-thread total with a session's subagent stats. */
+function combineSessionTokenTotals(mainThread, subagents) {
+    const subagentRecords = subagents.map(subagentTokenTotals);
+    const main = (0, tokenSummary_1.summarizeTokens)(mainThread);
+    const mainRecord = {
+        inputTokens: main.input,
+        outputTokens: main.output,
+        cacheReadTokens: main.cacheRead,
+        cacheWriteTokens: main.cacheWrite,
+        reasoningTokens: main.reasoning,
+        totalTokens: main.total,
+    };
+    return {
+        mainThread: main,
+        subagents: subagents.map((stats, index) => ({
+            agentId: stats.agentId,
+            ...(stats.agentType ? { agentType: stats.agentType } : {}),
+            ...(stats.description ? { description: stats.description } : {}),
+            summary: (0, tokenSummary_1.summarizeTokens)(subagentRecords[index]),
+        })),
+        subagentTotal: (0, tokenSummary_1.summarizeTokens)((0, tokenSummary_1.sumTokenTotals)(subagentRecords)),
+        combined: (0, tokenSummary_1.summarizeTokens)((0, tokenSummary_1.sumTokenTotals)([mainRecord, ...subagentRecords])),
+    };
+}
+/** Sum the usage a provider reader reports for one session transcript. */
+function readMainThreadTokenTotals(provider, sessionPath) {
+    const reader = provider.createReader(sessionPath);
+    const events = reader.readAll();
+    reader.flush();
+    let inputTokens = 0;
+    let outputTokens = 0;
+    let cacheReadTokens = 0;
+    let cacheWriteTokens = 0;
+    let reasoningTokens = 0;
+    let totalTokens = 0;
+    for (const event of events) {
+        const usage = (0, usageNormalization_1.extractNormalizedUsage)(event);
+        if (!usage)
+            continue;
+        inputTokens += usage.uncachedInputTokens;
+        outputTokens += usage.outputTokens;
+        cacheReadTokens += usage.cacheReadTokens;
+        cacheWriteTokens += usage.cacheWriteTokens;
+        reasoningTokens += usage.reasoningTokens;
+        totalTokens += usage.totalTokens;
+    }
+    return {
+        inputTokens,
+        outputTokens,
+        cacheReadTokens,
+        cacheWriteTokens,
+        reasoningTokens,
+        totalTokens,
+    };
+}
+/**
+ * Main thread plus subagents for one session. Pass `mainThread` when the
+ * caller already aggregated the transcript (an `EventAggregator`'s tokens) to
+ * skip re-reading it. Subagent discovery failures degrade to "no subagents".
+ */
+function collectSessionTokenTotals(provider, sessionPath, options = {}) {
+    const mainThread = options.mainThread ?? readMainThreadTokenTotals(provider, sessionPath);
+    return combineSessionTokenTotals(mainThread, scanSessionSubagents(provider, sessionPath));
+}
+/** A session's subagents by transcript path; discovery failures yield none. */
+function scanSessionSubagents(provider, sessionPath) {
+    try {
+        return provider.scanSubagents(path.dirname(sessionPath), provider.getSessionId(sessionPath));
+    }
+    catch {
+        return [];
+    }
+}

package/dist/stateFile.d.ts

@@ -44,8 +44,15 @@ export interface StateFileAccount {
 export interface StateFileContext {
     usedPercentage: number | null;
     contextWindowSize: number | null;
+    /** Input tokens including cache reads and writes (Claude Code status-line semantics). */
     totalInputTokens: number | null;
     totalOutputTokens: number | null;
+    /**
+     * Every token the session billed, cache included — the `summarizeTokens().total`
+     * figure the dashboards show. Absent or null when the writer does not know it
+     * (the status line only sees the current context).
+     */
+    totalTokens?: number | null;
 }
 export interface StateFileSession {
     sessionId: string | null;

package/dist/tokenSummary.d.ts

@@ -28,6 +28,8 @@ export interface TokenTotalsLike {
     outputTokens: number;
     cacheWriteTokens?: number;
     cacheReadTokens?: number;
+    /** Reasoning tokens, when the source tracks them (display only). */
+    reasoningTokens?: number;
     /**
      * A provider-semantics-aware total, when the source already computed one
      * (for example `AggregatedTokens.totalTokens`). Preferred over the
@@ -51,12 +53,36 @@ export interface TokenSummary {
     cacheWrite: number;
     /** Fraction of context tokens that came from cache reads (0..1), or null with no input. */
     cacheHitRatio: number | null;
+    /** Reasoning tokens reported by the provider (display only; may be inside `output`). */
+    reasoning: number;
+    /**
+     * Tokens in `total` beyond the four buckets — reasoning billed outside
+     * `output` by providers that report it separately. Zero when the buckets
+     * already add up to `total`.
+     */
+    billedOutsideBuckets: number;
 }
 /** Column label for `TokenSummary.total` on any surface. */
 export declare const TOKEN_TOTAL_LABEL = "Total (incl. cache)";
 /** Column label for `TokenSummary.context` on any surface. */
 export declare const TOKEN_CONTEXT_LABEL = "Context";
+/** Label for a session's own (main-thread) tokens when subagents are shown beside it. */
+export declare const TOKEN_MAIN_THREAD_LABEL = "Main thread";
+/** Label for the tokens a session's subagents used. */
+export declare const TOKEN_SUBAGENTS_LABEL = "Subagents";
+/** Label for main thread plus subagents. */
+export declare const TOKEN_SESSION_TOTAL_LABEL = "Session total (incl. subagents)";
 /** Derive the shared token vocabulary from any four-bucket token record. */
 export declare function summarizeTokens(totals: TokenTotalsLike): TokenSummary;
-/** Sum several token records bucket-by-bucket before summarizing. */
+/**
+ * One-line breakdown whose parts add up to the headline:
+ * `1.2M total incl. cache (12k in · 1.1M cache read · 40k cache write · 30k out)`.
+ * Pass the surface's own number formatter; the default prints plain integers.
+ */
+export declare function formatTokenBreakdown(summary: TokenSummary, fmt?: (n: number) => string): string;
+/**
+ * Sum several token records bucket-by-bucket before summarizing. `totalTokens`
+ * is summed only when every record carries one, so provider-aware totals
+ * survive the sum instead of falling back to the four-bucket arithmetic.
+ */
 export declare function sumTokenTotals(records: readonly TokenTotalsLike[]): TokenTotalsLike;

package/dist/tokenSummary.js

@@ -24,13 +24,20 @@
  * @module tokenSummary
  */
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.TOKEN_CONTEXT_LABEL = exports.TOKEN_TOTAL_LABEL = void 0;
+exports.TOKEN_SESSION_TOTAL_LABEL = exports.TOKEN_SUBAGENTS_LABEL = exports.TOKEN_MAIN_THREAD_LABEL = exports.TOKEN_CONTEXT_LABEL = exports.TOKEN_TOTAL_LABEL = void 0;
 exports.summarizeTokens = summarizeTokens;
+exports.formatTokenBreakdown = formatTokenBreakdown;
 exports.sumTokenTotals = sumTokenTotals;
 /** Column label for `TokenSummary.total` on any surface. */
 exports.TOKEN_TOTAL_LABEL = 'Total (incl. cache)';
 /** Column label for `TokenSummary.context` on any surface. */
 exports.TOKEN_CONTEXT_LABEL = 'Context';
+/** Label for a session's own (main-thread) tokens when subagents are shown beside it. */
+exports.TOKEN_MAIN_THREAD_LABEL = 'Main thread';
+/** Label for the tokens a session's subagents used. */
+exports.TOKEN_SUBAGENTS_LABEL = 'Subagents';
+/** Label for main thread plus subagents. */
+exports.TOKEN_SESSION_TOTAL_LABEL = 'Session total (incl. subagents)';
 function count(value) {
     return typeof value === 'number' && Number.isFinite(value) && value > 0 ? Math.floor(value) : 0;
 }
@@ -54,19 +61,59 @@ function summarizeTokens(totals) {
         cacheRead,
         cacheWrite,
         cacheHitRatio: context > 0 ? cacheRead / context : null,
+        reasoning: count(totals.reasoningTokens),
+        billedOutsideBuckets: Math.max(0, total - fourBucket),
     };
 }
-/** Sum several token records bucket-by-bucket before summarizing. */
+/**
+ * One-line breakdown whose parts add up to the headline:
+ * `1.2M total incl. cache (12k in · 1.1M cache read · 40k cache write · 30k out)`.
+ * Pass the surface's own number formatter; the default prints plain integers.
+ */
+function formatTokenBreakdown(summary, fmt = (n) => String(n)) {
+    const parts = [
+        `${fmt(summary.input)} in`,
+        `${fmt(summary.cacheRead)} cache read`,
+        `${fmt(summary.cacheWrite)} cache write`,
+        `${fmt(summary.output)} out`,
+    ];
+    if (summary.billedOutsideBuckets > 0) {
+        parts.push(`${fmt(summary.billedOutsideBuckets)} reasoning`);
+    }
+    return `${fmt(summary.total)} total incl. cache (${parts.join(' · ')})`;
+}
+/**
+ * Sum several token records bucket-by-bucket before summarizing. `totalTokens`
+ * is summed only when every record carries one, so provider-aware totals
+ * survive the sum instead of falling back to the four-bucket arithmetic.
+ */
 function sumTokenTotals(records) {
     let inputTokens = 0;
     let outputTokens = 0;
     let cacheWriteTokens = 0;
     let cacheReadTokens = 0;
+    let reasoningTokens = 0;
+    let totalTokens = 0;
+    let allHaveTotal = records.length > 0;
     for (const record of records) {
         inputTokens += count(record.inputTokens);
         outputTokens += count(record.outputTokens);
         cacheWriteTokens += count(record.cacheWriteTokens);
         cacheReadTokens += count(record.cacheReadTokens);
+        reasoningTokens += count(record.reasoningTokens);
+        if (typeof record.totalTokens === 'number' && Number.isFinite(record.totalTokens)) {
+            totalTokens += count(record.totalTokens);
+        }
+        else {
+            allHaveTotal = false;
+        }
     }
-    return { inputTokens, outputTokens, cacheWriteTokens, cacheReadTokens };
+    return {
+        inputTokens,
+        outputTokens,
+        cacheWriteTokens,
+        cacheReadTokens,
+        reasoningTokens,
+        ...(allHaveTotal ? { totalTokens } : {}),
+    };
 }

package/dist/types/codex.d.ts

@@ -287,4 +287,8 @@ export interface CodexDbThread {
     git_branch?: string;
     git_commit?: string;
     forked_from_id?: string;
+    /** `cli`, `exec`, … or a JSON object string for spawned subagents. */
+    source?: string;
+    agent_nickname?: string | null;
+    agent_role?: string | null;
 }

package/dist/types/sessionEvent.d.ts

@@ -45,6 +45,13 @@ export interface SessionMessage {
     usage?: MessageUsage;
     /** Authoritative disjoint usage projection, when normalized by a provider parser. */
     normalizedUsage?: import('../usageNormalization').NormalizedUsage;
+    /**
+     * `'correction'` marks usage that tops up a call already counted (a later
+     * split line of the same response reported more tokens). Add it to token and
+     * cost totals, but do not count another call or context sample. Absent means
+     * a regular call.
+     */
+    usageKind?: 'call' | 'correction';
     /** Message content (may be string or structured content) */
     content?: unknown;
     /** Provider stop reason (`end_turn`, `tool_use`, …) when the transcript carries one. */
@@ -222,6 +229,12 @@ export interface TokenUsage {
     reportedCost?: number;
     /** Number of reasoning/thinking tokens */
     reasoningTokens?: number;
+    /**
+     * `'correction'` tops up a call already counted (a later split line of the
+     * same response reported more tokens): add it to totals, but do not count a
+     * call or treat it as a context-size sample.
+     */
+    usageKind?: 'call' | 'correction';
 }
 /**
  * Tool invocation record.
@@ -299,6 +312,7 @@ export interface TimelineEvent {
         toolName?: string;
         toolUseId?: string;
         isError?: boolean;
+        /** Tokens billed for this response, cache included (see `summarizeTokens`). */
         tokenCount?: number;
         fullText?: string;
         /** Context tokens before compaction */
@@ -395,6 +409,14 @@ export interface SubagentStats {
     inputTokens: number;
     /** Total output tokens generated by this subagent */
     outputTokens: number;
+    /** Tokens read from the prompt cache by this subagent */
+    cacheReadTokens?: number;
+    /** Tokens written to the prompt cache by this subagent */
+    cacheWriteTokens?: number;
+    /** Reasoning tokens reported by this subagent (display only) */
+    reasoningTokens?: number;
+    /** Every billed token, cache included — the same vocabulary as `summarizeTokens().total` */
+    totalTokens?: number;
     /** Timestamp when subagent started (first event) */
     startTime?: Date;
     /** Timestamp when subagent ended (last event) */