sidekick-shared 0.23.1 → 0.24.0

package/dist/modelInfo.d.ts

@@ -24,16 +24,20 @@ export interface ModelPricing {
     cacheWriteCostPerMillion: number;
     cacheReadCostPerMillion: number;
 }
-/** Token usage for cost calculation. */
+/**
+ * Token usage for the legacy cost calculation contract.
+ * @deprecated Use NormalizedUsage and calculateNormalizedUsageCost. This shape
+ * cannot state whether reasoning is already included in output.
+ */
 export interface CostTokenUsage {
     inputTokens: number;
     outputTokens: number;
     cacheWriteTokens: number;
     cacheReadTokens: number;
     /**
-     * OpenAI o-series / Codex "reasoning" tokens. Billed at the output rate by
-     * OpenAI, so we multiply by `outputCostPerMillion` inside calculateCost.
-     * Optional for backward compatibility with existing callers.
+     * Legacy disjoint reasoning category. The compatibility calculator always
+     * adds it at the output rate, even when a provider already included it in
+     * output. Use NormalizedUsage to state inclusion semantics.
      */
     reasoningTokens?: number;
 }
@@ -55,7 +59,10 @@ export interface ModelInfo {
 }
 /** Provenance for a displayed cost value. */
 export type CostSource = 'reported' | 'estimated' | 'unpriced';
-/** Input for cost calculation that preserves reported-vs-estimated provenance. */
+/**
+ * Input for the legacy cost calculation contract.
+ * @deprecated Use NormalizedUsageCostInput.
+ */
 export interface CostProvenanceInput {
     usage: CostTokenUsage;
     modelId: string;
@@ -128,8 +135,9 @@ export declare function getModelInfo(modelId: string): ModelInfo;
 /**
  * Calculates cost from token usage and an explicit pricing object.
  *
- * Reasoning tokens (OpenAI o-series / Codex) are billed at the output rate,
- * matching OpenAI's billing behavior.
+ * Legacy behavior treats reasoning as disjoint and adds it at the output rate.
+ * @deprecated Use calculateNormalizedUsageCost. This legacy function always
+ * adds reasoning to output and cannot represent provider inclusion semantics.
  */
 export declare function calculateCostWithPricing(usage: CostTokenUsage, pricing: ModelPricing): number;
 /**
@@ -137,11 +145,13 @@ export declare function calculateCostWithPricing(usage: CostTokenUsage, pricing:
  *
  * Returns `null` for unknown models. Callers should render `—` in that case,
  * not $0 — so users don't confuse "missing pricing" with "free".
+ * @deprecated Use calculateNormalizedUsageCost.
  */
 export declare function calculateCost(usage: CostTokenUsage, modelId: string): number | null;
 /**
  * Calculates cost while preserving whether the value was provider-reported,
  * locally estimated from pricing, or unavailable because the model is unpriced.
+ * @deprecated Use calculateNormalizedUsageCost.
  */
 export declare function calculateCostWithProvenance(input: CostProvenanceInput): CostWithProvenance;
 /**

package/dist/modelInfo.js

@@ -386,8 +386,9 @@ function getModelInfo(modelId) {
 /**
  * Calculates cost from token usage and an explicit pricing object.
  *
- * Reasoning tokens (OpenAI o-series / Codex) are billed at the output rate,
- * matching OpenAI's billing behavior.
+ * Legacy behavior treats reasoning as disjoint and adds it at the output rate.
+ * @deprecated Use calculateNormalizedUsageCost. This legacy function always
+ * adds reasoning to output and cannot represent provider inclusion semantics.
  */
 function calculateCostWithPricing(usage, pricing) {
     const reasoning = usage.reasoningTokens ?? 0;
@@ -402,6 +403,7 @@ function calculateCostWithPricing(usage, pricing) {
  *
  * Returns `null` for unknown models. Callers should render `—` in that case,
  * not $0 — so users don't confuse "missing pricing" with "free".
+ * @deprecated Use calculateNormalizedUsageCost.
  */
 function calculateCost(usage, modelId) {
     const pricing = getModelPricing(modelId);
@@ -412,6 +414,7 @@ function calculateCost(usage, modelId) {
 /**
  * Calculates cost while preserving whether the value was provider-reported,
  * locally estimated from pricing, or unavailable because the model is unpriced.
+ * @deprecated Use calculateNormalizedUsageCost.
  */
 function calculateCostWithProvenance(input) {
     if (typeof input.reportedCostUsd === 'number' && Number.isFinite(input.reportedCostUsd)) {

package/dist/node.d.ts

@@ -7,3 +7,7 @@
  */
 export { hydratePricingCatalog, normalizeLiteLlmCatalog, LITELLM_CATALOG_URL, } from './pricingCatalog';
 export type { HydrateOptions, HydrateResult } from './pricingCatalog';
+export { listRecentSessions, readSessionTranscript } from './sessionTranscripts';
+export type { ProviderSessionIndex, ListRecentSessionsOptions } from './sessionTranscripts';
+export { ObservedSessionCollector, observedSessionSourceFromProvider, fileFingerprint, } from './observedSessionCollector';
+export type { ObservedSessionReference, ObservedSessionCollectionSource, ObservedSessionDiagnosticKind, ObservedSessionDiagnostic, ObservedSessionCollection, ObservedSessionCollectorOptions, } from './observedSessionCollector';

package/dist/node.js

@@ -7,8 +7,15 @@
  * for browser bundles — use `sidekick-shared/browser` there.
  */
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.LITELLM_CATALOG_URL = exports.normalizeLiteLlmCatalog = exports.hydratePricingCatalog = void 0;
+exports.fileFingerprint = exports.observedSessionSourceFromProvider = exports.ObservedSessionCollector = exports.readSessionTranscript = exports.listRecentSessions = exports.LITELLM_CATALOG_URL = exports.normalizeLiteLlmCatalog = exports.hydratePricingCatalog = void 0;
 var pricingCatalog_1 = require("./pricingCatalog");
 Object.defineProperty(exports, "hydratePricingCatalog", { enumerable: true, get: function () { return pricingCatalog_1.hydratePricingCatalog; } });
 Object.defineProperty(exports, "normalizeLiteLlmCatalog", { enumerable: true, get: function () { return pricingCatalog_1.normalizeLiteLlmCatalog; } });
 Object.defineProperty(exports, "LITELLM_CATALOG_URL", { enumerable: true, get: function () { return pricingCatalog_1.LITELLM_CATALOG_URL; } });
+var sessionTranscripts_1 = require("./sessionTranscripts");
+Object.defineProperty(exports, "listRecentSessions", { enumerable: true, get: function () { return sessionTranscripts_1.listRecentSessions; } });
+Object.defineProperty(exports, "readSessionTranscript", { enumerable: true, get: function () { return sessionTranscripts_1.readSessionTranscript; } });
+var observedSessionCollector_1 = require("./observedSessionCollector");
+Object.defineProperty(exports, "ObservedSessionCollector", { enumerable: true, get: function () { return observedSessionCollector_1.ObservedSessionCollector; } });
+Object.defineProperty(exports, "observedSessionSourceFromProvider", { enumerable: true, get: function () { return observedSessionCollector_1.observedSessionSourceFromProvider; } });
+Object.defineProperty(exports, "fileFingerprint", { enumerable: true, get: function () { return observedSessionCollector_1.fileFingerprint; } });

package/dist/observedSessionCollector.d.ts

@@ -0,0 +1,68 @@
+import type { ObservedAgentSessionV1 } from './types/observedSessionV1';
+import type { SessionProviderBase } from './providers/types';
+export interface ObservedSessionReference {
+    sessionId: string;
+    /** Opaque source locator used only by the source implementation. Never emitted in diagnostics. */
+    sourceKey?: string;
+    fingerprintHint?: string;
+}
+export interface ObservedSessionCollectionSource<T = unknown> {
+    providerId: string;
+    discover(): Promise<ObservedSessionReference[]> | ObservedSessionReference[];
+    read(reference: ObservedSessionReference): Promise<T> | T;
+    dispose?(): void;
+}
+export type ObservedSessionDiagnosticKind = 'provider-discovery-failed' | 'session-read-failed' | 'provider-recovered' | 'session-recovered';
+/** Content-safe diagnostics: identifiers and retry metadata only. */
+export interface ObservedSessionDiagnostic {
+    kind: ObservedSessionDiagnosticKind;
+    providerId: string;
+    sessionId?: string;
+    attempt?: number;
+    retryAt?: number;
+}
+export interface ObservedSessionCollection<T = unknown> {
+    providerId: string;
+    sessionId: string;
+    value: T;
+}
+export interface ObservedSessionCollectorOptions<T = unknown> {
+    sources: ObservedSessionCollectionSource<T>[];
+    initialBackoffMs?: number;
+    maxBackoffMs?: number;
+    clock?: {
+        now(): number;
+    };
+    fingerprint?: (source: ObservedSessionCollectionSource<T>, reference: ObservedSessionReference) => Promise<string | null> | string | null;
+    onObservation?: (observation: ObservedSessionCollection<T>) => void;
+    onDiagnostic?: (diagnostic: ObservedSessionDiagnostic) => void;
+}
+/**
+ * One-shot, host-scheduled observed-session collection with independent
+ * provider/session isolation and bounded retry state.
+ */
+export declare class ObservedSessionCollector<T = unknown> {
+    private readonly options;
+    private readonly failures;
+    private readonly initialBackoffMs;
+    private readonly maxBackoffMs;
+    private readonly clock;
+    constructor(options: ObservedSessionCollectorOptions<T>);
+    collect(): Promise<ObservedSessionCollection<T>[]>;
+    reset(): void;
+    dispose(): void;
+    private collectSource;
+    private collectSession;
+    private fingerprint;
+    private fail;
+    private recover;
+    private emitDiagnostic;
+    private key;
+}
+/**
+ * Adapt a provider using path-only discovery and independent adapter reads, so
+ * one malformed session cannot reject discovery of its healthy siblings.
+ */
+export declare function observedSessionSourceFromProvider(provider: SessionProviderBase, cwd: string): ObservedSessionCollectionSource<ObservedAgentSessionV1>;
+/** Size/mtime fingerprint suitable for retry bypass; returns null for synthetic DB locators. */
+export declare function fileFingerprint(sourcePath: string): string | null;

package/dist/observedSessionCollector.js

@@ -0,0 +1,178 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ObservedSessionCollector = void 0;
+exports.observedSessionSourceFromProvider = observedSessionSourceFromProvider;
+exports.fileFingerprint = fileFingerprint;
+const node_fs_1 = require("node:fs");
+const observedSessionV1_1 = require("./types/observedSessionV1");
+/**
+ * One-shot, host-scheduled observed-session collection with independent
+ * provider/session isolation and bounded retry state.
+ */
+class ObservedSessionCollector {
+    options;
+    failures = new Map();
+    initialBackoffMs;
+    maxBackoffMs;
+    clock;
+    constructor(options) {
+        this.options = options;
+        this.initialBackoffMs = Math.max(1, options.initialBackoffMs ?? 30_000);
+        this.maxBackoffMs = Math.max(this.initialBackoffMs, options.maxBackoffMs ?? 5 * 60_000);
+        this.clock = options.clock ?? { now: () => Date.now() };
+    }
+    async collect() {
+        const nested = await Promise.all(this.options.sources.map((source) => this.collectSource(source)));
+        return nested.flat();
+    }
+    reset() {
+        this.failures.clear();
+    }
+    dispose() {
+        for (const source of this.options.sources) {
+            try {
+                source.dispose?.();
+            }
+            catch {
+                // Disposal is best-effort and isolated per source.
+            }
+        }
+        this.reset();
+    }
+    async collectSource(source) {
+        const discoveryKey = `${source.providerId}\0$discovery`;
+        const discoveryFailure = this.failures.get(discoveryKey);
+        if (discoveryFailure && this.clock.now() < discoveryFailure.retryAt)
+            return [];
+        let references;
+        try {
+            references = await source.discover();
+            this.recover(discoveryKey, 'provider-recovered', source.providerId);
+        }
+        catch (error) {
+            this.fail(discoveryKey, 'provider-discovery-failed', source.providerId, undefined, null, error);
+            return [];
+        }
+        const activeKeys = new Set(references.map((ref) => this.key(source.providerId, ref.sessionId)));
+        for (const key of this.failures.keys()) {
+            if (key.startsWith(`${source.providerId}\0`) &&
+                !key.endsWith('$discovery') &&
+                !activeKeys.has(key)) {
+                this.failures.delete(key);
+            }
+        }
+        const rows = await Promise.all(references.map((reference) => this.collectSession(source, reference)));
+        return rows.filter((row) => row !== null);
+    }
+    async collectSession(source, reference) {
+        const key = this.key(source.providerId, reference.sessionId);
+        const fingerprint = await this.fingerprint(source, reference);
+        const prior = this.failures.get(key);
+        if (prior && prior.fingerprint === fingerprint && this.clock.now() < prior.retryAt)
+            return null;
+        let value;
+        try {
+            value = await source.read(reference);
+        }
+        catch (error) {
+            this.fail(key, 'session-read-failed', source.providerId, reference.sessionId, fingerprint, error);
+            return null;
+        }
+        this.recover(key, 'session-recovered', source.providerId, reference.sessionId);
+        const observation = { providerId: source.providerId, sessionId: reference.sessionId, value };
+        try {
+            this.options.onObservation?.(observation);
+        }
+        catch {
+            // Host callbacks cannot turn a healthy provider read into a collection failure.
+        }
+        return observation;
+    }
+    async fingerprint(source, reference) {
+        try {
+            return this.options.fingerprint
+                ? await this.options.fingerprint(source, reference)
+                : (reference.fingerprintHint ?? null);
+        }
+        catch {
+            return reference.fingerprintHint ?? null;
+        }
+    }
+    fail(key, kind, providerId, sessionId, fingerprint, error) {
+        const previous = this.failures.get(key);
+        const signature = failureSignature(error);
+        const fingerprintChanged = previous?.fingerprint !== fingerprint;
+        const attempt = previous && !fingerprintChanged ? previous.attempt + 1 : 1;
+        const delay = Math.min(this.maxBackoffMs, this.initialBackoffMs * 2 ** (attempt - 1));
+        const retryAt = this.clock.now() + delay;
+        const reportedSignature = previous?.reportedSignature ?? '';
+        this.failures.set(key, {
+            attempt,
+            retryAt,
+            fingerprint,
+            reportedSignature: signature,
+        });
+        if (signature !== reportedSignature || fingerprintChanged) {
+            this.emitDiagnostic({ kind, providerId, sessionId, attempt, retryAt });
+        }
+    }
+    recover(key, kind, providerId, sessionId) {
+        const prior = this.failures.get(key);
+        if (!prior)
+            return;
+        this.failures.delete(key);
+        this.emitDiagnostic({ kind, providerId, sessionId, attempt: prior.attempt });
+    }
+    emitDiagnostic(diagnostic) {
+        try {
+            this.options.onDiagnostic?.(diagnostic);
+        }
+        catch {
+            // Diagnostics are observational and never affect collection isolation.
+        }
+    }
+    key(providerId, sessionId) {
+        return `${providerId}\0${sessionId}`;
+    }
+}
+exports.ObservedSessionCollector = ObservedSessionCollector;
+/**
+ * Adapt a provider using path-only discovery and independent adapter reads, so
+ * one malformed session cannot reject discovery of its healthy siblings.
+ */
+function observedSessionSourceFromProvider(provider, cwd) {
+    const adapter = (0, observedSessionV1_1.createProviderSessionAdapterV1)(provider);
+    return {
+        providerId: provider.id,
+        discover() {
+            return provider.findAllSessions(cwd).map((sessionPath) => ({
+                sessionId: provider.getSessionId(sessionPath),
+                sourceKey: sessionPath,
+                fingerprintHint: provider.getSessionMetadata?.(sessionPath)?.mtime.getTime().toString() ??
+                    fileFingerprint(sessionPath) ??
+                    undefined,
+            }));
+        },
+        read(reference) {
+            if (!reference.sourceKey)
+                throw new Error('session source unavailable');
+            return adapter.read(reference.sourceKey, cwd);
+        },
+        dispose: () => adapter.dispose(),
+    };
+}
+/** Size/mtime fingerprint suitable for retry bypass; returns null for synthetic DB locators. */
+function fileFingerprint(sourcePath) {
+    try {
+        const stat = (0, node_fs_1.statSync)(sourcePath);
+        return `${stat.size}:${stat.mtimeMs}`;
+    }
+    catch {
+        return null;
+    }
+}
+function failureSignature(error) {
+    if (error instanceof Error)
+        return `${error.name}\0${error.message}`;
+    return typeof error === 'string' ? error : Object.prototype.toString.call(error);
+}

package/dist/parsers/codexParser.js

@@ -18,6 +18,7 @@ exports.normalizeCodexToolInput = normalizeCodexToolInput;
 exports.extractPatchFilePaths = extractPatchFilePaths;
 const codex_1 = require("../types/codex");
 const openCodeParser_1 = require("./openCodeParser");
+const usageNormalization_1 = require("../usageNormalization");
 function reportedCompaction(tokensBefore, tokensAfter) {
     if (typeof tokensBefore !== 'number' ||
         typeof tokensAfter !== 'number' ||
@@ -780,16 +781,28 @@ class CodexRolloutParser {
         const normalizedRateLimits = normalizeRateLimits(rateLimits);
         if (!usage && !normalizedRateLimits)
             return [];
-        const mappedUsage = usage
+        const normalizedUsage = usage
+            ? (0, usageNormalization_1.normalizeProviderUsage)({
+                semantics: 'openai',
+                provider: 'openai',
+                source: 'codex-token-count',
+                model: this.currentModel || undefined,
+                inputTokens: usage.input_tokens,
+                outputTokens: usage.output_tokens,
+                cacheReadTokens: usage.cached_input_tokens,
+                reasoningTokens: usage.reasoning_output_tokens,
+            })
+            : undefined;
+        const mappedUsage = normalizedUsage
             ? {
                 // Codex reports cached_input_tokens as a subset of input_tokens,
                 // while MessageUsage categories are disjoint. Normalize once here
                 // so aggregation and pricing do not count cached input twice.
-                input_tokens: Math.max(0, (usage.input_tokens || 0) - (usage.cached_input_tokens || 0)),
-                output_tokens: usage.output_tokens || 0,
-                cache_read_input_tokens: usage.cached_input_tokens || 0,
-                cache_creation_input_tokens: 0,
-                reasoning_tokens: usage.reasoning_output_tokens || 0,
+                input_tokens: normalizedUsage.uncachedInputTokens,
+                output_tokens: normalizedUsage.outputTokens,
+                cache_read_input_tokens: normalizedUsage.cacheReadTokens,
+                cache_creation_input_tokens: normalizedUsage.cacheWriteTokens,
+                reasoning_tokens: normalizedUsage.reasoningTokens,
             }
             : undefined;
         if (usage) {
@@ -804,9 +817,11 @@ class CodexRolloutParser {
                     sourceLabel: 'token count',
                     model: this.currentModel || undefined,
                     usage: mappedUsage,
+                    normalizedUsage,
                     content: [],
                 },
                 timestamp,
+                providerMetadata: { providerId: 'codex', source: 'codex-rollout' },
                 rateLimits: normalizedRateLimits,
             },
         ];

package/dist/parsers/openCodeParser.js

@@ -18,6 +18,7 @@ exports.normalizeToolInput = normalizeToolInput;
 exports.convertOpenCodeMessage = convertOpenCodeMessage;
 exports.parseDbMessageData = parseDbMessageData;
 exports.parseDbPartData = parseDbPartData;
+const usageNormalization_1 = require("../usageNormalization");
 /**
  * OpenCode → Claude Code tool name mapping.
  * OpenCode uses lowercase names; downstream code expects PascalCase.
@@ -322,7 +323,7 @@ function convertAssistantMessage(message, parts) {
         }
     }
     // Build usage data from message tokens
-    const reportedCost = message.cost && message.cost > 0
+    const reportedCost = typeof message.cost === 'number' && Number.isFinite(message.cost) && message.cost >= 0
         ? message.cost
         : stepFinishCost > 0
             ? stepFinishCost
@@ -335,6 +336,23 @@ function convertAssistantMessage(message, parts) {
         reported_cost: reportedCost,
         reasoning_tokens: message.tokens.reasoning || 0,
     };
+    const normalizedUsage = (0, usageNormalization_1.normalizeProviderUsage)({
+        semantics: message.providerID === 'openai'
+            ? 'openai'
+            : message.providerID === 'anthropic'
+                ? 'anthropic'
+                : 'sidekick',
+        provider: message.providerID ?? 'opencode',
+        source: 'opencode-message',
+        model: message.modelID,
+        inputTokens: message.tokens.input,
+        outputTokens: message.tokens.output,
+        cacheReadTokens: message.tokens.cacheRead,
+        cacheWriteTokens: message.tokens.cacheWrite,
+        reasoningTokens: message.tokens.reasoning,
+        reasoningIncludedInOutput: message.providerID === 'openai',
+        reportedCostUsd: reportedCost,
+    });
     const timestamp = toISOString(message.time.completed || message.time.created);
     const retryAttempts = parts
         .filter((part) => part.type === 'retry')
@@ -353,10 +371,13 @@ function convertAssistantMessage(message, parts) {
                 id: message.id,
                 model: message.modelID,
                 usage,
+                normalizedUsage,
                 content,
             },
             timestamp,
             providerMetadata: {
+                providerId: message.providerID ?? 'opencode',
+                source: 'opencode-message',
                 ...(retryAttempts.length > 0 ? { retryAttempts } : {}),
                 ...(finishReasons.length > 0 ? { finishReasons } : {}),
                 ...(message.error ? { providerError: message.error } : {}),

package/dist/parsers/subagentTraceParser.js

@@ -334,13 +334,19 @@ function rawToSessionEvent(raw) {
             }
         }
     }
-    return {
-        type: mappedType,
-        message: message || { role: 'unknown' },
+    const common = {
         timestamp,
         isSidechain: raw.isSidechain,
         permissionMode: raw.permissionMode,
-        tool,
-        result,
     };
+    if (mappedType === 'user' || mappedType === 'assistant') {
+        return { ...common, type: mappedType, message: message || { role: 'unknown' }, tool };
+    }
+    if (mappedType === 'summary') {
+        return { ...common, type: 'summary', message: message || { role: 'summary' } };
+    }
+    if (mappedType === 'tool_use') {
+        return tool ? { ...common, type: 'tool_use', message, tool } : null;
+    }
+    return result ? { ...common, type: 'tool_result', message, result } : null;
 }

package/dist/providers/claudeCode.js

@@ -52,6 +52,8 @@ const jsonl_1 = require("../parsers/jsonl");
 const sessionPathResolver_1 = require("../parsers/sessionPathResolver");
 const subagentScanner_1 = require("../parsers/subagentScanner");
 const modelContext_1 = require("../modelContext");
+const sessionEvent_1 = require("../schemas/sessionEvent");
+const usageNormalization_1 = require("../usageNormalization");
 /** Type guard for content blocks with a `type` string property */
 function isTypedBlock(block) {
     return (block !== null &&
@@ -102,7 +104,11 @@ class ClaudeCodeReader {
     constructor(sessionPath) {
         this.sessionPath = sessionPath;
         this.parser = new jsonl_1.JsonlParser({
-            onEvent: (e) => this.events.push(e),
+            onEvent: (raw) => {
+                for (const event of (0, sessionEvent_1.extractSessionEvents)(raw)) {
+                    this.events.push(normalizeClaudeUsage(event));
+                }
+            },
             onError: (_err, _line) => {
                 // Silently skip parse errors — no logging framework dependency
             },
@@ -180,6 +186,44 @@ class ClaudeCodeReader {
         return this._wasTruncated;
     }
 }
+function normalizeClaudeUsage(event) {
+    const message = event.message;
+    const usage = message?.usage;
+    if (!message || !usage) {
+        return {
+            ...event,
+            providerMetadata: {
+                ...event.providerMetadata,
+                providerId: 'claude-code',
+                source: 'claude-code-jsonl',
+            },
+        };
+    }
+    return {
+        ...event,
+        message: {
+            ...message,
+            normalizedUsage: (0, usageNormalization_1.normalizeProviderUsage)({
+                semantics: 'anthropic',
+                provider: 'anthropic',
+                source: 'claude-code-jsonl',
+                model: message.model,
+                inputTokens: usage.input_tokens,
+                outputTokens: usage.output_tokens,
+                cacheReadTokens: usage.cache_read_input_tokens,
+                cacheWriteTokens: usage.cache_creation_input_tokens,
+                reasoningTokens: usage.reasoning_tokens,
+                reasoningIncludedInOutput: false,
+                reportedCostUsd: usage.reported_cost,
+            }),
+        },
+        providerMetadata: {
+            ...event.providerMetadata,
+            providerId: 'claude-code',
+            source: 'claude-code-jsonl',
+        },
+    };
+}
 /**
  * Session provider for Claude Code CLI.
  *

package/dist/providers/codex.js

@@ -53,6 +53,7 @@ const codexParser_1 = require("../parsers/codexParser");
 const codexDatabase_1 = require("./codexDatabase");
 const codexProfiles_1 = require("../codexProfiles");
 const modelContext_1 = require("../modelContext");
+const usageNormalization_1 = require("../usageNormalization");
 // ---------------------------------------------------------------------------
 // Helper functions
 // ---------------------------------------------------------------------------
@@ -522,13 +523,22 @@ class CodexReader {
             // Propagate last token usage snapshot to the provider
             const lastUsage = this.parser.getLastTokenUsage();
             if (lastUsage && this.onTokenUsage) {
-                const cacheReadTokens = lastUsage.cached_input_tokens || 0;
+                const normalized = (0, usageNormalization_1.normalizeProviderUsage)({
+                    semantics: 'openai',
+                    provider: 'openai',
+                    source: 'codex-reader-snapshot',
+                    model: this.parser.getCurrentModel() || undefined,
+                    inputTokens: lastUsage.input_tokens,
+                    outputTokens: lastUsage.output_tokens,
+                    cacheReadTokens: lastUsage.cached_input_tokens,
+                    reasoningTokens: lastUsage.reasoning_output_tokens,
+                });
                 this.onTokenUsage({
-                    inputTokens: Math.max(0, (lastUsage.input_tokens || 0) - cacheReadTokens),
-                    outputTokens: lastUsage.output_tokens || 0,
-                    cacheWriteTokens: 0,
-                    cacheReadTokens,
-                    reasoningTokens: lastUsage.reasoning_output_tokens || 0,
+                    inputTokens: normalized.uncachedInputTokens,
+                    outputTokens: normalized.outputTokens,
+                    cacheWriteTokens: normalized.cacheWriteTokens,
+                    cacheReadTokens: normalized.cacheReadTokens,
+                    reasoningTokens: normalized.reasoningTokens,
                     model: this.parser.getCurrentModel() || 'unknown',
                     timestamp: new Date(),
                 });
@@ -868,7 +878,7 @@ class CodexProvider {
                             }
                         }
                         // Accumulate tokens from usage events
-                        if (event.message.usage) {
+                        if (event.message?.usage) {
                             stats.inputTokens += event.message.usage.input_tokens || 0;
                             stats.outputTokens += event.message.usage.output_tokens || 0;
                         }

package/dist/report/transcriptParser.d.ts

@@ -1,15 +1,7 @@
-/**
- * Parse Claude Code JSONL session files into typed transcript entries
- * with full, untruncated content suitable for HTML report rendering.
- */
+/** Report compatibility adapters over the canonical transcript projection. */
 import type { SessionEvent } from '../types/sessionEvent';
 import type { TranscriptEntry } from './types';
-/**
- * Parse a JSONL session file into an array of TranscriptEntry objects.
- *
- * Unlike the FollowEvent pipeline (which truncates to 120-200 chars),
- * this preserves full message content for HTML report rendering.
- */
+/** Parse a Claude Code JSONL session through the canonical provider reader. */
 export declare function parseTranscript(sessionPath: string): TranscriptEntry[];
-/** Parse canonical provider events into transcript entries. */
+/** Project canonical provider events into the legacy report transcript shape. */
 export declare function parseTranscriptFromEvents(events: SessionEvent[]): TranscriptEntry[];