PR #67569: fix(ui): populate context-window cache from gateway model catalog

• Repository: openclaw/openclaw
• Author: moorsecopers99
• State: open | merged: False
• Link: https://github.com/openclaw/openclaw/pull/67569

Description (problem / solution / changelog)

Summary

• Problem: The context window usage meter in the Control UI always shows 0% for Anthropic/Claude models, even though session_status correctly reports real usage (e.g. "Context: 81k/200k (41%)").
• Why it matters: Users cannot gauge how much context they have remaining in their sessions, defeating the purpose of the meter.
• What changed: (1) loadGatewayModelCatalog now feeds discovered contextWindow values into MODEL_CONTEXT_TOKEN_CACHE (both bare and provider-qualified keys) so subsequent synchronous lookups succeed. (2) Session row builders pass fallbackContextTokens: DEFAULT_CONTEXT_TOKENS as a safety net before the first catalog load.
• What did NOT change (scope boundary): No changes to the context-window cache module itself, model discovery, SKIP_EAGER_WARMUP_PRIMARY_COMMANDS, transcript storage, or the UI rendering logic. The meter already works correctly given a non-null contextTokens value.

Change Type (select all)

• Bug fix
• Feature
• Refactor required for the fix
• Docs
• Security hardening
• Chore/infra

Scope (select all touched areas)

• Gateway / orchestration
• Skills / tool execution
• Auth / tokens
• Memory / storage
• Integrations
• API / contracts
• UI / DX
• CI/CD / infra

Linked Issue/PR

• Closes #67530
• This PR fixes a bug or regression

Root Cause (if applicable)

• Root cause: The gateway process is in SKIP_EAGER_WARMUP_PRIMARY_COMMANDS (context.ts:136), so ensureContextWindowCacheLoaded() never runs at import time. The session listing calls resolveContextTokensForModel with allowAsyncLoad: false, which only runs primeConfiguredContextWindows() — loading from config, not from model discovery. Anthropic/Claude models have no explicit contextWindow in config (their values come from model discovery only), so the cache lookup returns undefined and the UI meter shows 0%.
• Missing detection / guardrail: No test verified that the gateway's synchronous session-listing path could resolve context windows for discovery-only models.
• Contributing context: session_status works because status.summary.runtime.ts has its own resolveContextTokensForModel that falls back to DEFAULT_CONTEXT_TOKENS (200k). Google/Gemini models work because they have explicit contextWindow values in config. The asymmetry between config-backed and discovery-backed models was the gap.

Regression Test Plan (if applicable)

• Coverage level that should have caught this:
  • Unit test
  • Seam / integration test
  • End-to-end test
  • Existing coverage already sufficient
• Target test or file: src/gateway/server-model-catalog.test.ts
• Scenario the test should lock in: After loadGatewayModelCatalog completes, MODEL_CONTEXT_TOKEN_CACHE contains both bare (claude-sonnet-4-6) and provider-qualified (anthropic/claude-sonnet-4-6) keys with correct context window values. Models without contextWindow are excluded.
• Why this is the smallest reliable guardrail: Tests the exact cache-population side-effect that was missing, without requiring a full gateway integration test.
• Existing test that already covers this (if any): None — added 1 new test file.

User-visible / Behavior Changes

• The context window percentage meter now shows correct values for Anthropic/Claude models (e.g. 41% for 81k/200k) instead of 0%.

Diagram (if applicable)

Before:
[sessions.list] -> resolveContextTokensForModel(allowAsyncLoad: false)
                -> primeConfiguredContextWindows() (config only)
                -> lookupCachedContextTokens("claude-sonnet-4-6") -> undefined
                -> UI meter: 0%

After (path 1 — catalog already loaded):
[loadGatewayModelCatalog] -> applyDiscoveredContextWindows(cache, catalog)
                          -> cache["claude-sonnet-4-6"] = 200_000
[sessions.list] -> resolveContextTokensForModel(allowAsyncLoad: false)
                -> lookupCachedContextTokens("claude-sonnet-4-6") -> 200_000
                -> UI meter: 41%

After (path 2 — catalog not yet loaded):
[sessions.list] -> resolveContextTokensForModel(allowAsyncLoad: false, fallback: 200_000)
                -> lookupCachedContextTokens("claude-sonnet-4-6") -> undefined
                -> fallbackContextTokens -> 200_000
                -> UI meter: 41%

Security Impact (required)

• New permissions/capabilities? No
• Secrets/tokens handling changed? No
• New/changed network calls? No
• Command/tool execution surface changed? No
• Data access scope changed? No

Repro + Verification

Environment

• OS: macOS / Linux
• Runtime/container: Node 22+
• Model/provider: anthropic/claude-sonnet-4-6
• Integration/channel: Control UI webchat

Steps

1. Configure OpenClaw with an Anthropic Claude model (no explicit contextWindow in config)
2. Have an active session with significant context usage
3. Observe the context percentage meter in the Control UI

Expected

• Meter shows correct percentage (e.g. 41% for 81k/200k)

Actual

• Meter shows 0%

Evidence

• Failing test/log before + passing after

$ pnpm test src/gateway/server-model-catalog.test.ts
 Test Files  1 passed (1)
      Tests  1 passed (1)

$ pnpm test src/gateway/server.sessions.gateway-server-sessions-a.test.ts
 Test Files  1 passed (1)
      Tests  51 passed (51)

$ pnpm check
... (tsgo, oxlint, import-cycles, madge-import-cycles all green)

Human Verification (required)

• Verified scenarios: New test confirms cache population with bare + qualified keys. Existing gateway session tests (51) pass. Full lint/type/cycle checks clean.
• Edge cases checked: Models without contextWindow excluded from cache. Fallback covers pre-catalog-load timing window. Provider-qualified keys handle the resolveContextTokensForModel qualified-key lookup path.
• What you did not verify: Live browser testing with a real Anthropic session — the synchronous cache path is tested at unit level.

Review Conversations

• I replied to or resolved every bot review conversation I addressed in this PR.
• I left unresolved only the conversations that still need reviewer or maintainer judgment.

Compatibility / Migration

• Backward compatible? Yes
• Config/env changes? No
• Migration needed? No

Risks and Mitigations

• Risk: DEFAULT_CONTEXT_TOKENS (200k) fallback is Anthropic-centric and may be incorrect for models with smaller windows.
  • Mitigation: The fallback only fires before the first loadGatewayModelCatalog call, which happens during chat.history (early in session load). After that, the cache has per-model values. This matches the existing behavior in getSessionDefaults (line 951) which uses the same fallback.
• Risk: applyDiscoveredContextWindows uses conservative (min) merge — a stale smaller value could persist.
  • Mitigation: The gateway model catalog is the canonical source and is loaded once per process. Config overrides are applied after discovery (via applyConfiguredContextWindows in the existing warm path), so explicit config always wins.

Changed files

• src/gateway/server-model-catalog.test.ts (added, +43/-0)
• src/gateway/server-model-catalog.ts (modified, +23/-1)
• src/gateway/session-utils.ts (modified, +7/-0)