sidekick-shared 0.27.6 → 0.28.0

package/dist/esm/usage/usageReports.js

@@ -0,0 +1,202 @@
+/**
+ * Daily, weekly, monthly, and per-session usage rows bucketed from usage
+ * events by the time of each event, so a session that crosses midnight is
+ * split across the days it actually ran in. Browser-safe: no Node imports.
+ *
+ * @module usage/usageReports
+ */
+import { classifyCostProvenance } from '../aggregation/costProvenance';
+import { formatLocalDateKey } from '../formatting';
+function dayParts(ms, utc) {
+    const date = new Date(ms);
+    return utc
+        ? {
+            year: date.getUTCFullYear(),
+            month: date.getUTCMonth(),
+            day: date.getUTCDate(),
+            weekday: date.getUTCDay(),
+        }
+        : {
+            year: date.getFullYear(),
+            month: date.getMonth(),
+            day: date.getDate(),
+            weekday: date.getDay(),
+        };
+}
+function pad(value) {
+    return String(value).padStart(2, '0');
+}
+/** The `YYYY-MM-DD` key of the week containing `ms`, starting on `weekStartsOn`. */
+export function weekKey(ms, options = {}) {
+    const utc = options.utc ?? false;
+    const start = options.weekStartsOn ?? 1;
+    const parts = dayParts(ms, utc);
+    const offset = (parts.weekday - start + 7) % 7;
+    if (utc) {
+        return new Date(Date.UTC(parts.year, parts.month, parts.day - offset))
+            .toISOString()
+            .slice(0, 10);
+    }
+    return formatLocalDateKey(new Date(parts.year, parts.month, parts.day - offset));
+}
+/** The time key for one event at the requested granularity. */
+export function usageBucketKey(event, options) {
+    const utc = options.utc ?? false;
+    switch (options.granularity) {
+        case 'session':
+            return event.sessionId;
+        case 'week':
+            return weekKey(event.timestamp, { utc, weekStartsOn: options.weekStartsOn });
+        case 'month': {
+            const parts = dayParts(event.timestamp, utc);
+            return `${parts.year}-${pad(parts.month + 1)}`;
+        }
+        case 'day':
+        default:
+            return utc
+                ? new Date(event.timestamp).toISOString().slice(0, 10)
+                : formatLocalDateKey(event.timestamp);
+    }
+}
+function emptyTokens() {
+    return { inputTokens: 0, outputTokens: 0, cacheWriteTokens: 0, cacheReadTokens: 0 };
+}
+function addTokens(target, source) {
+    target.inputTokens += source.inputTokens;
+    target.outputTokens += source.outputTokens;
+    target.cacheWriteTokens += source.cacheWriteTokens;
+    target.cacheReadTokens += source.cacheReadTokens;
+}
+/**
+ * Group usage events into rows. Rows are sorted by key (sessions by first
+ * event), then provider, project, and model, so tables read oldest first.
+ */
+export function bucketUsage(events, options) {
+    const groupBy = new Set(options.groupBy ?? ['provider']);
+    const isSession = options.granularity === 'session';
+    const byProvider = isSession || groupBy.has('provider');
+    const byProject = isSession || groupBy.has('project');
+    const byModel = groupBy.has('model');
+    const buckets = new Map();
+    for (const event of events) {
+        const key = usageBucketKey(event, options);
+        const provider = byProvider ? event.provider : null;
+        const project = byProject ? event.project : null;
+        const model = byModel ? event.model : null;
+        const id = [key, provider ?? '', project ?? '', model ?? ''].join('|');
+        let acc = buckets.get(id);
+        if (!acc) {
+            acc = {
+                row: {
+                    key,
+                    granularity: options.granularity,
+                    provider,
+                    project,
+                    model,
+                    sessionId: isSession ? event.sessionId : null,
+                    models: [],
+                    calls: 0,
+                    sessions: 0,
+                    tokens: emptyTokens(),
+                    totalTokens: 0,
+                    costUsd: 0,
+                    costProvenance: 'none',
+                    unpricedCalls: 0,
+                    firstTimestamp: event.timestamp,
+                    lastTimestamp: event.timestamp,
+                },
+                sessionIds: new Set(),
+                modelTokens: new Map(),
+                reportedCalls: 0,
+                estimatedCalls: 0,
+            };
+            buckets.set(id, acc);
+        }
+        const { row } = acc;
+        row.calls += 1;
+        addTokens(row.tokens, event.tokens);
+        row.totalTokens += event.tokens.totalTokens;
+        row.firstTimestamp = Math.min(row.firstTimestamp, event.timestamp);
+        row.lastTimestamp = Math.max(row.lastTimestamp, event.timestamp);
+        acc.sessionIds.add(event.sessionId);
+        acc.modelTokens.set(event.model, (acc.modelTokens.get(event.model) ?? 0) + event.tokens.totalTokens);
+        if (event.costUsd !== null) {
+            row.costUsd += event.costUsd;
+            if (event.costProvenance === 'provider-reported')
+                acc.reportedCalls += 1;
+            else
+                acc.estimatedCalls += 1;
+        }
+        else {
+            row.unpricedCalls += 1;
+        }
+    }
+    const rows = [];
+    for (const acc of buckets.values()) {
+        acc.row.sessions = acc.sessionIds.size;
+        acc.row.models = [...acc.modelTokens.entries()]
+            .sort((a, b) => b[1] - a[1])
+            .map(([model]) => model);
+        acc.row.costProvenance = classifyCostProvenance({
+            reportedCalls: acc.reportedCalls,
+            estimatedCalls: acc.estimatedCalls,
+            unpricedCalls: acc.row.unpricedCalls,
+        });
+        rows.push(acc.row);
+    }
+    return rows.sort((a, b) => (isSession ? a.firstTimestamp - b.firstTimestamp : a.key.localeCompare(b.key)) ||
+        (a.provider ?? '').localeCompare(b.provider ?? '') ||
+        (a.project ?? '').localeCompare(b.project ?? '') ||
+        (a.model ?? '').localeCompare(b.model ?? ''));
+}
+/**
+ * Sum rows that do not overlap (for example every row of one `bucketUsage`
+ * call). Pass the events too when rows are not per-session, so distinct
+ * sessions are counted once instead of once per row they appear in.
+ */
+export function summarizeUsageRows(rows, events) {
+    const totals = {
+        calls: 0,
+        sessions: 0,
+        tokens: emptyTokens(),
+        totalTokens: 0,
+        costUsd: 0,
+        costProvenance: 'none',
+        unpricedCalls: 0,
+    };
+    let reportedCalls = 0;
+    let estimatedCalls = 0;
+    const sessionIds = new Set();
+    for (const row of rows) {
+        totals.calls += row.calls;
+        addTokens(totals.tokens, row.tokens);
+        totals.totalTokens += row.totalTokens;
+        totals.costUsd += row.costUsd;
+        totals.unpricedCalls += row.unpricedCalls;
+        const priced = row.calls - row.unpricedCalls;
+        if (row.costProvenance === 'reported')
+            reportedCalls += priced;
+        else if (row.costProvenance === 'estimated')
+            estimatedCalls += priced;
+        else if (row.costProvenance === 'mixed') {
+            reportedCalls += 1;
+            estimatedCalls += 1;
+        }
+        if (row.sessionId)
+            sessionIds.add(row.sessionId);
+    }
+    if (events) {
+        for (const event of events)
+            sessionIds.add(event.sessionId);
+        totals.sessions = sessionIds.size;
+    }
+    else {
+        totals.sessions = sessionIds.size || rows.reduce((sum, row) => sum + row.sessions, 0);
+    }
+    totals.costProvenance = classifyCostProvenance({
+        reportedCalls,
+        estimatedCalls,
+        unpricedCalls: totals.unpricedCalls,
+    });
+    return totals;
+}

package/dist/esm/usageNormalization.js

@@ -0,0 +1,95 @@
+import { getModelPricing } from './modelInfo';
+function tokenCount(value) {
+    return typeof value === 'number' && Number.isFinite(value) && value > 0
+        ? Math.min(Number.MAX_SAFE_INTEGER, Math.floor(value))
+        : 0;
+}
+function reportedCost(value) {
+    return typeof value === 'number' && Number.isFinite(value) && value >= 0 ? value : undefined;
+}
+/** Convert provider-specific counters into finite, nonnegative, disjoint categories. */
+export function normalizeProviderUsage(input) {
+    const rawInput = tokenCount(input.inputTokens);
+    const cacheReadTokens = tokenCount(input.cacheReadTokens);
+    const cacheWriteTokens = tokenCount(input.cacheWriteTokens);
+    const outputTokens = tokenCount(input.outputTokens);
+    const reasoningTokens = tokenCount(input.reasoningTokens);
+    const isOpenAI = input.semantics === 'openai';
+    const uncachedInputTokens = isOpenAI ? Math.max(0, rawInput - cacheReadTokens) : rawInput;
+    const reasoningIncludedInOutput = input.reasoningIncludedInOutput ?? input.semantics === 'openai';
+    const cacheInclusiveInputTokens = uncachedInputTokens + cacheReadTokens + cacheWriteTokens;
+    const billableOutputTokens = outputTokens + (reasoningIncludedInOutput ? 0 : reasoningTokens);
+    const totalTokens = cacheInclusiveInputTokens + billableOutputTokens;
+    const semantics = isOpenAI
+        ? 'openai-inclusive-cache'
+        : input.semantics === 'anthropic'
+            ? 'anthropic-additive-cache'
+            : 'sidekick-disjoint';
+    return {
+        uncachedInputTokens,
+        cacheReadTokens,
+        cacheWriteTokens,
+        outputTokens,
+        reasoningTokens,
+        reasoningIncludedInOutput,
+        cacheInclusiveInputTokens,
+        billableOutputTokens,
+        totalTokens,
+        ...(input.model ? { model: input.model } : {}),
+        ...(reportedCost(input.reportedCostUsd) !== undefined
+            ? { reportedCostUsd: reportedCost(input.reportedCostUsd) }
+            : {}),
+        provenance: {
+            semantics,
+            ...(input.provider ? { provider: input.provider } : {}),
+            ...(input.source ? { source: input.source } : {}),
+        },
+    };
+}
+/** Extract normalized usage from an event, preserving parser-owned semantics when present. */
+export function extractNormalizedUsage(event) {
+    if (event.message?.normalizedUsage)
+        return event.message.normalizedUsage;
+    const usage = event.message?.usage;
+    if (!usage)
+        return null;
+    const providerId = event.providerMetadata?.providerId;
+    return normalizeProviderUsage({
+        semantics: 'sidekick',
+        provider: providerId,
+        source: event.providerMetadata?.source ?? 'legacy-message-usage',
+        model: event.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: providerId === 'codex' || providerId === 'openai',
+        reportedCostUsd: usage.reported_cost,
+    });
+}
+/** Price normalized, disjoint usage without double-counting reasoning tokens. */
+export function calculateNormalizedUsageCost(input) {
+    const { usage } = input;
+    const modelId = input.modelId ?? usage.model;
+    if (usage.reportedCostUsd !== undefined) {
+        return { costUsd: usage.reportedCostUsd, source: 'provider-reported', modelId, usage };
+    }
+    const explicit = input.pricing !== undefined;
+    const pricing = explicit ? input.pricing : modelId ? getModelPricing(modelId) : null;
+    if (!pricing)
+        return { costUsd: null, source: 'unpriced', modelId, usage };
+    const costUsd = (usage.uncachedInputTokens / 1_000_000) * pricing.inputCostPerMillion +
+        (usage.cacheReadTokens / 1_000_000) * pricing.cacheReadCostPerMillion +
+        (usage.cacheWriteTokens / 1_000_000) * pricing.cacheWriteCostPerMillion +
+        (usage.billableOutputTokens / 1_000_000) * pricing.outputCostPerMillion;
+    if (!Number.isFinite(costUsd) || costUsd < 0) {
+        return { costUsd: null, source: 'unpriced', modelId, usage };
+    }
+    return {
+        costUsd,
+        source: explicit ? 'explicit-pricing' : 'model-catalog',
+        modelId,
+        usage,
+    };
+}

package/dist/esm/watchers/eventBridge.js

@@ -0,0 +1,219 @@
+/**
+ * Converts SessionEvent (rich canonical format) to FollowEvent (flat summary).
+ *
+ * This bridge enables the two-tier event system:
+ *   Provider logs → Shared parsers → SessionEvent → toFollowEvents() → FollowEvent
+ *
+ * SessionEvent preserves full tool inputs, results, and message structure.
+ * FollowEvent is a lossy summary for timeline display and CLI output.
+ */
+import { formatToolSummary } from '../formatters/toolSummary';
+/**
+ * Converts a single SessionEvent to one or more FollowEvents.
+ *
+ * A single SessionEvent (e.g. an assistant message with tool_use blocks)
+ * may produce multiple FollowEvents (one per tool_use + one for text).
+ */
+export function toFollowEvents(event, providerId) {
+    const events = [];
+    const ts = event.timestamp || new Date().toISOString();
+    const permissionMode = event.permissionMode;
+    const usage = event.message?.usage;
+    const tokens = usage
+        ? { input: usage.input_tokens || 0, output: usage.output_tokens || 0 }
+        : undefined;
+    const cacheTokens = usage && (usage.cache_read_input_tokens || usage.cache_creation_input_tokens)
+        ? { read: usage.cache_read_input_tokens || 0, write: usage.cache_creation_input_tokens || 0 }
+        : undefined;
+    const cost = usage?.reported_cost;
+    const usageKind = usage ? event.message?.usageKind : undefined;
+    const model = event.message?.model;
+    const rateLimits = event.rateLimits;
+    switch (event.type) {
+        case 'user': {
+            const content = event.message?.content;
+            // Extract tool_result blocks from user messages
+            if (Array.isArray(content)) {
+                for (const block of content) {
+                    if (block.type === 'tool_result' && typeof block.tool_use_id === 'string') {
+                        const resultText = typeof block.content === 'string' ? truncate(block.content, 120) : '';
+                        events.push({
+                            providerId,
+                            type: 'tool_result',
+                            timestamp: ts,
+                            summary: resultText || '(tool result)',
+                            raw: block,
+                        });
+                    }
+                }
+            }
+            const text = extractTextContent(content);
+            if (text || events.length === 0) {
+                events.push({
+                    providerId,
+                    type: 'user',
+                    timestamp: ts,
+                    summary: text || '(user message)',
+                    model,
+                    raw: event,
+                });
+            }
+            break;
+        }
+        case 'assistant': {
+            const content = event.message?.content;
+            // Extract tool_use blocks first
+            if (Array.isArray(content)) {
+                for (const block of content) {
+                    if (block.type === 'tool_use' && typeof block.name === 'string') {
+                        const input = block.input
+                            ? summarizeToolInput(block.name, block.input)
+                            : '';
+                        events.push({
+                            providerId,
+                            type: 'tool_use',
+                            timestamp: ts,
+                            summary: input ? `${block.name} ${input}` : block.name,
+                            toolName: block.name,
+                            toolInput: input,
+                            model,
+                            raw: block,
+                        });
+                    }
+                }
+            }
+            // Emit assistant text (if any)
+            const text = extractTextContent(content);
+            if (text || events.length === 0) {
+                events.push({
+                    providerId,
+                    type: 'assistant',
+                    timestamp: ts,
+                    summary: text || '(thinking...)',
+                    tokens,
+                    cacheTokens,
+                    ...(usageKind ? { usageKind } : {}),
+                    cost,
+                    model,
+                    raw: event,
+                });
+            }
+            else if (tokens) {
+                // Attach tokens to the last tool_use event if no separate text
+                const last = events[events.length - 1];
+                last.tokens = tokens;
+                last.cacheTokens = cacheTokens;
+                if (usageKind)
+                    last.usageKind = usageKind;
+                last.cost = cost;
+            }
+            break;
+        }
+        case 'tool_use': {
+            const name = event.tool?.name || 'unknown';
+            const input = event.tool?.input ? summarizeToolInput(name, event.tool.input) : '';
+            events.push({
+                providerId,
+                type: 'tool_use',
+                timestamp: ts,
+                summary: input ? `${name} ${input}` : name,
+                toolName: name,
+                toolInput: input,
+                model,
+                raw: event,
+            });
+            break;
+        }
+        case 'tool_result': {
+            const output = event.result?.output;
+            const text = typeof output === 'string' ? truncate(output, 120) : '';
+            events.push({
+                providerId,
+                type: 'tool_result',
+                timestamp: ts,
+                summary: text || '(tool result)',
+                raw: event,
+            });
+            break;
+        }
+        case 'summary': {
+            events.push({
+                providerId,
+                type: 'summary',
+                timestamp: ts,
+                summary: 'Context compacted',
+                compaction: event.compaction,
+                raw: event,
+            });
+            break;
+        }
+        case 'system': {
+            const text = extractTextContent(event.message?.content);
+            const label = event.message?.sourceLabel || event.message?.role || 'system';
+            const summary = text ||
+                (usage ? `Tokens: ${usage.input_tokens || 0} in / ${usage.output_tokens || 0} out` : label);
+            events.push({
+                providerId,
+                type: 'system',
+                timestamp: ts,
+                summary: label && text ? `${label}: ${text}` : summary,
+                tokens,
+                cacheTokens,
+                ...(usageKind ? { usageKind } : {}),
+                cost,
+                model,
+                rateLimits,
+                raw: event,
+            });
+            break;
+        }
+        default: {
+            // Handle 'result' and other types as system events
+            const evtType = event.type;
+            if (evtType === 'result') {
+                events.push({
+                    providerId,
+                    type: 'system',
+                    timestamp: ts,
+                    summary: 'Session ended',
+                    raw: event,
+                });
+            }
+            break;
+        }
+    }
+    // Propagate permission mode to all generated events
+    if (permissionMode) {
+        for (const e of events) {
+            e.permissionMode = permissionMode;
+        }
+    }
+    if (rateLimits) {
+        for (const e of events) {
+            e.rateLimits = e.rateLimits ?? rateLimits;
+        }
+    }
+    return events;
+}
+// ── Helpers ──
+function extractTextContent(content) {
+    if (!content)
+        return '';
+    if (typeof content === 'string')
+        return truncate(content, 200);
+    if (Array.isArray(content)) {
+        for (const block of content) {
+            if (block.type === 'text' && typeof block.text === 'string') {
+                return truncate(block.text, 200);
+            }
+        }
+    }
+    return '';
+}
+function summarizeToolInput(toolName, input) {
+    return formatToolSummary(toolName, input);
+}
+function truncate(text, maxLen) {
+    const clean = text.replace(/\s+/g, ' ').trim();
+    return clean.length > maxLen ? clean.substring(0, maxLen - 3) + '...' : clean;
+}

package/dist/esm/watchers/factory.js

@@ -0,0 +1,63 @@
+/**
+ * Factory for creating the correct session watcher by provider.
+ */
+import * as path from 'path';
+import { getOpenCodeDataDir } from '../providers/openCode';
+import { JsonlSessionWatcher } from './jsonlWatcher';
+import { ProviderReaderSessionWatcher } from './providerReaderWatcher';
+import { SqliteSessionWatcher } from './sqliteWatcher';
+/**
+ * Resolve the session a command should act on: an exact or unique-prefix
+ * match of `sessionId` among the workspace's sessions, or the most recent
+ * session when no id is given. Throws with the available ids on a miss.
+ */
+export function resolveSessionPath(provider, workspacePath, sessionId) {
+    const sessions = provider.findAllSessions(workspacePath);
+    if (sessions.length === 0) {
+        throw new Error(`No sessions found for ${provider.displayName} in ${workspacePath}`);
+    }
+    if (!sessionId)
+        return sessions[0]; // most recent
+    const matches = sessions.map((sessionPath) => ({
+        sessionPath,
+        id: provider.getSessionId(sessionPath),
+    }));
+    const exact = matches.filter((candidate) => candidate.id === sessionId);
+    const candidates = exact.length > 0 ? exact : matches.filter((candidate) => candidate.id.startsWith(sessionId));
+    if (candidates.length === 0) {
+        throw new Error(`Session ${sessionId} not found. Available: ${sessions
+            .slice(0, 5)
+            .map((s) => path.basename(s))
+            .join(', ')}`);
+    }
+    if (candidates.length > 1) {
+        throw new Error(`Session ${sessionId} is ambiguous. Matches: ${candidates
+            .slice(0, 5)
+            .map((candidate) => candidate.id)
+            .join(', ')}`);
+    }
+    return candidates[0].sessionPath;
+}
+export function createWatcher(options) {
+    const { provider, workspacePath, sessionId, callbacks } = options;
+    const sessionPath = resolveSessionPath(provider, workspacePath, sessionId);
+    const watcher = createWatcherForProvider(provider, sessionPath, callbacks);
+    return { watcher, sessionPath };
+}
+function createWatcherForProvider(provider, sessionPath, callbacks) {
+    switch (provider.id) {
+        case 'claude-code':
+            return new JsonlSessionWatcher(provider.id, sessionPath, callbacks);
+        case 'codex':
+            return new ProviderReaderSessionWatcher(provider, sessionPath, callbacks);
+        case 'opencode': {
+            const dataDir = getOpenCodeDataDir();
+            const dbPath = path.join(dataDir, 'opencode.db');
+            // Session ID is the basename without extension
+            const sid = path.basename(sessionPath, '.json');
+            return new SqliteSessionWatcher(dbPath, sid, callbacks);
+        }
+        default:
+            throw new Error(`Unsupported provider: ${provider.id}`);
+    }
+}