Skip to content

feat(tui): add warning/compacting states to the context-usage gauge#3537

Merged
dgageot merged 1 commit into
mainfrom
feat/context-gauge-warning-states
Jul 8, 2026
Merged

feat(tui): add warning/compacting states to the context-usage gauge#3537
dgageot merged 1 commit into
mainfrom
feat/context-gauge-warning-states

Conversation

@Sayt-0

@Sayt-0 Sayt-0 commented Jul 8, 2026

Copy link
Copy Markdown
Member

Closes #3434

The always-on context gauge escalates its color (normal, warning, critical) as usage approaches the agent's configured compaction threshold, and reads "compacting..." while a compaction runs. Applies to both the main TUI sidebar and the lean TUI status line.

Issue expectations mapping

Expectation Implemented by
Color the gauge as it nears the compaction threshold styles.ContextGaugeLevelFor(fill, threshold): warning at 75% of the threshold, critical at 95%; applied to the sidebar (N%), the per-agent roster percentages, and the lean TUI bar
Color against the configurable threshold (#3433) runtime.Usage carries compaction_threshold, populated from agent.CompactionThreshold() at every TokenUsageEvent emit site
"compacting..." state driven by SessionCompactionEvent sidebar compacting flag toggled by the started/completed pair; lean TUI StatusModel.Compacting
Both main TUI sidebar and lean TUI status line pkg/tui/components/sidebar/sidebar.go, pkg/leantui/ui/status.go

Flow

runtime loop
  SessionUsage(sess, contextLimit, a.CompactionThreshold())
    -> TokenUsageEvent.Usage.compaction_threshold
         -> sidebar: warning/error style on "(N%)" and roster percentages
         -> leantui: RenderBar(pct, threshold) color escalation

doCompact
  SessionCompaction(started) ........ SessionCompactionCompleted(outcome)
    -> sidebar: "(compacting...)" replaces the percent, spinner stays active
    -> leantui: "compacting..." replaces the percent, token counts stay visible

Behavior details

  • Escalation bands are relative to the threshold (0.75x and 0.95x of it), so a custom compaction_threshold keeps a proportional visual runway; thresholds outside (0, 1] fall back to compaction.DefaultThreshold, mirroring compaction.ShouldCompact.
  • The lean TUI bar previously used hardcoded 0.6/0.85 breakpoints; at the default threshold the new bands land nearby (0.675/0.855).
  • Usage.CompactionThreshold is 0 (omitted from JSON) when unknown, so events from older servers keep working; consumers fall back to the default.
  • ESC cancel clears the sidebar compacting state; the lean TUI clears it on conversation reset.
  • SessionUsage gains an optional variadic threshold parameter, following the AgentInfo(..., contextLimit ...int64) backward-compatibility precedent in the same file.

Tests

Area Coverage
pkg/tui/styles classification table: default and custom thresholds, boundary values, out-of-range fallback
sidebar level escalation, configured threshold honored, per-agent levels, compacting indicator lifecycle, ESC cancel cleanup
leantui event-driven compacting state, threshold propagation, render output with and without context limit, bar width invariants
runtime SessionUsage carries the optional threshold

Validation: build, golangci-lint plus repo lint cops, go mod tidy --diff clean, full test suite green in touched packages (remaining repo failures are pre-existing sandbox network SSRF-guard tests, verified on a pristine checkout).

The always-on context gauge now escalates its color (normal -> warning ->
critical) as usage approaches the agent's configured compaction threshold,
and reads "compacting..." while a compaction runs, in both the main TUI
sidebar and the lean TUI status line.

TokenUsageEvent's Usage carries the agent's compaction_threshold so gauges
color against the configured value rather than hardcoded percentages; the
shared classification lives in pkg/tui/styles.

Closes #3434
@Sayt-0
Sayt-0 requested a review from a team as a code owner July 8, 2026 13:46
@Sayt-0 Sayt-0 added area/tui For features/issues/fixes related to the TUI kind/feat PR adds a new feature (maps to feat:). Use on PRs only. area/runtime Runtime engine, agent loop execution, tool dispatch, loop detection labels Jul 8, 2026
@dgageot
dgageot merged commit b5e27fa into main Jul 8, 2026
14 checks passed
@dgageot
dgageot deleted the feat/context-gauge-warning-states branch July 8, 2026 14:14
pull Bot pushed a commit to TheTechOddBug/cagent that referenced this pull request Jul 9, 2026
Piyush0049 pushed a commit to Piyush0049/docker-agent that referenced this pull request Jul 15, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

area/runtime Runtime engine, agent loop execution, tool dispatch, loop detection area/tui For features/issues/fixes related to the TUI kind/feat PR adds a new feature (maps to feat:). Use on PRs only.

Projects

None yet

Development

Successfully merging this pull request may close these issues.

feat(tui): add warning/compacting states to the context-usage gauge

2 participants