sidekick-shared 0.27.6 → 0.28.0

package/dist/esm/sessionStats.js

@@ -0,0 +1,160 @@
+/**
+ * One `readSessionStats()` implementation for every session provider.
+ *
+ * Claude Code, Codex, and OpenCode used to compute session stats three
+ * different ways (a hand-rolled JSONL scan, an aggregator drain, and a direct
+ * SQLite read with hardcoded zeros). Every provider now drains its reader once
+ * into the shared `EventAggregator`, so per-model totals use the
+ * cache-inclusive vocabulary, cost carries provenance, tool failures are
+ * split out, and compaction and truncation counts are real for all three.
+ */
+import { EventAggregator } from './aggregation/EventAggregator';
+const LABEL_MAX_LENGTH = 60;
+function isTextBlock(block) {
+    return (typeof block === 'object' &&
+        block !== null &&
+        typeof block.text === 'string' &&
+        typeof block.type === 'string' &&
+        ['text', 'input_text', 'output_text'].includes(block.type));
+}
+function messageText(content) {
+    if (typeof content === 'string')
+        return content;
+    if (!Array.isArray(content))
+        return null;
+    const block = content.find((item) => isTextBlock(item) && item.text.trim().length > 0);
+    return block && isTextBlock(block) ? block.text : null;
+}
+/**
+ * First user prompt in a session, compacted to one line and truncated the
+ * way every provider's `extractSessionLabel()` truncates (60 characters).
+ */
+export function firstUserPrompt(events, maxLength = LABEL_MAX_LENGTH) {
+    for (const event of events) {
+        if (event.type !== 'user')
+            continue;
+        const text = messageText(event.message?.content);
+        if (!text)
+            continue;
+        const compact = text.replace(/\s+/g, ' ').trim();
+        if (!compact)
+            continue;
+        return compact.length > maxLength ? `${compact.slice(0, maxLength - 3)}...` : compact;
+    }
+    return null;
+}
+/** Compute stats for an already-read event array through the shared aggregator. */
+export function computeSessionFileStats(events, options) {
+    const aggregator = new EventAggregator({
+        providerId: options.providerId,
+        computeContextSize: options.computeContextSize,
+    });
+    for (const event of events)
+        aggregator.processEvent(event);
+    const metrics = aggregator.getMetrics();
+    const modelUsage = {};
+    for (const model of metrics.modelStats) {
+        // `tokens` is the aggregator's cache-inclusive total for the model, the
+        // same figure `summarizeTokens().total` reports.
+        modelUsage[model.model] = {
+            calls: model.calls,
+            tokens: model.tokens,
+            costUsd: model.cost,
+            priced: model.priced !== false,
+        };
+    }
+    const toolUsage = {};
+    const toolFailures = {};
+    for (const tool of metrics.toolStats) {
+        toolUsage[tool.name] = tool.successCount + tool.failureCount + tool.pendingCount;
+        if (tool.failureCount > 0)
+            toolFailures[tool.name] = tool.failureCount;
+    }
+    return {
+        providerId: options.providerId,
+        sessionId: options.sessionId,
+        filePath: options.filePath,
+        label: options.label ?? firstUserPrompt(events),
+        startTime: metrics.sessionStartTime ?? '',
+        endTime: metrics.lastEventTime ?? '',
+        messageCount: metrics.messageCount,
+        tokens: {
+            input: metrics.tokens.inputTokens,
+            output: metrics.tokens.outputTokens,
+            cacheWrite: metrics.tokens.cacheWriteTokens,
+            cacheRead: metrics.tokens.cacheReadTokens,
+        },
+        modelUsage,
+        toolUsage,
+        toolFailures,
+        compactionEstimate: metrics.compactionCount,
+        truncationCount: metrics.truncationCount,
+        costUsd: metrics.tokens.costUsd,
+        costProvenance: metrics.tokens.costProvenance,
+        unpricedCalls: metrics.tokens.unpricedCalls,
+        availability: options.availability ?? 'full',
+        ...(options.unavailableReason ? { unavailableReason: options.unavailableReason } : {}),
+        reportedCost: metrics.tokens.costUsd,
+    };
+}
+/** The aggregator's context-size hook for a provider, or undefined for the default formula. */
+export function providerContextSizeFn(provider) {
+    if (!provider.computeContextSize)
+        return undefined;
+    return (usage) => provider.computeContextSize({ ...usage, model: '', timestamp: new Date() });
+}
+function errorMessage(error) {
+    return error instanceof Error ? error.message : String(error);
+}
+function describeMissingSource(provider) {
+    const status = provider.getRuntimeStatus?.();
+    if (status && !status.available) {
+        return status.message ?? `Provider runtime unavailable (${status.kind}).`;
+    }
+    return 'Session source not found.';
+}
+/**
+ * Read a session once through the provider's reader and compute its stats.
+ *
+ * The reader is drained with `readAll()` and then `flush()`ed so a final line
+ * without a trailing newline is included, and it is never opened a second
+ * time for the label. A source that cannot be read yields
+ * `availability: 'unavailable'` with a reason instead of silent zeros; a
+ * reader that reports truncation yields `partial`.
+ */
+export function readSessionFileStats(provider, sessionPath, options = {}) {
+    const base = {
+        providerId: provider.id,
+        sessionId: provider.getSessionId(sessionPath),
+        filePath: sessionPath,
+    };
+    let reader;
+    let events;
+    try {
+        reader = provider.createReader(sessionPath);
+        events = reader.readAll();
+        // Readers buffer line-oriented input; flushing emits a trailing partial
+        // line into the same array `readAll()` returned.
+        reader.flush();
+    }
+    catch (error) {
+        return computeSessionFileStats([], {
+            ...base,
+            availability: 'unavailable',
+            unavailableReason: errorMessage(error),
+        });
+    }
+    if (events.length === 0 && !reader.exists()) {
+        return computeSessionFileStats([], {
+            ...base,
+            availability: 'unavailable',
+            unavailableReason: describeMissingSource(provider),
+        });
+    }
+    return computeSessionFileStats(events, {
+        ...base,
+        label: options.resolveLabel?.() ?? undefined,
+        computeContextSize: providerContextSizeFn(provider),
+        availability: reader.wasTruncated() ? 'partial' : 'full',
+    });
+}

package/dist/esm/sessionTokenTotals.js

@@ -0,0 +1,98 @@
+/**
+ * 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 * as path from 'path';
+import { extractNormalizedUsage } from './usageNormalization';
+import { summarizeTokens, sumTokenTotals, } from './tokenSummary';
+/** Token record of one subagent, in `TokenTotalsLike` form. */
+export 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. */
+export function combineSessionTokenTotals(mainThread, subagents) {
+    const subagentRecords = subagents.map(subagentTokenTotals);
+    const main = 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: summarizeTokens(subagentRecords[index]),
+        })),
+        subagentTotal: summarizeTokens(sumTokenTotals(subagentRecords)),
+        combined: summarizeTokens(sumTokenTotals([mainRecord, ...subagentRecords])),
+    };
+}
+/** Sum the usage a provider reader reports for one session transcript. */
+export 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 = 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".
+ */
+export 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. */
+export function scanSessionSubagents(provider, sessionPath) {
+    try {
+        return provider.scanSubagents(path.dirname(sessionPath), provider.getSessionId(sessionPath));
+    }
+    catch {
+        return [];
+    }
+}

package/dist/esm/sessionTranscripts.js

@@ -0,0 +1,49 @@
+import { statSync } from 'node:fs';
+import { projectSessionTranscript, } from './transcript';
+/** List recent sessions using the provider's existing discovery and metadata APIs. */
+export function listRecentSessions(provider, workspacePath, options = {}) {
+    const limit = Math.max(0, options.limit ?? 20);
+    // Sort on mtime alone first so labels — the only per-file content read —
+    // are extracted just for the returned slice, not every discovered session.
+    return provider
+        .findAllSessions(workspacePath)
+        .map((sessionPath) => ({
+        sessionPath,
+        modifiedAt: sessionModifiedAt(provider, sessionPath).toISOString(),
+    }))
+        .sort((left, right) => right.modifiedAt.localeCompare(left.modifiedAt))
+        .slice(0, limit)
+        .map(({ sessionPath, modifiedAt }) => ({
+        provider: provider.id,
+        sessionId: provider.getSessionId(sessionPath),
+        sessionPath,
+        label: provider.extractSessionLabel(sessionPath),
+        modifiedAt,
+    }));
+}
+function sessionModifiedAt(provider, sessionPath) {
+    const metadata = provider.getSessionMetadata?.(sessionPath);
+    if (metadata)
+        return metadata.mtime;
+    try {
+        return statSync(sessionPath).mtime;
+    }
+    catch {
+        return new Date(0);
+    }
+}
+/** Read a canonical transcript through a provider's existing reader. */
+export function readSessionTranscript(provider, sessionPath, options = {}) {
+    const reader = provider.createReader(sessionPath);
+    try {
+        return projectSessionTranscript(reader.readAll(), {
+            ...options,
+            provider: provider.id,
+            sessionId: provider.getSessionId(sessionPath),
+            sourcePath: sessionPath,
+        });
+    }
+    finally {
+        reader.flush();
+    }
+}

package/dist/esm/stateFile.js

@@ -0,0 +1,119 @@
+/**
+ * `state.json`: a small, versioned file for external consumers (tmux
+ * status bars, menu-bar apps, scripts) that want Sidekick's current account,
+ * quota windows with freshness, context usage, session cost, and the active
+ * billing block without running a Sidekick command.
+ *
+ * Written by the status line on every prompt and by both dashboards on their
+ * refresh ticks, but only when the content changed, so the hot path costs one
+ * small read in the common case. The schema is public: `schemaVersion` is 1,
+ * fields are only ever added, and the matching zod schema lives in
+ * `sidekick-shared/schemas` (`sidekickStateFileSchema`). This module does not
+ * import zod, so the status-line fast path stays small.
+ *
+ * @module stateFile
+ */
+import * as fs from 'fs';
+import { getGlobalDataPath } from './paths';
+import { classifyQuotaFreshness } from './quota';
+import { atomicWriteJsonSync } from './writers/atomic';
+export const STATE_FILE_SCHEMA_VERSION = 1;
+export const STATE_FILE_NAME = 'state.json';
+export function getStateFilePath() {
+    return getGlobalDataPath(STATE_FILE_NAME);
+}
+/** Read the current state file; null when absent or unreadable. */
+export function readStateFile(filePath = getStateFilePath()) {
+    try {
+        const parsed = JSON.parse(fs.readFileSync(filePath, 'utf8'));
+        return parsed && parsed.schemaVersion === STATE_FILE_SCHEMA_VERSION ? parsed : null;
+    }
+    catch {
+        return null;
+    }
+}
+/** Key-order-independent serialisation, dropping undefined values. */
+function stableStringify(value) {
+    if (Array.isArray(value))
+        return `[${value.map(stableStringify).join(',')}]`;
+    if (value && typeof value === 'object') {
+        const record = value;
+        const entries = Object.keys(record)
+            .sort()
+            .filter((key) => record[key] !== undefined)
+            .map((key) => `${JSON.stringify(key)}:${stableStringify(record[key])}`);
+        return `{${entries.join(',')}}`;
+    }
+    return JSON.stringify(value) ?? 'null';
+}
+/** The content that decides whether a rewrite is needed: everything the writer does not stamp. */
+function comparable(state) {
+    return stableStringify({ ...state, schemaVersion: undefined, writtenAt: undefined });
+}
+/**
+ * Write the state file atomically, but only when something other than
+ * `writtenAt` changed since the last write. Returns true when a write
+ * happened. Never throws: the state file is a convenience for other tools.
+ */
+export function writeStateFile(state, options = {}) {
+    const filePath = options.filePath ?? getStateFilePath();
+    try {
+        const existing = readStateFile(filePath);
+        if (existing && comparable(existing) === comparable(state))
+            return false;
+        const next = {
+            schemaVersion: STATE_FILE_SCHEMA_VERSION,
+            writtenAt: (options.now ?? new Date()).toISOString(),
+            ...state,
+        };
+        atomicWriteJsonSync(filePath, next);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Project a quota sample onto the state-file shape. A live sample (for
+ * example from the status-line payload) carries `capturedAt` but no age, so
+ * the age and freshness are derived from `now` when the sample omits them.
+ */
+export function quotaToStateFile(quota, now = Date.now()) {
+    if (!quota || !quota.available)
+        return null;
+    let ageMs = typeof quota.ageMs === 'number' ? quota.ageMs : null;
+    let freshness = quota.freshness ?? null;
+    if (ageMs === null && quota.capturedAt) {
+        const capturedMs = Date.parse(quota.capturedAt);
+        if (Number.isFinite(capturedMs)) {
+            ageMs = Math.max(0, now - capturedMs);
+            freshness ??= classifyQuotaFreshness(ageMs);
+        }
+    }
+    return {
+        fiveHour: { utilization: quota.fiveHour.utilization, resetsAt: quota.fiveHour.resetsAt },
+        sevenDay: { utilization: quota.sevenDay.utilization, resetsAt: quota.sevenDay.resetsAt },
+        source: quota.source ?? null,
+        capturedSource: quota.capturedSource ?? null,
+        capturedAt: quota.capturedAt ?? null,
+        ageMs,
+        freshness,
+    };
+}
+/** Project a billing block onto the state-file shape (totals only). */
+export function billingBlockToStateFile(block) {
+    if (!block)
+        return null;
+    return {
+        start: block.start,
+        end: block.end,
+        isActive: block.isActive,
+        tokens: block.tokens.total,
+        costUsd: block.costUsd,
+        costProvenance: block.costProvenance,
+        burnRatePerMinute: block.burnRatePerMinute,
+        projectedTokens: block.projectedTokens,
+        projectedCostUsd: block.projectedCostUsd,
+        remainingMs: block.remainingMs,
+    };
+}

package/dist/esm/statusline/BurnRateCalculator.js

@@ -0,0 +1,40 @@
+/** Sliding-window burn-rate calculator shared by every Sidekick surface. */
+export class BurnRateCalculator {
+    events = [];
+    windowMs;
+    constructor(windowMinutes = 5) {
+        this.windowMs = windowMinutes * 60_000;
+    }
+    addEvent(tokens, timestamp = new Date()) {
+        this.events.push({ tokens, timestamp });
+        this.pruneOldEvents(timestamp);
+    }
+    calculateBurnRate(now = new Date()) {
+        this.pruneOldEvents(now);
+        if (this.events.length === 0)
+            return 0;
+        const totalTokens = this.events.reduce((sum, event) => sum + event.tokens, 0);
+        const elapsedMinutes = Math.max((now.getTime() - this.events[0].timestamp.getTime()) / 60_000, 1);
+        return totalTokens / elapsedMinutes;
+    }
+    estimateTimeToQuota(currentTokens, quotaLimit, now = new Date()) {
+        return estimateTimeToQuota(currentTokens, quotaLimit, this.calculateBurnRate(now));
+    }
+    getEventCount() {
+        return this.events.length;
+    }
+    reset() {
+        this.events = [];
+    }
+    pruneOldEvents(now) {
+        const cutoff = now.getTime() - this.windowMs;
+        this.events = this.events.filter((event) => event.timestamp.getTime() >= cutoff);
+    }
+}
+/** Pure ETA helper for cached or externally computed burn rates. */
+export function estimateTimeToQuota(currentUsage, quotaLimit, burnRatePerMinute) {
+    if (burnRatePerMinute <= 0)
+        return null;
+    const remaining = quotaLimit - currentUsage;
+    return remaining <= 0 ? 0 : remaining / burnRatePerMinute;
+}

package/dist/esm/statusline/claudeStatuslinePayload.js

@@ -0,0 +1,148 @@
+/**
+ * Parser for the JSON Claude Code pipes to its status-line command.
+ *
+ * Claude Code runs the configured `statusLine.command` after every response
+ * (debounced at 300 ms) with a JSON document on stdin describing the session:
+ * model, workspace, context-window usage, estimated session cost, and — for
+ * Claude.ai Pro and Max subscribers — the *official* five-hour and seven-day
+ * rate-limit windows. That last block is the same data `/usage` shows and
+ * needs no network call, so Sidekick treats it as its most authoritative
+ * quota source whenever the status line is installed.
+ *
+ * Only the fields Sidekick reads are typed here; the raw document is kept on
+ * `raw` for callers that need more. Browser-safe: no Node imports.
+ *
+ * @module statusline/claudeStatuslinePayload
+ */
+function isRecord(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+function num(value) {
+    return typeof value === 'number' && Number.isFinite(value) ? value : undefined;
+}
+function nullableNum(value) {
+    if (value === null)
+        return null;
+    return num(value);
+}
+function str(value) {
+    return typeof value === 'string' && value.length > 0 ? value : undefined;
+}
+function bool(value) {
+    return typeof value === 'boolean' ? value : undefined;
+}
+function window(value) {
+    if (!isRecord(value))
+        return undefined;
+    const usedPercentage = num(value.used_percentage);
+    const resetsAt = num(value.resets_at);
+    if (usedPercentage === undefined || resetsAt === undefined)
+        return undefined;
+    return { usedPercentage, resetsAt };
+}
+function defined(value) {
+    return Object.values(value).some((entry) => entry !== undefined) ? value : undefined;
+}
+/**
+ * Parse a status-line document. Returns `null` for empty input, non-JSON, or
+ * JSON that is not an object; never throws.
+ */
+export function parseClaudeStatuslinePayload(text) {
+    if (typeof text !== 'string' || !text.trim())
+        return null;
+    let raw;
+    try {
+        raw = JSON.parse(text);
+    }
+    catch {
+        return null;
+    }
+    if (!isRecord(raw))
+        return null;
+    const model = isRecord(raw.model) ? raw.model : undefined;
+    const workspace = isRecord(raw.workspace) ? raw.workspace : undefined;
+    const contextWindow = isRecord(raw.context_window) ? raw.context_window : undefined;
+    const cost = isRecord(raw.cost) ? raw.cost : undefined;
+    const rateLimits = isRecord(raw.rate_limits) ? raw.rate_limits : undefined;
+    const promptCache = isRecord(raw.prompt_cache) ? raw.prompt_cache : undefined;
+    return {
+        sessionId: str(raw.session_id),
+        transcriptPath: str(raw.transcript_path),
+        cwd: str(raw.cwd),
+        model: model ? defined({ id: str(model.id), displayName: str(model.display_name) }) : undefined,
+        workspace: workspace
+            ? defined({
+                currentDir: str(workspace.current_dir),
+                projectDir: str(workspace.project_dir),
+                gitWorktree: str(workspace.git_worktree),
+            })
+            : undefined,
+        contextWindow: contextWindow
+            ? defined({
+                usedPercentage: nullableNum(contextWindow.used_percentage),
+                remainingPercentage: nullableNum(contextWindow.remaining_percentage),
+                contextWindowSize: num(contextWindow.context_window_size),
+                totalInputTokens: num(contextWindow.total_input_tokens),
+                totalOutputTokens: num(contextWindow.total_output_tokens),
+            })
+            : undefined,
+        cost: cost
+            ? defined({
+                totalCostUsd: num(cost.total_cost_usd),
+                totalDurationMs: num(cost.total_duration_ms),
+                totalApiDurationMs: num(cost.total_api_duration_ms),
+                totalLinesAdded: num(cost.total_lines_added),
+                totalLinesRemoved: num(cost.total_lines_removed),
+            })
+            : undefined,
+        rateLimits: rateLimits
+            ? defined({
+                fiveHour: window(rateLimits.five_hour),
+                sevenDay: window(rateLimits.seven_day),
+                spendLimit: window(rateLimits.spend_limit),
+            })
+            : undefined,
+        promptCache: promptCache
+            ? defined({
+                warm: bool(promptCache.warm),
+                cachingObserved: bool(promptCache.caching_observed),
+                hitRatio: nullableNum(promptCache.hit_ratio),
+                requests: num(promptCache.requests),
+                misses: num(promptCache.misses),
+                expectedRebuilds: num(promptCache.expected_rebuilds),
+            })
+            : undefined,
+        raw,
+    };
+}
+function toWindow(live, fallback) {
+    if (live) {
+        return {
+            utilization: Math.max(0, live.usedPercentage),
+            resetsAt: new Date(live.resetsAt * 1000).toISOString(),
+        };
+    }
+    return fallback ?? { utilization: 0, resetsAt: '' };
+}
+/**
+ * Build a `QuotaState` from the official rate-limit block. Returns `null`
+ * when the payload carries no rate limits at all (API-key users, or before
+ * the first response of a session), so callers fall back to their other
+ * sources.
+ */
+export function quotaFromStatuslinePayload(payload, options = {}) {
+    const limits = payload.rateLimits;
+    if (!limits?.fiveHour && !limits?.sevenDay)
+        return null;
+    const now = options.now ?? new Date();
+    const fallback = options.fallback ?? undefined;
+    return {
+        fiveHour: toWindow(limits.fiveHour, fallback?.fiveHour),
+        sevenDay: toWindow(limits.sevenDay, fallback?.sevenDay),
+        available: true,
+        providerId: 'claude-code',
+        source: 'statusline',
+        capturedAt: now.toISOString(),
+        stale: false,
+    };
+}