sidekick-shared 0.24.5 → 0.26.0

package/dist/codexQuota.js

@@ -33,6 +33,7 @@ var __importStar = (this && this.__importStar) || (function () {
     };
 })();
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.enrichCodexQuota = enrichCodexQuota;
 exports.quotaFromCodexRateLimits = quotaFromCodexRateLimits;
 exports.readLatestCodexQuotaFromRollouts = readLatestCodexQuotaFromRollouts;
 exports.resolveCodexQuotaFromLocalSources = resolveCodexQuotaFromLocalSources;
@@ -45,6 +46,7 @@ const codexProfiles_1 = require("./codexProfiles");
 const quotaSnapshots_1 = require("./quotaSnapshots");
 const quota_1 = require("./quota");
 const codex_1 = require("./providers/codex");
+const rolloutWalker_1 = require("./providers/rolloutWalker");
 const codex_2 = require("./types/codex");
 const DEFAULT_TAIL_BYTES = 2 * 1024 * 1024;
 const DEFAULT_MAX_SESSION_FILES = 50;
@@ -105,6 +107,7 @@ function timestampToIso(seconds) {
 function accountEmail(account) {
     return account?.email ?? account?.metadata?.email;
 }
+/** Stamp a Codex quota sample with its runtime provider, projections, and account identity. */
 function enrichCodexQuota(state, account) {
     const withProjections = (0, quota_1.withQuotaProjections)(state);
     return {
@@ -278,39 +281,14 @@ function readLatestCodexQuotaHitFromRollouts(sessionPaths, options = {}) {
     }
     return latest;
 }
-function dedupePaths(paths) {
-    const seen = new Set();
-    const unique = [];
-    for (const filePath of paths) {
-        if (seen.has(filePath))
-            continue;
-        seen.add(filePath);
-        unique.push(filePath);
-    }
-    return unique;
-}
-function sortPathsByMtimeDesc(paths) {
-    return [...paths].sort((a, b) => {
-        const aMtime = safeMtimeMs(a);
-        const bMtime = safeMtimeMs(b);
-        return bMtime - aMtime;
-    });
-}
-function safeMtimeMs(filePath) {
-    try {
-        return fs.statSync(filePath).mtime.getTime();
-    }
-    catch {
-        return 0;
-    }
-}
-function findAccountRolloutFiles(codexHome) {
+/**
+ * The newest account-level rollouts, one capped walk across the monitored
+ * homes. `limit` bounds the walk itself, so a large history is never fully
+ * enumerated or stat'ed just to tail a handful of files.
+ */
+function findAccountRolloutFiles(codexHome, limit) {
     const homes = codexHome ? [codexHome] : (0, codexProfiles_1.getCodexMonitoringHomes)();
-    const files = [];
-    for (const home of homes) {
-        files.push(...findRolloutFiles(path.join(home, 'sessions')));
-    }
-    return sortPathsByMtimeDesc(dedupePaths(files));
+    return (0, rolloutWalker_1.walkRolloutFiles)(homes.map((home) => path.join(home, 'sessions')), { limit }).map((file) => file.path);
 }
 function resolveCodexQuotaFromLocalSources(options = {}) {
     const account = options.activeAccount !== undefined ? options.activeAccount : (0, codexProfiles_1.getActiveCodexAccount)();
@@ -335,7 +313,7 @@ function resolveCodexQuotaFromLocalSources(options = {}) {
             if (workspaceHit)
                 candidates.push(workspaceHit);
         }
-        const accountSessions = findAccountRolloutFiles(options.codexHome);
+        const accountSessions = findAccountRolloutFiles(options.codexHome, maxSessionFiles);
         const accountHit = readLatestCodexQuotaHitFromRollouts(accountSessions, {
             maxTailBytes,
             maxSessionFiles,
@@ -626,36 +604,3 @@ function readLatestQuotaFromRollout(sessionPath, maxTailBytes, source) {
     }
     return null;
 }
-function findRolloutFiles(sessionsDir) {
-    const results = [];
-    function visit(dir) {
-        let entries;
-        try {
-            entries = fs.readdirSync(dir, { withFileTypes: true });
-        }
-        catch {
-            return;
-        }
-        for (const entry of entries) {
-            const fullPath = path.join(dir, entry.name);
-            if (entry.isDirectory()) {
-                visit(fullPath);
-                continue;
-            }
-            if (!entry.isFile() || !entry.name.startsWith('rollout-') || !entry.name.endsWith('.jsonl'))
-                continue;
-            try {
-                const stat = fs.statSync(fullPath);
-                if (stat.size > 0) {
-                    results.push({ path: fullPath, mtime: stat.mtime.getTime() });
-                }
-            }
-            catch {
-                // Skip inaccessible files.
-            }
-        }
-    }
-    visit(sessionsDir);
-    results.sort((a, b) => b.mtime - a.mtime);
-    return results.map((item) => item.path);
-}

package/dist/codexQuotaWatcher.d.ts

@@ -6,6 +6,7 @@ import type { SavedAccountProfile } from './accountRegistry';
 import type { Disposable } from './quotaPoller';
 import type { QuotaState } from './quota';
 import type { ProviderQuotaState } from './providerQuota';
+import { type AccountsChangedEvent } from './accountChanges';
 type CodexAccountReader = () => SavedAccountProfile | null;
 type SnapshotReader = (providerId: 'codex', accountId: string) => QuotaState | null;
 type SnapshotWriter = (providerId: 'codex', accountId: string, quota: QuotaState) => void;
@@ -27,6 +28,7 @@ export interface CodexQuotaWatcherOptions {
     workspaceId?: string;
     /** Override the history append function (used by tests). Default: `appendQuotaHistorySample`. */
     appendHistorySample?: HistoryAppender;
+    subscribeAccountsChanged?: (listener: (event: AccountsChangedEvent) => void) => Disposable;
 }
 /**
  * Watches the active Codex rollout for quota snapshots and falls back to the
@@ -46,6 +48,7 @@ export declare class CodexQuotaWatcher implements Disposable {
     private readonly now;
     private readonly workspaceId;
     private readonly appendHistorySample;
+    private readonly subscribeAccountsChanged;
     private readonly listeners;
     private discoveryTimer;
     private provider;
@@ -56,6 +59,7 @@ export declare class CodexQuotaWatcher implements Disposable {
     private lastLocalScanAt;
     private lastLocalScanState;
     private running;
+    private accountSubscription;
     constructor(workspacePath: string, options?: CodexQuotaWatcherOptions);
     start(): void;
     stop(): void;
@@ -63,12 +67,14 @@ export declare class CodexQuotaWatcher implements Disposable {
     onUpdate(cb: (state: ProviderQuotaState<'codex'>) => void): Disposable;
     onQuotaUpdate(cb: (state: ProviderQuotaState<'codex'>) => void): Disposable;
     refresh(): void;
+    private handleAccountsChanged;
     private refreshActiveSession;
     private attachToSession;
     private ingestSessionUpdate;
     private emitCachedOrUnavailable;
     private emitState;
     private getProvider;
+    private safeGetActiveAccount;
     private teardownActiveSession;
 }
 export {};

package/dist/codexQuotaWatcher.js

@@ -40,6 +40,7 @@ const codexQuota_1 = require("./codexQuota");
 const quotaSnapshots_1 = require("./quotaSnapshots");
 const quotaHistory_1 = require("./quotaHistory");
 const codex_1 = require("./providers/codex");
+const accountChanges_1 = require("./accountChanges");
 const DEFAULT_DISCOVERY_POLL_INTERVAL_MS = 30_000;
 const DEFAULT_LOCAL_SCAN_CACHE_MS = 5 * 60_000;
 function accountEmail(account) {
@@ -86,6 +87,7 @@ class CodexQuotaWatcher {
     now;
     workspaceId;
     appendHistorySample;
+    subscribeAccountsChanged;
     listeners = [];
     discoveryTimer;
     provider = null;
@@ -96,6 +98,7 @@ class CodexQuotaWatcher {
     lastLocalScanAt = Number.NEGATIVE_INFINITY;
     lastLocalScanState = null;
     running = false;
+    accountSubscription = null;
     constructor(workspacePath, options = {}) {
         this.workspacePath = workspacePath;
         this.discoveryPollIntervalMs =
@@ -119,15 +122,14 @@ class CodexQuotaWatcher {
         this.now = options.now ?? Date.now;
         this.workspaceId = options.workspaceId;
         this.appendHistorySample = options.appendHistorySample ?? quotaHistory_1.appendQuotaHistorySample;
+        this.subscribeAccountsChanged = options.subscribeAccountsChanged ?? accountChanges_1.onAccountsChanged;
     }
     start() {
         if (this.running)
             return;
         this.running = true;
-        this.refreshActiveSession();
-        this.discoveryTimer = setInterval(() => {
-            this.refreshActiveSession();
-        }, this.discoveryPollIntervalMs);
+        this.accountSubscription ??= this.subscribeAccountsChanged(() => this.handleAccountsChanged());
+        this.handleAccountsChanged();
     }
     stop() {
         if (!this.running)
@@ -137,6 +139,8 @@ class CodexQuotaWatcher {
             clearInterval(this.discoveryTimer);
             this.discoveryTimer = undefined;
         }
+        this.accountSubscription?.dispose();
+        this.accountSubscription = null;
         this.teardownActiveSession();
     }
     dispose() {
@@ -157,21 +161,46 @@ class CodexQuotaWatcher {
         return this.onUpdate(cb);
     }
     refresh() {
-        this.refreshActiveSession();
+        this.handleAccountsChanged();
     }
-    refreshActiveSession() {
+    handleAccountsChanged() {
+        if (!this.running)
+            return;
+        const account = this.safeGetActiveAccount();
+        if (!account) {
+            if (this.discoveryTimer) {
+                clearInterval(this.discoveryTimer);
+                this.discoveryTimer = undefined;
+            }
+            this.teardownActiveSession();
+            this.emitState(makeUnavailableState(null, 'No Codex account configured'));
+            return;
+        }
+        if (!this.discoveryTimer) {
+            this.discoveryTimer = setInterval(() => {
+                this.refreshActiveSession();
+            }, this.discoveryPollIntervalMs);
+            this.discoveryTimer.unref?.();
+        }
+        this.refreshActiveSession(account);
+    }
+    refreshActiveSession(account = this.safeGetActiveAccount()) {
+        if (!account) {
+            this.handleAccountsChanged();
+            return;
+        }
         const provider = this.getProvider();
         const nextSessionPath = provider.findActiveSession(this.workspacePath);
         if (!nextSessionPath) {
             this.teardownActiveSession();
-            this.emitCachedOrUnavailable();
+            this.emitCachedOrUnavailable(account);
             return;
         }
         if (nextSessionPath !== this.sessionPath || this.reader == null) {
             this.attachToSession(nextSessionPath);
             return;
         }
-        this.ingestSessionUpdate('readNew');
+        this.ingestSessionUpdate('readNew', account);
     }
     attachToSession(nextSessionPath) {
         this.teardownActiveSession();
@@ -189,14 +218,30 @@ class CodexQuotaWatcher {
                 }
                 this.refreshActiveSession();
             });
+            if (typeof this.fileWatcher.on === 'function') {
+                this.fileWatcher.on('error', () => {
+                    try {
+                        this.fileWatcher?.close();
+                    }
+                    catch {
+                        // Discovery polling remains active.
+                    }
+                    this.fileWatcher = null;
+                });
+            }
         }
         catch {
             this.emitCachedOrUnavailable();
         }
     }
-    ingestSessionUpdate(mode) {
+    ingestSessionUpdate(mode, knownAccount) {
+        const account = knownAccount ?? this.safeGetActiveAccount();
+        if (!account) {
+            this.handleAccountsChanged();
+            return;
+        }
         if (!this.provider || !this.reader) {
-            this.emitCachedOrUnavailable();
+            this.emitCachedOrUnavailable(account);
             return;
         }
         if (!this.reader.exists()) {
@@ -211,48 +256,45 @@ class CodexQuotaWatcher {
         }
         const liveQuota = (0, codexQuota_1.quotaFromCodexRateLimits)(this.provider.getLastRateLimits(), 'session');
         if (!liveQuota) {
-            this.emitCachedOrUnavailable();
+            this.emitCachedOrUnavailable(account);
             return;
         }
-        const account = this.getActiveAccount();
-        const cached = account ? this.readSnapshot('codex', account.id) : null;
+        const cached = this.readSnapshot('codex', account.id);
         const liveQuotaWithResetCredits = {
             ...liveQuota,
             resetCredits: liveQuota.resetCredits ?? cached?.resetCredits,
         };
-        if (account) {
-            this.writeSnapshot('codex', account.id, liveQuotaWithResetCredits);
-            if (this.workspaceId) {
-                const sample = {
-                    timestamp: liveQuotaWithResetCredits.capturedAt ?? new Date().toISOString(),
-                    runtimeProvider: 'codex',
-                    providerId: account.id,
-                    workspaceId: this.workspaceId,
-                    fiveHour: {
-                        utilization: liveQuotaWithResetCredits.fiveHour.utilization,
-                        resetsAt: liveQuotaWithResetCredits.fiveHour.resetsAt,
-                    },
-                    sevenDay: {
-                        utilization: liveQuotaWithResetCredits.sevenDay.utilization,
-                        resetsAt: liveQuotaWithResetCredits.sevenDay.resetsAt,
-                    },
-                    available: liveQuotaWithResetCredits.available,
-                    error: liveQuotaWithResetCredits.error,
-                    source: liveQuotaWithResetCredits.source,
-                    stale: liveQuotaWithResetCredits.stale,
-                };
-                try {
-                    const result = this.appendHistorySample(sample);
-                    if (result && typeof result.catch === 'function') {
-                        result.catch(() => {
-                            // History append must never break the live emission path.
-                        });
-                    }
-                }
-                catch {
-                    // Synchronous errors swallowed for the same reason.
+        this.writeSnapshot('codex', account.id, liveQuotaWithResetCredits);
+        if (this.workspaceId) {
+            const sample = {
+                timestamp: liveQuotaWithResetCredits.capturedAt ?? new Date().toISOString(),
+                runtimeProvider: 'codex',
+                providerId: account.id,
+                workspaceId: this.workspaceId,
+                fiveHour: {
+                    utilization: liveQuotaWithResetCredits.fiveHour.utilization,
+                    resetsAt: liveQuotaWithResetCredits.fiveHour.resetsAt,
+                },
+                sevenDay: {
+                    utilization: liveQuotaWithResetCredits.sevenDay.utilization,
+                    resetsAt: liveQuotaWithResetCredits.sevenDay.resetsAt,
+                },
+                available: liveQuotaWithResetCredits.available,
+                error: liveQuotaWithResetCredits.error,
+                source: liveQuotaWithResetCredits.source,
+                stale: liveQuotaWithResetCredits.stale,
+            };
+            try {
+                const result = this.appendHistorySample(sample);
+                if (result && typeof result.catch === 'function') {
+                    result.catch(() => {
+                        // History append must never break the live emission path.
+                    });
                 }
             }
+            catch {
+                // Synchronous errors swallowed for the same reason.
+            }
         }
         this.emitState(enrichQuotaState({
             ...liveQuotaWithResetCredits,
@@ -260,8 +302,12 @@ class CodexQuotaWatcher {
             providerId: 'codex',
         }, account));
     }
-    emitCachedOrUnavailable() {
-        const account = this.getActiveAccount();
+    emitCachedOrUnavailable(knownAccount) {
+        const account = knownAccount ?? this.safeGetActiveAccount();
+        if (!account) {
+            this.emitState(makeUnavailableState(null, 'No Codex account configured'));
+            return;
+        }
         const scanNow = this.now();
         if (scanNow - this.lastLocalScanAt < this.localScanCacheMs) {
             if (this.lastLocalScanState) {
@@ -296,7 +342,7 @@ class CodexQuotaWatcher {
                 localProvider?.dispose();
             }
         }
-        const cached = account ? this.readSnapshot('codex', account.id) : null;
+        const cached = this.readSnapshot('codex', account.id);
         if (cached) {
             this.emitState(enrichQuotaState({
                 ...cached,
@@ -331,6 +377,14 @@ class CodexQuotaWatcher {
         }
         return this.provider;
     }
+    safeGetActiveAccount() {
+        try {
+            return this.getActiveAccount();
+        }
+        catch {
+            return null;
+        }
+    }
     teardownActiveSession() {
         if (this.fileWatcher) {
             this.fileWatcher.close();

package/dist/failingTools.d.ts

@@ -0,0 +1,37 @@
+/**
+ * Failing-tool trend rows shared by the CLI `stats` block and the VS Code
+ * Health tab. Browser-safe: no filesystem access; callers pass the two
+ * windows they read with `getTopFailingTools()`.
+ *
+ * @module failingTools
+ */
+/** The shape `getTopFailingTools()` returns; declared structurally to stay fs-free. */
+export interface FailingToolWindow {
+    tool: string;
+    failures: number;
+    categories?: Record<string, number>;
+}
+export type FailingToolTrend = 'up' | 'down' | 'flat';
+export interface FailingToolTrendRow {
+    tool: string;
+    /** Failures in the last 7 days. */
+    last7: number;
+    /** Failures in the last 30 days. */
+    last30: number;
+    /** Category counts over the 30-day window (or the 7-day one when only that is known). */
+    categories: Record<string, number>;
+    /** Whether the last week is worse, better, or in line with the 30-day weekly average. */
+    trend: FailingToolTrend;
+}
+/**
+ * Compare the last week against the 30-day weekly average: more than 10%
+ * above is `up`, more than 10% below is `down`, otherwise `flat`. A tool
+ * with no 30-day history but failures this week is `up`.
+ */
+export declare function failingToolTrend(last7: number, last30: number): FailingToolTrend;
+export declare const FAILING_TOOL_TREND_ARROWS: Record<FailingToolTrend, string>;
+/**
+ * Merge the 7-day and 30-day windows into one row per tool, ordered by
+ * 7-day failures, then 30-day failures, then name.
+ */
+export declare function mergeFailingToolWindows(last7: FailingToolWindow[], last30: FailingToolWindow[]): FailingToolTrendRow[];

package/dist/failingTools.js

@@ -0,0 +1,70 @@
+"use strict";
+/**
+ * Failing-tool trend rows shared by the CLI `stats` block and the VS Code
+ * Health tab. Browser-safe: no filesystem access; callers pass the two
+ * windows they read with `getTopFailingTools()`.
+ *
+ * @module failingTools
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.FAILING_TOOL_TREND_ARROWS = void 0;
+exports.failingToolTrend = failingToolTrend;
+exports.mergeFailingToolWindows = mergeFailingToolWindows;
+const TREND_TOLERANCE = 0.1;
+/**
+ * Compare the last week against the 30-day weekly average: more than 10%
+ * above is `up`, more than 10% below is `down`, otherwise `flat`. A tool
+ * with no 30-day history but failures this week is `up`.
+ */
+function failingToolTrend(last7, last30) {
+    const weeklyAverage = last30 / (30 / 7);
+    if (weeklyAverage <= 0)
+        return last7 > 0 ? 'up' : 'flat';
+    const ratio = last7 / weeklyAverage;
+    if (ratio > 1 + TREND_TOLERANCE)
+        return 'up';
+    if (ratio < 1 - TREND_TOLERANCE)
+        return 'down';
+    return 'flat';
+}
+exports.FAILING_TOOL_TREND_ARROWS = {
+    up: '↑',
+    down: '↓',
+    flat: '→',
+};
+/**
+ * Merge the 7-day and 30-day windows into one row per tool, ordered by
+ * 7-day failures, then 30-day failures, then name.
+ */
+function mergeFailingToolWindows(last7, last30) {
+    const rows = new Map();
+    for (const tool of last30) {
+        rows.set(tool.tool, {
+            tool: tool.tool,
+            last7: 0,
+            last30: tool.failures,
+            categories: { ...(tool.categories ?? {}) },
+            trend: 'flat',
+        });
+    }
+    for (const tool of last7) {
+        const row = rows.get(tool.tool);
+        if (row) {
+            row.last7 = tool.failures;
+            // A 7-day count cannot exceed the 30-day one; tolerate windows read at different instants.
+            row.last30 = Math.max(row.last30, tool.failures);
+        }
+        else {
+            rows.set(tool.tool, {
+                tool: tool.tool,
+                last7: tool.failures,
+                last30: tool.failures,
+                categories: { ...(tool.categories ?? {}) },
+                trend: 'flat',
+            });
+        }
+    }
+    for (const row of rows.values())
+        row.trend = failingToolTrend(row.last7, row.last30);
+    return [...rows.values()].sort((a, b) => b.last7 - a.last7 || b.last30 - a.last30 || a.tool.localeCompare(b.tool));
+}

package/dist/formatters/sessionDump.js

@@ -15,7 +15,9 @@ exports.fmtTokens = fmtTokens;
 exports.fmtCost = fmtCost;
 exports.formatTimestamp = formatTimestamp;
 exports.formatDuration = formatDuration;
+const costProvenance_1 = require("../aggregation/costProvenance");
 const formatting_1 = require("../formatting");
+const tokenSummary_1 = require("../tokenSummary");
 // ── JSON output ──
 /**
  * Serialize aggregated metrics as pretty-printed JSON.
@@ -128,9 +130,12 @@ function formatSessionMarkdown(metrics, options = {}) {
     lines.push(`| Output | ${fmtTokens(metrics.tokens.outputTokens)} |`);
     lines.push(`| Cache write | ${fmtTokens(metrics.tokens.cacheWriteTokens)} |`);
     lines.push(`| Cache read | ${fmtTokens(metrics.tokens.cacheReadTokens)} |`);
-    lines.push(`| Total | ${fmtTokens(metrics.tokens.inputTokens + metrics.tokens.outputTokens)} |`);
-    if (metrics.tokens.reportedCost > 0) {
-        lines.push(`| Cost | ${fmtCost(metrics.tokens.reportedCost)} |`);
+    lines.push(`| ${tokenSummary_1.TOKEN_TOTAL_LABEL} | ${fmtTokens((0, tokenSummary_1.summarizeTokens)(metrics.tokens).total)} |`);
+    if (metrics.tokens.costUsd > 0) {
+        lines.push(`| Cost | ${fmtCost(metrics.tokens.costUsd)} (${(0, costProvenance_1.describeCostProvenance)(metrics.tokens)}) |`);
+    }
+    else if (metrics.tokens.unpricedCalls > 0) {
+        lines.push(`| Cost | — (${(0, costProvenance_1.describeCostProvenance)(metrics.tokens)}) |`);
     }
     lines.push('');
     // Model stats
@@ -222,9 +227,9 @@ function formatHeader(metrics) {
 }
 function formatTokenSummary(metrics) {
     const t = metrics.tokens;
-    const total = t.inputTokens + t.outputTokens;
+    const total = (0, tokenSummary_1.summarizeTokens)(t).total;
     const parts = [
-        `Tokens: ${fmtTokens(total)} total`,
+        `Tokens: ${fmtTokens(total)} total incl. cache`,
         `(${fmtTokens(t.inputTokens)} in`,
         `${fmtTokens(t.outputTokens)} out`,
     ];
@@ -233,8 +238,9 @@ function formatTokenSummary(metrics) {
     if (t.cacheWriteTokens > 0)
         parts.push(`${fmtTokens(t.cacheWriteTokens)} cache-write`);
     const line = parts.join(', ');
-    if (t.reportedCost > 0)
-        return `${line})  Cost: ${fmtCost(t.reportedCost)}`;
+    if (t.costUsd > 0) {
+        return `${line})  Cost: ${fmtCost(t.costUsd)} (${(0, costProvenance_1.describeCostProvenance)(t)})`;
+    }
     return line + ')';
 }
 /** @internal Exported for tests. */

package/dist/formatting.d.ts

@@ -24,3 +24,16 @@ export interface FormatDurationMsOptions {
 export declare function formatTokenCount(value: number, options?: FormatTokenCountOptions): string;
 /** Format an elapsed duration in milliseconds. */
 export declare function formatDurationMs(ms: number, options?: FormatDurationMsOptions): string;
+/**
+ * Calendar-date key (`YYYY-MM-DD`) in the machine's local time zone.
+ *
+ * Sidekick buckets "today", daily history, and heatmaps by the user's local
+ * day, so every writer and reader of a date key goes through this helper.
+ * A UTC key would move late-evening work onto the next day for anyone west
+ * of Greenwich and onto the previous day for anyone east of it.
+ */
+export declare function formatLocalDateKey(value?: Date | number): string;
+/** Parse a `YYYY-MM-DD` key produced by `formatLocalDateKey` back into local midnight. */
+export declare function parseLocalDateKey(key: string): Date | null;
+/** Shift a `YYYY-MM-DD` key by whole local days (DST-safe). */
+export declare function addLocalDays(key: string, days: number): string;

package/dist/formatting.js

@@ -10,6 +10,9 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.formatTokenCount = formatTokenCount;
 exports.formatDurationMs = formatDurationMs;
+exports.formatLocalDateKey = formatLocalDateKey;
+exports.parseLocalDateKey = parseLocalDateKey;
+exports.addLocalDays = addLocalDays;
 /** Format a token count with compact `k` / `M` suffixes. */
 function formatTokenCount(value, options = {}) {
     if (!Number.isFinite(value))
@@ -52,3 +55,35 @@ function formatDurationMs(ms, options = {}) {
     }
     return `${minutes}m${separator}${remainingSeconds}s`;
 }
+/**
+ * Calendar-date key (`YYYY-MM-DD`) in the machine's local time zone.
+ *
+ * Sidekick buckets "today", daily history, and heatmaps by the user's local
+ * day, so every writer and reader of a date key goes through this helper.
+ * A UTC key would move late-evening work onto the next day for anyone west
+ * of Greenwich and onto the previous day for anyone east of it.
+ */
+function formatLocalDateKey(value = new Date()) {
+    const date = typeof value === 'number' ? new Date(value) : value;
+    if (Number.isNaN(date.getTime()))
+        return '';
+    const year = date.getFullYear();
+    const month = String(date.getMonth() + 1).padStart(2, '0');
+    const day = String(date.getDate()).padStart(2, '0');
+    return `${year}-${month}-${day}`;
+}
+/** Parse a `YYYY-MM-DD` key produced by `formatLocalDateKey` back into local midnight. */
+function parseLocalDateKey(key) {
+    const match = /^(\d{4})-(\d{2})-(\d{2})$/.exec(key);
+    if (!match)
+        return null;
+    const date = new Date(Number(match[1]), Number(match[2]) - 1, Number(match[3]));
+    return Number.isNaN(date.getTime()) ? null : date;
+}
+/** Shift a `YYYY-MM-DD` key by whole local days (DST-safe). */
+function addLocalDays(key, days) {
+    const date = parseLocalDateKey(key);
+    if (!date)
+        return key;
+    return formatLocalDateKey(new Date(date.getFullYear(), date.getMonth(), date.getDate() + days));
+}