sidekick-shared 0.27.6 → 0.28.0

package/dist/esm/quota.js

@@ -0,0 +1,182 @@
+export { QUOTA_PROVIDER_IDS } from './providerIds';
+const USAGE_URL = 'https://api.anthropic.com/api/oauth/usage';
+const BETA_HEADER = 'oauth-2025-04-20';
+const FETCH_TIMEOUT_MS = 10_000;
+export const FIVE_HOUR_WINDOW_MS = 5 * 3_600_000;
+export const SEVEN_DAY_WINDOW_MS = 7 * 86_400_000;
+/** A snapshot younger than this is as good as live. */
+export const QUOTA_FRESH_MAX_AGE_MS = 5 * 60_000;
+/** A snapshot older than this should be labelled as stale wherever it is shown. */
+export const QUOTA_AGING_MAX_AGE_MS = 60 * 60_000;
+/** Classify a cached sample's age. Non-finite or negative ages count as stale. */
+export function classifyQuotaFreshness(ageMs) {
+    if (typeof ageMs !== 'number' || !Number.isFinite(ageMs) || ageMs < 0)
+        return 'stale';
+    if (ageMs < QUOTA_FRESH_MAX_AGE_MS)
+        return 'fresh';
+    if (ageMs < QUOTA_AGING_MAX_AGE_MS)
+        return 'aging';
+    return 'stale';
+}
+/** Compact age label for status lines and table footers: `just now`, `3m ago`, `2h ago`, `3d ago`. */
+export function formatQuotaAge(ageMs) {
+    if (typeof ageMs !== 'number' || !Number.isFinite(ageMs) || ageMs < 0)
+        return 'age unknown';
+    const minutes = Math.floor(ageMs / 60_000);
+    if (minutes < 1)
+        return 'just now';
+    if (minutes < 60)
+        return `${minutes}m ago`;
+    const hours = Math.floor(minutes / 60);
+    if (hours < 48)
+        return `${hours}h ago`;
+    return `${Math.floor(hours / 24)}d ago`;
+}
+/**
+ * Projects utilization at end of window based on elapsed time.
+ *
+ * Formula: `current * (windowDuration / elapsed)`, capped at 200%.
+ */
+export function projectQuotaWindow(input) {
+    const { utilization, resetsAt, windowMs, capturedAt } = input;
+    if (!resetsAt || utilization <= 0 || !Number.isFinite(utilization) || windowMs <= 0)
+        return undefined;
+    const resetTime = new Date(resetsAt).getTime();
+    if (!Number.isFinite(resetTime))
+        return undefined;
+    const capturedTime = capturedAt ? Date.parse(capturedAt) : NaN;
+    const now = Number.isFinite(capturedTime) ? capturedTime : Date.now();
+    const elapsed = windowMs - (resetTime - now);
+    if (elapsed <= 0)
+        return undefined;
+    return Math.min(Math.round(utilization * (windowMs / elapsed)), 200);
+}
+export function withQuotaProjections(state, options = {}) {
+    if (!state.available)
+        return state;
+    const next = { ...state };
+    const capturedAt = options.capturedAt ?? state.capturedAt;
+    if (next.projectedFiveHour == null) {
+        const projected = projectQuotaWindow({
+            utilization: next.fiveHour.utilization,
+            resetsAt: next.fiveHour.resetsAt,
+            windowMs: options.fiveHourWindowMs ?? FIVE_HOUR_WINDOW_MS,
+            capturedAt,
+        });
+        if (projected !== undefined)
+            next.projectedFiveHour = projected;
+    }
+    if (next.projectedSevenDay == null) {
+        const projected = projectQuotaWindow({
+            utilization: next.sevenDay.utilization,
+            resetsAt: next.sevenDay.resetsAt,
+            windowMs: options.sevenDayWindowMs ?? SEVEN_DAY_WINDOW_MS,
+            capturedAt,
+        });
+        if (projected !== undefined)
+            next.projectedSevenDay = projected;
+    }
+    return next;
+}
+/**
+ * Helper to build an unavailable QuotaState.
+ */
+function unavailableState(error, meta = {}) {
+    return {
+        fiveHour: { utilization: 0, resetsAt: '' },
+        sevenDay: { utilization: 0, resetsAt: '' },
+        available: false,
+        error,
+        ...meta,
+    };
+}
+function parseRetryAfterMs(retryAfter) {
+    if (!retryAfter)
+        return undefined;
+    const seconds = Number(retryAfter);
+    if (Number.isFinite(seconds) && seconds >= 0) {
+        return Math.round(seconds * 1000);
+    }
+    const retryAt = Date.parse(retryAfter);
+    if (Number.isNaN(retryAt))
+        return undefined;
+    return Math.max(retryAt - Date.now(), 0);
+}
+/**
+ * Fetch current quota utilization from the Anthropic OAuth usage API.
+ *
+ * This is a **single-shot** function — it does not poll. The caller wraps
+ * it in a polling loop, VS Code EventEmitter, or CLI interval as needed.
+ *
+ * @param accessToken - OAuth access token from `readClaudeMaxCredentials()`
+ * @param options.fetchImpl - Fetch implementation (defaults to the global `fetch`; tests inject a stub)
+ * @returns QuotaState with utilization data and elapsed-time projections
+ */
+export async function fetchQuota(accessToken, options = {}) {
+    const controller = new AbortController();
+    const timeout = setTimeout(() => controller.abort(), FETCH_TIMEOUT_MS);
+    timeout.unref();
+    try {
+        const fetchImpl = options.fetchImpl ?? fetch;
+        const res = await fetchImpl(USAGE_URL, {
+            method: 'GET',
+            signal: controller.signal,
+            headers: {
+                Authorization: `Bearer ${accessToken}`,
+                'anthropic-beta': BETA_HEADER,
+                'Content-Type': 'application/json',
+            },
+        });
+        if (!res.ok) {
+            if (res.status === 401) {
+                return unavailableState('Sign in to Claude Code to view quota', {
+                    failureKind: 'auth',
+                    httpStatus: res.status,
+                });
+            }
+            if (res.status === 429) {
+                return unavailableState(`API error: ${res.status}`, {
+                    failureKind: 'rate_limit',
+                    httpStatus: res.status,
+                    retryAfterMs: parseRetryAfterMs(res.headers.get('retry-after')),
+                });
+            }
+            if (res.status >= 500 && res.status <= 599) {
+                return unavailableState(`API error: ${res.status}`, {
+                    failureKind: 'server',
+                    httpStatus: res.status,
+                });
+            }
+            return unavailableState(`API error: ${res.status}`, {
+                failureKind: 'unknown',
+                httpStatus: res.status,
+            });
+        }
+        const data = await res.json();
+        const fiveUtil = data.five_hour?.utilization ?? 0;
+        const sevenUtil = data.seven_day?.utilization ?? 0;
+        const fiveResetsAt = data.five_hour?.resets_at ?? '';
+        const sevenResetsAt = data.seven_day?.resets_at ?? '';
+        return {
+            fiveHour: { utilization: fiveUtil, resetsAt: fiveResetsAt },
+            sevenDay: { utilization: sevenUtil, resetsAt: sevenResetsAt },
+            available: true,
+            projectedFiveHour: projectQuotaWindow({
+                utilization: fiveUtil,
+                resetsAt: fiveResetsAt,
+                windowMs: FIVE_HOUR_WINDOW_MS,
+            }),
+            projectedSevenDay: projectQuotaWindow({
+                utilization: sevenUtil,
+                resetsAt: sevenResetsAt,
+                windowMs: SEVEN_DAY_WINDOW_MS,
+            }),
+        };
+    }
+    catch {
+        return unavailableState('Network error', { failureKind: 'network' });
+    }
+    finally {
+        clearTimeout(timeout);
+    }
+}

package/dist/esm/quotaHistory.js

@@ -0,0 +1,364 @@
+/**
+ * Append-only JSONL history of quota samples, scoped per workspace and per runtime provider.
+ *
+ * Sibling to `quotaSnapshots.ts`. Where snapshots persist a single most-recent sample per
+ * (provider, account), this module accumulates time-series samples so consumers (the VS Code
+ * dashboard, the `sidekick quota history` CLI, external consumers) can render heatmaps and
+ * trend visualisations over a 13-week window.
+ */
+import * as crypto from 'crypto';
+import * as fs from 'fs';
+import * as path from 'path';
+import { addLocalDays, formatLocalDateKey } from './formatting';
+import { getConfigDir } from './paths';
+import { writeQuotaSnapshot } from './quotaSnapshots';
+import { atomicWriteFileSync, withFileLockSync } from './writers/atomic';
+const DEFAULT_MIN_INTERVAL_MS = 60_000;
+const DEFAULT_RETENTION_DAYS = 91;
+const PRUNE_FILESIZE_THRESHOLD = 16 * 1024;
+const MS_PER_DAY = 86_400_000;
+/** Per-file append serialization across in-process callers. */
+const appendChains = new Map();
+/** Per-file last-write timestamp cache, used for the debounce check. */
+const lastWriteCache = new Map();
+/**
+ * Stable, opaque workspace identifier — first 16 hex chars of sha256(realpath).
+ * Shared between the VS Code extension (workspace folder fsPath) and the CLI (process.cwd()).
+ */
+export function getWorkspaceIdFromPath(workspacePath) {
+    let resolved;
+    try {
+        resolved = fs.realpathSync(workspacePath);
+    }
+    catch {
+        resolved = path.resolve(workspacePath);
+    }
+    return crypto.createHash('sha256').update(resolved).digest('hex').slice(0, 16);
+}
+function getHistoryFilePath(workspaceId, provider) {
+    return path.join(getConfigDir(), 'quota-history', workspaceId, `${provider}.jsonl`);
+}
+function ensureHistoryDir(workspaceId) {
+    fs.mkdirSync(path.join(getConfigDir(), 'quota-history', workspaceId), {
+        recursive: true,
+        mode: 0o700,
+    });
+}
+function parseSampleLine(line) {
+    const trimmed = line.trim();
+    if (!trimmed)
+        return null;
+    try {
+        const parsed = JSON.parse(trimmed);
+        if (parsed &&
+            typeof parsed === 'object' &&
+            typeof parsed.timestamp === 'string' &&
+            parsed.fiveHour &&
+            parsed.sevenDay) {
+            return parsed;
+        }
+        return null;
+    }
+    catch {
+        return null;
+    }
+}
+function readLastSampleTimestampMs(filePath) {
+    let fd;
+    try {
+        fd = fs.openSync(filePath, 'r');
+        const stat = fs.fstatSync(fd);
+        if (stat.size === 0)
+            return null;
+        const chunkSize = 4096;
+        let remaining = stat.size;
+        let buffer = Buffer.alloc(0);
+        while (remaining > 0) {
+            const readSize = Math.min(chunkSize, remaining);
+            const chunk = Buffer.alloc(readSize);
+            fs.readSync(fd, chunk, 0, readSize, remaining - readSize);
+            buffer = Buffer.concat([chunk, buffer]);
+            remaining -= readSize;
+            const text = buffer.toString('utf8');
+            // Look for the last newline that's not at end-of-text — that's the boundary of the final record.
+            const trimmedRight = text.replace(/\n+$/, '');
+            const lastNewline = trimmedRight.lastIndexOf('\n');
+            if (lastNewline >= 0) {
+                const lastLine = trimmedRight.slice(lastNewline + 1);
+                const sample = parseSampleLine(lastLine);
+                return sample ? Date.parse(sample.timestamp) || null : null;
+            }
+            if (remaining === 0) {
+                const sample = parseSampleLine(trimmedRight);
+                return sample ? Date.parse(sample.timestamp) || null : null;
+            }
+        }
+        return null;
+    }
+    catch (err) {
+        if (err?.code === 'ENOENT')
+            return null;
+        return null;
+    }
+    finally {
+        if (fd !== undefined) {
+            try {
+                fs.closeSync(fd);
+            }
+            catch {
+                // best effort
+            }
+        }
+    }
+}
+/**
+ * Append-and-prune under the shared cross-process lock. Without it a prune
+ * rewrite (rename over the file) could race another process's append, and
+ * the appended line would land on the old, unlinked inode.
+ */
+function withHistoryFileLock(filePath, operation) {
+    return withFileLockSync(`${filePath}.lock`, operation);
+}
+function atomicRewriteFile(filePath, contents) {
+    atomicWriteFileSync(filePath, contents, 0o600);
+}
+function pruneFileSync(filePath, retentionDays) {
+    let stat;
+    try {
+        stat = fs.statSync(filePath);
+    }
+    catch {
+        return { kept: 0, pruned: 0 };
+    }
+    if (stat.size === 0)
+        return { kept: 0, pruned: 0 };
+    const cutoffMs = Date.now() - retentionDays * MS_PER_DAY;
+    const raw = fs.readFileSync(filePath, 'utf8');
+    const lines = raw.split('\n');
+    const keptLines = [];
+    let pruned = 0;
+    for (const line of lines) {
+        if (!line.trim())
+            continue;
+        const sample = parseSampleLine(line);
+        if (!sample) {
+            // Drop malformed lines during prune so the file self-heals.
+            pruned += 1;
+            continue;
+        }
+        const ts = Date.parse(sample.timestamp);
+        if (Number.isFinite(ts) && ts >= cutoffMs) {
+            keptLines.push(line);
+        }
+        else {
+            pruned += 1;
+        }
+    }
+    if (pruned > 0) {
+        atomicRewriteFile(filePath, keptLines.length > 0 ? keptLines.join('\n') + '\n' : '');
+    }
+    return { kept: keptLines.length, pruned };
+}
+function sampleToQuotaState(sample) {
+    const providerId = runtimeProviderToSnapshotProvider(sample.runtimeProvider);
+    return {
+        fiveHour: { utilization: sample.fiveHour.utilization, resetsAt: sample.fiveHour.resetsAt },
+        sevenDay: { utilization: sample.sevenDay.utilization, resetsAt: sample.sevenDay.resetsAt },
+        available: sample.available,
+        error: sample.error,
+        providerId,
+        source: sample.source ?? 'session',
+        capturedAt: sample.timestamp,
+        stale: sample.stale,
+    };
+}
+/**
+ * Maps a runtime provider to the snapshot storage key.
+ * `'zai'` is allowed at the storage layer even though it is not part of
+ * `AccountProviderId` (z.ai has no full account management in v1).
+ */
+function runtimeProviderToSnapshotProvider(runtime) {
+    if (runtime === 'claude')
+        return 'claude-code';
+    if (runtime === 'zai')
+        return 'zai';
+    return 'codex';
+}
+async function runAppend(sample, filePath, options) {
+    let lastTs = lastWriteCache.get(filePath);
+    if (lastTs === undefined) {
+        const fromDisk = readLastSampleTimestampMs(filePath);
+        if (fromDisk !== null) {
+            lastTs = fromDisk;
+            lastWriteCache.set(filePath, fromDisk);
+        }
+    }
+    const sampleTs = Date.parse(sample.timestamp);
+    if (lastTs !== undefined &&
+        Number.isFinite(sampleTs) &&
+        sampleTs - lastTs < options.minIntervalMs) {
+        return;
+    }
+    ensureHistoryDir(sample.workspaceId);
+    const line = JSON.stringify(sample) + '\n';
+    withHistoryFileLock(filePath, () => {
+        fs.appendFileSync(filePath, line, { encoding: 'utf8', mode: 0o600 });
+        // Opportunistic prune. Skip when the file is small to avoid pointless rewrite churn.
+        try {
+            if (fs.statSync(filePath).size >= PRUNE_FILESIZE_THRESHOLD) {
+                pruneFileSync(filePath, options.retentionDays);
+            }
+        }
+        catch {
+            // ignore
+        }
+    });
+    lastWriteCache.set(filePath, Number.isFinite(sampleTs) ? sampleTs : Date.now());
+    // Backwards-compat: keep the latest-snapshot store hot so existing callers (DashboardViewProvider,
+    // codex session provider, external consumers) don't have to query history for "latest".
+    try {
+        const providerId = runtimeProviderToSnapshotProvider(sample.runtimeProvider);
+        writeQuotaSnapshot(providerId, sample.providerId, sampleToQuotaState(sample));
+    }
+    catch {
+        // Snapshot write failures must not poison the history append path.
+    }
+}
+export async function appendQuotaHistorySample(sample, options = {}) {
+    const resolved = {
+        minIntervalMs: options.minIntervalMs ?? DEFAULT_MIN_INTERVAL_MS,
+        retentionDays: options.retentionDays ?? DEFAULT_RETENTION_DAYS,
+    };
+    const filePath = getHistoryFilePath(sample.workspaceId, sample.runtimeProvider);
+    const previous = appendChains.get(filePath) ?? Promise.resolve();
+    const next = previous
+        .then(() => runAppend(sample, filePath, resolved))
+        .catch(() => {
+        // Swallow chain-level errors so a single failure doesn't break subsequent appends.
+    });
+    appendChains.set(filePath, next);
+    try {
+        await next;
+    }
+    finally {
+        if (appendChains.get(filePath) === next) {
+            appendChains.delete(filePath);
+        }
+    }
+}
+function defaultRangeMs() {
+    const toMs = Date.now();
+    const fromMs = toMs - DEFAULT_RETENTION_DAYS * MS_PER_DAY;
+    return { fromMs, toMs };
+}
+export async function readQuotaHistoryRange(options) {
+    const filePath = getHistoryFilePath(options.workspaceId, options.provider);
+    let raw;
+    try {
+        raw = await fs.promises.readFile(filePath, 'utf8');
+    }
+    catch (err) {
+        if (err?.code === 'ENOENT')
+            return [];
+        throw err;
+    }
+    const { fromMs: defaultFromMs, toMs: defaultToMs } = defaultRangeMs();
+    const fromMs = options.from ? Date.parse(options.from) : defaultFromMs;
+    const toMs = options.to ? Date.parse(options.to) : defaultToMs;
+    const samples = [];
+    for (const line of raw.split('\n')) {
+        const sample = parseSampleLine(line);
+        if (!sample)
+            continue;
+        const ts = Date.parse(sample.timestamp);
+        if (!Number.isFinite(ts))
+            continue;
+        if (ts < fromMs || ts > toMs)
+            continue;
+        samples.push(sample);
+    }
+    samples.sort((a, b) => Date.parse(a.timestamp) - Date.parse(b.timestamp));
+    return samples;
+}
+/**
+ * Daily buckets are keyed by the machine's local calendar day, matching the
+ * `today` brief, the historical-data store, and the dashboard date filters.
+ */
+function localDateString(ms) {
+    return formatLocalDateKey(ms);
+}
+export async function readQuotaHistoryDailyBuckets(options) {
+    const samples = await readQuotaHistoryRange(options);
+    const { fromMs: defaultFromMs, toMs: defaultToMs } = defaultRangeMs();
+    const fromMs = options.from ? Date.parse(options.from) : defaultFromMs;
+    const toMs = options.to ? Date.parse(options.to) : defaultToMs;
+    const startDate = localDateString(fromMs);
+    const endDate = localDateString(toMs);
+    const grouped = new Map();
+    for (const sample of samples) {
+        const sampleMs = Date.parse(sample.timestamp);
+        if (!Number.isFinite(sampleMs))
+            continue;
+        const day = localDateString(sampleMs);
+        const bucket = grouped.get(day);
+        if (bucket) {
+            bucket.push(sample);
+        }
+        else {
+            grouped.set(day, [sample]);
+        }
+    }
+    const buckets = [];
+    let cursor = startDate;
+    // Safety bound — 26 weeks worst case = 182 days; we cap iteration well above that.
+    for (let i = 0; i <= 366 && cursor <= endDate; i += 1) {
+        const daySamples = grouped.get(cursor);
+        if (!daySamples || daySamples.length === 0) {
+            buckets.push({
+                date: cursor,
+                samples: 0,
+                maxUtilizationFiveHour: 0,
+                maxUtilizationSevenDay: 0,
+                avgUtilizationFiveHour: 0,
+                avgUtilizationSevenDay: 0,
+                anyUnavailable: false,
+            });
+        }
+        else {
+            let maxFive = 0;
+            let maxSeven = 0;
+            let sumFive = 0;
+            let sumSeven = 0;
+            let anyUnavailable = false;
+            for (const s of daySamples) {
+                maxFive = Math.max(maxFive, s.fiveHour.utilization);
+                maxSeven = Math.max(maxSeven, s.sevenDay.utilization);
+                sumFive += s.fiveHour.utilization;
+                sumSeven += s.sevenDay.utilization;
+                if (!s.available)
+                    anyUnavailable = true;
+            }
+            const n = daySamples.length;
+            buckets.push({
+                date: cursor,
+                samples: n,
+                maxUtilizationFiveHour: maxFive,
+                maxUtilizationSevenDay: maxSeven,
+                avgUtilizationFiveHour: Math.round((sumFive / n) * 100) / 100,
+                avgUtilizationSevenDay: Math.round((sumSeven / n) * 100) / 100,
+                anyUnavailable,
+            });
+        }
+        cursor = addLocalDays(cursor, 1);
+    }
+    return buckets;
+}
+export async function pruneQuotaHistory(workspaceId, provider, retentionDays = DEFAULT_RETENTION_DAYS) {
+    const filePath = getHistoryFilePath(workspaceId, provider);
+    return pruneFileSync(filePath, retentionDays);
+}
+/** Test-only: wipe the in-memory mutex/debounce state. Not exported from index.ts. */
+export function _resetQuotaHistoryInMemoryStateForTests() {
+    appendChains.clear();
+    lastWriteCache.clear();
+}