📏 fix: Keep the Context Gauge's Used Count Above Its Own Breakdown

[danny-avila]

Summary

The context gauge can report fewer used tokens than the system prompt it lists, and its breakdown then drops the Messages row entirely.

On the snapshot path, useTokenUsage computes used tokens as contextBudget − remainingContextTokens (plus finalized output and retained tool results). Breakdown.tsx then derives the message share by subtraction:

const messageBudget = Math.max(0, usedTokens - instructionTokens - summaryTokens);

When a snapshot's remainingContextTokens was measured against a smaller instruction total than the effectiveInstructionTokens it publishes, usedTokens falls below instructionTokens. The clamp floors the share at 0, and a legend row renders only for a positive value, so Messages disappears. The percent and the "Free space" figure are understated by the same amount.

#16301 made this visible in e2e: with no saved memories, the memory instruction block now reaches the system prompt on a first turn (~57 tokens), while the fake model's first call reports 2 input tokens. context usage gauge › renders the granular breakdown from the live context snapshot and › preserves the granular breakdown after switching branches fail at the Messages assertion. Upstream CI skips e2e on these PRs, so a downstream fork running e2e on every PR caught it.

It is not only a test artifact. Applying the gauge's arithmetic to the last 400 persisted snapshots on a live deployment, 23 (about 6%) would hide the Messages row, for example effectiveInstructionTokens 12,887 with contextBudget − remainingContextTokens of 10,726. Every underflowing snapshot sampled had breakdown.messageTokens: 0.

The fix keeps the remaining-based count, which covers content the breakdown omits, but never lets it undercut the parts the snapshot itself reports:

const breakdownUsed = instructionTokens + normalizeTokenCount(breakdown.messageTokens);
const baseUsed =
  remainingContextTokens != null
    ? Math.max(maxTokens - remainingContextTokens, breakdownUsed)
    : breakdownUsed;

The legacy branch (no remainingContextTokens) is unchanged. The runway projection keeps its own measurement basis and is untouched.

The inconsistency itself originates in the @librechat/agents snapshot, where the published remaining and instruction counts can disagree; that is tracked separately in the SDK. This change makes the client robust to it.

Type of change

• Bug fix

Testing

Automated tests:

• useTokenUsage.spec.tsx:
  • an inconsistent snapshot (57 instruction + 2 message tokens, remaining measured as 2 used) reports 64 used with 5 output tokens, not 7
  • a remaining-based count larger than the breakdown is kept (195,000 pre-invoke + 2,000 output = 197,000)
• useTokenUsage.spec.tsx + TokenUsage suites: 46 passing; npm run typecheck in client clean

Screenshots / recordings

Before, the failing e2e popover: Context window 7 / 21.5K, Tool calls 0, System prompt 57, Free space 21.5K, no Messages row.

Risk / compatibility

Client-only. Used tokens can only rise, and only when the snapshot is internally inconsistent; consistent snapshots render exactly as before.

Checklist

• I reviewed my own changes
• Relevant tests have been added or updated
• Existing relevant tests pass
• The change does not introduce new warnings or errors
• User-facing or complex behavior is documented where necessary
• Required dependency changes have been merged/published
• Required documentation PR: N/A

[danny-avila]

@codex review

[chatgpt-codex-connector]

Codex Review Summary

This comment shows the latest Codex review activity on this pull request.

Review	Status	Commit	Review trigger
📝 Code Review	✅ Completed 2026-09-25T17:51:38.934466Z	0b341e1	Manual request

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review" or "@codex security review".

Codex reacts with 👀 while any review is running, comments if it has suggestions, and reacts with 👍 once all reviews finish with no findings.

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 0b341e11e3

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

[chatgpt-codex-connector]

Include summary tokens in the breakdown floor

When an inconsistent snapshot also represents a summarized turn, breakdown.summaryTokens is a separate part of the prompt, but this new floor only sums instructions and messages. If the remaining-based count is below instructionTokens + summaryTokens + messageTokens, usedTokens therefore still undercuts its own breakdown; Breakdown.tsx subsequently subtracts both instructions and the summary, which can again hide or understate the Messages row and make the displayed segments exceed the reported total. Include the normalized summary count in breakdownUsed, and cover this case with a nonzero-summary snapshot.

Useful? React with 👍 / 👎.