sidekick-shared 0.27.6 → 0.28.0

package/dist/esm/multiProviderQuotaService.js

@@ -0,0 +1,450 @@
+import { resolveActiveClaudeAccount } from './accounts';
+import { CodexQuotaWatcher } from './codexQuotaWatcher';
+import { readClaudeMaxCredentials } from './credentials';
+import { fetchPeakHoursStatus } from './peakHours';
+import { fetchQuota } from './quota';
+import { describeQuotaFailure } from './quotaPresentation';
+import { onAccountsChanged } from './accountChanges';
+const ACTIVE_POLL_INTERVAL_MS = 60_000;
+const IDLE_POLL_INTERVAL_MS = 300_000;
+const TRANSIENT_FAILURE_BACKOFF_MS = [30_000, 60_000, 120_000, 240_000, 300_000];
+const PEAK_HOURS_CACHE_MAX_AGE_MS = 10 * 60 * 1000;
+const SIGNED_OUT_ERROR = 'Sign in to a Claude account to view quota';
+function makeUnavailableClaudeState(error, failureKind) {
+    return {
+        runtimeProvider: 'claude',
+        fiveHour: { utilization: 0, resetsAt: '' },
+        sevenDay: { utilization: 0, resetsAt: '' },
+        available: false,
+        error,
+        failureKind,
+        providerId: 'claude-code',
+        source: 'api',
+    };
+}
+function formatDelay(ms) {
+    if (ms % 60_000 === 0)
+        return `${ms / 60_000}m`;
+    if (ms % 1_000 === 0)
+        return `${ms / 1_000}s`;
+    return `${ms}ms`;
+}
+function unavailablePeakHoursState() {
+    return {
+        status: 'unknown',
+        isPeak: false,
+        sessionLimitSpeed: 'unknown',
+        label: 'Peak hours unavailable',
+        peakHoursDescription: '',
+        nextChange: null,
+        minutesUntilChange: null,
+        note: '',
+        updatedAt: new Date().toISOString(),
+        unavailable: true,
+    };
+}
+export class MultiProviderQuotaService {
+    activeIntervalMs;
+    idleIntervalMs;
+    transientFailureBackoffMs;
+    peakHoursCacheMaxAgeMs;
+    includePeakHours;
+    readClaudeCredentials;
+    readClaudeAccount;
+    fetchClaudeQuota;
+    fetchPeakHours;
+    log;
+    subscribeAccountsChanged;
+    listeners = [];
+    codexWatcher;
+    ownsCodexWatcher;
+    codexSubscription = null;
+    zaiWatcher;
+    ownsZaiWatcher;
+    zaiSubscription = null;
+    timer;
+    polling = false;
+    quotaByProvider = {};
+    lastEmittedClaudeState = null;
+    lastSuccessfulClaudeState = null;
+    pollingMode = 'idle';
+    transientFailureStreak = 0;
+    cachedFallbackActive = false;
+    authUnavailableActive = false;
+    currentPeakHours;
+    lastFreshPeakHoursAt = 0;
+    peakHoursErrorLogged = false;
+    claudeDormant = false;
+    accountSubscription = null;
+    pollInFlight = false;
+    pendingWake = false;
+    constructor(options = {}) {
+        this.activeIntervalMs = options.activeIntervalMs ?? ACTIVE_POLL_INTERVAL_MS;
+        this.idleIntervalMs = options.idleIntervalMs ?? IDLE_POLL_INTERVAL_MS;
+        this.transientFailureBackoffMs =
+            options.transientFailureBackoffMs ?? TRANSIENT_FAILURE_BACKOFF_MS;
+        this.peakHoursCacheMaxAgeMs = options.peakHoursCacheMaxAgeMs ?? PEAK_HOURS_CACHE_MAX_AGE_MS;
+        this.includePeakHours = options.includePeakHours ?? true;
+        this.readClaudeCredentials = options.readClaudeCredentials ?? readClaudeMaxCredentials;
+        this.readClaudeAccount = options.readClaudeAccount ?? resolveActiveClaudeAccount;
+        this.fetchClaudeQuota = options.fetchClaudeQuota ?? fetchQuota;
+        this.fetchPeakHours = options.fetchPeakHours ?? fetchPeakHoursStatus;
+        this.subscribeAccountsChanged = options.subscribeAccountsChanged ?? onAccountsChanged;
+        this.log = options.log;
+        if (options.codexWatcher !== undefined) {
+            this.codexWatcher = options.codexWatcher;
+            this.ownsCodexWatcher = false;
+        }
+        else if (options.codexWorkspacePath) {
+            this.codexWatcher = new CodexQuotaWatcher(options.codexWorkspacePath);
+            this.ownsCodexWatcher = true;
+        }
+        else {
+            this.codexWatcher = null;
+            this.ownsCodexWatcher = false;
+        }
+        this.codexSubscription =
+            this.codexWatcher?.onUpdate((state) => {
+                this.updateProviderQuota('codex', state);
+            }) ?? null;
+        if (options.zaiWatcher !== undefined) {
+            this.zaiWatcher = options.zaiWatcher;
+            this.ownsZaiWatcher = false;
+        }
+        else {
+            this.zaiWatcher = null;
+            this.ownsZaiWatcher = false;
+        }
+        this.zaiSubscription =
+            this.zaiWatcher?.onUpdate((state) => {
+                this.updateProviderQuota('zai', state);
+            }) ?? null;
+    }
+    startPolling() {
+        if (this.polling)
+            return;
+        this.polling = true;
+        this.accountSubscription ??= this.subscribeAccountsChanged(() => this.wakeForAccountChange());
+        this.codexWatcher?.start();
+        this.zaiWatcher?.start();
+        this.wakeForAccountChange();
+        this.log?.('[Quota] Polling started');
+    }
+    stopPolling() {
+        if (!this.polling)
+            return;
+        this.polling = false;
+        this.claudeDormant = false;
+        if (this.timer) {
+            clearTimeout(this.timer);
+            this.timer = undefined;
+        }
+        this.codexWatcher?.stop();
+        this.zaiWatcher?.stop();
+        this.accountSubscription?.dispose();
+        this.accountSubscription = null;
+        this.log?.('[Quota] Polling stopped');
+    }
+    setPollingMode(mode) {
+        if (this.pollingMode === mode)
+            return;
+        this.pollingMode = mode;
+        if (!this.polling)
+            return;
+        if (this.transientFailureStreak > 0 && this.timer)
+            return;
+        if (this.timer) {
+            clearTimeout(this.timer);
+            this.timer = undefined;
+        }
+        this.scheduleNextPoll();
+    }
+    onUpdate(cb) {
+        this.listeners.push(cb);
+        return {
+            dispose: () => {
+                const index = this.listeners.indexOf(cb);
+                if (index >= 0)
+                    this.listeners.splice(index, 1);
+            },
+        };
+    }
+    onQuotaUpdate(cb) {
+        return this.onUpdate(cb);
+    }
+    getLatest() {
+        return { ...this.quotaByProvider };
+    }
+    updateProviderQuota(provider, state) {
+        if (provider === 'claude') {
+            const nextState = this.withClaudeAccountDetails({
+                ...state,
+                runtimeProvider: 'claude',
+                providerId: 'claude-code',
+            });
+            this.lastEmittedClaudeState = nextState;
+            if (nextState.available && nextState.stale !== true) {
+                this.lastSuccessfulClaudeState = nextState;
+            }
+            this.quotaByProvider = {
+                ...this.quotaByProvider,
+                claude: nextState,
+            };
+            this.emit();
+            return;
+        }
+        if (provider === 'zai') {
+            const nextState = {
+                ...state,
+                runtimeProvider: 'zai',
+                providerId: 'zai',
+            };
+            this.quotaByProvider = {
+                ...this.quotaByProvider,
+                zai: nextState,
+            };
+            this.emit();
+            return;
+        }
+        const nextState = {
+            ...state,
+            runtimeProvider: 'codex',
+            providerId: 'codex',
+        };
+        this.quotaByProvider = {
+            ...this.quotaByProvider,
+            codex: nextState,
+        };
+        this.emit();
+    }
+    dispose() {
+        this.stopPolling();
+        this.codexSubscription?.dispose();
+        this.codexSubscription = null;
+        if (this.ownsCodexWatcher) {
+            this.codexWatcher?.dispose();
+        }
+        this.zaiSubscription?.dispose();
+        this.zaiSubscription = null;
+        if (this.ownsZaiWatcher) {
+            this.zaiWatcher?.dispose();
+        }
+        this.listeners.splice(0, this.listeners.length);
+    }
+    async refreshPeakHours() {
+        if (!this.includePeakHours)
+            return;
+        let result;
+        try {
+            result = await this.fetchPeakHours();
+        }
+        catch (error) {
+            if (!this.peakHoursErrorLogged) {
+                this.log?.('[Quota] Peak-hours fetch threw unexpectedly', error);
+                this.peakHoursErrorLogged = true;
+            }
+            result = unavailablePeakHoursState();
+        }
+        if (!result.unavailable) {
+            this.currentPeakHours = result;
+            this.lastFreshPeakHoursAt = Date.now();
+            this.peakHoursErrorLogged = false;
+            return;
+        }
+        const cachedIsFresh = this.currentPeakHours !== undefined &&
+            !this.currentPeakHours.unavailable &&
+            Date.now() - this.lastFreshPeakHoursAt < this.peakHoursCacheMaxAgeMs;
+        if (cachedIsFresh)
+            return;
+        this.currentPeakHours = result;
+    }
+    async poll() {
+        if (!this.polling || this.pollInFlight) {
+            this.pendingWake = this.polling;
+            return;
+        }
+        this.pollInFlight = true;
+        this.pendingWake = false;
+        try {
+            let accountPresent = false;
+            try {
+                accountPresent = this.readClaudeAccount().source !== 'none';
+            }
+            catch {
+                accountPresent = false;
+            }
+            if (!accountPresent) {
+                this.claudeDormant = true;
+                this.resetTransientFailureState();
+                this.authUnavailableActive = false;
+                this.lastSuccessfulClaudeState = null;
+                // Stay visible while dormant: consumers render their sign-in prompt
+                // from an unavailable auth entry, not from a missing map key.
+                if (this.quotaByProvider.claude?.error !== SIGNED_OUT_ERROR) {
+                    this.lastEmittedClaudeState = null;
+                    this.emitClaudeState(makeUnavailableClaudeState(SIGNED_OUT_ERROR, 'auth'));
+                }
+                return;
+            }
+            this.claudeDormant = false;
+            await this.refreshPeakHours();
+            const creds = await this.readClaudeCredentials();
+            if (!creds) {
+                this.handleUnavailableState(makeUnavailableClaudeState('Renew your Claude Max OAuth to view quota', 'auth'));
+                return;
+            }
+            const state = await this.fetchClaudeQuota(creds.accessToken);
+            if (!state.available) {
+                this.handleUnavailableState({
+                    ...state,
+                    runtimeProvider: 'claude',
+                    providerId: 'claude-code',
+                    source: state.source ?? 'api',
+                });
+                return;
+            }
+            const recoveredAttempts = this.transientFailureStreak;
+            const recoveredFromFallback = recoveredAttempts > 0;
+            this.resetTransientFailureState();
+            this.authUnavailableActive = false;
+            if (recoveredFromFallback) {
+                this.log?.(`[Quota] Fetch recovered after ${recoveredAttempts} failed attempt(s)`);
+            }
+            this.emitClaudeState({
+                ...state,
+                runtimeProvider: 'claude',
+                providerId: 'claude-code',
+                source: state.source ?? 'api',
+            });
+        }
+        catch (error) {
+            if (this.transientFailureStreak === 0) {
+                this.log?.('[Quota] Poll error', error);
+            }
+            const message = error instanceof Error ? error.message : 'Unknown error';
+            this.handleTransientFailure(makeUnavailableClaudeState(message));
+        }
+        finally {
+            this.pollInFlight = false;
+            if (this.pendingWake) {
+                this.pendingWake = false;
+                void this.poll();
+            }
+            else if (!this.claudeDormant) {
+                this.scheduleNextPoll();
+            }
+        }
+    }
+    wakeForAccountChange() {
+        if (!this.polling)
+            return;
+        if (this.timer) {
+            clearTimeout(this.timer);
+            this.timer = undefined;
+        }
+        this.codexWatcher?.start();
+        this.zaiWatcher?.start();
+        if (this.pollInFlight) {
+            this.pendingWake = true;
+            return;
+        }
+        void this.poll();
+    }
+    emitClaudeState(state) {
+        const withPeakHours = this.currentPeakHours !== undefined ? { ...state, peakHours: this.currentPeakHours } : state;
+        const withFailure = {
+            ...withPeakHours,
+            failure: describeQuotaFailure(withPeakHours),
+        };
+        this.updateProviderQuota('claude', withFailure);
+    }
+    handleUnavailableState(state) {
+        if (state.failureKind === 'auth') {
+            this.resetTransientFailureState();
+            this.authUnavailableActive = true;
+            this.emitClaudeState(state);
+            return;
+        }
+        this.handleTransientFailure(state);
+    }
+    handleTransientFailure(state) {
+        this.authUnavailableActive = false;
+        this.transientFailureStreak += 1;
+        const retryDelay = this.getTransientFailureDelay();
+        const hasVisibleCachedSuccess = this.lastSuccessfulClaudeState !== null && this.lastEmittedClaudeState?.available === true;
+        if (this.transientFailureStreak === 1) {
+            if (hasVisibleCachedSuccess) {
+                this.log?.(`[Quota] Fetch failed, using cached data; retrying in ${formatDelay(retryDelay)}`);
+            }
+            else {
+                this.log?.(`[Quota] Fetch unavailable; retrying in ${formatDelay(retryDelay)}`);
+            }
+        }
+        this.cachedFallbackActive = hasVisibleCachedSuccess;
+        if (hasVisibleCachedSuccess) {
+            this.emitClaudeState({
+                ...this.lastSuccessfulClaudeState,
+                error: state.error,
+                failureKind: state.failureKind,
+                httpStatus: state.httpStatus,
+                retryAfterMs: state.retryAfterMs,
+                source: 'cache',
+                stale: true,
+            });
+        }
+        else {
+            this.emitClaudeState(state);
+        }
+    }
+    getTransientFailureDelay() {
+        return this.transientFailureBackoffMs[Math.min(this.transientFailureStreak - 1, this.transientFailureBackoffMs.length - 1)];
+    }
+    resetTransientFailureState() {
+        this.transientFailureStreak = 0;
+        this.cachedFallbackActive = false;
+    }
+    scheduleNextPoll() {
+        if (!this.polling)
+            return;
+        if (this.timer) {
+            clearTimeout(this.timer);
+        }
+        let delay = this.pollingMode === 'active' ? this.activeIntervalMs : this.idleIntervalMs;
+        if (this.transientFailureStreak > 0) {
+            delay = this.getTransientFailureDelay();
+        }
+        else if (this.authUnavailableActive || this.lastEmittedClaudeState?.available !== true) {
+            delay = this.idleIntervalMs;
+        }
+        else if (this.cachedFallbackActive) {
+            delay = this.idleIntervalMs;
+        }
+        this.timer = setTimeout(() => void this.poll(), delay);
+    }
+    withClaudeAccountDetails(state) {
+        const resolved = this.readClaudeAccount();
+        const accountEmail = resolved.email;
+        if (!accountEmail) {
+            const nextState = { ...state };
+            delete nextState.accountLabel;
+            delete nextState.accountDetail;
+            return nextState;
+        }
+        return {
+            ...state,
+            accountLabel: resolved.label ?? accountEmail,
+            accountDetail: accountEmail,
+        };
+    }
+    emit() {
+        const snapshot = { ...this.quotaByProvider };
+        for (const listener of this.listeners) {
+            try {
+                listener(snapshot);
+            }
+            catch {
+                // Listener failures should not break polling.
+            }
+        }
+    }
+}

package/dist/esm/node.js

@@ -0,0 +1,46 @@
+/**
+ * Node-only entry.
+ *
+ * Pricing catalog hydration from the LiteLLM source. Requires `node:fs`
+ * and `node:path`; safe for extension-host and CLI consumers. Not safe
+ * for browser bundles — use `sidekick-shared/browser` there.
+ */
+export { hydratePricingCatalog, normalizeLiteLlmCatalog, normalizeLiteLlmContextWindows, LITELLM_CATALOG_URL, } from './pricingCatalog';
+export { loadObservedContextWindows, recordObservedContextWindow, getObservedContextWindowPath, } from './observedContextWindows';
+export { listRecentSessions, readSessionTranscript } from './sessionTranscripts';
+export { collectPromptHistory, isPromptHistorySessionSettled, parsePromptHistoryCursor, } from './promptHistory';
+export { collectSessionPromptHistory } from './sessionPromptHistory';
+export { HUMAN_CLAUDE_ENTRYPOINTS, HUMAN_CODEX_SOURCES, humanPromptText, isHumanPrompt, } from './humanPrompt';
+export { computeSessionFileStats, firstUserPrompt, providerContextSizeFn, readSessionFileStats, } from './sessionStats';
+export { readSessionReportInputs } from './report/sessionReportInputs';
+export { fingerprintString, sessionFingerprintParts } from './sessionFingerprint';
+export { STATE_FILE_NAME, STATE_FILE_SCHEMA_VERSION, billingBlockToStateFile, getStateFilePath, quotaToStateFile, readStateFile, writeStateFile, } from './stateFile';
+export { BILLING_BLOCK_DURATION_MS, computeBillingBlocks, findActiveBillingBlock, } from './usage/billingBlocks';
+export { MAX_USAGE_CACHE_FILES, USAGE_CACHE_VERSION, collectUsageEvents, getUsageCacheDir, pruneUsageCache, } from './usage/usageEvents';
+export { collectSessionTokenTotals, combineSessionTokenTotals, readMainThreadTokenTotals, scanSessionSubagents, subagentTokenTotals, } from './sessionTokenTotals';
+export { applySessionSummary, isFileImported, markFileImported, removeSessionSummary, sessionSummaryFromStats, } from './historicalStore';
+export { ACTIVE_SESSION_MTIME_THRESHOLD_MS, importSessionHistory, } from './usage/importSessionHistory';
+export { bucketUsage, summarizeUsageRows, usageBucketKey, weekKey } from './usage/usageReports';
+export { findCodexRolloutFile } from './providers/codex';
+export { walkRolloutFiles, walkRolloutFilesAsync } from './providers/rolloutWalker';
+export { readCodexHistory } from './parsers/codexHistory';
+export { listSessionPreviews, listSessionPreviewsAsync, readSessionPreview, readSessionPreviewAsync, } from './sessionPreviews';
+export { ObservedSessionCollector, observedSessionSourceFromProvider, fileFingerprint, fileFingerprintParts, } from './observedSessionCollector';
+export { DirectoryListingCache, splitWatchedPath } from './providers/directoryListingCache';
+export { createSessionProviders } from './providers/factory';
+export { SYNTHETIC_MODEL } from './usage/claudeUsageDedupe';
+// Sidekick's config root
+export { CONFIG_DIR_ENV_VAR, getConfigDir, getConfigDirOverride, getDefaultConfigDir, } from './paths';
+// Claude Code session directories (Claude's own path encoding)
+export { encodeWorkspacePath as encodeClaudeWorkspacePath, getSessionDirectory as getClaudeSessionDirectory, } from './parsers/sessionPathResolver';
+// Provider homes the CLIs read for this process
+export { getLiveClaudeHome, getDefaultClaudeHome, isDefaultClaudeHome, getClaudeProjectsDir, } from './claudePaths';
+export { getSystemCodexHome, getCodexMonitoringHomes, resolveSidekickCodexHome, getCodexExecutionEnv, getCodexSessionsDirs, CODEX_SESSIONS_SUBDIR, CODEX_ARCHIVED_SESSIONS_SUBDIR, } from './codexPaths';
+export { fetchProviderServiceStatus } from './providerServiceStatus';
+// Tool categories across providers
+export { classifyTool, TOOL_CATEGORIES } from './toolCategory';
+// Workspace roots and git worktrees
+export { resolveWorkspaceRoots } from './workspaceRoots';
+export { discoverWorktreeSiblings, resolveWorktreeMainRepo } from './parsers/sessionPathResolver';
+// Bounded JSONL tail reader
+export { createJsonlTail, DEFAULT_JSONL_TAIL_MAX_LINE_BYTES, DEFAULT_JSONL_TAIL_READ_BYTES, } from './watchers/jsonlTail';

package/dist/esm/observedContextWindows.js

@@ -0,0 +1,165 @@
+/**
+ * Persisted record of context windows providers actually reported (Node-only).
+ *
+ * Some agents report the real context window for the running session — Codex
+ * emits `model_context_window` on every `token_count` event. That number is the
+ * *effective* window for the account and tier, which can sit well below the
+ * model's published maximum (e.g. 258,400 observed for `gpt-5.6-sol` against a
+ * catalog maximum of 1,050,000).
+ *
+ * A live session uses that value directly. This module keeps it across runs, so
+ * historical and static views don't fall back to a published maximum that would
+ * make the context gauge read far too empty.
+ *
+ * Precedence, most-trusted first: runtime → observed (here) → LiteLLM catalog →
+ * static table. See `modelContext.ts`.
+ *
+ * ## Where the store lives — two seams, one story
+ *
+ * Reader ({@link loadObservedContextWindows}) and writer
+ * ({@link recordObservedContextWindow}) resolve the store path identically:
+ * explicit `cacheDir` option → `setConfigDir()` / `SIDEKICK_CONFIG_DIR` (via
+ * `getConfigDir()`) → platform default. The global config-dir override is the
+ * deployment-level seam external consumers use to relocate every Sidekick
+ * store at once; the per-call `cacheDir` is the isolation seam for tests and
+ * multi-tenant hosts. Providers deliberately do NOT thread `cacheDir` —
+ * `CodexProvider` records observations with default options, which follow the
+ * global override, so a default-options load always sees what a
+ * default-options record wrote.
+ *
+ * @module observedContextWindows
+ */
+import { promises as fs } from 'node:fs';
+import * as path from 'node:path';
+import { _setObservedContextWindows, _getObservedContextWindows } from './modelContext';
+import { getConfigDir } from './paths';
+import { updateJsonStoreAtomic } from './writers/atomic';
+// ── Constants ──
+const STORE_FILE_NAME = 'observed-context-windows.json';
+const STORE_VERSION = 1;
+/**
+ * Observations older than this are ignored on load. A provider reports its
+ * context window on every session, so a live model refreshes its entry
+ * constantly; an entry that has gone quiet this long belongs to a tier or
+ * model the user no longer runs and must not outrank the catalog forever.
+ */
+export const OBSERVED_CONTEXT_WINDOW_TTL_MS = 30 * 86_400_000;
+/** Resolve the on-disk store path. */
+export function getObservedContextWindowPath(cacheDir) {
+    return path.join(cacheDir ?? getConfigDir(), STORE_FILE_NAME);
+}
+function emptyStore() {
+    return { version: STORE_VERSION, models: {} };
+}
+/**
+ * Last value successfully persisted, per resolved store path.
+ *
+ * The in-memory override table in `modelContext` is process-global by design —
+ * a lookup should answer the same way everywhere. That makes it unusable as the
+ * write dedupe: with two `cacheDir`s in one process (two temp dirs in a test
+ * suite, a multi-tenant host, a CLI and extension host sharing a process), the
+ * global would already hold the value from the first store and the second store
+ * would never be written at all.
+ */
+const lastPersistedByStore = new Map();
+/** Reset the per-store write dedupe. Test-only; not part of the public API. */
+export function _clearObservedContextWindowWriteCache() {
+    lastPersistedByStore.clear();
+}
+/**
+ * Keep only well-formed, recent entries; a hand-edited or partly-corrupt file
+ * shouldn't poison lookups, and a stale observation shouldn't outrank the
+ * catalog (see {@link OBSERVED_CONTEXT_WINDOW_TTL_MS}).
+ */
+function toOverrideMap(store, now = Date.now()) {
+    const out = {};
+    for (const [modelId, entry] of Object.entries(store.models ?? {})) {
+        const window = entry?.contextWindow;
+        if (typeof window !== 'number' || !Number.isFinite(window) || window <= 0)
+            continue;
+        const observedAt = typeof entry.observedAt === 'string' ? Date.parse(entry.observedAt) : NaN;
+        if (Number.isFinite(observedAt) && now - observedAt > OBSERVED_CONTEXT_WINDOW_TTL_MS)
+            continue;
+        out[modelId] = window;
+    }
+    return out;
+}
+// ── Public API ──
+/**
+ * Load persisted observations and apply them as context-window overrides.
+ *
+ * Always resolves — never throws. A missing, unreadable, or malformed store
+ * leaves the overrides empty and lookups fall through to catalog/static.
+ */
+export async function loadObservedContextWindows(options = {}) {
+    const storePath = getObservedContextWindowPath(options.cacheDir);
+    try {
+        const raw = await fs.readFile(storePath, 'utf8');
+        const parsed = JSON.parse(raw);
+        if (!parsed || typeof parsed !== 'object' || !parsed.models)
+            return {};
+        const overrides = toOverrideMap(parsed);
+        _setObservedContextWindows(overrides);
+        return overrides;
+    }
+    catch (err) {
+        const code = err.code;
+        if (code !== 'ENOENT') {
+            options.logger?.(`observedContextWindows: failed to load ${storePath}: ${String(err)}`);
+        }
+        return {};
+    }
+}
+/**
+ * Record a provider-reported context window for a model.
+ *
+ * Applies in memory immediately, then persists — but only when the value
+ * actually changed *for that store*. Codex reports a window on every
+ * `token_count` event, so an unconditional write would mean disk I/O many times
+ * per session for a value that almost never moves.
+ *
+ * Always resolves — never throws. Persistence failures are logged and dropped;
+ * the in-memory override still stands for this process, and the next call
+ * retries the write.
+ */
+export async function recordObservedContextWindow(modelId, contextWindow, options = {}) {
+    const normalizedId = modelId?.trim().toLowerCase();
+    if (!normalizedId)
+        return;
+    if (!Number.isFinite(contextWindow) || contextWindow <= 0)
+        return;
+    const current = _getObservedContextWindows();
+    if (current[normalizedId] !== contextWindow) {
+        _setObservedContextWindows({ ...current, [normalizedId]: contextWindow });
+    }
+    const storePath = getObservedContextWindowPath(options.cacheDir);
+    const persisted = lastPersistedByStore.get(storePath);
+    if (persisted?.get(normalizedId) === contextWindow)
+        return;
+    try {
+        // Lock-guarded read-modify-write: the CLI and the extension host can both
+        // be observing sessions at once, and each should merge rather than clobber.
+        await updateJsonStoreAtomic(storePath, emptyStore, (latest) => {
+            const models = latest?.models ?? {};
+            if (models[normalizedId]?.contextWindow === contextWindow)
+                return latest;
+            return {
+                version: STORE_VERSION,
+                models: {
+                    ...models,
+                    [normalizedId]: { contextWindow, observedAt: new Date().toISOString() },
+                },
+            };
+        });
+        // Recorded only on success, so a transient EACCES retries next time.
+        let store = lastPersistedByStore.get(storePath);
+        if (!store) {
+            store = new Map();
+            lastPersistedByStore.set(storePath, store);
+        }
+        store.set(normalizedId, contextWindow);
+    }
+    catch (err) {
+        options.logger?.(`observedContextWindows: failed to persist ${storePath}: ${String(err)}`);
+    }
+}