Skip to content

agentop: Polish the TUI look with no change to behavior #2015

Open

Description

@huang195

Problem

The agentop TUI shows the right information, but it looks flat. Most of the screen is one color. You cannot see at a glance which columns are ids and which are money, or which rows failed. The key hints are bracket text that is hard to scan.

Goal

Polish the look of every agentop pane. Change only color, weight and frame glyphs. Do not change what agentop does or what it shows.

The reference mockup is /tmp/agentop-mock.y0Jq/polished.html on the author's machine (made from real captured screens). The text and the column positions in it are not changed. It shows each pane at 140 columns: Agents, Sessions, Events, Detail, Timeline, Usage, Pipeline, the $ spend drawer and the ? help. Earlier mockups (mockup.html, panes.html) are not the reference: their tab bar, breadcrumbs and status chips with a background are out of scope. Where this text and the mockup differ, this text wins.

Non-goals

  • No new information on the screen. No breadcrumb, no context percent, no live dots, no summary lines, no counter labels.
  • No new keys, panes, columns, flags, config fields or preferences.
  • No change to row counts, to layout reservations (layout()), or to which hint survives a narrow terminal.
  • No tab bar.
  • No migration to Bubble Tea v2 or Lip Gloss v2.

Hard rules (these make sure nothing that works now breaks)

  1. The plain text does not change. Under the Ascii color profile (what go test gets, because tests have no TTY), every pane renders byte-identical text to main. With a color profile, the stripped text (ansi.Strip) is identical except for two things:
    • Each key hint [k] on a hint line becomes the chip k (same width).
    • The selected table row's first column (a blank pad now) becomes ▌.
  2. Existing tests stay as they are. Do not edit an assertion in an existing test, with one exception: a test that forces a color profile, and checks a [k] hint or the first column of the selected row, may change to the new text. Every other existing test must pass with no edit. If one fails, the change is wrong. Two color tests depend on how renderRow splits a row into runs, so keep that split: rowLook in search_test.go finds the cursor row by the SGR prefix of Selected.Render("x"), so the fill after a cell's text on the cursor row stays one run in Selected alone. TestSetSearch_TheCursorRowKeepsItsStyleAfterAHighlight (table/search_test.go) needs the text and the fill as one run when no cell style applies. With a nil cell-style hook, a zero Alt and a zero Bar, the table output is byte-identical to main.
  3. Widths do not change. lipgloss.Width of every rendered line is the same as on main. Never cut or pad a styled string with a function that counts escape bytes (runewidth.Truncate, runewidth.FillRight, len). Style after those steps. A cut that understands ANSI (truncToWidth, ansi.Truncate, lipgloss.Width) may run after styling, as footer.go (fitStatusLine) and detail_pane.go (the REQUEST │ line) do today. Keep those lines in their current order, and let the width test prove them.
  4. Table cells keep no ANSI. TestSessionsRows_CarryNoANSIUnderAForcedColourProfile stays. Rows hold plain text. All per-cell color is added inside tui/table after the cell is cut to width (see "Table styling").
  5. Search highlighting keeps working. A search match (Styles.Match, Styles.CurrentMatch) is drawn over the cell color. A marked row (Styles.Marked) keeps its warn ink over the column ink. The selected row keeps its background tint (colorSelectedBg) and bold, and the column inks show through.
  6. Gauges keep their meaning. A cell style can set only foreground and bold. It must never set Reverse or Background (read the tableStyles comment in styles.go).
  7. Both themes. Each new color is a lipgloss.AdaptiveColor with a Light and a Dark value, in styles.go, next to the existing palette.
  8. Monochrome stays as it is. Under the Ascii profile, key hints keep their brackets, and the selected row has no ▌ (rule 1). The selected row has no visible mark under Ascii today (termenv drops bold there too), and this change does not alter that.
  9. No slower rendering. Build the new styles once, as package-level values. New code must not call lipgloss.NewStyle() for each cell (the existing calls in renderRow and headersView may stay). Under Ascii, termenv skips all styling, so the existing benchmarks cannot see the color path. Add a TrueColor variant of BenchmarkRebuildEventsTable (events_rebuild_bench_test.go) and a new benchmark of table.Model.View() for a full events page, under both Ascii and TrueColor. Run them on main and on the branch. A regression of more than 10% on any of them blocks the PR.

Palette additions (tui/styles.go)

Name Light Dark Use
colorDim #9CA3AF #4B5563 dividers, separators ·, —, ~, +, feedback URL
colorZebraBg #F3F4F6 #15151C background of every second table row
colorChipBg #E5E7EB #374151 key chip background
colorChipFg #111827 #F3F4F6 key chip text
colorTool #B45309 #F59E0B agent tool rows (┗⚒, ┣⚒)

Keep colorAccent, colorOK, colorWarn, colorError, colorMuted, colorInbound, colorOutbound and colorSelectedBg as they are. Add styleDim, styleBold, styleChip and styleSeg (the accent background with colorOnSeries ink, bold: a selected option) from them.

Table styling (tui/table)

The vendored table is ours (see its package doc). Add:

  • A cell style hook. Add WithCellStyle(func(row Row, col int) lipgloss.Style), or the same as a Model field set by the pane. renderRow calls it for each drawn cell. It gets the full row, so the hook can see a tool row by cell 0. renderRow applies the result to the cut text (texts[i]), not to the padding. Order of precedence, from low to high: cell style, then row style (Selected adds background and bold; Marked replaces the ink), then the match styles. A nil hook means "no cell style", which is the behavior of today.
  • Zebra rows. Add Styles.Alt. Rows with an odd index (r%2 == 1) that are not the cursor row and not marked get it as their row background. Section rows (one cell) follow the same rule.
  • Selection bar. Add Styles.Bar (tui sets it to colorAccent ink; table cannot import tui). On the cursor row, when the color profile is not Ascii and Bar is not zero, draw the first cell's left pad column as ▌ in Bar, on the selected background. The width stays the same.
  • Header. tableStyles() changes Header from accent bold to muted bold.

Tests for the table: precedence (cell under row under match), zebra on odd rows only, the bar only with color and only on the cursor row, the same lipgloss.Width with and without styles, and no change in output when the hook is nil.

What each pane gets

Per-cell styles are keyed by column identity, not by the header text. Header text changes at run time: Sessions declares SAVED and alignSessionsHeaders shows SAVED~ (sessions_pane.go:141), Agents shows "COST "+window (agents_pane.go:282), and Events adds ▲/▼ to a sorted column (events_columns.go:486). Use the Events column ids (colDuration and the others), and for the other tables the column order that the pane declares. The styles must follow the column picker and hidden columns. A cell whose text is — is always styleDim.

Pane (file) Column styles
Sessions (sessions_pane.go) SESSION, AGENT, SERVER, UPDATED muted. COST bold. SAVED~ ok. CTX(1M): brackets ▕ ▏ dim, filled blocks accent. TITLE, EVENTS, TOKENS default
Agents (agents_pane.go) ▸/▾ accent. Top-level agent names bold. LAST SEEN, SERVER muted. COST TODAY bold
Events (events_pane.go, events_columns.go) # and TIME muted. DIR: out in colorOutbound, in in colorInbound. ACTION: modify accent, deny and other refusals error, tunnel dim, the others muted. STATUS: 2xx and ok ok, 4xx and running warn, 5xx, lost and errors error. BYTES muted with ↑/↓ dim. HOST muted. Tool rows: ┗⚒/┣⚒, the tool name and the ⋯ mark in colorTool. The status of a tool row follows the STATUS rule. Subagent block rows (▸─ …) in accent
Pipeline (pipeline_pane.go) # muted. DIRECTION in the inbound or outbound color. PLUGIN bold. DEPS ✓ ok. BODY muted. ── (app) ── dim
Catalog, Namespaces, Pods Name column bold. Other columns muted

The real ACTION and STATUS value sets are in the code. Map each value that the code can produce to one of these color groups, and add a test that lists them.

Chrome

  • Title line (each styleTitle.Render(title) in paneView and the pickers): a renderTitle(title string) string helper. agentop is accent bold. · is dim. A URL and a (uuid) are muted. The rest is bold default ink. Text unchanged.
  • Spend band (spend_band.go, renderSpendBandStyled): labels stay muted. Amounts become bold. ~, +, — and · dim. Bobcoins amounts in warn. ALL SESSIONS muted. Keep the plain and styled line widths equal (spend_band_test.go checks this).
  • Divider (renderDivider callers): styleDim, not styleMuted.
  • Status line (footerView): unchanged, except that the feedback text is styleDim.
  • Hint lines: a renderHints(fitted string) string helper, called after fitHintLine. With color, each [x] (no space inside) becomes styleChip.Render(" x "), and the rest is muted. Under Ascii, it returns styleHint.Render(fitted), which is today's output. Use it for the footer hint line, the help overlay's closing line, the timeline's ▸ [←→] … line, and the hint lines of the server picker, the column picker and the clear dialog.
  • Spend drawer (spend_drawer.go): the WHERE IT WENT and BY MODEL headings muted bold. Bars accent. Percents muted. Amounts bold. saved … ok. Parenthesized notes dim. On the controls line, the selected axis ([model]) is styleSeg, and the keys ([a], [w], [$]) are chips.
  • Overlays (styleBorder: help, clear, server picker, column picker, events side panel): the border becomes accent. In the help overlay, keep renderKeyGroup's current emphasis (help_overlay.go:590): the current pane's group has an accent-bold heading and green keys, and the other groups stay muted. That emphasis is information, so it stays.
  • Detail (detail_pane.go): the word REQUEST / RESPONSE is styleSeg, and the │ after it is dim. In the rest of that line (m.detailSummary, one plain string today), · is dim, the status follows the STATUS rule, and the cost is bold. Build the styled summary from its parts, or style the plain string with a text-preserving helper. Either way, keep the truncToWidth cut after it. The section line ▾ ━━ REQUEST · … is accent bold. Keep the existing JSON colorizer (json_colorize.go) as it is. Fold marks ▾/▸ are accent.
  • Timeline (timeline_pane.go): keep the state colors. Axis labels (axisLabels), the right-hand figures and the legend text are muted. The │ before the figures and the separator rule are dim.
  • Usage (usage_render.go, usage_pane.go): in the USAGE — … — … line, USAGE is accent bold and — dim. Bars accent, unless a breakdown gives them series colors (keep those). Axis numbers and ticks muted. In the totals line, the labels are muted and the values bold. updated … ago is dim.

Tests to add

  • Plain-text invariant for each pane and helper: render under TrueColor, then ansi.Strip it. The result equals the Ascii render after the two allowed changes (chips and the bar). Run it at 80, 100 and 140 columns.
  • Width invariant: lipgloss.Width of each line is the same under Ascii and TrueColor.
  • The table tests from "Table styling".
  • renderHints: chips under color, brackets under Ascii, the same width, and no chip for a bracket that holds a space.
  • The ACTION/STATUS color-group lists.

Verification

  1. go vet ./... and gofmt -l . in cmd/agentop.
  2. scripts/dev/go-test-shards.sh -short cmd/agentop while you work. Before the PR, scripts/dev/go-test-shards.sh -race cmd/agentop and, from cmd/agentop, go test -race $(go list ./... | grep -v 'agentop$').
  3. The benchmarks in rule 9, before and after.
  4. A live check: build agentop, drive it with expect against the local proxy at 140×30 and at 80×24 on each pane, and check each line's width and the column positions against main. Do not run make dev-install or restart the service.

Size

About 1,500 changed lines with tests. That is less than 2,000, so it is one PR.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

Labels

No labels
No labels

Type

No type

Projects

Milestone

No milestone

Relationships

None yet

Development

No branches or pull requests

Issue actions