sidekick-shared 0.27.6 → 0.28.0

package/dist/esm/usage/importSessionHistory.js

@@ -0,0 +1,84 @@
+/**
+ * Import finished sessions from every provider into the history store.
+ *
+ * The VS Code extension used to import Claude Code only, by hand-parsing
+ * JSONL files; the CLI could not import at all. This walks the sessions
+ * every provider knows about, reads each once through the unified stats
+ * path, and hands a `SessionSummary` to the caller, which applies it to the
+ * store it owns (the extension's debounced persistence service or the CLI's
+ * locked atomic writer). Dedupe is the caller's `isImported` answer
+ * (imported file paths plus persisted session ids); the capped per-session
+ * list is deliberately not used as the dedupe key.
+ *
+ * Node-only: reads session files.
+ *
+ * @module usage/importSessionHistory
+ */
+import { sessionSummaryFromStats } from '../historicalStore';
+import { listSessionPreviewsAsync } from '../sessionPreviews';
+import { readSessionFileStats } from '../sessionStats';
+/** Files modified more recently than this are skipped: they may still be live. */
+export const ACTIVE_SESSION_MTIME_THRESHOLD_MS = 60_000;
+function yieldToEventLoop() {
+    return new Promise((resolve) => setImmediate(resolve));
+}
+export async function importSessionHistory(options) {
+    const now = options.now ?? new Date();
+    const threshold = options.activeFileThresholdMs ?? ACTIVE_SESSION_MTIME_THRESHOLD_MS;
+    const listed = await listSessionPreviewsAsync(options.providers, {
+        since: options.since,
+        workspacePath: options.workspacePath,
+        limit: Number.MAX_SAFE_INTEGER,
+    });
+    const providerById = new Map(options.providers.map((provider) => [provider.id, provider]));
+    const result = {
+        filesFound: listed.previews.length,
+        filesProcessed: 0,
+        filesSkipped: 0,
+        filesUnavailable: 0,
+        sessionsImported: 0,
+        messagesImported: 0,
+        diagnostics: [...listed.diagnostics],
+    };
+    const total = listed.previews.length;
+    let loaded = 0;
+    for (const preview of listed.previews) {
+        loaded += 1;
+        const provider = providerById.get(preview.provider);
+        const modifiedMs = Date.parse(preview.modifiedAt);
+        const recentlyModified = Number.isFinite(modifiedMs) && now.getTime() - modifiedMs < threshold;
+        if (!provider || recentlyModified || options.isImported(preview.sessionId, preview.filePath)) {
+            result.filesSkipped += 1;
+            options.onProgress?.(loaded, total);
+            continue;
+        }
+        const stats = readSessionFileStats(provider, preview.filePath);
+        result.filesProcessed += 1;
+        if (stats.availability === 'unavailable') {
+            result.filesUnavailable += 1;
+            result.diagnostics.push({
+                providerId: preview.provider,
+                kind: 'read_failed',
+                severity: 'warning',
+                phase: 'read',
+                message: `${preview.provider} session ${preview.sessionId}: ${stats.unavailableReason ?? 'unavailable'}`,
+            });
+        }
+        else if (Object.keys(stats.modelUsage).length === 0) {
+            // No usage record at all (for example a prompt that never got an
+            // answer): nothing to credit, but mark the file so it is not re-read
+            // on every run.
+            result.filesUnavailable += 1;
+            options.markImported(preview.filePath);
+        }
+        else {
+            options.applySummary(sessionSummaryFromStats(stats, { project: preview.workspacePath }), preview.filePath);
+            options.markImported(preview.filePath);
+            result.sessionsImported += 1;
+            result.messagesImported += stats.messageCount;
+        }
+        options.onProgress?.(loaded, total);
+        await yieldToEventLoop();
+    }
+    return result;
+}

package/dist/esm/usage/subagentUsage.js

@@ -0,0 +1,18 @@
+/**
+ * Accumulate normalized usage into a subagent's token fields so every
+ * provider's `scanSubagents()` reports the same four buckets and the same
+ * cache-inclusive total as `summarizeTokens()`.
+ *
+ * Browser-safe: no Node imports.
+ *
+ * @module usage/subagentUsage
+ */
+/** Add one usage record (a call or a correction) to a subagent's token totals. */
+export function addUsageToSubagent(stats, usage) {
+    stats.inputTokens += usage.uncachedInputTokens;
+    stats.outputTokens += usage.outputTokens;
+    stats.cacheReadTokens = (stats.cacheReadTokens ?? 0) + usage.cacheReadTokens;
+    stats.cacheWriteTokens = (stats.cacheWriteTokens ?? 0) + usage.cacheWriteTokens;
+    stats.reasoningTokens = (stats.reasoningTokens ?? 0) + usage.reasoningTokens;
+    stats.totalTokens = (stats.totalTokens ?? 0) + usage.totalTokens;
+}

package/dist/esm/usage/usageEvents.js

@@ -0,0 +1,402 @@
+/**
+ * Usage events collected from session logs, cached per session.
+ *
+ * Feeds the billing-block view and the log-derived daily/weekly/monthly
+ * reports, so CLI-only users get numbers without the extension's history
+ * store. Each session is read once through its provider reader; the
+ * extracted usage is cached under `<configDir>/usage-cache/` keyed by the
+ * session's size and mtime, so a repeat run only re-reads sessions that
+ * changed. Token counts are cached raw and priced at load time, so a pricing
+ * catalog refresh never leaves stale costs behind. Cache files are touched on
+ * every hit and pruned least-recently-used, once per collection.
+ *
+ * A Claude Code session's subagents write their own transcripts under
+ * `<sessionId>/subagents/`; their usage is attributed to the parent session
+ * and their sizes and mtimes join the fingerprint. (Codex spawned subagents
+ * are top-level rollouts, already listed as sessions of their own.)
+ *
+ * Node-only: reads session files and the cache directory.
+ *
+ * @module usage/usageEvents
+ */
+import * as fs from 'fs';
+import * as path from 'path';
+import { getConfigDir } from '../paths';
+import { listSessionPreviewsAsync } from '../sessionPreviews';
+import { calculateNormalizedUsageCost, extractNormalizedUsage } from '../usageNormalization';
+import { atomicWriteJson } from '../writers/atomic';
+import { resolveWorkspaceRoots } from '../workspaceRoots';
+/**
+ * Bump when the cached record shape or the counting rules change; older files
+ * are re-read. v2: Claude split lines and duplicate Codex `token_count` events
+ * are counted once, and Claude subagent transcripts are included.
+ */
+export const USAGE_CACHE_VERSION = 2;
+/**
+ * Most-recently-used cache files kept on disk. Sized for a busy month of
+ * sessions (files are a few KB each); a collection larger than this still
+ * completes, it just re-reads what was evicted. Pruning runs once after a
+ * collection, never during one, so a working set is never evicted mid-run.
+ */
+export const MAX_USAGE_CACHE_FILES = 5000;
+export function getUsageCacheDir() {
+    return path.join(getConfigDir(), 'usage-cache');
+}
+function cacheFilePath(dir, provider, sessionId) {
+    const safe = sessionId.replace(/[^A-Za-z0-9._-]/g, '_');
+    return path.join(dir, `${provider}--${safe}.json`);
+}
+function toMs(value, label) {
+    if (value === undefined)
+        return null;
+    const ms = value instanceof Date ? value.getTime() : Date.parse(value);
+    if (!Number.isFinite(ms))
+        throw new RangeError(`Invalid \`${label}\` value: ${String(value)}`);
+    return ms;
+}
+/** Mark a cache file as recently used so LRU pruning keeps it. Best-effort. */
+function touch(filePath) {
+    try {
+        const now = new Date();
+        fs.utimesSync(filePath, now, now);
+    }
+    catch {
+        // Read-only cache or vanished file; the next miss rewrites it.
+    }
+}
+function readCache(filePath) {
+    try {
+        const parsed = JSON.parse(fs.readFileSync(filePath, 'utf8'));
+        if (parsed?.version !== USAGE_CACHE_VERSION || !Array.isArray(parsed.events))
+            return null;
+        return parsed;
+    }
+    catch {
+        return null;
+    }
+}
+/** Deletes all but the `keep` most recently used cache files (by mtime). Best-effort. */
+export function pruneUsageCache(keep = MAX_USAGE_CACHE_FILES, dir = getUsageCacheDir()) {
+    try {
+        const entries = fs
+            .readdirSync(dir)
+            .filter((name) => name.endsWith('.json'))
+            .map((name) => {
+            const filePath = path.join(dir, name);
+            try {
+                return { filePath, mtimeMs: fs.statSync(filePath).mtimeMs };
+            }
+            catch {
+                return null;
+            }
+        })
+            .filter((entry) => entry !== null)
+            .sort((a, b) => b.mtimeMs - a.mtimeMs);
+        let removed = 0;
+        for (const entry of entries.slice(Math.max(0, keep))) {
+            try {
+                fs.unlinkSync(entry.filePath);
+                removed += 1;
+            }
+            catch {
+                // Already gone; skip.
+            }
+        }
+        return removed;
+    }
+    catch {
+        return 0;
+    }
+}
+function cachedEventFromUsage(usage, timestamp, model) {
+    const record = {
+        t: timestamp,
+        m: model,
+        i: usage.uncachedInputTokens,
+        o: usage.outputTokens,
+        cw: usage.cacheWriteTokens,
+        cr: usage.cacheReadTokens,
+        bo: usage.billableOutputTokens,
+        tt: usage.totalTokens,
+    };
+    if (usage.reportedCostUsd !== undefined)
+        record.rc = usage.reportedCostUsd;
+    return record;
+}
+/** Price a cached event with the current catalog (or its provider-reported cost). */
+function priceCachedEvent(cached, provider, sessionId, project, sessionFile) {
+    const usage = {
+        uncachedInputTokens: cached.i,
+        cacheReadTokens: cached.cr,
+        cacheWriteTokens: cached.cw,
+        outputTokens: cached.o,
+        reasoningTokens: 0,
+        reasoningIncludedInOutput: true,
+        cacheInclusiveInputTokens: cached.i + cached.cr + cached.cw,
+        billableOutputTokens: cached.bo,
+        totalTokens: cached.tt,
+        ...(cached.rc !== undefined ? { reportedCostUsd: cached.rc } : {}),
+        provenance: { semantics: 'sidekick-disjoint' },
+    };
+    const priced = calculateNormalizedUsageCost({
+        usage,
+        modelId: cached.m === 'unknown' ? undefined : cached.m,
+    });
+    return {
+        timestamp: cached.t,
+        provider,
+        sessionId,
+        project,
+        model: cached.m,
+        tokens: {
+            inputTokens: cached.i,
+            outputTokens: cached.o,
+            cacheWriteTokens: cached.cw,
+            cacheReadTokens: cached.cr,
+            totalTokens: cached.tt,
+        },
+        costUsd: priced.costUsd,
+        costProvenance: priced.source,
+        filePath: sessionFile,
+    };
+}
+const CLAUDE_AGENT_FILE = /^agent-.+\.jsonl$/;
+/** Claude Code subagent transcripts of a session, sorted by name. */
+function claudeSubagentFiles(preview) {
+    if (preview.provider !== 'claude-code')
+        return [];
+    const dir = path.join(path.dirname(preview.filePath), preview.sessionId, 'subagents');
+    let names;
+    try {
+        names = fs.readdirSync(dir).filter((name) => CLAUDE_AGENT_FILE.test(name));
+    }
+    catch {
+        return [];
+    }
+    const files = [];
+    for (const name of names.sort()) {
+        try {
+            const stat = fs.statSync(path.join(dir, name));
+            files.push({
+                path: path.join(dir, name),
+                name,
+                sizeBytes: stat.size,
+                modifiedAt: stat.mtimeMs,
+            });
+        }
+        catch {
+            // Removed between listing and stat; the next collection re-reads.
+        }
+    }
+    return files;
+}
+function sessionFingerprint(preview, subagents) {
+    const base = `${preview.sizeBytes}:${preview.modifiedAt}`;
+    if (subagents.length === 0)
+        return base;
+    return `${base}|${subagents.map((f) => `${f.name}:${f.sizeBytes}:${f.modifiedAt}`).join(',')}`;
+}
+function readTranscriptUsage(provider, filePath, cached) {
+    const reader = provider.createReader(filePath);
+    const events = reader.readAll();
+    reader.flush();
+    // A correction tops up the call its message already recorded, so it merges
+    // into that record instead of counting as another call.
+    const byMessageId = new Map();
+    for (const event of events) {
+        const usage = extractNormalizedUsage(event);
+        if (!usage)
+            continue;
+        const messageId = event.message?.id;
+        const target = event.message?.usageKind === 'correction' && messageId
+            ? byMessageId.get(messageId)
+            : undefined;
+        if (target) {
+            target.i += usage.uncachedInputTokens;
+            target.o += usage.outputTokens;
+            target.cw += usage.cacheWriteTokens;
+            target.cr += usage.cacheReadTokens;
+            target.bo += usage.billableOutputTokens;
+            target.tt += usage.totalTokens;
+            continue;
+        }
+        const timestamp = Date.parse(event.timestamp);
+        if (!Number.isFinite(timestamp))
+            continue;
+        const record = cachedEventFromUsage(usage, timestamp, event.message?.model ?? usage.model ?? 'unknown');
+        cached.push(record);
+        if (messageId)
+            byMessageId.set(messageId, record);
+    }
+}
+function readSessionUsage(provider, preview, subagents) {
+    const cached = [];
+    readTranscriptUsage(provider, preview.filePath, cached);
+    for (const file of subagents)
+        readTranscriptUsage(provider, file.path, cached);
+    cached.sort((a, b) => a.t - b.t);
+    return cached;
+}
+function yieldToEventLoop() {
+    return new Promise((resolve) => setImmediate(resolve));
+}
+/**
+ * Collect priced usage events for every session touched in the window.
+ *
+ * Sessions are enumerated with `listSessionPreviewsAsync` (the `since`
+ * cutoff applies to the session mtime there and to the event timestamp
+ * here), read once each unless the cache already holds their fingerprint,
+ * and yielded between reads so long-lived hosts stay responsive.
+ */
+export async function collectUsageEvents(options) {
+    const sinceMs = toMs(options.since, 'since');
+    const untilMs = toMs(options.until, 'until');
+    const cacheDir = options.cacheDir ?? getUsageCacheDir();
+    const useCache = !options.noCache;
+    const signal = options.signal;
+    signal?.throwIfAborted();
+    const scope = usageScope(options);
+    const listed = await listScopedPreviews(options, scope?.listingRoots);
+    signal?.throwIfAborted();
+    const diagnostics = [...listed.diagnostics];
+    for (const diagnostic of listed.diagnostics)
+        options.onDiagnostic?.(diagnostic);
+    const providerById = new Map(options.providers.map((provider) => [provider.id, provider]));
+    const events = [];
+    const sessions = [];
+    let cacheHits = 0;
+    let cacheMisses = 0;
+    let wroteCache = false;
+    for (const preview of listed.previews) {
+        signal?.throwIfAborted();
+        const provider = providerById.get(preview.provider);
+        if (!provider)
+            continue;
+        const subagentFiles = claudeSubagentFiles(preview);
+        const fingerprint = sessionFingerprint(preview, subagentFiles);
+        const filePath = cacheFilePath(cacheDir, preview.provider, preview.sessionId);
+        let cachedEvents = null;
+        let project = preview.workspacePath;
+        let fromCache = false;
+        if (useCache) {
+            const cached = readCache(filePath);
+            if (cached && cached.fingerprint === fingerprint && cached.sessionId === preview.sessionId) {
+                cachedEvents = cached.events;
+                project = project ?? cached.project;
+                fromCache = true;
+                cacheHits += 1;
+                touch(filePath);
+            }
+        }
+        if (!cachedEvents) {
+            cacheMisses += 1;
+            try {
+                cachedEvents = readSessionUsage(provider, preview, subagentFiles);
+            }
+            catch (error) {
+                const diagnostic = {
+                    providerId: preview.provider,
+                    kind: 'read_failed',
+                    severity: 'warning',
+                    phase: 'read',
+                    message: `Could not read usage for ${preview.provider} session ${preview.sessionId}: ${error instanceof Error ? error.message : String(error)}`,
+                };
+                diagnostics.push(diagnostic);
+                options.onDiagnostic?.(diagnostic);
+                continue;
+            }
+            if (useCache) {
+                const record = {
+                    version: USAGE_CACHE_VERSION,
+                    provider: preview.provider,
+                    sessionId: preview.sessionId,
+                    fingerprint,
+                    project,
+                    events: cachedEvents,
+                };
+                try {
+                    await atomicWriteJson(filePath, record);
+                    wroteCache = true;
+                }
+                catch {
+                    // The cache is an accelerator; a failed write only costs a re-read.
+                }
+            }
+            await yieldToEventLoop();
+        }
+        let first = null;
+        let last = null;
+        let count = 0;
+        for (const cached of cachedEvents) {
+            if (sinceMs !== null && cached.t < sinceMs)
+                continue;
+            if (untilMs !== null && cached.t > untilMs)
+                continue;
+            events.push(priceCachedEvent(cached, preview.provider, preview.sessionId, project, preview.filePath));
+            first = first === null ? cached.t : Math.min(first, cached.t);
+            last = last === null ? cached.t : Math.max(last, cached.t);
+            count += 1;
+        }
+        sessions.push({
+            provider: preview.provider,
+            sessionId: preview.sessionId,
+            filePath: preview.filePath,
+            project,
+            fingerprint,
+            firstTimestamp: first,
+            lastTimestamp: last,
+            eventCount: count,
+            fromCache,
+        });
+    }
+    if (wroteCache)
+        pruneUsageCache(MAX_USAGE_CACHE_FILES, cacheDir);
+    events.sort((a, b) => a.timestamp - b.timestamp);
+    return {
+        events,
+        sessions,
+        diagnostics,
+        cacheHits,
+        cacheMisses,
+        ...(scope ? { roots: scope.roots } : {}),
+    };
+}
+/** The roots to list, or undefined for an unscoped (or legacy single-root) call. */
+function usageScope(options) {
+    if (options.workspacePaths) {
+        return resolveWorkspaceRoots(options.workspacePaths, {
+            includeWorktrees: options.includeWorktrees !== false,
+        });
+    }
+    if (options.workspacePath && options.includeWorktrees === true) {
+        return resolveWorkspaceRoots([options.workspacePath], { includeWorktrees: true });
+    }
+    return undefined;
+}
+/** Lists previews once per root and keeps each session file once. */
+async function listScopedPreviews(options, listingRoots) {
+    const list = (workspacePath) => listSessionPreviewsAsync(options.providers, {
+        since: options.since,
+        workspacePath,
+        limit: Number.MAX_SAFE_INTEGER,
+        concurrency: options.concurrency,
+    });
+    if (!listingRoots)
+        return list(options.workspacePath);
+    const byFile = new Map();
+    const diagnostics = new Map();
+    for (const root of listingRoots) {
+        options.signal?.throwIfAborted();
+        const listed = await list(root);
+        // Each root lists every provider again; report each problem once.
+        for (const diagnostic of listed.diagnostics) {
+            diagnostics.set(JSON.stringify(diagnostic), diagnostic);
+        }
+        for (const preview of listed.previews) {
+            if (!byFile.has(preview.filePath))
+                byFile.set(preview.filePath, preview);
+        }
+    }
+    const previews = [...byFile.values()].sort((left, right) => Date.parse(right.modifiedAt) - Date.parse(left.modifiedAt));
+    return { previews, diagnostics: [...diagnostics.values()] };
+}