sidekick-shared 0.22.0 → 0.23.0

package/dist/sessionMonitor.js

@@ -0,0 +1,71 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SessionMonitor = void 0;
+const EventAggregator_1 = require("./aggregation/EventAggregator");
+/**
+ * UI-independent session monitor for library consumers. It owns one provider
+ * reader and the canonical aggregator; hosts decide how often to call `poll()`.
+ */
+class SessionMonitor {
+    provider;
+    aggregator;
+    reader = null;
+    sessionPath = null;
+    listeners = new Set();
+    replayOnAttach;
+    constructor(provider, options = {}) {
+        this.provider = provider;
+        this.replayOnAttach = options.replayOnAttach ?? true;
+        this.aggregator = new EventAggregator_1.EventAggregator({ ...options, providerId: provider.id });
+    }
+    attach(sessionPath, replay = this.replayOnAttach) {
+        this.aggregator.reset();
+        this.reader = this.provider.createReader(sessionPath);
+        this.sessionPath = sessionPath;
+        if (replay)
+            this.consume(this.reader.readAll());
+        return this.getMetrics();
+    }
+    attachLatest(workspacePath, replay = this.replayOnAttach) {
+        const sessionPath = this.provider.findActiveSession(workspacePath);
+        return sessionPath ? this.attach(sessionPath, replay) : null;
+    }
+    poll() {
+        if (!this.reader)
+            return [];
+        if (this.reader.wasTruncated())
+            this.aggregator.reset();
+        const events = this.reader.readNew();
+        this.consume(events);
+        return events;
+    }
+    process(event) {
+        this.aggregator.processEvent(event);
+        for (const listener of this.listeners)
+            listener(event);
+    }
+    onEvent(listener) {
+        this.listeners.add(listener);
+        return () => this.listeners.delete(listener);
+    }
+    getMetrics() {
+        return this.aggregator.getMetrics();
+    }
+    getSessionPath() {
+        return this.sessionPath;
+    }
+    reset() {
+        this.reader?.reset();
+        this.aggregator.reset();
+    }
+    dispose() {
+        this.listeners.clear();
+        this.reader = null;
+        this.provider.dispose();
+    }
+    consume(events) {
+        for (const event of events)
+            this.process(event);
+    }
+}
+exports.SessionMonitor = SessionMonitor;

package/dist/statusline/BurnRateCalculator.d.ts

@@ -0,0 +1,14 @@
+/** Sliding-window burn-rate calculator shared by every Sidekick surface. */
+export declare class BurnRateCalculator {
+    private events;
+    private readonly windowMs;
+    constructor(windowMinutes?: number);
+    addEvent(tokens: number, timestamp?: Date): void;
+    calculateBurnRate(now?: Date): number;
+    estimateTimeToQuota(currentTokens: number, quotaLimit: number, now?: Date): number | null;
+    getEventCount(): number;
+    reset(): void;
+    private pruneOldEvents;
+}
+/** Pure ETA helper for cached or externally computed burn rates. */
+export declare function estimateTimeToQuota(currentUsage: number, quotaLimit: number, burnRatePerMinute: number): number | null;

package/dist/statusline/BurnRateCalculator.js

@@ -0,0 +1,45 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.BurnRateCalculator = void 0;
+exports.estimateTimeToQuota = estimateTimeToQuota;
+/** Sliding-window burn-rate calculator shared by every Sidekick surface. */
+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);
+    }
+}
+exports.BurnRateCalculator = BurnRateCalculator;
+/** Pure ETA helper for cached or externally computed burn rates. */
+function estimateTimeToQuota(currentUsage, quotaLimit, burnRatePerMinute) {
+    if (burnRatePerMinute <= 0)
+        return null;
+    const remaining = quotaLimit - currentUsage;
+    return remaining <= 0 ? 0 : remaining / burnRatePerMinute;
+}

package/dist/statusline/formatter.d.ts

@@ -0,0 +1,16 @@
+import type { ActiveAccountStatus } from '../accountStatus';
+import type { QuotaState } from '../quota';
+export interface StatuslineInput {
+    accounts: ActiveAccountStatus;
+    claudeQuota?: QuotaState | null;
+    codexQuota?: QuotaState | null;
+    now?: Date;
+}
+export interface StatuslineSelection {
+    providerId: 'claude-code' | 'codex';
+    accountId?: string;
+    accountLabel: string;
+    quota: QuotaState | null;
+}
+export declare function selectStatuslineAccount(input: StatuslineInput): StatuslineSelection | null;
+export declare function formatStatusline(input: StatuslineInput): string;

package/dist/statusline/formatter.js

@@ -0,0 +1,77 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.selectStatuslineAccount = selectStatuslineAccount;
+exports.formatStatusline = formatStatusline;
+const quota_1 = require("../quota");
+const BurnRateCalculator_1 = require("./BurnRateCalculator");
+function selectStatuslineAccount(input) {
+    if (input.accounts.claude.present) {
+        return {
+            providerId: 'claude-code',
+            accountId: input.accounts.claude.accountId,
+            accountLabel: input.accounts.claude.label ?? input.accounts.claude.email ?? 'claude',
+            quota: input.claudeQuota ?? null,
+        };
+    }
+    if (input.accounts.codex.present) {
+        return {
+            providerId: 'codex',
+            accountId: input.accounts.codex.accountId,
+            accountLabel: input.accounts.codex.label ?? input.accounts.codex.email ?? 'codex',
+            quota: input.codexQuota ?? null,
+        };
+    }
+    return null;
+}
+function formatStatusline(input) {
+    const selected = selectStatuslineAccount(input);
+    if (!selected)
+        return 'acct:none · quota unavailable';
+    const account = compactLabel(selected.accountLabel);
+    const quota = selected.quota;
+    if (!quota?.available)
+        return `acct:${account} · quota unavailable`;
+    const now = input.now ?? new Date();
+    const utilization = clampPercent(quota.fiveHour.utilization);
+    const reset = formatReset(quota.fiveHour.resetsAt, now);
+    const eta = estimateWindowEta(quota, now);
+    const etaText = eta == null ? '' : ` · ~${formatMinutes(eta)} left`;
+    return `acct:${account} · 5h ${Math.round(utilization)}% resets ${reset}${etaText}`;
+}
+function estimateWindowEta(quota, now) {
+    const resetAt = Date.parse(quota.fiveHour.resetsAt);
+    if (!Number.isFinite(resetAt))
+        return null;
+    const capturedAt = quota.capturedAt ? Date.parse(quota.capturedAt) : now.getTime();
+    const sampleAt = Number.isFinite(capturedAt) ? capturedAt : now.getTime();
+    const elapsedMinutes = (sampleAt - (resetAt - quota_1.FIVE_HOUR_WINDOW_MS)) / 60_000;
+    if (elapsedMinutes <= 0 || quota.fiveHour.utilization <= 0)
+        return null;
+    const burnRate = quota.fiveHour.utilization / elapsedMinutes;
+    return (0, BurnRateCalculator_1.estimateTimeToQuota)(quota.fiveHour.utilization, 100, burnRate);
+}
+function compactLabel(value) {
+    const trimmed = value.trim();
+    const localPart = trimmed.includes('@') ? trimmed.split('@')[0] : trimmed;
+    return localPart.replace(/\s+/g, '-').slice(0, 24) || 'unknown';
+}
+function clampPercent(value) {
+    return Number.isFinite(value) ? Math.min(100, Math.max(0, value)) : 0;
+}
+function formatReset(value, fallback) {
+    const reset = new Date(value);
+    const date = Number.isNaN(reset.getTime()) ? fallback : reset;
+    return new Intl.DateTimeFormat(undefined, {
+        hour: '2-digit',
+        minute: '2-digit',
+        hour12: false,
+    }).format(date);
+}
+function formatMinutes(value) {
+    const minutes = Math.max(0, Math.round(value));
+    if (minutes < 60)
+        return `${minutes}min`;
+    const hours = Math.floor(minutes / 60);
+    const remainder = minutes % 60;
+    return remainder ? `${hours}h${remainder}m` : `${hours}h`;
+}

package/dist/statusline/index.d.ts

@@ -0,0 +1,7 @@
+export { getActiveAccountStatus } from '../accountStatus';
+export type { ActiveAccountStatus, ActiveProviderAccountStatus } from '../accountStatus';
+export { readQuotaSnapshot } from '../quotaSnapshots';
+export type { QuotaSnapshotProviderId } from '../quotaSnapshots';
+export { BurnRateCalculator, estimateTimeToQuota } from './BurnRateCalculator';
+export { formatStatusline, selectStatuslineAccount } from './formatter';
+export type { StatuslineInput, StatuslineSelection } from './formatter';

package/dist/statusline/index.js

@@ -0,0 +1,13 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.selectStatuslineAccount = exports.formatStatusline = exports.estimateTimeToQuota = exports.BurnRateCalculator = exports.readQuotaSnapshot = exports.getActiveAccountStatus = void 0;
+var accountStatus_1 = require("../accountStatus");
+Object.defineProperty(exports, "getActiveAccountStatus", { enumerable: true, get: function () { return accountStatus_1.getActiveAccountStatus; } });
+var quotaSnapshots_1 = require("../quotaSnapshots");
+Object.defineProperty(exports, "readQuotaSnapshot", { enumerable: true, get: function () { return quotaSnapshots_1.readQuotaSnapshot; } });
+var BurnRateCalculator_1 = require("./BurnRateCalculator");
+Object.defineProperty(exports, "BurnRateCalculator", { enumerable: true, get: function () { return BurnRateCalculator_1.BurnRateCalculator; } });
+Object.defineProperty(exports, "estimateTimeToQuota", { enumerable: true, get: function () { return BurnRateCalculator_1.estimateTimeToQuota; } });
+var formatter_1 = require("./formatter");
+Object.defineProperty(exports, "formatStatusline", { enumerable: true, get: function () { return formatter_1.formatStatusline; } });
+Object.defineProperty(exports, "selectStatuslineAccount", { enumerable: true, get: function () { return formatter_1.selectStatuslineAccount; } });

package/dist/types/codex.d.ts

@@ -124,6 +124,8 @@ export interface CodexCustomToolCallOutputItem {
 /** Context compaction marker. */
 export interface CodexCompacted {
     summary?: string;
+    tokens_before?: number;
+    tokens_after?: number;
 }
 /** Turn context providing model and policy info. */
 export interface CodexTurnContext {

package/dist/types/historicalData.d.ts

@@ -10,8 +10,12 @@
  *     $0 because pricing was unknown — surfaced in the dashboard footer.
  * Legacy records (schemaVersion 1 or missing) have neither field and should
  * be treated as fully priced.
+ *
+ * Schema version 3 (2026-07-18) adds a capped per-session record list with
+ * provider/project dimensions, beta quality factors, churn, and impact cost.
  */
-export declare const HISTORICAL_DATA_SCHEMA_VERSION = 2;
+export declare const HISTORICAL_DATA_SCHEMA_VERSION = 3;
+export declare const HISTORICAL_SESSION_RETENTION_LIMIT = 500;
 export interface TokenTotals {
     inputTokens: number;
     outputTokens: number;
@@ -74,9 +78,32 @@ export interface HistoricalDataStore {
     monthly: Record<string, MonthlyData>;
     allTime: AllTimeStats;
     lastSaved: string;
+    /** Capped durable per-session records, newest last (schema v3). */
+    sessions?: SessionHistoryRecord[];
     importedFiles?: string[];
     lastImportTimestamp?: string;
 }
+export interface SessionHistoryRecord {
+    sessionId: string;
+    provider: string;
+    project: string;
+    startTime: string;
+    endTime: string;
+    tokens: TokenTotals;
+    totalCost: number;
+    messageCount: number;
+    qualityScore: number;
+    qualityFactors: Array<{
+        id: string;
+        label: string;
+        contribution: number;
+        maximum: number;
+        detail: string;
+    }>;
+    additions: number;
+    deletions: number;
+    costPerChangedLine: number | null;
+}
 export interface SessionSummary {
     sessionId: string;
     startTime: string;
@@ -96,5 +123,12 @@ export interface SessionSummary {
      * Omitted on v1 records or when every model was priced.
      */
     unpricedModelIds?: string[];
+    provider?: string;
+    project?: string;
+    qualityScore?: number;
+    qualityFactors?: SessionHistoryRecord['qualityFactors'];
+    additions?: number;
+    deletions?: number;
+    costPerChangedLine?: number | null;
 }
 export declare function createEmptyTokenTotals(): TokenTotals;

package/dist/types/historicalData.js

@@ -11,11 +11,15 @@
  *     $0 because pricing was unknown — surfaced in the dashboard footer.
  * Legacy records (schemaVersion 1 or missing) have neither field and should
  * be treated as fully priced.
+ *
+ * Schema version 3 (2026-07-18) adds a capped per-session record list with
+ * provider/project dimensions, beta quality factors, churn, and impact cost.
  */
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.HISTORICAL_DATA_SCHEMA_VERSION = void 0;
+exports.HISTORICAL_SESSION_RETENTION_LIMIT = exports.HISTORICAL_DATA_SCHEMA_VERSION = void 0;
 exports.createEmptyTokenTotals = createEmptyTokenTotals;
-exports.HISTORICAL_DATA_SCHEMA_VERSION = 2;
+exports.HISTORICAL_DATA_SCHEMA_VERSION = 3;
+exports.HISTORICAL_SESSION_RETENTION_LIMIT = 500;
 function createEmptyTokenTotals() {
     return {
         inputTokens: 0,

package/dist/types/observedSessionV1.d.ts

@@ -0,0 +1,70 @@
+import type { SessionEvent } from './sessionEvent';
+import type { ProviderId, SessionProviderBase } from '../providers/types';
+export type ObservationProvenanceV1 = 'reported' | 'estimated' | 'inferred';
+export interface SessionEvidenceRefV1 {
+    schemaVersion: 1;
+    provider: ProviderId;
+    sessionId: string;
+    sourcePath?: string;
+    eventIndex?: number;
+    eventId?: string;
+    timestamp?: string;
+}
+export interface ObservedValueV1<T> {
+    value: T;
+    provenance: ObservationProvenanceV1;
+    confidence: number;
+    evidence: SessionEvidenceRefV1[];
+}
+export interface PendingUserRequestV1 {
+    schemaVersion: 1;
+    id: string;
+    provider: ProviderId;
+    sessionId: string;
+    kind: ObservedValueV1<'prompt_response' | 'tool_approval' | 'question'>;
+    requestedAt: ObservedValueV1<string>;
+    prompt: ObservedValueV1<string | null>;
+}
+export interface ObservedAgentSessionV1 {
+    schemaVersion: 1;
+    identity: {
+        provider: ProviderId;
+        sessionId: string;
+        sourcePath: string;
+    };
+    cwd: ObservedValueV1<string>;
+    model: ObservedValueV1<string | null>;
+    activity: ObservedValueV1<'active' | 'idle' | 'ended' | 'unknown'>;
+    usage: {
+        inputTokens: ObservedValueV1<number>;
+        outputTokens: ObservedValueV1<number>;
+        cacheReadTokens: ObservedValueV1<number>;
+        cacheWriteTokens: ObservedValueV1<number>;
+        costUsd: ObservedValueV1<number>;
+    };
+    pendingUserRequest: PendingUserRequestV1 | null;
+    observedAt: string;
+}
+export interface ProviderCapabilitiesV1 {
+    schemaVersion: 1;
+    provider: ProviderId;
+    resume: ObservedValueV1<boolean>;
+    forkLineage: ObservedValueV1<boolean>;
+    quotaSource: ObservedValueV1<'api' | 'session' | 'mixed' | 'none'>;
+    assetExtraction: ObservedValueV1<boolean>;
+}
+export interface ProviderSessionAdapterV1 {
+    readonly schemaVersion: 1;
+    readonly provider: ProviderId;
+    readonly capabilities: ProviderCapabilitiesV1;
+    discover(cwd: string): Promise<ObservedAgentSessionV1[]>;
+    read(sessionPath: string, cwd?: string): Promise<ObservedAgentSessionV1>;
+    watch(sessionPath: string, listener: (session: ObservedAgentSessionV1) => void, cwd?: string): {
+        dispose(): void;
+    };
+    dispose(): void;
+}
+export declare function derivePendingUserRequestV1(provider: ProviderId, sessionId: string, sourcePath: string, events: SessionEvent[]): PendingUserRequestV1 | null;
+export declare function createProviderSessionAdapterV1(sessionProvider: SessionProviderBase, options?: {
+    pollIntervalMs?: number;
+}): ProviderSessionAdapterV1;

package/dist/types/observedSessionV1.js

@@ -0,0 +1,185 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.derivePendingUserRequestV1 = derivePendingUserRequestV1;
+exports.createProviderSessionAdapterV1 = createProviderSessionAdapterV1;
+function evidence(provider, sessionId, sourcePath, event, eventIndex) {
+    return [
+        {
+            schemaVersion: 1,
+            provider,
+            sessionId,
+            sourcePath,
+            eventIndex,
+            eventId: event?.message.id,
+            timestamp: event?.timestamp,
+        },
+    ];
+}
+function observed(value, provenance, confidence, refs) {
+    return { value, provenance, confidence, evidence: refs };
+}
+function derivePendingUserRequestV1(provider, sessionId, sourcePath, events) {
+    for (let index = events.length - 1; index >= 0; index--) {
+        const event = events[index];
+        // A user/tool-result event after a request means the human has responded.
+        if (event.type === 'user')
+            return null;
+        const request = waitingToolRequest(event);
+        if (request) {
+            const refs = evidence(provider, sessionId, sourcePath, event, index);
+            return {
+                schemaVersion: 1,
+                id: `${provider}:${sessionId}:${request.id ?? event.message.id ?? index}`,
+                provider,
+                sessionId,
+                kind: observed(request.kind, 'inferred', request.kind === 'question' ? 0.95 : 0.9, refs),
+                requestedAt: observed(event.timestamp, 'reported', 1, refs),
+                prompt: observed(request.prompt, request.prompt ? 'reported' : 'inferred', request.prompt ? 0.95 : 0.4, refs),
+            };
+        }
+        // A later assistant turn proves any older request was already resolved.
+        if (event.type === 'assistant' || event.type === 'tool_use')
+            return null;
+    }
+    return null;
+}
+function waitingToolRequest(event) {
+    const calls = [];
+    if (event.type === 'tool_use') {
+        calls.push({ id: event.message.id, name: event.tool?.name, input: event.tool?.input });
+    }
+    if (Array.isArray(event.message.content)) {
+        for (const block of event.message.content) {
+            if (!block || typeof block !== 'object')
+                continue;
+            const value = block;
+            if (value.type !== 'tool_use')
+                continue;
+            calls.push({
+                id: typeof value.id === 'string' ? value.id : undefined,
+                name: typeof value.name === 'string' ? value.name : undefined,
+                input: value.input,
+            });
+        }
+    }
+    for (let index = calls.length - 1; index >= 0; index--) {
+        const call = calls[index];
+        if (call.name !== 'AskUserQuestion' && call.name !== 'ExitPlanMode')
+            continue;
+        return {
+            id: call.id,
+            kind: call.name === 'AskUserQuestion' ? 'question' : 'tool_approval',
+            prompt: waitingToolPrompt(call.input, call.name),
+        };
+    }
+    return null;
+}
+function waitingToolPrompt(input, toolName) {
+    if (!input || typeof input !== 'object') {
+        return toolName === 'ExitPlanMode' ? 'Approve the proposed plan?' : null;
+    }
+    const record = input;
+    if (typeof record.question === 'string')
+        return record.question;
+    if (typeof record.prompt === 'string')
+        return record.prompt;
+    if (Array.isArray(record.questions)) {
+        const questions = record.questions
+            .map((question) => question && typeof question === 'object' && 'question' in question
+            ? String(question.question ?? '')
+            : '')
+            .filter(Boolean);
+        if (questions.length > 0)
+            return questions.join('\n');
+    }
+    if (toolName === 'ExitPlanMode')
+        return 'Approve the proposed plan?';
+    return null;
+}
+function providerCapabilities(provider) {
+    const refs = [];
+    const known = (value) => observed(value, 'inferred', 1, refs);
+    return {
+        schemaVersion: 1,
+        provider,
+        resume: known(true),
+        forkLineage: known(provider !== 'opencode'),
+        quotaSource: known(provider === 'claude-code' ? 'api' : provider === 'codex' ? 'mixed' : 'none'),
+        assetExtraction: known(true),
+    };
+}
+function createProviderSessionAdapterV1(sessionProvider, options = {}) {
+    const pollIntervalMs = options.pollIntervalMs ?? 2_000;
+    const adapter = {
+        schemaVersion: 1,
+        provider: sessionProvider.id,
+        capabilities: providerCapabilities(sessionProvider.id),
+        async discover(cwd) {
+            return Promise.all(sessionProvider.findAllSessions(cwd).map((sessionPath) => adapter.read(sessionPath, cwd)));
+        },
+        async read(sessionPath, cwd = '') {
+            const stats = sessionProvider.readSessionStats(sessionPath);
+            const events = sessionProvider.createReader(sessionPath).readAll();
+            const refs = evidence(sessionProvider.id, stats.sessionId, sessionPath);
+            const model = Object.entries(stats.modelUsage).sort((left, right) => right[1].calls - left[1].calls)[0]?.[0] ?? null;
+            const metadata = sessionProvider.getSessionMetadata?.(sessionPath);
+            const modifiedAt = metadata?.mtime.getTime() ?? Date.parse(stats.endTime);
+            const recent = Number.isFinite(modifiedAt) && Date.now() - modifiedAt < 2 * 60_000;
+            return {
+                schemaVersion: 1,
+                identity: {
+                    provider: sessionProvider.id,
+                    sessionId: stats.sessionId,
+                    sourcePath: sessionPath,
+                },
+                cwd: observed(cwd, 'inferred', cwd ? 0.95 : 0.4, refs),
+                model: observed(model, model ? 'reported' : 'inferred', model ? 1 : 0.2, refs),
+                activity: observed(recent ? 'active' : 'idle', 'inferred', 0.8, refs),
+                usage: {
+                    inputTokens: observed(stats.tokens.input, 'reported', 1, refs),
+                    outputTokens: observed(stats.tokens.output, 'reported', 1, refs),
+                    cacheReadTokens: observed(stats.tokens.cacheRead, 'reported', 1, refs),
+                    cacheWriteTokens: observed(stats.tokens.cacheWrite, 'reported', 1, refs),
+                    costUsd: observed(stats.reportedCost, stats.reportedCost > 0 ? 'reported' : 'estimated', stats.reportedCost > 0 ? 1 : 0.5, refs),
+                },
+                pendingUserRequest: derivePendingUserRequestV1(sessionProvider.id, stats.sessionId, sessionPath, events),
+                observedAt: new Date().toISOString(),
+            };
+        },
+        watch(sessionPath, listener, cwd) {
+            let disposed = false;
+            let lastSignature = '';
+            const update = async () => {
+                if (disposed)
+                    return;
+                try {
+                    const session = await adapter.read(sessionPath, cwd);
+                    const signature = JSON.stringify({
+                        activity: session.activity,
+                        model: session.model,
+                        usage: session.usage,
+                        pendingUserRequest: session.pendingUserRequest,
+                    });
+                    if (signature !== lastSignature) {
+                        lastSignature = signature;
+                        listener(session);
+                    }
+                }
+                catch {
+                    // Observed sources can disappear between polling iterations.
+                }
+            };
+            void update();
+            const timer = setInterval(update, pollIntervalMs);
+            timer.unref?.();
+            return {
+                dispose: () => {
+                    disposed = true;
+                    clearInterval(timer);
+                },
+            };
+        },
+        dispose: () => sessionProvider.dispose(),
+    };
+    return adapter;
+}

package/dist/types/opencode.d.ts

@@ -234,6 +234,7 @@ export interface DbProject {
     id: string;
     worktree: string;
     name: string | null;
+    sandboxes: string[];
     time_created: number;
     time_updated: number;
 }

package/dist/types/sessionEvent.d.ts

@@ -76,6 +76,21 @@ export interface SessionEvent {
             resetsAt: number;
         };
     };
+    /** Exact context compaction counts when reported by the provider. */
+    compaction?: {
+        tokensBefore: number;
+        tokensAfter: number;
+    };
+    /** Provider-specific signals normalized for shared analytics. */
+    providerMetadata?: {
+        retryAttempts?: number[];
+        finishReasons?: string[];
+        providerError?: {
+            type?: string;
+            message?: string;
+            code?: string | number;
+        };
+    };
     /** Tool use details (when type is 'tool_use') */
     tool?: {
         name: string;
@@ -156,7 +171,7 @@ export interface ToolCall {
     /** Truncated error message if the call failed */
     errorMessage?: string;
     /** Error category (permission, not_found, timeout, syntax, exit_code, tool_error, other) */
-    errorCategory?: string;
+    errorCategory?: import('../extractors/errorTaxonomy').ErrorCategory;
     /** Tool use ID for correlation with tool_result */
     toolUseId?: string;
     /** Truncated tool output/result content (max 5000 chars) */
@@ -506,6 +521,8 @@ export interface CompactionEvent {
     contextAfter: number;
     /** Tokens reclaimed (contextBefore - contextAfter) */
     tokensReclaimed: number;
+    /** Whether the provider reported exact counts or Sidekick inferred them. */
+    source: 'reported' | 'heuristic';
 }
 /**
  * Record of a tool output truncation event.

package/dist/watchers/eventBridge.js

@@ -141,6 +141,7 @@ function toFollowEvents(event, providerId) {
                 type: 'summary',
                 timestamp: ts,
                 summary: 'Context compacted',
+                compaction: event.compaction,
                 raw: event,
             });
             break;

package/dist/watchers/types.d.ts

@@ -36,6 +36,11 @@ export interface FollowEvent {
             resetsAt: number;
         };
     };
+    /** Exact compaction counts when supplied by the provider. */
+    compaction?: {
+        tokensBefore: number;
+        tokensAfter: number;
+    };
     /** Original raw event for JSON output. */
     raw?: unknown;
 }

package/dist/writers/atomic.d.ts

@@ -0,0 +1,4 @@
+export declare function atomicWriteJson(filePath: string, value: unknown): Promise<void>;
+export declare function atomicWriteJsonSync(filePath: string, value: unknown): void;
+/** Serializes read-modify-write cycles across Sidekick processes. */
+export declare function updateJsonStoreAtomic<T>(filePath: string, createEmpty: () => T, update: (latest: T) => T | Promise<T>): Promise<T>;