import * as fs from 'fs';

import { readFile } from 'node:fs/promises';

import * as os from 'os';

import * as path from 'path';

// Removed tinyglobby dependency - using native fs instead

// Removed zod dependency - using native validation instead

import { calculateCostBreakdown, getModelRatesPerMillion } from './pricing';

import { addClaudeReferenceUsage, claudeReferenceUsage, hasKnownClaudeCacheCreationShape, normalizeClaudeNativeUsage } from './claudeReferenceUsage';

import { detachedPromptPrefix, isRetryDuplicatePrompt } from './promptDedup';

import {

dayKeyInZone,

formatHourLabel,

hourKeyInZone,

monthKeyInZone,

rollingDayKeysFromDayKey,

} from './dateKeys';

import { I18n } from './i18n';

import { DayUsage } from './heatmap';

import { ShareInput, ShareRange, rangeLabel as shareRangeLabel } from './shareCard';

import {

scanUsageManifest,

sortUsageFilesByEarliestTimestamp,

UsageManifest,

} from './claudeUsageFiles';

import { LoadUsageDiagnostics } from './refreshDiagnostics';

import { ownRecordValue, setRecordValue } from './ownRecord';

import { classifyPromptTextOrigin } from './promptOrigin';

import {

AttributionEntry,

AttributionScope,

BranchUsage,

ClaudeUsageRecord,

CostlyMessage,

ContentAnalysis,

ContextWindowInfo,

FrameworkOverheadKind,

ContentSlice,

ProjectGroup,

ProjectUsage,

SessionData,

SessionUsage,

SkillUse,

ThinkingShare,

UsageAttribution,

UsageData,

WorkflowUsage,

} from './types';

/** In-memory provenance only; never accept this flag from JSONL metadata. */

type ClaudeSessionEvidenceRecord = ClaudeUsageRecord & { _unownedAgentSession?: true };

export type ClaudeSessionUsage = SessionUsage & { _unownedAgentSession?: true };

/** Flat agent files have no path-proven parent. Keep their usage/session rows,

* but do not treat their basename as evidence of an independent conversation.

* Record sessionId/isSidechain metadata is not an established ownership contract

* here; nested agents retain the existing parent-directory contract. No I/O. */

export function tagClaudeSessionEvidence(record: ClaudeUsageRecord, filePath: string): void {

const tagged = record as ClaudeSessionEvidenceRecord;

if (/(?:^|[\\/])projects[\\/][^\\/]+[\\/]agent-[^\\/]+\.jsonl$/.test(filePath)) {

tagged._unownedAgentSession = true;

} else {

delete tagged._unownedAgentSession;

}

}

/** One-pass bounds; spreading an unbounded history exceeds V8's argument limit. */

export function recordTimestampBounds(

records: Iterable<Pick<ClaudeUsageRecord, 'timestamp'>>,

ignoreInvalid = true,

): { first: number; last: number } {

let first = Infinity;

let last = -Infinity;

for (const record of records) {

const timestamp = Date.parse(record.timestamp);

if (!Number.isFinite(timestamp)) {

if (!ignoreInvalid) return { first: NaN, last: NaN };

continue;

}

if (timestamp < first) first = timestamp;

if (timestamp > last) last = timestamp;

}

return first === Infinity ? { first: 0, last: 0 } : { first, last };

}

// Constants

const CLAUDE_CONFIG_DIR_ENV = 'CLAUDE_CONFIG_DIR';

const CLAUDE_PROJECTS_DIR_NAME = 'projects';

const DEFAULT_CLAUDE_CODE_PATH = '.claude';

const USAGE_DATA_GLOB_PATTERN = '**/*.jsonl';

const USER_HOME_DIR = os.homedir();

// XDG config directory

const XDG_CONFIG_DIR = process.env.XDG_CONFIG_HOME || path.join(USER_HOME_DIR, '.config');

const DEFAULT_CLAUDE_CONFIG_PATH = path.join(XDG_CONFIG_DIR, 'claude');

// Identify usage records by structural shape only.

//

// Previously we dropped any record whose secondary fields had an unexpected

// type (e.g. `model` is null, `requestId` is a number). That cost us records

// from proxies and from new Claude Code features (xhigh / ultracode /

// workflow) that occasionally write atypical field types. Now we accept any

// record that has the minimum it takes to count tokens — timestamp + the

// numeric token fields — and downstream code is responsible for coercing the

// optional fields safely.

//

// The companion function `validationDropReason` lets the loader log *why* a

// record was rejected so users can spot format drift without us guessing.

export function validateUsageRecord(data: any): data is ClaudeUsageRecord {

if (!data || typeof data !== 'object') return false;

if (typeof data.timestamp !== 'string') return false;

if (!data.message || typeof data.message !== 'object') return false;

if (!data.message.usage || typeof data.message.usage !== 'object') return false;

const usage = data.message.usage;

// We require both token fields to be numbers — they are the whole point of

// the record. Anything else is best-effort: a missing model, a null

// requestId, an isApiErrorMessage that's "true" (string) — they get

// accepted now, and the aggregators treat the value as 0/undefined.

if (typeof usage.input_tokens !== 'number') return false;

if (typeof usage.output_tokens !== 'number') return false;

return true;

}

/** Optional model metadata must not retain arbitrary objects or collide with

* object-map prototypes. Keep valid numeric usage, with no invented price for

* malformed labels. Absent/null labels retain the established skip behavior. */

function usageModelName(value: unknown): string | undefined {

if (value === undefined || value === null || value === '') return undefined;

if (typeof value !== 'string' || value.length > 256 || /[\x00-\x1f\x7f]/.test(value) ||

Object.prototype.hasOwnProperty.call(Object.prototype, value)) return '<unknown>';

return value;

}

/** Keep only usage evidence after content analysis has inspected the raw line.

* A usage-bearing assistant row may contain a very large response/tool body;

* retaining the parsed row would pin that body in every dashboard snapshot. */

export function compactUsageRecord(data: ClaudeUsageRecord): ClaudeUsageRecord {

const sourceUsage = normalizeClaudeNativeUsage(data.message.usage);

const model = usageModelName(data.message.model);

const usage: ClaudeUsageRecord['message']['usage'] = {

input_tokens: sourceUsage.input_tokens,

output_tokens: sourceUsage.output_tokens,

...(sourceUsage.cache_creation_input_tokens !== undefined

? { cache_creation_input_tokens: sourceUsage.cache_creation_input_tokens } : {}),

...(sourceUsage.cache_read_input_tokens !== undefined

? { cache_read_input_tokens: sourceUsage.cache_read_input_tokens } : {}),

...(sourceUsage.cache_creation !== undefined ? {

cache_creation: {

// Keep only a bounded numeric rejection marker, not unknown fields or

// their bodies. Pricing still sees exactly the original known counts.

...(!hasKnownClaudeCacheCreationShape(sourceUsage.cache_creation)

? { _unsupportedTTLShape: 1 } : {}),

...(sourceUsage.cache_creation?.ephemeral_1h_input_tokens !== undefined

? { ephemeral_1h_input_tokens: sourceUsage.cache_creation.ephemeral_1h_input_tokens } : {}),

...(sourceUsage.cache_creation?.ephemeral_5m_input_tokens !== undefined

? { ephemeral_5m_input_tokens: sourceUsage.cache_creation.ephemeral_5m_input_tokens } : {}),

},

} : {}),

};

return {

timestamp: data.timestamp,

...(data.version !== undefined ? { version: data.version } : {}),

message: {

usage,

...(model !== undefined ? { model } : {}),

...(data.message.id !== undefined ? { id: data.message.id } : {}),

},

...(data.costUSD !== undefined ? { costUSD: data.costUSD } : {}),

...(data.requestId !== undefined ? { requestId: data.requestId } : {}),

...(data.isApiErrorMessage !== undefined ? { isApiErrorMessage: data.isApiErrorMessage } : {}),

};

}

function validationDropReason(data: any): string {

if (!data || typeof data !== 'object') return 'not-an-object';

if (typeof data.timestamp !== 'string') return 'timestamp-missing-or-non-string';

if (!data.message || typeof data.message !== 'object') return 'message-missing';

if (!data.message.usage || typeof data.message.usage !== 'object') return 'usage-missing';

if (typeof data.message.usage.input_tokens !== 'number') return 'input_tokens-not-a-number';

if (typeof data.message.usage.output_tokens !== 'number') return 'output_tokens-not-a-number';

return 'other';

}

// --- Content-consumption analysis helpers ---

// These estimate which conversation content uses tokens. Token figures are

// derived from character counts, so they are approximate; the relative shares

// between categories are the dependable signal.

export interface AnalysisBucket {

tokens: number;

chars: number;

count: number;

}

/** Numeric-only structural summaries retained by the incremental Claude index.

* They are sufficient to replay the legacy accumulator's cross-file tool

* mappings without keeping tool-result bodies or tool arguments. */

export type AnalysisStructuralEvent =

| {

kind: 'tool-use';

toolId: string;

toolName: string;

skillUse?: SkillUse;

}

| {

kind: 'tool-result';

toolId: string;

tokens: number;

chars: number;

count: number;

}

| {

kind: 'command';

skillUse: SkillUse;

};

export interface AnalysisAcc {

cat: Record<string, AnalysisBucket>;

tools: Record<string, AnalysisBucket>;

toolIdToName: Record<string, string>;

seenUuids: Set<string>;

cutoffMs: number;

prompts: { cwd: string; text: string; observedAtEpochMs: number }[];

// Estimated thinking vs. total assistant-output tokens, per session and per

// local day ("YYYY-MM-DD") — feeds the thinking-share column / Today line.

thinkingBySession: Record<string, ThinkingShare>;

thinkingByDay: Record<string, ThinkingShare>;

// Skill / slash-command invocations (capped) + tool_use_id → skillUses index

// so the matching tool result's size can be attributed to the skill.

skillUses: SkillUse[];

// Per-skill count of matching tool-result blocks. Per-file incremental

// contributions retain this alongside every local skill candidate so the

// global 5,000-use cap can be applied before skill-preamble overhead is

// materialized, exactly like the one-accumulator full loader.

skillPreambleCounts: number[];

skillByToolId: Record<string, number>;

frameworkOverhead: Partial<Record<FrameworkOverheadKind, { tokens: number; count: number }>>;

observedInputEstimatedTokens: number;

userAuthoredEstimatedTokens: number;

toolResultEstimatedTokens: number;

/** Present only for per-file incremental contributions. The legacy full

* loader does not pay this retention cost. */

structuralEvents?: AnalysisStructuralEvent[];

}

// cutoffMs: ignore log lines older than this (0 = no cutoff).

export function newAnalysisAcc(cutoffMs: number, captureStructuralEvents = false): AnalysisAcc {

return {

cat: {},

tools: {},

toolIdToName: {},

seenUuids: new Set<string>(),

cutoffMs,

prompts: [],

thinkingBySession: {},

thinkingByDay: {},

skillUses: [],

skillPreambleCounts: [],

skillByToolId: {},

frameworkOverhead: {},

observedInputEstimatedTokens: 0,

userAuthoredEstimatedTokens: 0,

toolResultEstimatedTokens: 0,

...(captureStructuralEvents ? { structuralEvents: [] } : {}),

};

}

/**

* Exact rolling content-analysis cutoff shared by the full loader and the

* incremental index. Keep millisecond precision: rounding could retain expired

* content, prompt samples and calibration contributions. The full loader also

* reuses this single captured cutoff for analysis and calibration, so a clock

* advance during parsing cannot give them different windows.

*/

export function analysisWindowCutoffMs(nowMs: number, windowDays: number): number {

return nowMs - windowDays * 24 * 60 * 60 * 1000;

}

const MAX_SKILL_USES = 5000;

// Session-management slash commands: invoking them says nothing about what

// the usage was for, but the at-or-after attribution rule would credit them

// with everything that follows. Real skills (from the Skill tool) and

// substantive commands like /code-review are never filtered.

const TRIVIAL_COMMANDS = new Set([

'/model', '/clear', '/compact', '/help', '/config', '/status', '/cost',

'/doctor', '/login', '/logout', '/exit', '/resume', '/usage',

'/usage-credits', '/extra-usage', '/context', '/memory', '/goal',

'/todos', '/release-notes', '/fast', '/effort', '/permissions', '/hooks',

'/mcp', '/agents', '/export', '/rewind', '/init', '/add-dir', '/ide',

]);

// "YYYY-MM-DD" key for a log line's timestamp, in the user's configured

// timezone (empty = system zone), so day/month bucketing is consistent

// (see dateKeys.ts). '' when unparsable.

function localDayKey(timestamp: unknown): string {

if (typeof timestamp !== 'string') {

return '';

}

return dayKeyInZone(new Date(timestamp), I18n.getTimezone());

}

// Collect an actual user prompt (capped + truncated) for the AI-advice feature.

function collectPrompt(

acc: AnalysisAcc,

cwd: string,

text: string,

observedAtEpochMs: number,

): void {

const trimmed = text.trim();

if (trimmed.length < 4) {

return;

}

// The caller has already applied classifyPromptTextOrigin. Do not repeat a

// looser tag heuristic here: unknown custom elements may be user-authored

// Web Component examples and must remain eligible for explicit opt-in.

acc.prompts.push({

cwd,

text: detachedPromptPrefix(trimmed, 2500),

observedAtEpochMs: Number.isFinite(observedAtEpochMs) ? observedAtEpochMs : 0,

});

if (acc.prompts.length > 600) {

acc.prompts.shift();

}

}

// Detect a slash-command echo (<command-name>/foo</command-name>…) and record

// it as a skill use; the echo block's size approximates the injected prompt.

function collectCommandUse(acc: AnalysisAcc, text: string, sessionId: string, timestamp: unknown): void {

if (acc.skillUses.length >= MAX_SKILL_USES || !text.startsWith('<command-name>')) {

return;

}

const m = text.match(/^<command-name>([^<]{1,80})<\/command-name>/);

if (!m) {

return;

}

const name = detachedPromptPrefix(m[1].trim(), 80);

if (TRIVIAL_COMMANDS.has(name.toLowerCase())) {

return;

}

const ts = typeof timestamp === 'string' ? Date.parse(timestamp) : NaN;

const use: SkillUse = {

name,

sessionId,

day: localDayKey(timestamp),

ts: isNaN(ts) ? 0 : ts,

estTokens: estimateTokens(text),

};

acc.skillUses.push(use);

acc.skillPreambleCounts.push(0);

acc.structuralEvents?.push({ kind: 'command', skillUse: { ...use } });

}

// Rough token estimate from text length (CJK characters are denser than ASCII).

function estimateTokens(text: string): number {

const len = text.length;

if (len === 0) {

return 0;

}

if (len > 200000) {

return Math.round(len / 4);

}

let cjk = 0;

for (let i = 0; i < len; i++) {

const code = text.charCodeAt(i);

if (code >= 0x3000 && code <= 0x9fff) {

cjk++;

}

}

return Math.round(cjk / 1.5 + (len - cjk) / 4);

}

// Flatten a content value (string, or array of blocks) to plain text.

function blockText(content: unknown): string {

if (typeof content === 'string') {

return content;

}

if (Array.isArray(content)) {

let text = '';

for (const block of content) {

if (typeof block === 'string') {

text += block;

} else if (block && typeof block === 'object' && typeof (block as { text?: unknown }).text === 'string') {

text += (block as { text: string }).text;

}

}

return text;

}

return '';

}

function addToBucket(map: Record<string, AnalysisBucket>, key: string, text: string): void {

if (!text) {

return;

}

if (!ownRecordValue(map, key)) {

setRecordValue(map, key, { tokens: 0, chars: 0, count: 0 });

}

map[key].tokens += estimateTokens(text);

map[key].chars += text.length;

map[key].count += 1;

}

function addFrameworkOverhead(

acc: AnalysisAcc,

kind: FrameworkOverheadKind,

tokens: number,

): void {

if (!Number.isFinite(tokens) || tokens < 0) {

return;

}

const current = acc.frameworkOverhead[kind] || { tokens: 0, count: 0 };

current.tokens += tokens;

current.count += 1;

acc.frameworkOverhead[kind] = current;

}

function trackPromptTextOrigin(

parsed: any,

acc: AnalysisAcc,

text: string,

isSubagentFile: boolean,

): 'user-authored' | FrameworkOverheadKind {

const origin = classifyPromptTextOrigin({

text,

isMeta: parsed.isMeta === true,

isSidechain: parsed.isSidechain === true,

isSubagentFile,

});

const tokens = estimateTokens(text);

acc.observedInputEstimatedTokens += tokens;

if (origin === 'user-authored') {

acc.userAuthoredEstimatedTokens += tokens;

} else {

addFrameworkOverhead(acc, origin, tokens);

}

return origin;

}

// Accumulate one raw log line into the content analysis.

// isSubagentFile: lines from sub-agent / workflow logs still count toward the

// token-consumption buckets, but their "user" lines are agent-framework task

// dispatches — never harvest them as prompt samples for the AI-advice feature.

// sessionId: parent session of the source file (for the thinking-share maps).

export function analyzeLine(parsed: any, acc: AnalysisAcc, isSubagentFile = false, sessionId = ''): void {

if (!parsed || typeof parsed !== 'object') {

return;

}

// Scope the analysis to a recent window so it reflects current habits.

if (acc.cutoffMs > 0) {

const ts = typeof parsed.timestamp === 'string' ? Date.parse(parsed.timestamp) : NaN;

if (!isNaN(ts) && ts < acc.cutoffMs) {

return;

}

}

const uuid = typeof parsed.uuid === 'string' ? parsed.uuid : null;

if (uuid) {

if (acc.seenUuids.has(uuid)) {

return;

}

acc.seenUuids.add(uuid);

}

const message = parsed.message;

if (!message || typeof message !== 'object') {

return;

}

const role = message.role || parsed.type;

const content = message.content;

const cwd = typeof parsed.cwd === 'string' ? parsed.cwd : '';

if (role === 'assistant') {

// Thinking share: estimated thinking tokens vs. all assistant output

// (text + thinking + tool-call JSON), per session and per local day.

const trackThinking = (thinkingTokens: number, totalTokens: number, hidden = false): void => {

if (totalTokens <= 0) {

return;

}

const add = (map: Record<string, ThinkingShare>, key: string): void => {

if (!key) {

return;

}

if (!ownRecordValue(map, key)) {

setRecordValue(map, key, { thinking: 0, assistantTotal: 0 });

}

map[key].thinking += thinkingTokens;

map[key].assistantTotal += totalTokens;

if (hidden) {

map[key].hiddenThinking = true;

}

};

add(acc.thinkingBySession, sessionId);

add(acc.thinkingByDay, localDayKey(parsed.timestamp));

};

if (Array.isArray(content)) {

let thinkingTokens = 0;

let totalTokens = 0;

let hiddenThinking = false;

for (const block of content) {

if (!block || typeof block !== 'object') {

continue;

}

if (block.type === 'text' && typeof block.text === 'string') {

addToBucket(acc.cat, 'assistantText', block.text);

totalTokens += estimateTokens(block.text);

} else if (block.type === 'thinking' && typeof block.thinking === 'string') {

addToBucket(acc.cat, 'assistantThinking', block.thinking);

const est = estimateTokens(block.thinking);

thinkingTokens += est;

totalTokens += est;

// Thinking happened but the raw text isn't exposed (Fable 5 / Opus 4.8

// omit it, leaving "" + an encrypted signature). Flag it so the UI can

// say "hidden" instead of an untrue 0%.

if (est === 0 && typeof (block as { signature?: unknown }).signature === 'string') {

hiddenThinking = true;

}

} else if (block.type === 'tool_use') {

let structuralSkillUse: SkillUse | undefined;

if (typeof block.id === 'string' && typeof block.name === 'string') {

setRecordValue(acc.toolIdToName, block.id, block.name);

// Skill invocations: remember the tool_use_id so the matching

// tool result's size can be attributed to the skill.

const skillName = (block.input as { skill?: unknown } | undefined)?.skill;

if (block.name === 'Skill' && typeof skillName === 'string' && acc.skillUses.length < MAX_SKILL_USES) {

setRecordValue(acc.skillByToolId, block.id, acc.skillUses.length);

const skillTs = typeof parsed.timestamp === 'string' ? Date.parse(parsed.timestamp) : NaN;

structuralSkillUse = {

name: skillName,

sessionId,

day: localDayKey(parsed.timestamp),

ts: isNaN(skillTs) ? 0 : skillTs,

estTokens: 0,

};

acc.skillUses.push(structuralSkillUse);

acc.skillPreambleCounts.push(0);

}

acc.structuralEvents?.push({

kind: 'tool-use',

toolId: block.id,

toolName: block.name,

...(structuralSkillUse ? { skillUse: { ...structuralSkillUse } } : {}),

});

}

const inputJson = JSON.stringify(block.input || {});

addToBucket(acc.cat, 'toolCalls', inputJson);

totalTokens += estimateTokens(inputJson);

}

}

trackThinking(thinkingTokens, totalTokens, hiddenThinking);

} else if (typeof content === 'string') {

addToBucket(acc.cat, 'assistantText', content);

trackThinking(0, estimateTokens(content));

}

} else if (role === 'user') {

// Prompt samples must be genuine top-level user messages: nothing from

// sub-agent logs, meta lines (command echoes) or sidechain dispatches.

const allowPromptSample = !isSubagentFile && !parsed.isMeta && !parsed.isSidechain;

if (typeof content === 'string') {

const origin = trackPromptTextOrigin(parsed, acc, content, isSubagentFile);

// Keep the legacy content-category shape stable for the current UI and

// calibration path. The separate numeric overlay above is the only

// source for framework-vs-user advice evidence.

addToBucket(acc.cat, 'userPrompts', content);

collectCommandUse(acc, content, sessionId, parsed.timestamp);

if (allowPromptSample && origin === 'user-authored') {

collectPrompt(acc, cwd, content, Date.parse(parsed.timestamp));

}

} else if (Array.isArray(content)) {

for (const block of content) {

if (!block || typeof block !== 'object') {

continue;

}

if (block.type === 'tool_result') {

const text = blockText(block.content);

const toolResultTokens = estimateTokens(text);

acc.structuralEvents?.push({

kind: 'tool-result',

toolId: String(block.tool_use_id),

tokens: toolResultTokens,

chars: text.length,

count: text ? 1 : 0,

});

acc.toolResultEstimatedTokens += toolResultTokens;

acc.observedInputEstimatedTokens += toolResultTokens + 8;

addToBucket(acc.cat, 'toolResults', text);

addToBucket(acc.tools, ownRecordValue(acc.toolIdToName, block.tool_use_id) || 'unknown', text);

// Count only a fixed structural envelope proxy here; the tool-result

// body remains in its ordinary consumption bucket and is never

// mistaken for user-authored prose.

addFrameworkOverhead(acc, 'tool-result-envelope', 8);

// The injected skill prompt comes back as the Skill tool's result —

// its size is the best available estimate of the skill's footprint.

const skillIdx = ownRecordValue(acc.skillByToolId, block.tool_use_id);

if (skillIdx !== undefined && acc.skillUses[skillIdx]) {

const skillTokens = estimateTokens(text);

acc.skillUses[skillIdx].estTokens += skillTokens;

acc.skillPreambleCounts[skillIdx] = (acc.skillPreambleCounts[skillIdx] ?? 0) + 1;

addFrameworkOverhead(acc, 'skill-preamble', skillTokens);

}

} else if (block.type === 'text' && typeof block.text === 'string') {

const origin = trackPromptTextOrigin(parsed, acc, block.text, isSubagentFile);

addToBucket(acc.cat, 'userPrompts', block.text);

collectCommandUse(acc, block.text, sessionId, parsed.timestamp);

if (allowPromptSample && origin === 'user-authored') {

collectPrompt(acc, cwd, block.text, Date.parse(parsed.timestamp));

}

}

}

}

}

}

export function finalizeAnalysis(acc: AnalysisAcc): ContentAnalysis {

const toSlices = (map: Record<string, AnalysisBucket>): ContentSlice[] =>

Object.keys(map)

.map((key) => ({ key, estimatedTokens: map[key].tokens, charCount: map[key].chars, count: map[key].count }))

.sort((a, b) => b.estimatedTokens - a.estimatedTokens);

const categories = toSlices(acc.cat);

const frameworkComponents = (Object.entries(acc.frameworkOverhead) as Array<

[FrameworkOverheadKind, { tokens: number; count: number }]

>)

.map(([kind, value]) => ({ kind, estimatedTokens: value.tokens, count: value.count }))

.sort((a, b) => a.kind.localeCompare(b.kind));

return {

categories,

toolResultBreakdown: toSlices(acc.tools),

totalEstimatedTokens: categories.reduce((sum, c) => sum + c.estimatedTokens, 0),

recentPrompts: acc.prompts.slice(-300),

frameworkOverhead: {

frameworkEstimatedTokens: frameworkComponents.reduce(

(sum, component) => sum + component.estimatedTokens,

0,

),

observedInputEstimatedTokens: acc.observedInputEstimatedTokens,

userAuthoredEstimatedTokens: acc.userAuthoredEstimatedTokens,

toolResultEstimatedTokens: acc.toolResultEstimatedTokens,

classifiedEvents: frameworkComponents.reduce((sum, component) => sum + component.count, 0),

components: frameworkComponents,

},

thinkingBySession: acc.thinkingBySession,

thinkingByDay: acc.thinkingByDay,

skillUses: acc.skillUses,

};

}

/** Merge one already-parsed file's content-analysis contribution. The maps

* used only while parsing a stream (toolIdToName / skillByToolId) deliberately

* stay file-local; the user-visible buckets, prompts, thinking and skill uses

* are additive and retain the same global caps as the legacy full scan. */

export function mergeAnalysisAcc(target: AnalysisAcc, source: AnalysisAcc): void {

const mergeBuckets = (

into: Record<string, AnalysisBucket>,

from: Record<string, AnalysisBucket>,

): void => {

for (const [key, value] of Object.entries(from)) {

const bucket = ownRecordValue(into, key) ?? { tokens: 0, chars: 0, count: 0 };

bucket.tokens += value.tokens;

bucket.chars += value.chars;

bucket.count += value.count;

setRecordValue(into, key, bucket);

}

};

mergeBuckets(target.cat, source.cat);

mergeBuckets(target.tools, source.tools);

for (const uuid of source.seenUuids) target.seenUuids.add(uuid);

for (const prompt of source.prompts) {

target.prompts.push(prompt);

if (target.prompts.length > 600) target.prompts.shift();

}

const mergeThinking = (

into: Record<string, ThinkingShare>,

from: Record<string, ThinkingShare>,

): void => {

for (const [key, value] of Object.entries(from)) {

const current = ownRecordValue(into, key) ?? { thinking: 0, assistantTotal: 0 };

current.thinking += value.thinking;

current.assistantTotal += value.assistantTotal;

if (value.hiddenThinking) current.hiddenThinking = true;

setRecordValue(into, key, current);

}

};

mergeThinking(target.thinkingBySession, source.thinkingBySession);

mergeThinking(target.thinkingByDay, source.thinkingByDay);

for (const [index, use] of source.skillUses.entries()) {

if (target.skillUses.length >= MAX_SKILL_USES) break;

target.skillUses.push({ ...use });

const preambleCount = source.skillPreambleCounts[index] ?? 0;

target.skillPreambleCounts.push(preambleCount);

if (preambleCount > 0) {

const current = target.frameworkOverhead['skill-preamble'] ?? { tokens: 0, count: 0 };

current.tokens += use.estTokens;

current.count += preambleCount;

target.frameworkOverhead['skill-preamble'] = current;

}

}

for (const [kind, value] of Object.entries(source.frameworkOverhead) as Array<

[FrameworkOverheadKind, { tokens: number; count: number }]

>) {

// Skill preambles follow the same global cap as their Skill invocation.

// They were accumulated locally while parsing so matching tool results can

// still be associated, then are reconstructed above only for retained uses.

if (kind === 'skill-preamble') continue;

const current = target.frameworkOverhead[kind] ?? { tokens: 0, count: 0 };

current.tokens += value.tokens;

current.count += value.count;

target.frameworkOverhead[kind] = current;

}

target.observedInputEstimatedTokens += source.observedInputEstimatedTokens;

target.userAuthoredEstimatedTokens += source.userAuthoredEstimatedTokens;

target.toolResultEstimatedTokens += source.toolResultEstimatedTokens;

}

export function finalizeAnalysisWithCalibration(

acc: AnalysisAcc,

records: readonly ClaudeUsageRecord[],

cutoffMs: number,

): ContentAnalysis {

const contentAnalysis = finalizeAnalysis(acc);

let realOutputTokens = 0;

let realInputSideTokens = 0;

for (const record of records) {

if (record._isUserPrompt) continue;

const timestamp = Date.parse(record.timestamp);

if (isNaN(timestamp) || timestamp < cutoffMs) continue;

const usage = record.message.usage;

realOutputTokens += usage.output_tokens || 0;

realInputSideTokens += (usage.input_tokens || 0) +

(usage.cache_creation_input_tokens || 0);

}

if (realOutputTokens > 0 || realInputSideTokens > 0) {

contentAnalysis.calibration = { realOutputTokens, realInputSideTokens };

}

return contentAnalysis;

}

export class ClaudeDataLoader {

static getClaudePaths(): string[] {

const paths: string[] = [];

const normalizedPaths = new Set<string>();

// Check environment variable first (supports comma-separated paths)

const envPaths = (process.env[CLAUDE_CONFIG_DIR_ENV] ?? '').trim();

if (envPaths !== '') {

const envPathList = envPaths

.split(',')

.map((p) => p.trim())

.filter((p) => p !== '');

for (const envPath of envPathList) {

const normalizedPath = path.resolve(envPath);

if (fs.existsSync(normalizedPath) && fs.statSync(normalizedPath).isDirectory()) {

const projectsPath = path.join(normalizedPath, CLAUDE_PROJECTS_DIR_NAME);

if (fs.existsSync(projectsPath) && fs.statSync(projectsPath).isDirectory()) {

if (!normalizedPaths.has(normalizedPath)) {

normalizedPaths.add(normalizedPath);

paths.push(normalizedPath);

}

}

}

}

}

// Add default paths if they exist

const defaultPaths = [DEFAULT_CLAUDE_CONFIG_PATH, path.join(USER_HOME_DIR, DEFAULT_CLAUDE_CODE_PATH)];

for (const defaultPath of defaultPaths) {

const normalizedPath = path.resolve(defaultPath);

if (fs.existsSync(normalizedPath) && fs.statSync(normalizedPath).isDirectory()) {

const projectsPath = path.join(normalizedPath, CLAUDE_PROJECTS_DIR_NAME);

if (fs.existsSync(projectsPath) && fs.statSync(projectsPath).isDirectory()) {

if (!normalizedPaths.has(normalizedPath)) {

normalizedPaths.add(normalizedPath);

paths.push(normalizedPath);

}

}

}

}

return paths;

}

static async findClaudeDataDirectory(customPath?: string): Promise<string | null> {

if (customPath) {

const projectsPath = path.join(customPath, CLAUDE_PROJECTS_DIR_NAME);

if (fs.existsSync(projectsPath) && fs.statSync(projectsPath).isDirectory()) {

return customPath;

}

return null;

}

const claudePaths = this.getClaudePaths();

return claudePaths.length > 0 ? claudePaths[0] : null;

}

/** Locate the .jsonl log file(s) and sub-agent dir for a session id. */

static async findSessionFiles(sessionId: string, dataDirectory?: string | null): Promise<string[]> {

if (!sessionId || /[\\/]/.test(sessionId) || sessionId === 'unknown') { return []; }

const roots = new Set<string>(this.getClaudePaths());

if (dataDirectory) { roots.add(dataDirectory); }

const fileName = sessionId + '.jsonl';

const matches: string[] = [];

const walk = async (dir: string): Promise<void> => {

let entries;

try {

entries = await fs.promises.readdir(dir, { withFileTypes: true });

} catch {

return;

}

for (const e of entries) {

const full = path.join(dir, e.name);

if (e.isDirectory()) {

if (e.name === sessionId) {

matches.push(full); // session's sub-agent container — remove whole

} else {

await walk(full);

}

} else if (e.isFile() && e.name === fileName) {

matches.push(full);

}

}

};

for (const root of roots) {

const projectsDir = path.join(root, CLAUDE_PROJECTS_DIR_NAME);

if (fs.existsSync(projectsDir)) {

await walk(projectsDir);

}

}

return matches;

}

static async loadUsageRecords(

dataDirectory?: string,

options?: {

analyzeContent?: boolean;

windowDays?: number;

log?: (line: string) => void;

manifest?: UsageManifest;

}

): Promise<{

records: ClaudeUsageRecord[];

contentAnalysis: ContentAnalysis | null;

diagnostics: LoadUsageDiagnostics;

}> {

const analyzeContent = options?.analyzeContent !== false; // default true

// How many days back the content analysis (and its prompt sample) looks.

// Configurable via advice.promptWindowDays; defaults to 30.

const windowDays = Math.min(365, Math.max(1, Math.round(options?.windowDays ?? 30)));

const analysisCutoffMs = analysisWindowCutoffMs(Date.now(), windowDays);

const log = options?.log;

const readParseStarted = performance.now();

let filesDiscovered = 0;

let filesFailed = 0;

let bytesRead = 0;

let linesParsed = 0;

const diagnostics = (): LoadUsageDiagnostics => ({

filesDiscovered,

filesFailed,

bytesRead,

linesParsed,

readParseMs: performance.now() - readParseStarted,

});

try {

const claudePaths = dataDirectory ? [dataDirectory] : this.getClaudePaths();

const manifest = options?.manifest ?? await scanUsageManifest(claudePaths);

filesDiscovered = manifest.entries.size;

const sorted = await sortUsageFilesByEarliestTimestamp([...manifest.entries.values()]);

bytesRead += sorted.bytesRead;

const sortedFiles = sorted.files;

// Usage identities are resolved after every file has been read. Claude

// normally writes both messageId and requestId, but some transcript rows

// omit requestId. Waiting until the full load is known lets a missing ID

// join the sole request for that message without merging genuinely

// distinct requests that happen to reuse a messageId.

const usageRecordIndexes: number[] = [];

const requestIdsByMessage = new Map<string, Set<string>>();

let records: ClaudeUsageRecord[] = [];

// sessionId → conversation title. Current Claude Code writes

// `custom-title` (user-set) and `ai-title` (auto) lines; older versions

// wrote `summary`. A custom title always wins over an AI one.

const aiTitleBySession: Record<string, string> = Object.create(null);

const customTitleBySession: Record<string, string> = Object.create(null);

// Content analysis (last `windowDays` days, default 30) is optional —

// skipped when the user disables it via claudeCodeUsage.enableContentAnalysis.

const analysis = analyzeContent ? newAnalysisAcc(analysisCutoffMs) : null;

// Per-refresh caches for sub-agent attribution lookups: agent type from

// agent-*.meta.json (keyed by meta path) and workflow display name from

// the session's workflows/scripts dir (keyed by workflow id).

const agentTypeCache = new Map<string, string>();

const workflowNameCache = new Map<string, string>();

let fileIndex = 0;

// Diagnostic counters so the "Show Diagnostic Logs" command can explain

// how many records were seen / rejected / deduped without speculation.

const stats = {

files: sortedFiles.length,

linesScanned: 0,

parseErrors: 0,

rejected: {} as Record<string, number>,

replacedByDedup: 0,

skippedByDedup: 0,

kept: 0,

userPrompts: 0,

// model name → { count, totalTokens }. totalTokens lets us tell whether

// records exist but are all zeros (proxy-placeholder only).

// Diagnostic detail is optional and bounded, independently of the

// number/length of labels in source logs. Never retain arbitrary paths

// or prototype properties as model names for the output channel.

models: new Map<string, { count: number; tokens: number }>(),

otherModels: { count: 0, tokens: 0 },

};

for (const file of sortedFiles) {

try {

const content = await readFile(file, 'utf-8');

bytesRead += Buffer.byteLength(content, 'utf8');

const lines = content

.trim()

.split('\n')

.filter((line) => line.trim() !== '');

// Each .jsonl file is one Claude Code conversation/session.

const sessionInfo = this.parseSessionInfo(file);

// Sub-agent / workflow logs: count their usage, but never harvest

// user prompts from them (their "user" lines are agent-framework

// task dispatches, not something the user typed).

const isSubagentFile = /[\\/]subagents[\\/]/.test(file);

// Sub-agent attribution, derived from the file path — NOT from cwd:

// worktree-isolated agents have a cwd pointing at a temporary git

// worktree (see docs/V2.1-WORKFLOW-SPEC.md §2.2).

let agentInfo: {

agentId: string;

agentType: string;

workflowId?: string;

workflowName?: string;

task?: string;

} | null = null;

if (isSubagentFile) {

const agentId = path.basename(file, '.jsonl');

const agentType = await this.readAgentType(file, agentTypeCache);

const wfMatch = file.match(/[\\/]subagents[\\/]workflows[\\/](wf_[^\\/]+)[\\/]/);

if (wfMatch) {

const workflowId = wfMatch[1];

const workflowName = await this.resolveWorkflowName(file, workflowId, workflowNameCache);

agentInfo = { agentId, agentType, workflowId, workflowName };

} else {

agentInfo = { agentId, agentType };

}

}

// Per-session (per-file) map of prompt digest → last-counted epoch ms,

// to drop API-error retry re-logs of the same prompt from the Messages

// count (see promptDedup.ts).

const recentPrompts = new Map<string, number>();

for (const line of lines) {

linesParsed += 1;

stats.linesScanned += 1;

try {

const parsed = JSON.parse(line) as unknown;

// Feed every line into the content analysis (not only usage records).

if (analysis) {

analyzeLine(parsed, analysis, isSubagentFile, sessionInfo.sessionId);

}

// Conversation title lines. Keep the last seen of each kind —

// titles get refreshed as the chat evolves.

const lineAny = parsed as Record<string, unknown>;

if (lineAny.type === 'ai-title' && typeof lineAny.aiTitle === 'string') {

aiTitleBySession[sessionInfo.sessionId] = lineAny.aiTitle;

} else if (lineAny.type === 'custom-title' && typeof lineAny.customTitle === 'string') {

customTitleBySession[sessionInfo.sessionId] = lineAny.customTitle;

} else if (lineAny.type === 'summary' && typeof lineAny.summary === 'string') {

// Legacy location (older Claude Code versions).

aiTitleBySession[sessionInfo.sessionId] = lineAny.summary;

}

// A sub-agent log's first user message is the task that was

// dispatched to the agent — capture it (truncated) as the

// agent's display label for the Workflows drill-down.

if (agentInfo && agentInfo.task === undefined) {

const role =

(lineAny.message as { role?: unknown } | undefined)?.role ?? lineAny.type;

if (role === 'user') {

const content = (lineAny.message as { content?: unknown } | undefined)?.content;

const text =

typeof content === 'string'

? content

: Array.isArray(content)

? content

.filter(

(b: { type?: unknown; text?: unknown }) =>

b?.type === 'text' && typeof b.text === 'string'

)

.map((b: { text: string }) => b.text)

.join(' ')

: '';

const trimmed = text.replace(/\s+/g, ' ').trim();

if (trimmed.length > 0) {

agentInfo.task = detachedPromptPrefix(trimmed, 200);

}

}

}