📏 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 separately reported instructions, summary, and messages:

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

Legacy snapshots without remainingContextTokens use the same three-bucket sum. Breakdown-based branch-history readings include the summary as well, so the restored gauge and runway share one basis. Remaining-based runway growth still uses the backend's raw remaining reading.

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: inconsistent snapshots with and without a summary, legacy live and restored snapshots, and a summarized snapshot whose larger remaining-based total stays unchanged.
• tokens.spec.ts: legacy branch-history readings include the summary.
• useTokenUsage.spec.tsx, tokens.spec.ts, and Breakdown.spec.tsx: 115 passing; npx tsc --noEmit 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. Remaining-based used tokens rise only when they undercut the reported three-bucket breakdown. Legacy snapshots with a nonzero summary now include that previously omitted bucket. Consistent remaining-based snapshots render exactly as before; stored formats are unchanged.

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-27T12:46:05.996804Z	44d8777	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".

[danny-avila]

@codex review the latest head

[chatgpt-codex-connector]

Codex Review: Didn't find any major issues. 🎉

Reviewed commit: 44d877717b

ℹ️ 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".