sidekick-shared 0.24.1 → 0.24.3

package/README.md

@@ -69,17 +69,17 @@ npm install sidekick-shared
 
 `sidekick-shared` ships three public entry points plus a few convenience subpaths. Pick the one that matches your runtime.
 
-| Path                           | Runtime                    | What it exposes                                                                                                                                     |
-| ------------------------------ | -------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `sidekick-shared`              | Node (CLI, extension host) | Full public API (readers, providers, parsers, pricing, …).                                                                                          |
-| `sidekick-shared/browser`      | **Browser / webview**      | Pure helpers: usage normalization/pricing, token estimation, transcript and assistant-turn projection, model/context math.                          |
-| `sidekick-shared/node`         | Node only                  | LiteLLM pricing hydration, recent-session/transcript reads, and resilient observed-session collection (`fs` + providers).                           |
-| `sidekick-shared/phrases`      | Any runtime                | Phrase arrays + `getRandomPhrase()`.                                                                                                                |
-| `sidekick-shared/modelContext` | Any runtime                | Direct access to the context-window module.                                                                                                         |
-| `sidekick-shared/modelInfo`    | Any runtime                | Direct access to model parsing and cost math.                                                                                                       |
-| `sidekick-shared/formatting`   | Any runtime                | Direct access to pure token and duration display helpers.                                                                                           |
-| `sidekick-shared/schemas`      | Any runtime                | Pure Zod boundary schemas (session events, assistant turns, observed-session V1, quota, account status, quota history) — fs-free, no Node builtins. |
-| `sidekick-shared/statusline`   | Node only                  | Cache-only statusline surface: account status + quota snapshot readers, `formatStatusline()`, and burn-rate estimates.                              |
+| Path                           | Runtime                    | What it exposes                                                                                                                                                                   |
+| ------------------------------ | -------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `sidekick-shared`              | Node (CLI, extension host) | Full public API (readers, providers, parsers, pricing, …).                                                                                                                        |
+| `sidekick-shared/browser`      | **Browser / webview**      | Pure helpers: usage normalization/pricing, token estimation, transcript and assistant-turn projection, model/context math.                                                        |
+| `sidekick-shared/node`         | Node only                  | LiteLLM pricing and context-window hydration, observed context-window persistence, recent-session/transcript reads, and resilient observed-session collection (`fs` + providers). |
+| `sidekick-shared/phrases`      | Any runtime                | Phrase arrays + `getRandomPhrase()`.                                                                                                                                              |
+| `sidekick-shared/modelContext` | Any runtime                | Direct access to the context-window module.                                                                                                                                       |
+| `sidekick-shared/modelInfo`    | Any runtime                | Direct access to model parsing and cost math.                                                                                                                                     |
+| `sidekick-shared/formatting`   | Any runtime                | Direct access to pure token and duration display helpers.                                                                                                                         |
+| `sidekick-shared/schemas`      | Any runtime                | Pure Zod boundary schemas (session events, assistant turns, observed-session V1, quota, account status, quota history) — fs-free, no Node builtins.                               |
+| `sidekick-shared/statusline`   | Node only                  | Cache-only statusline surface: account status + quota snapshot readers, `formatStatusline()`, and burn-rate estimates.                                                            |
 
 ### Browser / webview runtimes
 
@@ -103,14 +103,23 @@ import {
 
 ### Node / CLI / extension host
 
-Hydrate the pricing catalog from the `node` subpath:
+Hydrate the model catalog from the `node` subpath. One fetch covers both prices and context window sizes:
 
 ```typescript
-import { hydratePricingCatalog } from 'sidekick-shared/node';
+import { hydratePricingCatalog, loadObservedContextWindows } from 'sidekick-shared/node';
 
-await hydratePricingCatalog({ cacheDir: '~/.config/sidekick' });
+const { entries, contextWindowEntries } = await hydratePricingCatalog({
+  cacheDir: '~/.config/sidekick',
+});
+
+// Context windows a provider reported on an earlier run. These outrank the
+// catalog, which only knows each model's published maximum — Codex reports the
+// window your account tier actually gets. Local read, offline-safe.
+await loadObservedContextWindows();
 ```
 
+Both calls always resolve; a network failure, missing cache, or malformed store leaves lookups on the static tables. To record a window a provider reports at runtime, call `recordObservedContextWindow(modelId, window)` — it persists only when the value changes.
+
 ### Normalize and price provider usage
 
 ```typescript

package/dist/index.d.ts

@@ -164,8 +164,10 @@ export type { StatuslineInput, StatuslineSelection } from './statusline/formatte
 export { getModelContextWindowSize, DEFAULT_CONTEXT_WINDOW } from './modelContext';
 export { parseModelId, getModelPricing, getModelInfo, calculateCost, calculateCostWithPricing, calculateCostWithProvenance, mergeCostSources, shortModelName, getModelDisplayInfo, compareModelIds, sortModelIds, formatCost, } from './modelInfo';
 export type { ModelPricing, CostTokenUsage, CostSource, CostProvenanceInput, CostWithProvenance, ModelInfo, ModelProvider, ParsedModelId, ModelDisplayInfo, } from './modelInfo';
-export { hydratePricingCatalog, normalizeLiteLlmCatalog, LITELLM_CATALOG_URL, } from './pricingCatalog';
+export { hydratePricingCatalog, normalizeLiteLlmCatalog, normalizeLiteLlmContextWindows, LITELLM_CATALOG_URL, } from './pricingCatalog';
 export type { HydrateOptions, HydrateResult } from './pricingCatalog';
+export { loadObservedContextWindows, recordObservedContextWindow, getObservedContextWindowPath, } from './observedContextWindows';
+export type { ObservedContextWindowOptions, ObservedContextWindowStore, } from './observedContextWindows';
 export { extractTokenUsage } from './extractors/tokenUsage';
 export { extractUrls, extractFilePaths, extractCommands } from './extractors/sessionAssets';
 export type { AssetAgent, ExtractedAsset, ExtractedAssetProvenance, ExtractedAssetType, ExtractedAssets, SourceAssets, } from './extractors/sessionAssets';

package/dist/index.js

@@ -8,8 +8,8 @@ exports.createSessionContextProjector = exports.calculateSessionContextPressure
 exports.scoreSessionQuality = exports.calculateQualityTrend = exports.PatternExtractor = exports.HeatmapTracker = exports.FrequencyTracker = exports.readErrorHistory = exports.getTopFailingTools = exports.appendErrorHistory = exports.MAX_ERROR_HISTORY_SESSIONS = exports.ERROR_HISTORY_SCHEMA_VERSION = exports.getSnapshotPath = exports.isSnapshotValid = exports.deleteSnapshot = exports.loadSnapshot = exports.saveSnapshot = exports.SessionMonitor = exports.parseTodoDependencies = exports.EventAggregator = exports.getRandomPhrase = exports.PHRASE_CATEGORIES = exports.ALL_PHRASES = exports.HIGHLIGHT_CSS = exports.clearHighlightCache = exports.highlightEvent = exports.formatSessionJson = exports.formatSessionMarkdown = exports.formatSessionText = exports.classifyNoise = exports.shouldMergeWithPrevious = exports.classifyFollowEvent = exports.classifyMessage = exports.getSoftNoiseReason = exports.isHardNoiseFollowEvent = exports.isHardNoise = exports.formatToolSummary = exports.formatTokenCount = exports.formatDurationMs = exports.createJsonlTail = exports.toFollowEvents = exports.createWatcher = exports.parseChangelog = exports.extractProposedPlanShared = exports.parsePlanMarkdownShared = exports.PlanExtractor = exports.segmentAssistantTurn = exports.reasoningSummary = exports.isAssistantTurnSubagentTool = exports.extractTurnSubagents = exports.assistantTurnEventsFromSessionEvents = exports.readSessionContextSnapshot = void 0;
 exports.getCodexProfileHome = exports.getCodexProfilesDir = exports.readClaudeProfileIdentity = exports.isClaudeProfileAuthenticated = exports.claudeKeychainService = exports.claudeKeychainSuffix = exports.getClaudeProfileHome = exports.getClaudeProfilesDir = exports.getActiveAccountStatus = exports.removeSavedAccountProfile = exports.replaceSavedAccountProfiles = exports.setActiveSavedAccount = exports.upsertSavedAccountProfile = exports.getActiveSavedAccount = exports.listSavedAccountProfiles = exports.writeSavedAccountRegistry = exports.readSavedAccountRegistry = exports.getAccountsDir = exports.resolveClaudeLoginCommand = exports.listAllAccounts = exports.switchAccount = exports.spawnAccountLogin = exports.finalizeAccountLogin = exports.getAccountLoginStatus = exports.beginAccountLogin = exports.isMultiAccountEnabled = exports.resolveActiveClaudeAccount = exports.getActiveAccount = exports.listAccounts = exports.removeAccount = exports.reconcileClaudeAuthState = exports.applyActiveClaudeToLiveHome = exports.resolveActiveClaudeHome = exports.switchToAccount = exports.addCurrentAccount = exports.readActiveClaudeAccount = exports.writeAccountRegistry = exports.readAccountRegistry = exports.ensureDefaultAccounts = exports.readClaudeMaxAccessTokenSync = exports.readClaudeMaxCredentials = exports.writeActiveCredentials = exports.readActiveCredentials = exports.openInBrowser = exports.parseTranscriptFromEvents = exports.parseTranscript = exports.generateHtmlReport = exports.formatCompactionLedger = exports.calculateCompactionLedger = exports.calculateCodeImpact = void 0;
 exports.selectStatuslineAccount = exports.formatStatusline = exports.estimateTimeToQuota = exports.BurnRateCalculator = exports.MultiProviderQuotaService = exports.resolveZaiQuota = exports.readZaiCredentials = exports.quotaStateFromZaiQuotaLimitPayload = exports.fetchZaiQuotaFromApi = exports.CodexQuotaWatcher = exports.resolveCodexQuotaFromLocalSources = exports.resolveCodexQuota = exports.readLatestCodexQuotaFromRollouts = exports.quotaFromCodexRateLimits = exports.fetchCodexQuotaFromApi = exports.fetchCodexResetCreditsFromApi = exports.getWorkspaceIdFromPath = exports.pruneQuotaHistory = exports.readQuotaHistoryDailyBuckets = exports.readQuotaHistoryRange = exports.appendQuotaHistorySample = exports.writeQuotaSnapshot = exports.readQuotaSnapshot = exports.QuotaPoller = exports.describeQuotaFailure = exports.withQuotaProjections = exports.projectQuotaWindow = exports.fetchQuota = exports.SEVEN_DAY_WINDOW_MS = exports.FIVE_HOUR_WINDOW_MS = exports.AutoSwitchController = exports.decideAutoSwitch = exports.DEFAULT_AUTO_SWITCH_CONFIG = exports.removeLauncher = exports.writeLauncher = exports.isShellHookInstalled = exports.uninstallShellHook = exports.installShellHook = exports.setTerminalActiveProfile = exports.removeCodexAccount = exports.switchToCodexAccount = exports.finalizeCodexAccount = exports.prepareCodexAccount = exports.getCodexExecutionEnv = exports.resolveSidekickCodexHome = exports.resolveActiveCodexAccount = exports.getActiveCodexAccount = exports.listCodexAccounts = exports.getSystemCodexHome = exports.getCodexMonitoringHomes = void 0;
-exports.zaiProviderQuotaStateSchema = exports.codexProviderQuotaStateSchema = exports.claudeProviderQuotaStateSchema = exports.providerQuotaStateSchema = exports.runtimeQuotaProviderSchema = exports.quotaFailureDescriptorSchema = exports.peakHoursStateSchema = exports.codexResetCreditsSnapshotSchema = exports.codexResetCreditSchema = exports.quotaSourceSchema = exports.quotaProviderIdSchema = exports.quotaFailureKindSchema = exports.quotaStateSchema = exports.quotaWindowSchema = exports.extractSessionEvents = exports.permissionModeSchema = exports.sessionEventSchema = exports.sessionMessageSchema = exports.messageUsageSchema = exports.ToolCallTracker = exports.extractToolCalls = exports.extractToolCall = exports.extractErrorMessage = exports.categorizeError = exports.gatherAssetsForCwd = exports.codexSessions = exports.readCodexAssets = exports.claudeSessions = exports.readClaudeAssets = exports.extractCommands = exports.extractFilePaths = exports.extractUrls = exports.extractTokenUsage = exports.LITELLM_CATALOG_URL = exports.normalizeLiteLlmCatalog = exports.hydratePricingCatalog = exports.formatCost = exports.sortModelIds = exports.compareModelIds = exports.getModelDisplayInfo = exports.shortModelName = exports.mergeCostSources = exports.calculateCostWithProvenance = exports.calculateCostWithPricing = exports.calculateCost = exports.getModelInfo = exports.getModelPricing = exports.parseModelId = exports.DEFAULT_CONTEXT_WINDOW = exports.getModelContextWindowSize = void 0;
-exports.scopePeakHoursToSessionProvider = exports.isClaudeCodeSessionProvider = exports.fetchPeakHoursStatus = exports.createPeakHoursNotApplicableState = exports.runDoctor = exports.getSessionDiagnostics = exports.formatHealthReport = exports.fetchOpenAIStatus = exports.fetchProviderStatus = exports.assistantTurnToolRefSchema = exports.assistantTurnToolGroupStepSchema = exports.assistantTurnTimelineItemSchema = exports.assistantTurnSubagentStatusSchema = exports.assistantTurnSubagentSchema = exports.assistantTurnReasoningTimelineItemSchema = exports.assistantTurnProjectionSchema = exports.assistantTurnProcessStepSchema = exports.assistantTurnProcessSchema = exports.assistantTurnNarrationStepSchema = exports.assistantTurnEventTypeSchema = exports.assistantTurnEventSchema = exports.listAllAccountsResultSchema = exports.savedAccountProfileSchema = exports.accountEntrySchema = exports.accountLoginStatusSchema = exports.beginAccountLoginResultSchema = exports.accountManagerResultSchema = exports.accountProviderIdSchema = exports.activeAccountStatusSchema = exports.activeProviderAccountStatusSchema = exports.quotaHistoryDailyBucketSchema = exports.quotaHistorySampleSchema = exports.quotaHistoryRuntimeProviderSchema = exports.providerQuotaMapSchema = void 0;
+exports.runtimeQuotaProviderSchema = exports.quotaFailureDescriptorSchema = exports.peakHoursStateSchema = exports.codexResetCreditsSnapshotSchema = exports.codexResetCreditSchema = exports.quotaSourceSchema = exports.quotaProviderIdSchema = exports.quotaFailureKindSchema = exports.quotaStateSchema = exports.quotaWindowSchema = exports.extractSessionEvents = exports.permissionModeSchema = exports.sessionEventSchema = exports.sessionMessageSchema = exports.messageUsageSchema = exports.ToolCallTracker = exports.extractToolCalls = exports.extractToolCall = exports.extractErrorMessage = exports.categorizeError = exports.gatherAssetsForCwd = exports.codexSessions = exports.readCodexAssets = exports.claudeSessions = exports.readClaudeAssets = exports.extractCommands = exports.extractFilePaths = exports.extractUrls = exports.extractTokenUsage = exports.getObservedContextWindowPath = exports.recordObservedContextWindow = exports.loadObservedContextWindows = exports.LITELLM_CATALOG_URL = exports.normalizeLiteLlmContextWindows = exports.normalizeLiteLlmCatalog = exports.hydratePricingCatalog = exports.formatCost = exports.sortModelIds = exports.compareModelIds = exports.getModelDisplayInfo = exports.shortModelName = exports.mergeCostSources = exports.calculateCostWithProvenance = exports.calculateCostWithPricing = exports.calculateCost = exports.getModelInfo = exports.getModelPricing = exports.parseModelId = exports.DEFAULT_CONTEXT_WINDOW = exports.getModelContextWindowSize = void 0;
+exports.scopePeakHoursToSessionProvider = exports.isClaudeCodeSessionProvider = exports.fetchPeakHoursStatus = exports.createPeakHoursNotApplicableState = exports.runDoctor = exports.getSessionDiagnostics = exports.formatHealthReport = exports.fetchOpenAIStatus = exports.fetchProviderStatus = exports.assistantTurnToolRefSchema = exports.assistantTurnToolGroupStepSchema = exports.assistantTurnTimelineItemSchema = exports.assistantTurnSubagentStatusSchema = exports.assistantTurnSubagentSchema = exports.assistantTurnReasoningTimelineItemSchema = exports.assistantTurnProjectionSchema = exports.assistantTurnProcessStepSchema = exports.assistantTurnProcessSchema = exports.assistantTurnNarrationStepSchema = exports.assistantTurnEventTypeSchema = exports.assistantTurnEventSchema = exports.listAllAccountsResultSchema = exports.savedAccountProfileSchema = exports.accountEntrySchema = exports.accountLoginStatusSchema = exports.beginAccountLoginResultSchema = exports.accountManagerResultSchema = exports.accountProviderIdSchema = exports.activeAccountStatusSchema = exports.activeProviderAccountStatusSchema = exports.quotaHistoryDailyBucketSchema = exports.quotaHistorySampleSchema = exports.quotaHistoryRuntimeProviderSchema = exports.providerQuotaMapSchema = exports.zaiProviderQuotaStateSchema = exports.codexProviderQuotaStateSchema = exports.claudeProviderQuotaStateSchema = exports.providerQuotaStateSchema = void 0;
 var usageNormalization_1 = require("./usageNormalization");
 Object.defineProperty(exports, "normalizeProviderUsage", { enumerable: true, get: function () { return usageNormalization_1.normalizeProviderUsage; } });
 Object.defineProperty(exports, "extractNormalizedUsage", { enumerable: true, get: function () { return usageNormalization_1.extractNormalizedUsage; } });
@@ -397,7 +397,13 @@ Object.defineProperty(exports, "formatCost", { enumerable: true, get: function (
 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; } });
+Object.defineProperty(exports, "normalizeLiteLlmContextWindows", { enumerable: true, get: function () { return pricingCatalog_1.normalizeLiteLlmContextWindows; } });
 Object.defineProperty(exports, "LITELLM_CATALOG_URL", { enumerable: true, get: function () { return pricingCatalog_1.LITELLM_CATALOG_URL; } });
+// Observed context windows (provider-reported, persisted) — Node-only.
+var observedContextWindows_1 = require("./observedContextWindows");
+Object.defineProperty(exports, "loadObservedContextWindows", { enumerable: true, get: function () { return observedContextWindows_1.loadObservedContextWindows; } });
+Object.defineProperty(exports, "recordObservedContextWindow", { enumerable: true, get: function () { return observedContextWindows_1.recordObservedContextWindow; } });
+Object.defineProperty(exports, "getObservedContextWindowPath", { enumerable: true, get: function () { return observedContextWindows_1.getObservedContextWindowPath; } });
 // Extractors — per-event token usage and tool call extraction
 var tokenUsage_1 = require("./extractors/tokenUsage");
 Object.defineProperty(exports, "extractTokenUsage", { enumerable: true, get: function () { return tokenUsage_1.extractTokenUsage; } });

package/dist/modelContext.d.ts

@@ -1,19 +1,66 @@
 /**
  * Centralized model ID → context window size lookup.
  * Single source of truth used by all providers and the CLI dashboard.
+ *
+ * Resolution is layered, most-trusted first:
+ *   1. Runtime-reported — providers that self-report their window (Codex) apply
+ *      it in `getContextWindowLimit`, ahead of this module.
+ *   2. Observed overrides — the last window a provider actually reported for a
+ *      model, persisted across runs by `observedContextWindows.ts`. Reflects the
+ *      effective window for this account/tier, which can be well below the
+ *      model's published maximum.
+ *   3. Catalog overrides — `max_input_tokens` from the LiteLLM catalog, hydrated
+ *      by `pricingCatalog.ts`. Keeps new models correct without a code change.
+ *   4. The static table below — offline baseline of last resort.
+ *
+ * Within that order, match quality comes first: every layer is tried for an
+ * exact hit before any layer is tried for a prefix hit. See
+ * `getModelContextWindowSize`.
+ *
+ * Layers 2 and 3 are pushed in by Node-only modules through the `_set*` hooks,
+ * so this file stays browser-safe (no node:fs, no fetch) and can be bundled for
+ * webviews. Same pattern as `_setPricingOverrides` in `modelInfo.ts`.
  */
 /** Default context window size when model is unknown. */
 export declare const DEFAULT_CONTEXT_WINDOW = 200000;
+/**
+ * Internal: replace the observed-context-window map. Called by
+ * `observedContextWindows.ts` on load and on each newly observed value.
+ * Not part of the stable public API.
+ */
+export declare function _setObservedContextWindows(overrides: Record<string, number>): void;
+/** Internal: snapshot observed overrides (test + diagnostics). */
+export declare function _getObservedContextWindows(): Record<string, number>;
+/** Internal: clear observed overrides (used by tests). */
+export declare function _clearObservedContextWindows(): void;
+/**
+ * Internal: replace the catalog-context-window map. Called by
+ * `pricingCatalog.ts` after a successful LiteLLM hydration.
+ * Not part of the stable public API.
+ */
+export declare function _setCatalogContextWindows(overrides: Record<string, number>): void;
+/** Internal: snapshot catalog overrides (test + diagnostics). */
+export declare function _getCatalogContextWindows(): Record<string, number>;
+/** Internal: clear catalog overrides (used by tests and when disabling hydration). */
+export declare function _clearCatalogContextWindows(): void;
 /**
  * Returns the context window size for a model ID.
  *
  * Input is trimmed and lowercased before lookup, so padded or mixed-case
- * IDs (e.g. "Claude-Opus-4-8 ") resolve without caller-side normalization.
+ * IDs (e.g. "Claude-Opus-5 ") resolve without caller-side normalization.
  *
  * Lookup order:
  * 1. Explicit "[1m]" suffix (Claude Code's 1M-variant marker) → 1_000_000
- * 2. Exact match against MODEL_CONTEXT_SIZES
- * 3. Longest-prefix match (e.g. "claude-opus-4-6-20250414" → "claude-opus-4-6")
+ * 2. Exact match, most-trusted layer first: observed → catalog → static
+ * 3. Longest-prefix match, same layer order
+ *    (e.g. "claude-opus-4-6-20250414" → "claude-opus-4-6")
  * 4. DEFAULT_CONTEXT_WINDOW
+ *
+ * Match quality outranks layer trust: an exact hit in *any* layer beats a
+ * prefix guess in *every* layer. Resolving each layer fully before moving on
+ * would let a catalog key that merely happens to be a prefix shadow a curated
+ * static entry — e.g. the catalog has no "claude-sonnet-4-7", and prefix-first
+ * would hand it "claude-sonnet-4" (128K, a GitHub Copilot deployment) instead
+ * of the static table's exact 1M.
  */
 export declare function getModelContextWindowSize(modelId?: string): number;

package/dist/modelContext.js

@@ -2,17 +2,44 @@
 /**
  * Centralized model ID → context window size lookup.
  * Single source of truth used by all providers and the CLI dashboard.
+ *
+ * Resolution is layered, most-trusted first:
+ *   1. Runtime-reported — providers that self-report their window (Codex) apply
+ *      it in `getContextWindowLimit`, ahead of this module.
+ *   2. Observed overrides — the last window a provider actually reported for a
+ *      model, persisted across runs by `observedContextWindows.ts`. Reflects the
+ *      effective window for this account/tier, which can be well below the
+ *      model's published maximum.
+ *   3. Catalog overrides — `max_input_tokens` from the LiteLLM catalog, hydrated
+ *      by `pricingCatalog.ts`. Keeps new models correct without a code change.
+ *   4. The static table below — offline baseline of last resort.
+ *
+ * Within that order, match quality comes first: every layer is tried for an
+ * exact hit before any layer is tried for a prefix hit. See
+ * `getModelContextWindowSize`.
+ *
+ * Layers 2 and 3 are pushed in by Node-only modules through the `_set*` hooks,
+ * so this file stays browser-safe (no node:fs, no fetch) and can be bundled for
+ * webviews. Same pattern as `_setPricingOverrides` in `modelInfo.ts`.
  */
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.DEFAULT_CONTEXT_WINDOW = void 0;
+exports._setObservedContextWindows = _setObservedContextWindows;
+exports._getObservedContextWindows = _getObservedContextWindows;
+exports._clearObservedContextWindows = _clearObservedContextWindows;
+exports._setCatalogContextWindows = _setCatalogContextWindows;
+exports._getCatalogContextWindows = _getCatalogContextWindows;
+exports._clearCatalogContextWindows = _clearCatalogContextWindows;
 exports.getModelContextWindowSize = getModelContextWindowSize;
 /** Known model context window sizes (in tokens). */
 const MODEL_CONTEXT_SIZES = {
     // Claude — native 1M context (Fable 5, Opus 4.6+, Sonnet 4.6+)
     'claude-fable-5': 1_000_000,
+    'claude-opus-5': 1_000_000,
     'claude-opus-4-8': 1_000_000,
     'claude-opus-4-7': 1_000_000,
     'claude-opus-4-6': 1_000_000,
+    'claude-sonnet-5': 1_000_000,
     'claude-sonnet-4-7': 1_000_000,
     'claude-sonnet-4-6': 1_000_000,
     // Claude 4 family
@@ -30,7 +57,15 @@ const MODEL_CONTEXT_SIZES = {
     // OpenAI GPT-4.1 series (1M context)
     'gpt-4.1': 1_048_576,
     // OpenAI GPT-5 series (keys sorted longest-first below; explicit entries
-    // for every variant so prefix matching can't misclassify a new one)
+    // for every variant so prefix matching can't misclassify a new one).
+    // These are published model maxima. Codex reports a smaller *effective*
+    // window per account tier via token_count; that value wins through the
+    // observed-override layer.
+    'gpt-5.6-sol': 1_050_000,
+    'gpt-5.6-terra': 1_050_000,
+    'gpt-5.6-luna': 1_050_000,
+    'gpt-5.6': 1_050_000,
+    'gpt-5.5': 1_050_000,
     'gpt-5.4': 1_050_000,
     'gpt-5.3-codex-spark': 128_000,
     'gpt-5.3-codex': 400_000,
@@ -49,20 +84,100 @@ const MODEL_CONTEXT_SIZES = {
     deepseek: 128_000,
 };
 /** Prefix keys sorted longest-first for correct prefix matching. */
-const SORTED_KEYS = Object.keys(MODEL_CONTEXT_SIZES).sort((a, b) => b.length - a.length);
+const SORTED_KEYS = sortKeysLongestFirst(MODEL_CONTEXT_SIZES);
 /** Default context window size when model is unknown. */
 exports.DEFAULT_CONTEXT_WINDOW = 200_000;
+// ── Override Tables (populated at runtime by Node-only modules) ──
+let observedTable = {};
+let observedSortedKeys = [];
+let catalogTable = {};
+let catalogSortedKeys = [];
+function sortKeysLongestFirst(table) {
+    return Object.keys(table).sort((a, b) => b.length - a.length);
+}
+/**
+ * Lowercase keys so lookups match regardless of how the source spelled them.
+ * The LiteLLM catalog publishes some IDs mixed-case; the static table and the
+ * lookup path are both lowercase. Drops non-positive and non-finite values.
+ */
+function normalizeOverrides(overrides) {
+    const out = {};
+    for (const [key, value] of Object.entries(overrides)) {
+        if (!Number.isFinite(value) || value <= 0)
+            continue;
+        out[key.trim().toLowerCase()] = value;
+    }
+    return out;
+}
+/**
+ * Internal: replace the observed-context-window map. Called by
+ * `observedContextWindows.ts` on load and on each newly observed value.
+ * Not part of the stable public API.
+ */
+function _setObservedContextWindows(overrides) {
+    observedTable = normalizeOverrides(overrides);
+    observedSortedKeys = sortKeysLongestFirst(observedTable);
+}
+/** Internal: snapshot observed overrides (test + diagnostics). */
+function _getObservedContextWindows() {
+    return { ...observedTable };
+}
+/** Internal: clear observed overrides (used by tests). */
+function _clearObservedContextWindows() {
+    observedTable = {};
+    observedSortedKeys = [];
+}
+/**
+ * Internal: replace the catalog-context-window map. Called by
+ * `pricingCatalog.ts` after a successful LiteLLM hydration.
+ * Not part of the stable public API.
+ */
+function _setCatalogContextWindows(overrides) {
+    catalogTable = normalizeOverrides(overrides);
+    catalogSortedKeys = sortKeysLongestFirst(catalogTable);
+}
+/** Internal: snapshot catalog overrides (test + diagnostics). */
+function _getCatalogContextWindows() {
+    return { ...catalogTable };
+}
+/** Internal: clear catalog overrides (used by tests and when disabling hydration). */
+function _clearCatalogContextWindows() {
+    catalogTable = {};
+    catalogSortedKeys = [];
+}
+// ── Lookup ──
+/** Exact match against one table. */
+function exactWindow(table, modelId) {
+    const hit = table[modelId];
+    return hit === undefined ? null : hit;
+}
+/** Longest-prefix match against one table. */
+function prefixWindow(table, sortedKeys, modelId) {
+    for (const key of sortedKeys) {
+        if (modelId.startsWith(key))
+            return table[key];
+    }
+    return null;
+}
 /**
  * Returns the context window size for a model ID.
  *
  * Input is trimmed and lowercased before lookup, so padded or mixed-case
- * IDs (e.g. "Claude-Opus-4-8 ") resolve without caller-side normalization.
+ * IDs (e.g. "Claude-Opus-5 ") resolve without caller-side normalization.
  *
  * Lookup order:
  * 1. Explicit "[1m]" suffix (Claude Code's 1M-variant marker) → 1_000_000
- * 2. Exact match against MODEL_CONTEXT_SIZES
- * 3. Longest-prefix match (e.g. "claude-opus-4-6-20250414" → "claude-opus-4-6")
+ * 2. Exact match, most-trusted layer first: observed → catalog → static
+ * 3. Longest-prefix match, same layer order
+ *    (e.g. "claude-opus-4-6-20250414" → "claude-opus-4-6")
  * 4. DEFAULT_CONTEXT_WINDOW
+ *
+ * Match quality outranks layer trust: an exact hit in *any* layer beats a
+ * prefix guess in *every* layer. Resolving each layer fully before moving on
+ * would let a catalog key that merely happens to be a prefix shadow a curated
+ * static entry — e.g. the catalog has no "claude-sonnet-4-7", and prefix-first
+ * would hand it "claude-sonnet-4" (128K, a GitHub Copilot deployment) instead
+ * of the static table's exact 1M.
  */
 function getModelContextWindowSize(modelId) {
     if (!modelId)
@@ -72,21 +187,24 @@ function getModelContextWindowSize(modelId) {
     if (/\[1m\]/i.test(modelId))
         return 1_000_000;
     // Strip the suffix if present, so the normal lookup still succeeds when
-    // a caller passes e.g. "claude-opus-4-7[1m]" and we've already handled it.
+    // a caller passes e.g. "claude-opus-5[1m]" and we've already handled it.
     // Trim/lowercase so padded or mixed-case IDs match the lowercase table keys.
     const normalized = modelId
         .replace(/\[1m\]/gi, '')
         .trim()
         .toLowerCase();
-    // Exact match
-    if (MODEL_CONTEXT_SIZES[normalized] !== undefined) {
-        return MODEL_CONTEXT_SIZES[normalized];
-    }
-    // Longest-prefix match
-    for (const key of SORTED_KEYS) {
-        if (normalized.startsWith(key)) {
-            return MODEL_CONTEXT_SIZES[key];
-        }
-    }
+    // Pass 1 — exact matches, most-trusted layer first.
+    const exact = exactWindow(observedTable, normalized) ??
+        exactWindow(catalogTable, normalized) ??
+        exactWindow(MODEL_CONTEXT_SIZES, normalized);
+    if (exact !== null)
+        return exact;
+    // Pass 2 — longest-prefix matches, same layer order. Resolves versioned IDs
+    // that no layer spells out, e.g. "claude-opus-4-6-20250414".
+    const prefix = prefixWindow(observedTable, observedSortedKeys, normalized) ??
+        prefixWindow(catalogTable, catalogSortedKeys, normalized) ??
+        prefixWindow(MODEL_CONTEXT_SIZES, SORTED_KEYS, normalized);
+    if (prefix !== null)
+        return prefix;
     return exports.DEFAULT_CONTEXT_WINDOW;
 }

package/dist/modelInfo.js

@@ -76,6 +76,17 @@ const PRICING_TABLE = {
         cacheWriteCostPerMillion: 1.0,
         cacheReadCostPerMillion: 0.08,
     },
+    // Sonnet 5 carries the standard rate here. The introductory $2/$10 (through
+    // 2026-08-31) arrives via catalog hydration, which supersedes this baseline.
+    // Sonnet 5 is $2/$10, not the $3/$15 every earlier Sonnet charged, and it
+    // carries no >200K surcharge the way Sonnet 4.5 does. The catalog agrees
+    // across all eleven of its Sonnet 5 entries.
+    'claude-sonnet-5': {
+        inputCostPerMillion: 2.0,
+        outputCostPerMillion: 10.0,
+        cacheWriteCostPerMillion: 2.5,
+        cacheReadCostPerMillion: 0.2,
+    },
     'claude-sonnet-4-6': {
         inputCostPerMillion: 3.0,
         outputCostPerMillion: 15.0,
@@ -106,6 +117,12 @@ const PRICING_TABLE = {
         cacheWriteCostPerMillion: 3.75,
         cacheReadCostPerMillion: 0.3,
     },
+    'claude-opus-5': {
+        inputCostPerMillion: 5.0,
+        outputCostPerMillion: 25.0,
+        cacheWriteCostPerMillion: 6.25,
+        cacheReadCostPerMillion: 0.5,
+    },
     'claude-opus-4-8': {
         inputCostPerMillion: 5.0,
         outputCostPerMillion: 25.0,
@@ -162,6 +179,21 @@ const PRICING_TABLE = {
         cacheReadCostPerMillion: 1.5,
     },
     // ── OpenAI: GPT-4.x family ──
+    // The `-tts`, `-transcribe`, and `-realtime-preview` variants also bill above
+    // the key they inherit, but no coding agent routes to them, so they are left
+    // out rather than carried here. Catalog hydration still prices them correctly.
+    'gpt-4.1-mini': {
+        inputCostPerMillion: 0.4,
+        outputCostPerMillion: 1.6,
+        cacheWriteCostPerMillion: 0,
+        cacheReadCostPerMillion: 0.1,
+    },
+    'gpt-4.1-nano': {
+        inputCostPerMillion: 0.1,
+        outputCostPerMillion: 0.4,
+        cacheWriteCostPerMillion: 0,
+        cacheReadCostPerMillion: 0.025,
+    },
     'gpt-4.1': {
         inputCostPerMillion: 2.0,
         outputCostPerMillion: 8.0,
@@ -174,6 +206,14 @@ const PRICING_TABLE = {
         cacheWriteCostPerMillion: 0,
         cacheReadCostPerMillion: 0.075,
     },
+    // The launch snapshot kept its original $5/$15 when gpt-4o was cut to
+    // $2.50/$10, so a pinned id must not read the current rate.
+    'gpt-4o-2024-05-13': {
+        inputCostPerMillion: 5.0,
+        outputCostPerMillion: 15.0,
+        cacheWriteCostPerMillion: 0,
+        cacheReadCostPerMillion: 0,
+    },
     'gpt-4o': {
         inputCostPerMillion: 2.5,
         outputCostPerMillion: 10.0,
@@ -186,27 +226,132 @@ const PRICING_TABLE = {
         cacheWriteCostPerMillion: 0,
         cacheReadCostPerMillion: 0,
     },
-    // ── OpenAI: GPT-5 family (baseline estimate; LiteLLM catalog overrides) ──
-    // Codex emits `gpt-5.4`, `gpt-5.3-codex`, `gpt-5`. Anchoring the static
-    // estimate to gpt-4o-tier rates so offline users see a reasonable ballpark.
+    // ── OpenAI: GPT-5 family ──
+    // Published rates, verified against the LiteLLM catalog. Runtime hydration
+    // still supersedes these; they are the offline baseline.
+    //
+    // Every tier that ships at a rate of its own needs an entry of its own. Keys
+    // are matched longest-first, so a `-mini`/`-nano`/`-pro` variant with no entry
+    // silently inherits its base model's rate and reports a wrong number rather
+    // than none — `gpt-5-nano` read 25x its true cost this way.
+    'gpt-5.6-sol': {
+        inputCostPerMillion: 5.0,
+        outputCostPerMillion: 30.0,
+        cacheWriteCostPerMillion: 6.25,
+        cacheReadCostPerMillion: 0.5,
+    },
+    'gpt-5.6-terra': {
+        inputCostPerMillion: 2.5,
+        outputCostPerMillion: 15.0,
+        cacheWriteCostPerMillion: 3.13,
+        cacheReadCostPerMillion: 0.25,
+    },
+    'gpt-5.6-luna': {
+        inputCostPerMillion: 1.0,
+        outputCostPerMillion: 6.0,
+        cacheWriteCostPerMillion: 1.25,
+        cacheReadCostPerMillion: 0.1,
+    },
+    'gpt-5.6': {
+        inputCostPerMillion: 5.0,
+        outputCostPerMillion: 30.0,
+        cacheWriteCostPerMillion: 6.25,
+        cacheReadCostPerMillion: 0.5,
+    },
+    'gpt-5.5-pro': {
+        inputCostPerMillion: 30.0,
+        outputCostPerMillion: 180.0,
+        cacheWriteCostPerMillion: 0,
+        cacheReadCostPerMillion: 3.0,
+    },
+    'gpt-5.5': {
+        inputCostPerMillion: 5.0,
+        outputCostPerMillion: 30.0,
+        cacheWriteCostPerMillion: 0,
+        cacheReadCostPerMillion: 0.5,
+    },
+    'gpt-5.4-mini': {
+        inputCostPerMillion: 0.75,
+        outputCostPerMillion: 4.5,
+        cacheWriteCostPerMillion: 0,
+        cacheReadCostPerMillion: 0.07,
+    },
+    'gpt-5.4-nano': {
+        inputCostPerMillion: 0.2,
+        outputCostPerMillion: 1.25,
+        cacheWriteCostPerMillion: 0,
+        cacheReadCostPerMillion: 0.02,
+    },
+    'gpt-5.4-pro': {
+        inputCostPerMillion: 30.0,
+        outputCostPerMillion: 180.0,
+        cacheWriteCostPerMillion: 0,
+        cacheReadCostPerMillion: 3.0,
+    },
     'gpt-5.4': {
-        inputCostPerMillion: 1.25,
-        outputCostPerMillion: 10.0,
+        inputCostPerMillion: 2.5,
+        outputCostPerMillion: 15.0,
         cacheWriteCostPerMillion: 0,
-        cacheReadCostPerMillion: 0.125,
+        cacheReadCostPerMillion: 0.25,
     },
     'gpt-5.3-codex': {
-        inputCostPerMillion: 1.25,
-        outputCostPerMillion: 10.0,
+        inputCostPerMillion: 1.75,
+        outputCostPerMillion: 14.0,
         cacheWriteCostPerMillion: 0,
-        cacheReadCostPerMillion: 0.125,
+        cacheReadCostPerMillion: 0.175,
+    },
+    'gpt-5.3-chat-latest': {
+        inputCostPerMillion: 1.75,
+        outputCostPerMillion: 14.0,
+        cacheWriteCostPerMillion: 0,
+        cacheReadCostPerMillion: 0.175,
     },
+    // No bare `gpt-5.3` ships in the catalog; both real variants above are
+    // $1.75/$14. This entry stays an estimate and only answers ids that match
+    // neither variant.
     'gpt-5.3': {
         inputCostPerMillion: 1.25,
         outputCostPerMillion: 10.0,
         cacheWriteCostPerMillion: 0,
         cacheReadCostPerMillion: 0.125,
     },
+    'gpt-5.2-pro': {
+        inputCostPerMillion: 21.0,
+        outputCostPerMillion: 168.0,
+        cacheWriteCostPerMillion: 0,
+        cacheReadCostPerMillion: 0,
+    },
+    // Also answers `gpt-5.2-codex` and `gpt-5.2-chat*`, which bill at this rate.
+    'gpt-5.2': {
+        inputCostPerMillion: 1.75,
+        outputCostPerMillion: 14.0,
+        cacheWriteCostPerMillion: 0,
+        cacheReadCostPerMillion: 0.175,
+    },
+    'gpt-5.1-codex-mini': {
+        inputCostPerMillion: 0.25,
+        outputCostPerMillion: 2.0,
+        cacheWriteCostPerMillion: 0,
+        cacheReadCostPerMillion: 0.025,
+    },
+    'gpt-5-pro': {
+        inputCostPerMillion: 15.0,
+        outputCostPerMillion: 120.0,
+        cacheWriteCostPerMillion: 0,
+        cacheReadCostPerMillion: 0,
+    },
+    'gpt-5-mini': {
+        inputCostPerMillion: 0.25,
+        outputCostPerMillion: 2.0,
+        cacheWriteCostPerMillion: 0,
+        cacheReadCostPerMillion: 0.025,
+    },
+    'gpt-5-nano': {
+        inputCostPerMillion: 0.05,
+        outputCostPerMillion: 0.4,
+        cacheWriteCostPerMillion: 0,
+        cacheReadCostPerMillion: 0.005,
+    },
     'gpt-5': {
         inputCostPerMillion: 1.25,
         outputCostPerMillion: 10.0,
@@ -214,23 +359,46 @@ const PRICING_TABLE = {
         cacheReadCostPerMillion: 0.125,
     },
     // ── OpenAI: o-series (reasoning models) ──
+    // The `-pro` and deep-research tiers cost an order of magnitude more than the
+    // base model whose key they would otherwise match.
+    'o3-deep-research': {
+        inputCostPerMillion: 10.0,
+        outputCostPerMillion: 40.0,
+        cacheWriteCostPerMillion: 0,
+        cacheReadCostPerMillion: 2.5,
+    },
     'o3-mini': {
         inputCostPerMillion: 1.1,
         outputCostPerMillion: 4.4,
         cacheWriteCostPerMillion: 0,
         cacheReadCostPerMillion: 0.55,
     },
+    'o3-pro': {
+        inputCostPerMillion: 20.0,
+        outputCostPerMillion: 80.0,
+        cacheWriteCostPerMillion: 0,
+        cacheReadCostPerMillion: 0,
+    },
     o3: {
         inputCostPerMillion: 2.0,
         outputCostPerMillion: 8.0,
         cacheWriteCostPerMillion: 0,
         cacheReadCostPerMillion: 0.5,
     },
+    // OpenAI cut o1-mini to $1.10/$4.40 after launch; $3/$12 was the launch rate.
+    // No bare catalog key settles it — Azure's $1.21/$4.84 is its usual 1.1x
+    // uplift on exactly this number, and Replicate's OpenAI passthrough agrees.
     'o1-mini': {
-        inputCostPerMillion: 3.0,
-        outputCostPerMillion: 12.0,
+        inputCostPerMillion: 1.1,
+        outputCostPerMillion: 4.4,
         cacheWriteCostPerMillion: 0,
-        cacheReadCostPerMillion: 1.5,
+        cacheReadCostPerMillion: 0.55,
+    },
+    'o1-pro': {
+        inputCostPerMillion: 150.0,
+        outputCostPerMillion: 600.0,
+        cacheWriteCostPerMillion: 0,
+        cacheReadCostPerMillion: 0,
     },
     o1: {
         inputCostPerMillion: 15.0,

package/dist/node.d.ts

@@ -5,8 +5,10 @@
  * and `node:path`; safe for extension-host and CLI consumers. Not safe
  * for browser bundles — use `sidekick-shared/browser` there.
  */
-export { hydratePricingCatalog, normalizeLiteLlmCatalog, LITELLM_CATALOG_URL, } from './pricingCatalog';
+export { hydratePricingCatalog, normalizeLiteLlmCatalog, normalizeLiteLlmContextWindows, LITELLM_CATALOG_URL, } from './pricingCatalog';
 export type { HydrateOptions, HydrateResult } from './pricingCatalog';
+export { loadObservedContextWindows, recordObservedContextWindow, getObservedContextWindowPath, } from './observedContextWindows';
+export type { ObservedContextWindowOptions, ObservedContextWindowStore, } from './observedContextWindows';
 export { listRecentSessions, readSessionTranscript } from './sessionTranscripts';
 export type { ProviderSessionIndex, ListRecentSessionsOptions } from './sessionTranscripts';
 export { ObservedSessionCollector, observedSessionSourceFromProvider, fileFingerprint, } from './observedSessionCollector';

package/dist/node.js

@@ -7,11 +7,16 @@
  * for browser bundles — use `sidekick-shared/browser` there.
  */
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.fileFingerprint = exports.observedSessionSourceFromProvider = exports.ObservedSessionCollector = exports.readSessionTranscript = exports.listRecentSessions = exports.LITELLM_CATALOG_URL = exports.normalizeLiteLlmCatalog = exports.hydratePricingCatalog = void 0;
+exports.fileFingerprint = exports.observedSessionSourceFromProvider = exports.ObservedSessionCollector = exports.readSessionTranscript = exports.listRecentSessions = exports.getObservedContextWindowPath = exports.recordObservedContextWindow = exports.loadObservedContextWindows = exports.LITELLM_CATALOG_URL = exports.normalizeLiteLlmContextWindows = exports.normalizeLiteLlmCatalog = exports.hydratePricingCatalog = 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; } });
+Object.defineProperty(exports, "normalizeLiteLlmContextWindows", { enumerable: true, get: function () { return pricingCatalog_1.normalizeLiteLlmContextWindows; } });
 Object.defineProperty(exports, "LITELLM_CATALOG_URL", { enumerable: true, get: function () { return pricingCatalog_1.LITELLM_CATALOG_URL; } });
+var observedContextWindows_1 = require("./observedContextWindows");
+Object.defineProperty(exports, "loadObservedContextWindows", { enumerable: true, get: function () { return observedContextWindows_1.loadObservedContextWindows; } });
+Object.defineProperty(exports, "recordObservedContextWindow", { enumerable: true, get: function () { return observedContextWindows_1.recordObservedContextWindow; } });
+Object.defineProperty(exports, "getObservedContextWindowPath", { enumerable: true, get: function () { return observedContextWindows_1.getObservedContextWindowPath; } });
 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; } });

package/dist/observedContextWindows.d.ts

@@ -0,0 +1,54 @@
+/**
+ * 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`.
+ *
+ * @module observedContextWindows
+ */
+export interface ObservedContextWindowOptions {
+    /** Directory for the store (defaults to the Sidekick config dir). */
+    cacheDir?: string;
+    /** Optional logger (useful for diagnostics without pulling a logger dep). */
+    logger?: (msg: string) => void;
+}
+export interface ObservedContextWindowEntry {
+    contextWindow: number;
+    /** ISO timestamp of the most recent observation. */
+    observedAt: string;
+}
+export interface ObservedContextWindowStore {
+    version: 1;
+    models: Record<string, ObservedContextWindowEntry>;
+}
+/** Resolve the on-disk store path. */
+export declare function getObservedContextWindowPath(cacheDir?: string): string;
+/**
+ * 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 declare function loadObservedContextWindows(options?: ObservedContextWindowOptions): Promise<Record<string, number>>;
+/**
+ * Record a provider-reported context window for a model.
+ *
+ * Applies in memory immediately, then persists — but only when the value
+ * actually changed. 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.
+ */
+export declare function recordObservedContextWindow(modelId: string, contextWindow: number, options?: ObservedContextWindowOptions): Promise<void>;

package/dist/observedContextWindows.js

@@ -0,0 +1,150 @@
+"use strict";
+/**
+ * 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`.
+ *
+ * @module observedContextWindows
+ */
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.getObservedContextWindowPath = getObservedContextWindowPath;
+exports.loadObservedContextWindows = loadObservedContextWindows;
+exports.recordObservedContextWindow = recordObservedContextWindow;
+const node_fs_1 = require("node:fs");
+const path = __importStar(require("node:path"));
+const modelContext_1 = require("./modelContext");
+const paths_1 = require("./paths");
+const atomic_1 = require("./writers/atomic");
+// ── Constants ──
+const STORE_FILE_NAME = 'observed-context-windows.json';
+const STORE_VERSION = 1;
+/** Resolve the on-disk store path. */
+function getObservedContextWindowPath(cacheDir) {
+    return path.join(cacheDir ?? (0, paths_1.getConfigDir)(), STORE_FILE_NAME);
+}
+function emptyStore() {
+    return { version: STORE_VERSION, models: {} };
+}
+/** Keep only well-formed entries; a hand-edited or partly-corrupt file shouldn't poison lookups. */
+function toOverrideMap(store) {
+    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;
+        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.
+ */
+async function loadObservedContextWindows(options = {}) {
+    const storePath = getObservedContextWindowPath(options.cacheDir);
+    try {
+        const raw = await node_fs_1.promises.readFile(storePath, 'utf8');
+        const parsed = JSON.parse(raw);
+        if (!parsed || typeof parsed !== 'object' || !parsed.models)
+            return {};
+        const overrides = toOverrideMap(parsed);
+        (0, modelContext_1._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. 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.
+ */
+async function recordObservedContextWindow(modelId, contextWindow, options = {}) {
+    const normalizedId = modelId?.trim().toLowerCase();
+    if (!normalizedId)
+        return;
+    if (!Number.isFinite(contextWindow) || contextWindow <= 0)
+        return;
+    const current = (0, modelContext_1._getObservedContextWindows)();
+    if (current[normalizedId] === contextWindow)
+        return;
+    (0, modelContext_1._setObservedContextWindows)({ ...current, [normalizedId]: contextWindow });
+    const storePath = getObservedContextWindowPath(options.cacheDir);
+    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 (0, atomic_1.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() },
+                },
+            };
+        });
+    }
+    catch (err) {
+        options.logger?.(`observedContextWindows: failed to persist ${storePath}: ${String(err)}`);
+    }
+}

package/dist/pricingCatalog.d.ts

@@ -36,6 +36,8 @@ export interface HydrateResult {
     source: 'cache' | 'network' | 'offline';
     /** Number of pricing entries applied to the override map. */
     entries: number;
+    /** Number of context-window entries applied to the override map. */
+    contextWindowEntries: number;
     /** ISO timestamp of the fetch that produced the cache. */
     fetchedAt: string;
 }
@@ -56,3 +58,13 @@ export declare function hydratePricingCatalog(options: HydrateOptions): Promise<
  * Exported for tests; rarely called directly.
  */
 export declare function normalizeLiteLlmCatalog(raw: unknown): Record<string, ModelPricing>;
+/**
+ * Convert a LiteLLM catalog payload to a model → context-window override map.
+ *
+ * Kept separate from `normalizeLiteLlmCatalog` rather than folded into its
+ * return type: that function is public API on a published package, and pricing
+ * and context coverage differ (an entry can have one without the other).
+ *
+ * Exported for tests; rarely called directly.
+ */
+export declare function normalizeLiteLlmContextWindows(raw: unknown): Record<string, number>;

package/dist/pricingCatalog.js

@@ -54,8 +54,10 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.LITELLM_CATALOG_URL = void 0;
 exports.hydratePricingCatalog = hydratePricingCatalog;
 exports.normalizeLiteLlmCatalog = normalizeLiteLlmCatalog;
+exports.normalizeLiteLlmContextWindows = normalizeLiteLlmContextWindows;
 const node_fs_1 = require("node:fs");
 const path = __importStar(require("node:path"));
+const modelContext_1 = require("./modelContext");
 const modelInfo_1 = require("./modelInfo");
 // ── Constants ──
 exports.LITELLM_CATALOG_URL = 'https://raw.githubusercontent.com/BerriAI/litellm/main/model_prices_and_context_window.json';
@@ -80,43 +82,51 @@ async function hydratePricingCatalog(options) {
     // 1. Fresh cache?
     const cached = await readCache(cachePath);
     if (cached && now - Date.parse(cached.fetchedAt) < ttlMs) {
-        (0, modelInfo_1._setPricingOverrides)(cached.overrides);
-        return {
-            source: 'cache',
-            entries: Object.keys(cached.overrides).length,
-            fetchedAt: cached.fetchedAt,
-        };
+        return applyCacheFile(cached, 'cache');
     }
     // 2. Try network.
     if (fetchImpl) {
         const fetched = await fetchCatalog(url, fetchImpl, timeoutMs, logger);
         if (fetched) {
-            const overrides = normalizeLiteLlmCatalog(fetched);
             const payload = {
                 fetchedAt: new Date(now).toISOString(),
                 url,
-                overrides,
+                overrides: normalizeLiteLlmCatalog(fetched),
+                contextWindows: normalizeLiteLlmContextWindows(fetched),
             };
             await writeCache(cachePath, payload, logger);
-            (0, modelInfo_1._setPricingOverrides)(overrides);
-            return {
-                source: 'network',
-                entries: Object.keys(overrides).length,
-                fetchedAt: payload.fetchedAt,
-            };
+            return applyCacheFile(payload, 'network');
         }
     }
     // 3. Fall back to stale cache if present.
     if (cached) {
-        (0, modelInfo_1._setPricingOverrides)(cached.overrides);
-        return {
-            source: 'cache',
-            entries: Object.keys(cached.overrides).length,
-            fetchedAt: cached.fetchedAt,
-        };
+        return applyCacheFile(cached, 'cache');
     }
-    // 4. Nothing we can do — stay on static table.
-    return { source: 'offline', entries: 0, fetchedAt: new Date(now).toISOString() };
+    // 4. Nothing we can do — stay on static tables.
+    return {
+        source: 'offline',
+        entries: 0,
+        contextWindowEntries: 0,
+        fetchedAt: new Date(now).toISOString(),
+    };
+}
+/**
+ * Push a cache payload into both override maps and describe what was applied.
+ * `contextWindows` is absent on caches written before context hydration; those
+ * contribute no overrides rather than clearing whatever is already loaded.
+ */
+function applyCacheFile(cache, source) {
+    const contextWindows = cache.contextWindows ?? {};
+    (0, modelInfo_1._setPricingOverrides)(cache.overrides);
+    if (Object.keys(contextWindows).length > 0) {
+        (0, modelContext_1._setCatalogContextWindows)(contextWindows);
+    }
+    return {
+        source,
+        entries: Object.keys(cache.overrides).length,
+        contextWindowEntries: Object.keys(contextWindows).length,
+        fetchedAt: cache.fetchedAt,
+    };
 }
 /**
  * Convert a LiteLLM catalog payload to our `ModelPricing` override map.
@@ -145,6 +155,57 @@ function normalizeLiteLlmCatalog(raw) {
     }
     return out;
 }
+/**
+ * Convert a LiteLLM catalog payload to a model → context-window override map.
+ *
+ * Kept separate from `normalizeLiteLlmCatalog` rather than folded into its
+ * return type: that function is public API on a published package, and pricing
+ * and context coverage differ (an entry can have one without the other).
+ *
+ * Exported for tests; rarely called directly.
+ */
+function normalizeLiteLlmContextWindows(raw) {
+    const out = {};
+    if (!raw || typeof raw !== 'object')
+        return out;
+    // Bare-model aliases are gathered separately rather than written as we go. A
+    // `provider/model` entry describes that *provider's deployment* window, which
+    // is often a truncation of the model's own — the live catalog carries five
+    // different windows for `claude-sonnet-4`, from GitHub Copilot's 128K to
+    // Vertex's 1M. Taking whichever appeared first in the JSON is a coin flip, so
+    // an alias is only promoted when every provider mentioning it agrees.
+    const aliasWindows = new Map();
+    for (const [key, entry] of Object.entries(raw)) {
+        // LiteLLM ships a `sample_spec` header entry. Skip it.
+        if (key === 'sample_spec')
+            continue;
+        if (!entry || typeof entry !== 'object')
+            continue;
+        const window = entry.max_input_tokens;
+        if (typeof window !== 'number' || !Number.isFinite(window) || window <= 0)
+            continue;
+        out[key] = window;
+        const bare = stripProviderPrefix(key);
+        if (bare && bare !== key) {
+            const seen = aliasWindows.get(bare) ?? new Set();
+            seen.add(window);
+            aliasWindows.set(bare, seen);
+        }
+    }
+    for (const [bare, windows] of aliasWindows) {
+        // A top-level entry for the same ID is authoritative — never shadow it.
+        if (out[bare] !== undefined)
+            continue;
+        // Providers disagree, so none of their numbers can be attributed to the
+        // bare model. Record nothing and let a more trusted layer answer.
+        if (windows.size !== 1)
+            continue;
+        const [only] = windows;
+        if (typeof only === 'number')
+            out[bare] = only;
+    }
+    return out;
+}
 // ── Internals ──
 function liteLlmEntryToPricing(entry) {
     const input = entry.input_cost_per_token;

package/dist/providers/codex.js

@@ -53,6 +53,7 @@ const codexParser_1 = require("../parsers/codexParser");
 const codexDatabase_1 = require("./codexDatabase");
 const codexProfiles_1 = require("../codexProfiles");
 const modelContext_1 = require("../modelContext");
+const observedContextWindows_1 = require("../observedContextWindows");
 const usageNormalization_1 = require("../usageNormalization");
 // ---------------------------------------------------------------------------
 // Helper functions
@@ -510,10 +511,12 @@ class CodexReader {
                     // Skip malformed JSON lines
                 }
             }
-            // Propagate model_context_window from token_count events to the provider
+            // Propagate model_context_window from token_count events to the provider.
+            // The model comes along so the value can be persisted per model — the
+            // window Codex reports is tier-specific, not the published maximum.
             const mcw = this.parser.getModelContextWindow();
             if (mcw && this.onContextWindowLimit) {
-                this.onContextWindowLimit(mcw);
+                this.onContextWindowLimit(mcw, this.parser.getCurrentModel() ?? undefined);
             }
             // Propagate rate_limits from token_count events to the provider
             const rateLimits = this.parser.getLastRateLimits();
@@ -791,8 +794,15 @@ class CodexProvider {
     }
     // --- Data reading ---
     createReader(sessionPath) {
-        return new CodexReader(sessionPath, (limit) => {
+        return new CodexReader(sessionPath, (limit, modelId) => {
             this.dynamicContextWindowLimit = limit;
+            if (modelId) {
+                // Fire-and-forget: persist so historical/static views keep this
+                // tier-specific window instead of falling back to the catalog maximum.
+                void (0, observedContextWindows_1.recordObservedContextWindow)(modelId, limit).catch(() => {
+                    /* non-fatal; the in-memory limit above still applies */
+                });
+            }
         }, (limits) => {
             this.lastRateLimitsData = limits;
         }, (usage) => {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "sidekick-shared",
-  "version": "0.24.1",
+  "version": "0.24.3",
   "description": "Shared data access layer for Sidekick — readers, types, providers, credentials, quota",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",