sidekick-shared 0.25.0 → 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/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));
+}

package/dist/historicalStore.d.ts

@@ -0,0 +1,47 @@
+/**
+ * Pure mutations of the `historical-data.json` store.
+ *
+ * Ported verbatim from the VS Code extension's HistoricalDataService so the
+ * CLI importer and the extension apply session summaries the same way:
+ * a session's previous contribution is subtracted before the new one is
+ * added (idempotent replacement), daily, hourly, monthly, and all-time
+ * buckets are updated together, and the per-session record list is capped
+ * at `HISTORICAL_SESSION_RETENTION_LIMIT`. Browser-safe: no Node imports.
+ *
+ * @module historicalStore
+ */
+import type { SessionFileStats } from './providers/types';
+import type { HistoricalDataStore, SessionHistoryRecord, SessionSummary } from './types/historicalData';
+export interface ApplySessionSummaryOptions {
+    /** Clock for `updatedAt` stamps (default `new Date()`). */
+    now?: Date;
+    /** Cap on `store.sessions` (default `HISTORICAL_SESSION_RETENTION_LIMIT`). */
+    retentionLimit?: number;
+}
+/** Subtract a previously saved session's contribution from every bucket. */
+export declare function removeSessionSummary(store: HistoricalDataStore, record: SessionHistoryRecord, now?: Date): void;
+/**
+ * Apply a completed session to the daily, hourly, monthly, and all-time
+ * buckets and the capped per-session list. Re-applying the same session id
+ * replaces its earlier contribution instead of double counting it.
+ *
+ * Returns the stored per-session record.
+ */
+export declare function applySessionSummary(store: HistoricalDataStore, summary: SessionSummary, options?: ApplySessionSummaryOptions): SessionHistoryRecord;
+/** Whether a session file has already been folded into the store. */
+export declare function isFileImported(store: HistoricalDataStore, filePath: string): boolean;
+/** Record a session file as imported. Returns false when it was already listed. */
+export declare function markFileImported(store: HistoricalDataStore, filePath: string, now?: Date): boolean;
+export interface SessionSummaryFromStatsOptions {
+    /** Session provider id stored on the record (default `stats.providerId`). */
+    provider?: string;
+    /** Workspace path stored on the record (default `'unknown'`). */
+    project?: string | null;
+}
+/**
+ * Build the summary the history store expects from unified session stats,
+ * so the CLI importer and the extension's first-activation import store the
+ * same per-model cost, tool success/failure split, and unpriced markers.
+ * Pending tool calls count as successes (stats only split out failures).
+ */
+export declare function sessionSummaryFromStats(stats: SessionFileStats, options?: SessionSummaryFromStatsOptions): SessionSummary;