sidekick-shared 0.24.5 → 0.26.0

package/dist/multiProviderQuotaService.d.ts

@@ -4,6 +4,7 @@ import type { PeakHoursState } from './peakHours';
 import type { QuotaState } from './quota';
 import type { Disposable } from './quotaPoller';
 import type { ProviderQuotaMap, ProviderQuotaState } from './providerQuota';
+import { type AccountsChangedEvent } from './accountChanges';
 type Logger = (message: string, error?: unknown) => void;
 interface CodexWatcherLike extends Disposable {
     start(): void;
@@ -28,6 +29,7 @@ export interface MultiProviderQuotaServiceOptions {
     readClaudeAccount?: typeof resolveActiveClaudeAccount;
     fetchClaudeQuota?: (accessToken: string) => Promise<QuotaState>;
     fetchPeakHours?: () => Promise<PeakHoursState>;
+    subscribeAccountsChanged?: (listener: (event: AccountsChangedEvent) => void) => Disposable;
     log?: Logger;
 }
 export declare class MultiProviderQuotaService implements Disposable {
@@ -41,6 +43,7 @@ export declare class MultiProviderQuotaService implements Disposable {
     private readonly fetchClaudeQuota;
     private readonly fetchPeakHours;
     private readonly log?;
+    private readonly subscribeAccountsChanged;
     private readonly listeners;
     private readonly codexWatcher;
     private readonly ownsCodexWatcher;
@@ -60,6 +63,10 @@ export declare class MultiProviderQuotaService implements Disposable {
     private currentPeakHours;
     private lastFreshPeakHoursAt;
     private peakHoursErrorLogged;
+    private claudeDormant;
+    private accountSubscription;
+    private pollInFlight;
+    private pendingWake;
     constructor(options?: MultiProviderQuotaServiceOptions);
     startPolling(): void;
     stopPolling(): void;
@@ -73,6 +80,7 @@ export declare class MultiProviderQuotaService implements Disposable {
     dispose(): void;
     private refreshPeakHours;
     private poll;
+    private wakeForAccountChange;
     private emitClaudeState;
     private handleUnavailableState;
     private handleTransientFailure;

package/dist/multiProviderQuotaService.js

@@ -7,10 +7,12 @@ const credentials_1 = require("./credentials");
 const peakHours_1 = require("./peakHours");
 const quota_1 = require("./quota");
 const quotaPresentation_1 = require("./quotaPresentation");
+const accountChanges_1 = require("./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',
@@ -55,6 +57,7 @@ class MultiProviderQuotaService {
     fetchClaudeQuota;
     fetchPeakHours;
     log;
+    subscribeAccountsChanged;
     listeners = [];
     codexWatcher;
     ownsCodexWatcher;
@@ -74,6 +77,10 @@ class MultiProviderQuotaService {
     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;
@@ -85,6 +92,7 @@ class MultiProviderQuotaService {
         this.readClaudeAccount = options.readClaudeAccount ?? accounts_1.resolveActiveClaudeAccount;
         this.fetchClaudeQuota = options.fetchClaudeQuota ?? quota_1.fetchQuota;
         this.fetchPeakHours = options.fetchPeakHours ?? peakHours_1.fetchPeakHoursStatus;
+        this.subscribeAccountsChanged = options.subscribeAccountsChanged ?? accountChanges_1.onAccountsChanged;
         this.log = options.log;
         if (options.codexWatcher !== undefined) {
             this.codexWatcher = options.codexWatcher;
@@ -119,21 +127,25 @@ class MultiProviderQuotaService {
         if (this.polling)
             return;
         this.polling = true;
+        this.accountSubscription ??= this.subscribeAccountsChanged(() => this.wakeForAccountChange());
         this.codexWatcher?.start();
         this.zaiWatcher?.start();
-        void this.poll();
+        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) {
@@ -250,8 +262,35 @@ class MultiProviderQuotaService {
         this.currentPeakHours = result;
     }
     async poll() {
-        await this.refreshPeakHours();
+        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'));
@@ -289,9 +328,31 @@ class MultiProviderQuotaService {
             this.handleTransientFailure(makeUnavailableClaudeState(message));
         }
         finally {
-            this.scheduleNextPoll();
+            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 = {

package/dist/node.d.ts

@@ -10,12 +10,31 @@ export type { HydrateOptions, HydrateResult } from './pricingCatalog';
 export { loadObservedContextWindows, recordObservedContextWindow, getObservedContextWindowPath, } from './observedContextWindows';
 export type { ObservedContextWindowOptions, ObservedContextWindowStore, } from './observedContextWindows';
 export { listRecentSessions, readSessionTranscript } from './sessionTranscripts';
+export { computeSessionFileStats, firstUserPrompt, providerContextSizeFn, readSessionFileStats, } from './sessionStats';
+export { readSessionReportInputs } from './report/sessionReportInputs';
+export type { SessionReportInputs } from './report/sessionReportInputs';
+export { fingerprintString, sessionFingerprintParts } from './sessionFingerprint';
+export { STATE_FILE_NAME, STATE_FILE_SCHEMA_VERSION, billingBlockToStateFile, getStateFilePath, quotaToStateFile, readStateFile, writeStateFile, } from './stateFile';
+export type { SidekickStateFile, SidekickStateInput, StateFileAccount, StateFileBillingBlock, StateFileContext, StateFileQuota, StateFileQuotaWindow, StateFileSession, StateFileWriter, WriteStateFileOptions, } from './stateFile';
+export type { ComputeSessionFileStatsOptions, ReadSessionFileStatsOptions } from './sessionStats';
+export { BILLING_BLOCK_DURATION_MS, computeBillingBlocks, findActiveBillingBlock, } from './usage/billingBlocks';
+export type { BillingBlock, BillingBlockInput, BillingBlockModelUsage, BillingBlockTokens, ComputeBillingBlocksOptions, } from './usage/billingBlocks';
+export { MAX_USAGE_CACHE_FILES, USAGE_CACHE_VERSION, collectUsageEvents, getUsageCacheDir, pruneUsageCache, } from './usage/usageEvents';
+export type { CollectUsageEventsOptions, CollectUsageEventsResult, UsageEventRecord, UsageSessionRecord, } from './usage/usageEvents';
+export { applySessionSummary, isFileImported, markFileImported, removeSessionSummary, sessionSummaryFromStats, } from './historicalStore';
+export type { ApplySessionSummaryOptions, SessionSummaryFromStatsOptions } from './historicalStore';
+export { ACTIVE_SESSION_MTIME_THRESHOLD_MS, importSessionHistory, } from './usage/importSessionHistory';
+export type { ImportSessionHistoryOptions, ImportSessionHistoryResult, } from './usage/importSessionHistory';
+export { bucketUsage, summarizeUsageRows, usageBucketKey, weekKey } from './usage/usageReports';
+export type { BucketUsageOptions, UsageBucketRow, UsageGranularity, UsageGroupDimension, UsageTotals, } from './usage/usageReports';
 export type { ProviderSessionIndex, ListRecentSessionsOptions } from './sessionTranscripts';
 export { findCodexRolloutFile } from './providers/codex';
+export { walkRolloutFiles, walkRolloutFilesAsync } from './providers/rolloutWalker';
+export type { RolloutFileInfo, WalkRolloutFilesOptions } from './providers/rolloutWalker';
 export type { FindCodexRolloutFileOptions } from './providers/codex';
 export { readCodexHistory } from './parsers/codexHistory';
 export type { CodexHistoryEntry, ReadCodexHistoryOptions } from './parsers/codexHistory';
-export { listSessionPreviews, readSessionPreview } from './sessionPreviews';
-export type { ListSessionPreviewsOptions, ReadSessionPreviewOptions, SessionPreview, } from './sessionPreviews';
-export { ObservedSessionCollector, observedSessionSourceFromProvider, fileFingerprint, } from './observedSessionCollector';
-export type { ObservedSessionReference, ObservedSessionCollectionSource, ProviderObservedSessionCollectionSource, ObservedSessionDiagnosticKind, ObservedSessionDiagnostic, ObservedSessionCollection, ObservedSessionCollectorOptions, } from './observedSessionCollector';
+export { listSessionPreviews, listSessionPreviewsAsync, readSessionPreview, readSessionPreviewAsync, } from './sessionPreviews';
+export type { AsyncSessionPreviewOptions, ListSessionPreviewsAsyncOptions, ListSessionPreviewsOptions, ReadSessionPreviewAsyncOptions, ReadSessionPreviewOptions, SessionPreview, SessionPreviewListResult, SessionPreviewReadResult, } from './sessionPreviews';
+export { ObservedSessionCollector, observedSessionSourceFromProvider, fileFingerprint, fileFingerprintParts, } from './observedSessionCollector';
+export type { KnownObservedSessionFingerprint, ObservedSessionChange, ObservedSessionChangeBatch, ObservedSessionChangeType, ObservedSessionReference, ObservedSessionFingerprintParts, ObservedSessionSourceSubscribeOptions, ObservedSessionSubscribeOptions, ObservedSessionCollectionSource, ProviderObservedSessionCollectionSource, ObservedSessionDiagnosticKind, ObservedSessionDiagnosticPhase, ObservedSessionDiagnosticSeverity, ObservedSessionDiagnostic, ObservedSessionCollection, ObservedSessionCollectorOptions, } from './observedSessionCollector';

package/dist/node.js

@@ -7,7 +7,8 @@
  * for browser bundles — use `sidekick-shared/browser` there.
  */
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.fileFingerprint = exports.observedSessionSourceFromProvider = exports.ObservedSessionCollector = exports.readSessionPreview = exports.listSessionPreviews = exports.readCodexHistory = exports.findCodexRolloutFile = exports.readSessionTranscript = exports.listRecentSessions = exports.getObservedContextWindowPath = exports.recordObservedContextWindow = exports.loadObservedContextWindows = exports.LITELLM_CATALOG_URL = exports.normalizeLiteLlmContextWindows = exports.normalizeLiteLlmCatalog = exports.hydratePricingCatalog = void 0;
+exports.readSessionPreviewAsync = exports.readSessionPreview = exports.listSessionPreviewsAsync = exports.listSessionPreviews = exports.readCodexHistory = exports.walkRolloutFilesAsync = exports.walkRolloutFiles = exports.findCodexRolloutFile = exports.weekKey = exports.usageBucketKey = exports.summarizeUsageRows = exports.bucketUsage = exports.importSessionHistory = exports.ACTIVE_SESSION_MTIME_THRESHOLD_MS = exports.sessionSummaryFromStats = exports.removeSessionSummary = exports.markFileImported = exports.isFileImported = exports.applySessionSummary = exports.pruneUsageCache = exports.getUsageCacheDir = exports.collectUsageEvents = exports.USAGE_CACHE_VERSION = exports.MAX_USAGE_CACHE_FILES = exports.findActiveBillingBlock = exports.computeBillingBlocks = exports.BILLING_BLOCK_DURATION_MS = exports.writeStateFile = exports.readStateFile = exports.quotaToStateFile = exports.getStateFilePath = exports.billingBlockToStateFile = exports.STATE_FILE_SCHEMA_VERSION = exports.STATE_FILE_NAME = exports.sessionFingerprintParts = exports.fingerprintString = exports.readSessionReportInputs = exports.readSessionFileStats = exports.providerContextSizeFn = exports.firstUserPrompt = exports.computeSessionFileStats = exports.readSessionTranscript = exports.listRecentSessions = exports.getObservedContextWindowPath = exports.recordObservedContextWindow = exports.loadObservedContextWindows = exports.LITELLM_CATALOG_URL = exports.normalizeLiteLlmContextWindows = exports.normalizeLiteLlmCatalog = exports.hydratePricingCatalog = void 0;
+exports.fileFingerprintParts = exports.fileFingerprint = exports.observedSessionSourceFromProvider = exports.ObservedSessionCollector = void 0;
 var pricingCatalog_1 = require("./pricingCatalog");
 Object.defineProperty(exports, "hydratePricingCatalog", { enumerable: true, get: function () { return pricingCatalog_1.hydratePricingCatalog; } });
 Object.defineProperty(exports, "normalizeLiteLlmCatalog", { enumerable: true, get: function () { return pricingCatalog_1.normalizeLiteLlmCatalog; } });
@@ -20,14 +21,62 @@ Object.defineProperty(exports, "getObservedContextWindowPath", { enumerable: tru
 var sessionTranscripts_1 = require("./sessionTranscripts");
 Object.defineProperty(exports, "listRecentSessions", { enumerable: true, get: function () { return sessionTranscripts_1.listRecentSessions; } });
 Object.defineProperty(exports, "readSessionTranscript", { enumerable: true, get: function () { return sessionTranscripts_1.readSessionTranscript; } });
+var sessionStats_1 = require("./sessionStats");
+Object.defineProperty(exports, "computeSessionFileStats", { enumerable: true, get: function () { return sessionStats_1.computeSessionFileStats; } });
+Object.defineProperty(exports, "firstUserPrompt", { enumerable: true, get: function () { return sessionStats_1.firstUserPrompt; } });
+Object.defineProperty(exports, "providerContextSizeFn", { enumerable: true, get: function () { return sessionStats_1.providerContextSizeFn; } });
+Object.defineProperty(exports, "readSessionFileStats", { enumerable: true, get: function () { return sessionStats_1.readSessionFileStats; } });
+var sessionReportInputs_1 = require("./report/sessionReportInputs");
+Object.defineProperty(exports, "readSessionReportInputs", { enumerable: true, get: function () { return sessionReportInputs_1.readSessionReportInputs; } });
+var sessionFingerprint_1 = require("./sessionFingerprint");
+Object.defineProperty(exports, "fingerprintString", { enumerable: true, get: function () { return sessionFingerprint_1.fingerprintString; } });
+Object.defineProperty(exports, "sessionFingerprintParts", { enumerable: true, get: function () { return sessionFingerprint_1.sessionFingerprintParts; } });
+var stateFile_1 = require("./stateFile");
+Object.defineProperty(exports, "STATE_FILE_NAME", { enumerable: true, get: function () { return stateFile_1.STATE_FILE_NAME; } });
+Object.defineProperty(exports, "STATE_FILE_SCHEMA_VERSION", { enumerable: true, get: function () { return stateFile_1.STATE_FILE_SCHEMA_VERSION; } });
+Object.defineProperty(exports, "billingBlockToStateFile", { enumerable: true, get: function () { return stateFile_1.billingBlockToStateFile; } });
+Object.defineProperty(exports, "getStateFilePath", { enumerable: true, get: function () { return stateFile_1.getStateFilePath; } });
+Object.defineProperty(exports, "quotaToStateFile", { enumerable: true, get: function () { return stateFile_1.quotaToStateFile; } });
+Object.defineProperty(exports, "readStateFile", { enumerable: true, get: function () { return stateFile_1.readStateFile; } });
+Object.defineProperty(exports, "writeStateFile", { enumerable: true, get: function () { return stateFile_1.writeStateFile; } });
+var billingBlocks_1 = require("./usage/billingBlocks");
+Object.defineProperty(exports, "BILLING_BLOCK_DURATION_MS", { enumerable: true, get: function () { return billingBlocks_1.BILLING_BLOCK_DURATION_MS; } });
+Object.defineProperty(exports, "computeBillingBlocks", { enumerable: true, get: function () { return billingBlocks_1.computeBillingBlocks; } });
+Object.defineProperty(exports, "findActiveBillingBlock", { enumerable: true, get: function () { return billingBlocks_1.findActiveBillingBlock; } });
+var usageEvents_1 = require("./usage/usageEvents");
+Object.defineProperty(exports, "MAX_USAGE_CACHE_FILES", { enumerable: true, get: function () { return usageEvents_1.MAX_USAGE_CACHE_FILES; } });
+Object.defineProperty(exports, "USAGE_CACHE_VERSION", { enumerable: true, get: function () { return usageEvents_1.USAGE_CACHE_VERSION; } });
+Object.defineProperty(exports, "collectUsageEvents", { enumerable: true, get: function () { return usageEvents_1.collectUsageEvents; } });
+Object.defineProperty(exports, "getUsageCacheDir", { enumerable: true, get: function () { return usageEvents_1.getUsageCacheDir; } });
+Object.defineProperty(exports, "pruneUsageCache", { enumerable: true, get: function () { return usageEvents_1.pruneUsageCache; } });
+var historicalStore_1 = require("./historicalStore");
+Object.defineProperty(exports, "applySessionSummary", { enumerable: true, get: function () { return historicalStore_1.applySessionSummary; } });
+Object.defineProperty(exports, "isFileImported", { enumerable: true, get: function () { return historicalStore_1.isFileImported; } });
+Object.defineProperty(exports, "markFileImported", { enumerable: true, get: function () { return historicalStore_1.markFileImported; } });
+Object.defineProperty(exports, "removeSessionSummary", { enumerable: true, get: function () { return historicalStore_1.removeSessionSummary; } });
+Object.defineProperty(exports, "sessionSummaryFromStats", { enumerable: true, get: function () { return historicalStore_1.sessionSummaryFromStats; } });
+var importSessionHistory_1 = require("./usage/importSessionHistory");
+Object.defineProperty(exports, "ACTIVE_SESSION_MTIME_THRESHOLD_MS", { enumerable: true, get: function () { return importSessionHistory_1.ACTIVE_SESSION_MTIME_THRESHOLD_MS; } });
+Object.defineProperty(exports, "importSessionHistory", { enumerable: true, get: function () { return importSessionHistory_1.importSessionHistory; } });
+var usageReports_1 = require("./usage/usageReports");
+Object.defineProperty(exports, "bucketUsage", { enumerable: true, get: function () { return usageReports_1.bucketUsage; } });
+Object.defineProperty(exports, "summarizeUsageRows", { enumerable: true, get: function () { return usageReports_1.summarizeUsageRows; } });
+Object.defineProperty(exports, "usageBucketKey", { enumerable: true, get: function () { return usageReports_1.usageBucketKey; } });
+Object.defineProperty(exports, "weekKey", { enumerable: true, get: function () { return usageReports_1.weekKey; } });
 var codex_1 = require("./providers/codex");
 Object.defineProperty(exports, "findCodexRolloutFile", { enumerable: true, get: function () { return codex_1.findCodexRolloutFile; } });
+var rolloutWalker_1 = require("./providers/rolloutWalker");
+Object.defineProperty(exports, "walkRolloutFiles", { enumerable: true, get: function () { return rolloutWalker_1.walkRolloutFiles; } });
+Object.defineProperty(exports, "walkRolloutFilesAsync", { enumerable: true, get: function () { return rolloutWalker_1.walkRolloutFilesAsync; } });
 var codexHistory_1 = require("./parsers/codexHistory");
 Object.defineProperty(exports, "readCodexHistory", { enumerable: true, get: function () { return codexHistory_1.readCodexHistory; } });
 var sessionPreviews_1 = require("./sessionPreviews");
 Object.defineProperty(exports, "listSessionPreviews", { enumerable: true, get: function () { return sessionPreviews_1.listSessionPreviews; } });
+Object.defineProperty(exports, "listSessionPreviewsAsync", { enumerable: true, get: function () { return sessionPreviews_1.listSessionPreviewsAsync; } });
 Object.defineProperty(exports, "readSessionPreview", { enumerable: true, get: function () { return sessionPreviews_1.readSessionPreview; } });
+Object.defineProperty(exports, "readSessionPreviewAsync", { enumerable: true, get: function () { return sessionPreviews_1.readSessionPreviewAsync; } });
 var observedSessionCollector_1 = require("./observedSessionCollector");
 Object.defineProperty(exports, "ObservedSessionCollector", { enumerable: true, get: function () { return observedSessionCollector_1.ObservedSessionCollector; } });
 Object.defineProperty(exports, "observedSessionSourceFromProvider", { enumerable: true, get: function () { return observedSessionCollector_1.observedSessionSourceFromProvider; } });
 Object.defineProperty(exports, "fileFingerprint", { enumerable: true, get: function () { return observedSessionCollector_1.fileFingerprint; } });
+Object.defineProperty(exports, "fileFingerprintParts", { enumerable: true, get: function () { return observedSessionCollector_1.fileFingerprintParts; } });

package/dist/observedContextWindows.d.ts

@@ -44,6 +44,13 @@ export interface ObservedContextWindowStore {
     version: 1;
     models: Record<string, ObservedContextWindowEntry>;
 }
+/**
+ * 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 declare const OBSERVED_CONTEXT_WINDOW_TTL_MS: number;
 /** Resolve the on-disk store path. */
 export declare function getObservedContextWindowPath(cacheDir?: string): string;
 /** Reset the per-store write dedupe. Test-only; not part of the public API. */

package/dist/observedContextWindows.js

@@ -64,6 +64,7 @@ var __importStar = (this && this.__importStar) || (function () {
     };
 })();
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.OBSERVED_CONTEXT_WINDOW_TTL_MS = void 0;
 exports.getObservedContextWindowPath = getObservedContextWindowPath;
 exports._clearObservedContextWindowWriteCache = _clearObservedContextWindowWriteCache;
 exports.loadObservedContextWindows = loadObservedContextWindows;
@@ -76,6 +77,13 @@ const atomic_1 = require("./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.
+ */
+exports.OBSERVED_CONTEXT_WINDOW_TTL_MS = 30 * 86_400_000;
 /** Resolve the on-disk store path. */
 function getObservedContextWindowPath(cacheDir) {
     return path.join(cacheDir ?? (0, paths_1.getConfigDir)(), STORE_FILE_NAME);
@@ -98,13 +106,20 @@ const lastPersistedByStore = new Map();
 function _clearObservedContextWindowWriteCache() {
     lastPersistedByStore.clear();
 }
-/** Keep only well-formed entries; a hand-edited or partly-corrupt file shouldn't poison lookups. */
-function toOverrideMap(store) {
+/**
+ * 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 > exports.OBSERVED_CONTEXT_WINDOW_TTL_MS)
+            continue;
         out[modelId] = window;
     }
     return out;

package/dist/observedSessionCollector.d.ts

@@ -1,24 +1,42 @@
-import type { ObservedAgentSessionV1, ProviderCapabilitiesV1 } from './types/observedSessionV1';
+import type { ObservedAgentSessionV1, ProviderCapabilitiesV1, ProviderSessionAdapterV1Options } from './types/observedSessionV1';
 import type { SessionProviderBase } from './providers/types';
+import type { ObservedSessionFingerprintParts } from './sessionFingerprint';
+export { fileFingerprint, fileFingerprintParts } from './sessionFingerprint';
+export type { ObservedSessionFingerprintParts } from './sessionFingerprint';
 export interface ObservedSessionReference {
     sessionId: string;
     /** Opaque source locator used only by the source implementation. Never emitted in diagnostics. */
     sourceKey?: string;
+    /** Backward-compatible opaque fingerprint. */
     fingerprintHint?: string;
+    /** Structured fingerprint for consumers that previously parsed fingerprintHint. */
+    fingerprintParts?: ObservedSessionFingerprintParts;
+}
+export interface ObservedSessionSourceSubscribeOptions {
+    pollIntervalMs?: number;
 }
 export interface ObservedSessionCollectionSource<T = unknown> {
     providerId: string;
     discover(): Promise<ObservedSessionReference[]> | ObservedSessionReference[];
     read(reference: ObservedSessionReference): Promise<T> | T;
+    refreshCached?(reference: ObservedSessionReference, value: T, observedAt: string): Promise<T> | T;
+    /** Low-level invalidation signal; the collector performs fingerprint reconciliation. */
+    subscribe?(listener: () => void, options?: ObservedSessionSourceSubscribeOptions): {
+        dispose(): void;
+    };
     dispose?(): void;
 }
 export interface ProviderObservedSessionCollectionSource extends ObservedSessionCollectionSource<ObservedAgentSessionV1> {
     capabilities: ProviderCapabilitiesV1;
 }
 export type ObservedSessionDiagnosticKind = 'provider-discovery-failed' | 'session-read-failed' | 'provider-recovered' | 'session-recovered';
+export type ObservedSessionDiagnosticSeverity = 'info' | 'warning' | 'error';
+export type ObservedSessionDiagnosticPhase = 'discover' | 'read' | 'recover';
 /** Content-safe diagnostics: identifiers and retry metadata only. */
 export interface ObservedSessionDiagnostic {
     kind: ObservedSessionDiagnosticKind;
+    severity: ObservedSessionDiagnosticSeverity;
+    phase: ObservedSessionDiagnosticPhase;
     providerId: string;
     sessionId?: string;
     attempt?: number;
@@ -28,6 +46,13 @@ export interface ObservedSessionCollection<T = unknown> {
     providerId: string;
     sessionId: string;
     value: T;
+    fingerprint: string | null;
+    fingerprintParts: ObservedSessionFingerprintParts | null;
+    cacheHit: boolean;
+    /** Time this observation was returned. */
+    observedAt: string;
+    /** Time content was last parsed; unchanged on a cache hit. */
+    contentObservedAt: string;
 }
 export interface ObservedSessionCollectorOptions<T = unknown> {
     sources: ObservedSessionCollectionSource<T>[];
@@ -37,26 +62,69 @@ export interface ObservedSessionCollectorOptions<T = unknown> {
         now(): number;
     };
     fingerprint?: (source: ObservedSessionCollectionSource<T>, reference: ObservedSessionReference) => Promise<string | null> | string | null;
+    maxConcurrentReads?: number;
+    yieldBetweenReads?: () => Promise<void> | void;
     onObservation?: (observation: ObservedSessionCollection<T>) => void;
     onDiagnostic?: (diagnostic: ObservedSessionDiagnostic) => void;
 }
+export type ObservedSessionChangeType = 'added' | 'changed' | 'removed';
+export interface ObservedSessionChange {
+    type: ObservedSessionChangeType;
+    reference: ObservedSessionReference;
+    previousFingerprint: string | null;
+    previousFingerprintParts: ObservedSessionFingerprintParts | null;
+    fingerprint: string | null;
+    fingerprintParts: ObservedSessionFingerprintParts | null;
+}
+export interface ObservedSessionChangeBatch {
+    providerId: string;
+    changes: ObservedSessionChange[];
+    observedAt: string;
+}
+export interface KnownObservedSessionFingerprint {
+    providerId: string;
+    sessionId: string;
+    fingerprint: string;
+    fingerprintParts?: ObservedSessionFingerprintParts;
+}
+export interface ObservedSessionSubscribeOptions {
+    debounceMs?: number;
+    pollIntervalMs?: number;
+    knownFingerprints?: readonly KnownObservedSessionFingerprint[];
+}
 /**
- * One-shot, host-scheduled observed-session collection with independent
- * provider/session isolation and bounded retry state.
+ * Fail-soft observed-session collection with fingerprint-keyed parse caching,
+ * cooperative reads, and optional provider-level subscriptions.
  */
 export declare class ObservedSessionCollector<T = unknown> {
     private readonly options;
     private readonly failures;
+    private readonly cache;
+    private readonly subscriptions;
     private readonly initialBackoffMs;
     private readonly maxBackoffMs;
     private readonly clock;
+    private readonly maxConcurrentReads;
+    private readonly yieldBetweenReads;
     constructor(options: ObservedSessionCollectorOptions<T>);
     collect(): Promise<ObservedSessionCollection<T>[]>;
+    /**
+     * Subscribe to debounced provider changes. The listener receives fingerprints
+     * only; call collect() to consume changed sessions through the parse cache.
+     */
+    subscribe(listener: (batch: ObservedSessionChangeBatch) => void, options?: ObservedSessionSubscribeOptions): {
+        dispose(): void;
+    };
     reset(): void;
     dispose(): void;
     private collectSource;
     private collectSession;
+    private makeObservation;
+    private emitObservation;
+    private reconcileSource;
     private fingerprint;
+    private evictMissing;
+    private mapWithConcurrency;
     private fail;
     private recover;
     private emitDiagnostic;
@@ -66,6 +134,4 @@ export declare class ObservedSessionCollector<T = unknown> {
  * Adapt a provider using path-only discovery and independent adapter reads, so
  * one malformed session cannot reject discovery of its healthy siblings.
  */
-export declare function observedSessionSourceFromProvider(provider: SessionProviderBase, cwd: string): ProviderObservedSessionCollectionSource;
-/** Size/mtime fingerprint suitable for retry bypass; returns null for synthetic DB locators. */
-export declare function fileFingerprint(sourcePath: string): string | null;
+export declare function observedSessionSourceFromProvider(provider: SessionProviderBase, cwd: string, options?: ProviderSessionAdapterV1Options): ProviderObservedSessionCollectionSource;