feat(quota-chip): add Settings toggle, flip default to off

[nesquena-hermes]

feat(quota-chip): add Settings toggle, flip default to off

Direct follow-up to the v0.51.78 stage-371 release that shipped the ambient provider quota chip (@ai-ag2026's #2082, hardened with the @media (max-width:1399.98px) clutter gate). Adds a Settings → Preferences checkbox to opt into the chip, with default off.

Why this is a follow-up not a rework

The chip itself is well-built — fetch path, rendering, tab-visibility refresh, and the wide-desktop @media gate all work as designed. The only piece missing was user agency: even on wide desktops where the chip fits cleanly, a user who doesn't want an always-on quota indicator in their composer couldn't turn it off without inspecting devtools.

This PR adds the per-user opt-in. The default flips from "visible whenever you're on wide desktop with quota data" to "hidden everywhere unless you explicitly enable it in Settings."

Wiring

• api/config.py — "show_quota_chip": False in _SETTINGS_DEFAULTS, added to _SETTINGS_BOOL_KEYS (auto-flows into _SETTINGS_ALLOWED_KEYS)
• static/boot.js — window._showQuotaChip initialized from settings, default-false on fetch-failure
• static/panels.js — payload + body + _applySavedSettingsUi propagation, live refresh on toggle change
• static/ui.js — renderProviderQuotaIndicator and refreshProviderQuotaIndicator both short-circuit when disabled. Refresh skips the /api/provider/quota fetch entirely, so the chip-disabled state has zero runtime cost.
• static/index.html — new Settings field after "Show token usage", with description text explaining the wide-display gate ("Default off. Only visible on wide displays (≥1400px) when enabled, to keep the composer uncluttered on laptop and standard desktop widths.")
• static/i18n.js — settings_label_quota_chip + settings_desc_quota_chip in 11 locales

Tests

tests/test_quota_chip_settings_toggle.py — 6 regression cases pin:

• Settings field present (id, data-i18n labels)
• show_quota_chip default-False in _SETTINGS_DEFAULTS and _SETTINGS_BOOL_KEYS
• renderProviderQuotaIndicator early-hides BEFORE the existing text-computation path
• refreshProviderQuotaIndicator short-circuits BEFORE the fetch
• Boot initializes window._showQuotaChip from settings, defaults to false on settings-fetch failure
• panels.js full round-trip (payload, body, load, save, live-refresh)
• All 11 locale strings present

5790 tests pass on this branch (up from 5784 on master after stage-371 merged).

UX evidence

Self-verified at 1920×1080 (wide desktop) before opening this PR:

• Default state: composer footer clean, no green chip (was visible by default before this PR)
• Settings panel: new checkbox below "Show token usage", unchecked by default, description text fully readable
• Toggled checkbox ON, then re-rendered: chip "OpenRouter $2.40" appears in the composer footer between model picker and reasoning chip, as designed
• 1280/1440 viewports already hidden via existing @media (max-width:1399.98px) rule — no additional viewport work needed

[nesquena-hermes]

Ready for independent review (self-built PR, nesquena APPROVED required before merge). 161 LOC additive across the standard settings-round-trip wiring + 6 regression tests + 11 locale strings. UX self-verified at 1920×1080 (default-hidden state, Settings checkbox unchecked, post-toggle chip appearance). 1280/1440 viewports are already hidden via the existing stage-371 @media rule and don't need re-screenshot — composer at those widths is unchanged from current master.

CI green expected — pytest passed 5790 / 0-failed locally.

Once approved + CI green, this is eligible to batch with #2406 / #2407 / #2408 (Michaelyklam's three queued contributor PRs once their independent reviews land) into stage-372 — or ship as its own single-PR release lane, whichever lands its review first.

[nesquena]

Review — end-to-end ✅ (clean APPROVE, no fix pushed)

What this ships

161-line follow-up to the v0.51.78 stage-371 release that shipped the ambient quota chip (@ai-ag2026's #2082). Adds a Settings → Preferences opt-in toggle and flips the default from on-when-wide to off everywhere. Net effect for existing users: the chip disappears until they explicitly turn it on.

Touches: api/config.py (+2), static/boot.js (+2), static/i18n.js (+22 in 11 locales), static/index.html (+7), static/panels.js (+20/-3), static/ui.js (+16), tests/test_quota_chip_settings_toggle.py (+92 new, 6 tests). CI green on 3.11/3.12/3.13.

Traced against upstream hermes-agent

Pulled a fresh tarball. No cross-tool surface — show_quota_chip lives in webui-internal _SETTINGS_DEFAULTS at api/config.py:4022 (not in config.yaml). The CLI doesn't read this preference. /api/provider/quota is also webui-only.

End-to-end trace

Server settings layer

• api/config.py:4022 — "show_quota_chip": False added to _SETTINGS_DEFAULTS.
• api/config.py:4156 — "show_quota_chip" added to _SETTINGS_BOOL_KEYS, which auto-flows into _SETTINGS_ALLOWED_KEYS (the writable allow-list). Round-trip safe.

Boot path

• static/boot.js:1390 — window._showQuotaChip = s.show_quota_chip === true (strict). Settings load success path.
• static/boot.js:1456 — window._showQuotaChip = false in the settings-fetch-failed defaults block. Safe-fail.
• static/boot.js:1532 — refreshProviderQuotaIndicator() called at boot. With default off, the function short-circuits to a no-op (no fetch).

Render short-circuit at static/ui.js:675-687

function renderProviderQuotaIndicator(status){
  const chip = $('providerQuotaChip');
  const label = $('providerQuotaChipLabel');
  if(!chip||!label) return;
  if(window._showQuotaChip !== true){
    chip.hidden = true;
    label.textContent = '';
    chip.removeAttribute('title');
    return;
  }
  // ... existing render logic
}

Guard runs before _providerQuotaIndicatorText(status) is computed. Test pins this ordering via line-index comparison.

Refresh short-circuit at static/ui.js:699-707

async function refreshProviderQuotaIndicator(){
  if(window._showQuotaChip !== true){
    const chip = $('providerQuotaChip');
    if(chip){ chip.hidden=true; chip.removeAttribute('title'); }
    return;
  }
  // ... existing in-flight guard + fetch
}

Skips the /api/provider/quota fetch entirely when disabled — chip-off users have zero runtime cost. The visibility-change listener at static/ui.js:719 also flows through this gated entry point.

Settings panel round-trip

• Load: static/panels.js:5500-5510 — checkbox initialized from settings.show_quota_chip === true. Change listener updates window._showQuotaChip AND calls refreshProviderQuotaIndicator() for live refresh (no reload required).
• Save payload (autosave): static/panels.js:5258-5259 — payload.show_quota_chip = showQuotaChipCb.checked.
• Save body (explicit save): static/panels.js:6376, 6395 — body.show_quota_chip = showQuotaChip === true.
• _applySavedSettingsUi at static/panels.js:6278-6281 — window._showQuotaChip = showQuotaChip === true propagated post-save.

HTML field

• static/index.html:1024-1030 — new <div class="settings-field"> placed AFTER "Show token usage" (a sibling boolean toggle), BEFORE "Show TPS". Visual grouping with related display-toggles is sensible.

i18n

• settings_label_quota_chip + settings_desc_quota_chip in 11 locales. Description copy explicitly mentions the wide-display gate ("Only visible on wide displays (≥1400px) when enabled") so users understand the relationship to the @media rule.

Other audit — things that are correct already

Security

• No HTML insertion of user data. The checkbox value is a boolean round-tripped through /api/settings. The render+refresh helpers only call DOM attribute setters (textContent, title, hidden).
• Settings allow-list (_SETTINGS_ALLOWED_KEYS via _SETTINGS_BOOL_KEYS) is the canonical write boundary; this PR correctly extends both.

Type-strict gates

• All four checks use === true (strict equality). Defends against 'true' string, 1, truthy objects, etc. — useful when localStorage or stale body.show_quota_chip could leak a non-boolean.

Zero-cost when disabled

• refreshProviderQuotaIndicator early-returns BEFORE the in-flight flag and BEFORE the network call. Disabled users never make /api/provider/quota requests, never burn server quota-probe semaphores (#2030's _account_usage_probe_semaphore).

Default-safe failure paths

• Settings fetch fails in boot.js? window._showQuotaChip = false in the catch block.
• Property missing entirely from /api/settings response? s.show_quota_chip === true returns false for undefined.
• Settings fetch succeeds but show_quota_chip is 'true' (string)? Strict equality fails → false. Defensive.

Visibility-change re-fire

• The visibilitychange listener at static/ui.js:719 fires refreshProviderQuotaIndicator() when tab becomes visible. With chip disabled, this is a cheap no-op (early-return on _showQuotaChip !== true).

No conflict with #2082's existing chip behavior

• The original chip rendering, fetch path, and @media (max-width:1399.98px) clutter gate are all preserved. This PR adds a guard upstream of all of them.

Behavioural harness (Node)

Case 1: default off — render with status, no fetch         ✓ chip stays hidden
Case 2: default off — refresh skips fetch                  ✓ fetchCount=0
Case 3: enabled — render shows chip                        ✓ label="P 50%"
Case 4: enabled — refresh fires fetch                      ✓ fetchCount=1
Case 5: stringy truthy non-boolean — strict === rejects    ✓ chip hidden
Case 6: toggle off mid-stream — refresh hides immediately  ✓ second refresh no-op

6/6 cases verify the gate behavior, ordering, strict-equality defense, and toggle-off responsiveness.

Edge-case trace

Scenario	Expected	Actual
Fresh install, default off	chip hidden, no fetch	✅ harness
User toggles on in Settings	live refresh, chip appears	✅ harness + listener
User toggles off mid-session	next refresh hides + skips fetch	✅ harness
Settings fetch fails on boot	_showQuotaChip = false	✅ test + diff line 1456
Localstorage stale 'true' (string)	rejected by strict ===	✅ harness
visibilitychange fires while disabled	cheap no-op	✅ gated entry point
Save+reload round-trip	state persists	✅ allow-list + boot read
Cross-tool: CLI reads same config.yaml	unaffected (webui-only setting)	✅
@1399.98px viewport, enabled	hidden by @media gate	✅ pre-existing CSS
≥1400px viewport, enabled, no quota data	hidden by inner render branch	✅ pre-existing logic

Tests

• PR-targeted: 6/6 pass (tests/test_quota_chip_settings_toggle.py).
• Full suite (Python 3.14, local): 5669 passed, 63 skipped, 3 xpassed, 0 failed (ignoring test_docker_env_readonly_vars.py macOS bash 3.2 baseline + test_ctl_script.py).
• CI: 3.11/3.12/3.13 all green.
• Behavioural harness: 6/6 gate scenarios verified.

Minor observations (non-blocking)

1. Default flip is a UX regression for early adopters of #2082. Anyone who liked the ambient chip from v0.51.78 will see it disappear on update. The Settings field is discoverable via Preferences but won't be obvious unless they specifically look for it. CHANGELOG copy (not in this PR's diff) will need to call this out — "default behavior changed, opt in via Settings → Preferences." Not a blocker; matches the Telegram directive.
2. Settings field placement. Placed between "Show token usage" and "Show TPS" — sensible grouping with other display toggles. If/when more chip-style toggles arrive, consider a <section>-level grouping ("Composer chrome" / "Status indicators") to scale. Pre-existing layout pattern; not in scope.
3. _applySavedSettingsUi signature growth. The opts object now has 11 keys (sendKey, showTokenUsage, showQuotaChip, showTps, fadeTextEffect, showCliSessions, theme, skin, language, sidebarDensity, fontSize). At some point this should be a destructured object passed by reference rather than enumerated. Pre-existing pattern; not in this PR's scope.
4. No regression test for the visibility-change listener. The 6 new tests cover render + refresh + boot + panels + i18n + config. The visibilitychange flow is tested transitively because it calls refreshProviderQuotaIndicator() which IS tested. Acceptable; pre-existing #2082 didn't cover it either.

Recommendation

Approved. Clean opt-in toggle with proper zero-cost short-circuiting when disabled. Strict equality defense, 6 regression tests, behavioural harness confirms all gate transitions. Default flip honors the maintainer's directive while preserving the chip's value for users who explicitly opt in.

✅ Parked at approval — ready for the release agent's merge/tag pipeline.

[nesquena-hermes]

Shipped via stage-372 / PR #2414 / v0.51.79 (Release BC). Attribution preserved in the squashed stage commit and the v0.51.79 CHANGELOG entry. Thank you!