From 31d0770a53422a559aceae71d49f227b16986ecc Mon Sep 17 00:00:00 2001 From: Hai Huang Date: Thu, 19 Nov 2026 17:08:59 -0500 Subject: [PATCH 1/8] docs: Add the agentop key grammar design Assisted-By: Claude (Anthropic AI) Signed-off-by: Hai Huang --- .../2026-11-19-agentop-key-grammar-design.md | 81 +++++++++++++++++++ 1 file changed, 81 insertions(+) create mode 100644 docs/superpowers/specs/2026-11-19-agentop-key-grammar-design.md diff --git a/docs/superpowers/specs/2026-11-19-agentop-key-grammar-design.md b/docs/superpowers/specs/2026-11-19-agentop-key-grammar-design.md new file mode 100644 index 000000000..7772a786c --- /dev/null +++ b/docs/superpowers/specs/2026-11-19-agentop-key-grammar-design.md @@ -0,0 +1,81 @@ +# agentop key grammar + +Date: 2026-11-19. Stacked on PR #2011. + +## Intent + +Many people built the agentop TUI over many rounds. The UI is now stable, and its keys, +text and look are not the same from pane to pane. The goal is one set of rules that every +pane obeys, so that agentop feels like one tool. + +This is project 1 of 3: + +1. Key grammar (this document). +2. Hint text grammar: footers, the `?` overlay, flash messages. +3. Visual style: titles, colors, empty/loading/error states, number formats. + +## Rules + +1. One key has one meaning on every pane. On a pane where the key does not apply, it + does nothing. +2. Only a modal (column picker, edit confirm, erase confirm, server picker, search + prompt) can give a key a different meaning. The modal shows those keys in its own + hint line. A modal never uses `x` (erase) for a different action. +3. One concept uses one key. `w` is the window on every pane that has one. The values + can be different when the data is different. The footer shows the current value. +4. `esc` goes back on every pane. On a list, `←`/`h` go back and `→`/`l` open. On a + chart with a cursor (Timeline), they move the cursor along the axis. +5. A global case in `handleKey` checks the pane, or it is a real global key: + `q`, `ctrl+c`, `p`, `?`, `/`, `n`/`N`, `$`, the jump keys and navigation. + +## Changes + +| Key | Today | After | +|---|---|---| +| `s` | Global: toggles `hideInactive` from every pane | Events only. The column picker keeps `s` = sort | +| `x` | Column picker: toggle a column (`space` also toggles) | Erase only. The column picker toggles with `space` only | +| `w` | Footers show `[w] window` | Footers show the current value, for example `[w] 1h` | + +There are no other key changes. `↵`, `S`, `r`, `n`/`N`, `G` and `a`/`A` obey the +rules already. + +The `w` value sets stay as they are, because each one reads different data: + +- Usage: `10m/1h/6h`. It reads the in-memory usage ring, which holds about 6 hours. +- Timeline: `5m/1h/24h/all`, cut to the session length. It reads one session. +- Agents and the spend drawer: `1h/today/7d/month`. They read the cost ledger. + +## Guard tests + +1. In the `?` overlay tables, a key that is not in a modal section has one meaning on + all panes. The test has a short list of the exceptions that the rules allow, such as + `↵` and the Timeline axis keys. +2. A global case in `handleKey` without a pane check is a failure, unless its key is in + the real-global list of rule 5. +3. Each modal's hint line names each key that the modal handles. + +## Approaches + +- **A. Fix the violations and add guard tests (chosen).** It is small, it has low risk + on a stable UI, and the tests stop the next drift. +- B. One key registry that generates dispatch, footer and overlay. Drift becomes + impossible, but it rewrites `keys.go` (about 1,400 lines) and every footer. That is + the most risk on code that works. +- C. A for the keys, and a registry for text only. This choice is moved to project 2, + because most of the drift a registry would stop is in the text. + +## Not in scope + +- Hint text spelling (`[esc]`/`[Esc]`, `[↵]`/`[enter]`) and verbs. That is project 2. +- Colors, titles, formats. That is project 3. + +## Left to the builder + +- How the guard tests find the global cases (an AST walk or a table). +- The exact exception list in guard test 1. +- Docs: `cmd/agentop/README.md` and `docs/using-agentop.md` must say that `s` works on + Events only, and that the column picker toggles with `space`. + +## Size + +One PR: 3 small code changes, 3 guard tests and the doc lines. From 9bba0d73ebe621a10142d629542449b2ca8eec0d Mon Sep 17 00:00:00 2001 From: Hai Huang Date: Thu, 19 Nov 2026 17:12:42 -0500 Subject: [PATCH 2/8] docs: Add the agentop key grammar plan Assisted-By: Claude (Anthropic AI) Signed-off-by: Hai Huang --- .../plans/2026-11-19-agentop-key-grammar.md | 95 +++++++++++++++++++ 1 file changed, 95 insertions(+) create mode 100644 docs/superpowers/plans/2026-11-19-agentop-key-grammar.md diff --git a/docs/superpowers/plans/2026-11-19-agentop-key-grammar.md b/docs/superpowers/plans/2026-11-19-agentop-key-grammar.md new file mode 100644 index 000000000..108d87cd3 --- /dev/null +++ b/docs/superpowers/plans/2026-11-19-agentop-key-grammar.md @@ -0,0 +1,95 @@ +# agentop key grammar Implementation Plan + +> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking. + +**Goal:** Make each agentop key keep one meaning on every pane, and add tests that keep it so. + +**Architecture:** Three small changes in `cmd/agentop/tui` (`s` scoped to Events, column picker +toggles with `space` only, `[w]` hints show the current window), then guard tests that read the +`?` overlay tables and walk `keys.go` with `go/ast`. + +**Tech Stack:** Go 1.26.10, Bubble Tea, `go/parser` + `go/ast` (already used by `removed_keys_test.go`). + +**Spec:** `docs/superpowers/specs/2026-11-19-agentop-key-grammar-design.md` + +## Global Constraints + +- Work in `cmd/agentop`. Run tests with `GOWORK=off`. +- While you change code: `GOWORK=off go test ./tui/...`. Before the PR: `scripts/dev/go-test-shards.sh -race cmd/agentop` from the repo root, and `go vet ./...` and `gofmt -l .` in `cmd/agentop`. +- Commits: `git commit -s`, trailer `Assisted-By: Claude (Anthropic AI) `. +- Real global keys (rule 5): `q`, `ctrl+c`, `p`, `?`, `/`, `n`, `N`, `$`, the jump keys (`u`, `T`, `P`, `A`), and navigation (`g`, `G`, `b`, `f`, `pgup`, `pgdown`, `pgdn`, `esc`, `left`, `h`, `enter`, `right`, `l`). +- The `w` value sets do not change. + +## Review Focus + +1. `s` typed into the search prompt on Events stays a search character (the search block runs first). Task 1 test. +2. `s` inside the column picker still sorts after the global `s` is scoped. Task 1 test. +3. `[w]` on Agents before the first rows reply: the label is the requested window, not empty. Task 3 test. +4. `[w]` on Timeline for a session shorter than the chosen window shows `all`, the window drawn. Task 3 test. +5. Footer width: a longer `[w] ` must still fit; `fitHintLine` drops from the front. Task 3 runs `footer_fit_test.go`. + +--- + +### Task 1: `s` works on Events only + +**Files:** +- Modify: `cmd/agentop/tui/keys.go` (global `case "s"` near line 490; the Usage block's `case "s"` near line 172) +- Test: `cmd/agentop/tui/help_pane_map_test.go` +- Docs: `cmd/agentop/README.md`, `docs/using-agentop.md` (each sentence about `s`) + +- [ ] **Step 1: Failing test** `TestSKey_TogglesOnlyOnEvents`: for each pane in `paneSessions, paneAgents, panePipeline, paneTimeline, paneDetail, paneUsage`, `handleKey(keyRune('s'))` leaves `hideInactive == false`. On `paneEvents` it sets `hideInactive == true`. Keep `TestUsagePane_RemovedSKeyDoesNothing`. +- [ ] **Step 2:** Run `GOWORK=off go test ./tui/ -run TestSKey_TogglesOnlyOnEvents`. Expect FAIL on `paneSessions`. +- [ ] **Step 3:** In the global `case "s"`, return nil unless `m.pane == paneEvents`. Delete the Usage block's `case "s"`, because the global case now covers it. Delete the false part of the comment ("accepting the key on other panes … before drilling into a session"). +- [ ] **Step 4:** Run `GOWORK=off go test ./tui/...`. Expect PASS. Fix every existing test that pressed `s` off Events and expected the toggle. +- [ ] **Step 5:** Docs: where they say `s` works anywhere or sets the filter before you open a session, say it works on Events. +- [ ] **Step 6:** Commit `fix: Make s toggle the passthrough rows on the Events pane only`. + +### Task 2: The column picker toggles with `space` only + +**Files:** +- Modify: `cmd/agentop/tui/keys.go` (`case " ", "x":` in the column picker block, near line 300) +- Modify: `cmd/agentop/tui/events_columns.go:828` (hint line) +- Test: `cmd/agentop/tui/settings_persist_test.go:199` and any other test that presses `x` in the picker +- Docs: README and `docs/using-agentop.md` lines that name `x` in the picker + +- [ ] **Step 1: Failing test** `TestColumnPicker_XDoesNotToggle`: open the picker (`m.colPicker = true`), copy `m.eventColumns`, press `x`, assert the map is unchanged and `m.colPicker` stays true. Press `space`, assert the column under the cursor flipped. +- [ ] **Step 2:** Run it. Expect FAIL. +- [ ] **Step 3:** Change the case to `case " ":`. The hint line becomes `[↑↓] move [space] toggle [s] sort [r] reset [esc]/[enter] close [q] quit`. `x` then goes to the picker's `default:` arm, which swallows it. +- [ ] **Step 4:** Change the tests that pressed `x` to press `space`. Run `GOWORK=off go test ./tui/...`. Expect PASS. +- [ ] **Step 5:** Docs. Commit `fix: Toggle a column with space only in the column picker`. + +### Task 3: `[w]` hints show the current window + +**Files:** +- Modify: `cmd/agentop/tui/keys.go` `helpView` (Timeline near 1310, Usage near 1326, Agents near 1372) +- Test: `cmd/agentop/tui/footer_test.go` + +**Interfaces:** +- Consumes: `formatWindowLabel(time.Duration) string` (`spend.go`), `(*usageState).window() (window, resolution time.Duration)`, `(*timelineState).window(now time.Time) int` with `timelineWindows[i].label`, `(*model).agentsWindowLabel() string`. + +- [ ] **Step 1: Failing test** `TestFooter_WShowsTheCurrentWindow`: + - Usage at the default window: footer contains `[w] 10m` (the first `usageWindows` entry; use the actual default if it differs). After `cycleWindow()`: `[w] 1h`. + - Timeline with a 10-minute session and `windowIdx` = the `1h` entry: footer contains `[w] all`. + - Agents with `agentsRowsWindow == ""`: footer contains `"[w] " + m.agentsWindowLabel()`, and that label is not empty. + - No footer of the three contains `[w] window`. +- [ ] **Step 2:** Run it. Expect FAIL. +- [ ] **Step 3:** Replace each `[w] window` with `"[w] " +