sidekick-shared 0.22.0 → 0.23.1

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,84 @@
+"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 nowMs = now.getTime();
+    if (resetAt <= nowMs)
+        return null;
+    const capturedAt = quota.capturedAt ? Date.parse(quota.capturedAt) : now.getTime();
+    const sampleAt = Number.isFinite(capturedAt) ? capturedAt : now.getTime();
+    if (sampleAt >= resetAt)
+        return null;
+    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;
+    const eta = (0, BurnRateCalculator_1.estimateTimeToQuota)(quota.fiveHour.utilization, 100, burnRate);
+    const minutesUntilReset = (resetAt - nowMs) / 60_000;
+    return eta !== null && eta < minutesUntilReset ? eta : null;
+}
+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/terminalSync.js

@@ -107,20 +107,28 @@ function buildShellHookBlock() {
 function getShellRcPaths() {
     const zshrc = path.join(os.homedir(), '.zshrc');
     const bashrc = path.join(os.homedir(), '.bashrc');
-    const paths = [zshrc];
-    if (fs.existsSync(bashrc))
-        paths.push(bashrc);
-    return paths;
+    const existing = [zshrc, bashrc].filter((filePath) => fs.existsSync(filePath));
+    if (existing.length > 0)
+        return existing;
+    const shell = path.basename(process.env.SHELL ?? 'zsh');
+    return shell === 'bash' ? [bashrc] : [zshrc];
+}
+function resolveShellRcTarget(filePath) {
+    if (!fs.existsSync(filePath))
+        return { filePath, mode: 0o600 };
+    const realPath = fs.realpathSync(filePath);
+    return { filePath: realPath, mode: fs.statSync(realPath).mode & 0o777 };
 }
 function stripShellHook(content) {
     const pattern = new RegExp(`${HOOK_START}[\\s\\S]*?${HOOK_END}\\n?`, 'g');
     return content.replace(pattern, '').replace(/\n{3,}/g, '\n\n');
 }
 function installHookInFile(filePath) {
-    const existing = fs.existsSync(filePath) ? fs.readFileSync(filePath, 'utf8') : '';
+    const target = resolveShellRcTarget(filePath);
+    const existing = fs.existsSync(target.filePath) ? fs.readFileSync(target.filePath, 'utf8') : '';
     const cleaned = stripShellHook(existing).replace(/\s*$/, '');
     const next = cleaned ? `${cleaned}\n\n${buildShellHookBlock()}` : buildShellHookBlock();
-    atomicWriteFile(filePath, next, 0o600);
+    atomicWriteFile(target.filePath, next, target.mode);
 }
 function installShellHook() {
     for (const rcPath of getShellRcPaths()) {
@@ -130,7 +138,8 @@ function installShellHook() {
 function uninstallHookInFile(filePath) {
     if (!fs.existsSync(filePath))
         return;
-    atomicWriteFile(filePath, stripShellHook(fs.readFileSync(filePath, 'utf8')), 0o600);
+    const target = resolveShellRcTarget(filePath);
+    atomicWriteFile(target.filePath, stripShellHook(fs.readFileSync(target.filePath, 'utf8')), target.mode);
 }
 function uninstallShellHook() {
     for (const rcPath of getShellRcPaths()) {

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;
@@ -47,6 +51,13 @@ export interface DailyData {
     toolUsage: ToolUsageRecord[];
     updatedAt: string;
 }
+export interface HourlyData {
+    hour: number;
+    tokens: TokenTotals;
+    totalCost: number;
+    messageCount: number;
+    sessionCount: number;
+}
 export interface MonthlyData {
     month: string;
     tokens: TokenTotals;
@@ -71,12 +82,41 @@ export interface AllTimeStats {
 export interface HistoricalDataStore {
     schemaVersion: number;
     daily: Record<string, DailyData>;
+    /** Hourly buckets keyed by local YYYY-MM-DD. */
+    hourly?: Record<string, HourlyData[]>;
     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;
+    /** Schema v3 additive fields used to make aggregate replacement idempotent. */
+    modelUsage?: ModelUsageRecord[];
+    toolUsage?: ToolUsageRecord[];
+    unpricedModelIds?: string[];
+    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 +136,13 @@ 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;
+export declare function createEmptyDataStore(): HistoricalDataStore;

package/dist/types/historicalData.js

@@ -11,11 +11,16 @@
  *     $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.createEmptyDataStore = createEmptyDataStore;
+exports.HISTORICAL_DATA_SCHEMA_VERSION = 3;
+exports.HISTORICAL_SESSION_RETENTION_LIMIT = 500;
 function createEmptyTokenTotals() {
     return {
         inputTokens: 0,
@@ -24,3 +29,24 @@ function createEmptyTokenTotals() {
         cacheReadTokens: 0,
     };
 }
+function createEmptyDataStore() {
+    const now = new Date().toISOString();
+    return {
+        schemaVersion: exports.HISTORICAL_DATA_SCHEMA_VERSION,
+        daily: {},
+        monthly: {},
+        sessions: [],
+        allTime: {
+            tokens: createEmptyTokenTotals(),
+            totalCost: 0,
+            messageCount: 0,
+            sessionCount: 0,
+            firstDate: '',
+            lastDate: '',
+            modelUsage: [],
+            toolUsage: [],
+            updatedAt: now,
+        },
+        lastSaved: now,
+    };
+}

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;