Skip to content
Open
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
4 changes: 2 additions & 2 deletions cmd/agentop/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -674,7 +674,7 @@ agentop is for, and the others are surfaces you visit and leave.

updated 7s ago (every 20s)

[m] metric [w] window [b] breakdown [s] this session [esc] back [?] keys [q] quit
[m] metric [w] 10m [o] breakdown [/] search [esc] back [?] keys [q] quit
```

Under `latency` the bars give way to mean-with-whiskers and the breakdown
Expand Down Expand Up @@ -863,7 +863,7 @@ Layered on top of all of them:
| `n` / `N` | any pane with a search, and the key help | next / previous match, wrapping at both ends; in a text view an off-screen match is scrolled to a third of the way down |
| `x` | sessions, agents | erase the row under the cursor, in memory and on disk: the highlighted session, or every session of the highlighted agent — on *All agents*, every session this Cortex holds; that confirmation also shows the size on disk. Asks first, with the count; `y` erases, `n`/`esc` keeps. The cost ledger is kept. An agent still using a session brings it back with its next request. Refused — with the proxy's reason — anywhere but a loopback-only laptop install. Not in the footer; the `?` overlay names it |
| `s` | events | toggle hiding exchanges no plugin acted on (default: shown; an exchange is hidden only when no plugin acted on either half; the events footer shows the hidden count) |
| `c` | events | open the column picker (`↑↓`/`jk` move, `space`/`x` toggle, `s` sort, `r` reset, `Esc`/`Enter`/`c` close); the selection and sort are saved on close |
| `c` | events | open the column picker (`↑↓`/`jk` move, `space` toggle, `s` sort, `r` reset, `Esc`/`Enter`/`c` close); the selection and sort are saved on close |
| `s` | column picker | sort by the column under the cursor: descending → ascending → chronological. Pressing it on a different column starts that column descending. `#` is not sortable — its order already *is* chronological |
| `p` | any | pause/resume stream |
| `y` | detail | yank the event of the section the cursor is in (request or response) to `~/.cortex/agentop-events` (path stays until the next keypress) |
Expand Down
2 changes: 1 addition & 1 deletion cmd/agentop/tui/events_columns.go
Original file line number Diff line number Diff line change
Expand Up @@ -825,7 +825,7 @@ func renderColumnPicker(sel map[eventColumnID]bool, widths map[eventColumnID]int
// fitHintLine, so a narrow terminal drops hints from the front and keeps
// [q] quit rather than wrapping the line. Same treatment the footer gets.
b.WriteString(styleHint.Render(fitHintLine(
"[↑↓] move [space]/[x] toggle [s] sort [r] reset [esc]/[enter] close [q] quit",
"[↑↓] move [space] toggle [s] sort [r] reset [esc]/[enter] close [q] quit",
width-borderWidth)))

// MaxWidth as a backstop. overlayCenter is explicit that bounding the panel is
Expand Down
17 changes: 17 additions & 0 deletions cmd/agentop/tui/events_columns_test.go
Original file line number Diff line number Diff line change
Expand Up @@ -2,6 +2,7 @@ package tui

import (
"context"
"maps"
"strings"
"testing"
"time"
Expand Down Expand Up @@ -973,3 +974,19 @@ func TestRenderColumnPicker_ShowsSort(t *testing.T) {
t.Errorf("picker marks a sort when none is active: %q", none)
}
}

// `x` is the erase key, so the picker does not reuse it: only `space` toggles.
func TestColumnPicker_XDoesNotToggle(t *testing.T) {
m := newTestEventsModel(t)
m.handleKey(keyRune('c'))
before := maps.Clone(m.eventColumns)
m.handleKey(keyRune('x'))
if !maps.Equal(before, m.eventColumns) || !m.colPicker {
t.Errorf("`x` changed the columns (%v -> %v) or closed the picker", before, m.eventColumns)
}
id := eventColumns[m.colCursor].id
m.handleKey(keyRune(' '))
if m.eventColumns[id] == before[id] {
t.Errorf("`space` did not toggle column %q", id)
}
}
42 changes: 42 additions & 0 deletions cmd/agentop/tui/footer_test.go
Original file line number Diff line number Diff line change
Expand Up @@ -7,6 +7,8 @@ import (

"github.com/charmbracelet/lipgloss"
"github.com/muesli/termenv"

"github.com/rossoctl/cortex/core/session/timeline"
)

// statusRow returns the first line of the footer — the status row, where the
Expand Down Expand Up @@ -130,3 +132,43 @@ func TestFooterShowsSearchOnEveryPane(t *testing.T) {
}
}
}

// Each [w] hint names the window it is on now, so the key reads the same on every pane.
func TestFooter_WShowsTheCurrentWindow(t *testing.T) {
u := &model{pane: paneUsage}
if got := u.helpView(); !strings.Contains(got, "[w] 10m") {
t.Errorf("usage footer at the first window: %q, want [w] 10m", got)
}
u.usage.cycleWindow()
if got := u.helpView(); !strings.Contains(got, "[w] 1h") {
t.Errorf("usage footer after w: %q, want [w] 1h", got)
}

resetSettingsForTest(t)
tl := timelineModel(t, 120, 40) // a 30-minute session
tl.timeline.windowIdx = 1 // 1h: longer than the session, so "all" is drawn
if got := tl.helpView(); !strings.Contains(got, "[w] all") {
t.Errorf("timeline footer: %q, want [w] all", got)
}
// An ended session with a tool that never ended: the pane draws from tl.End, not the clock.
tl.timeline.tl.Tools = append(tl.timeline.tl.Tools, timeline.Tool{Agent: timeline.MainAgent, ID: "open", Name: "Bash", Start: tlAt(1700)})
_, _, _, win := tl.timelineRange()
if want := "[w] " + timelineWindows[win].label + " "; !strings.Contains(tl.helpView(), want) {
t.Errorf("timeline footer with an open tool: %q, want %q", tl.helpView(), want)
}

a := &model{pane: paneAgents}
label := a.agentsWindowLabel()
if label == "" {
t.Fatal("agentsWindowLabel is empty before the first rows reply")
}
if got := a.helpView(); !strings.Contains(got, "[w] "+label) {
t.Errorf("agents footer: %q, want [w] %s", got, label)
}

for _, m := range []*model{u, tl, a} {
if strings.Contains(m.helpView(), "[w] window") {
t.Errorf("pane %v still says [w] window", m.pane)
}
}
}
2 changes: 1 addition & 1 deletion cmd/agentop/tui/help_overlay_test.go
Original file line number Diff line number Diff line change
Expand Up @@ -301,7 +301,7 @@ func TestFooterHintsMentionUsageKey(t *testing.T) {
// The usage pane's own footer must not fall through to the bare default.
m.pane = paneUsage
got := m.helpView()
for _, want := range []string{"[m] metric", "[w] window", "[o] breakdown"} {
for _, want := range []string{"[m] metric", "[w] 10m", "[o] breakdown"} {
if !strings.Contains(got, want) {
t.Errorf("usage footer omits %q:\n %s", want, got)
}
Expand Down
16 changes: 16 additions & 0 deletions cmd/agentop/tui/help_pane_map_test.go
Original file line number Diff line number Diff line change
Expand Up @@ -508,3 +508,19 @@ func TestHelpBody_WrapsProseToTheGivenWidth(t *testing.T) {
}
}
}

// `s` hides the Events table's passthrough rows, so it works only where that table is.
func TestSKey_TogglesOnlyOnEvents(t *testing.T) {
for _, p := range []paneID{paneSessions, paneAgents, panePipeline, paneTimeline, paneDetail, paneUsage} {
m := &model{pane: p}
m.handleKey(keyRune('s'))
if m.hideInactive {
t.Errorf("pane %v: `s` toggled hideInactive off the Events pane", p)
}
}
m := &model{pane: paneEvents}
m.handleKey(keyRune('s'))
if !m.hideInactive {
t.Error("`s` on Events did not toggle hideInactive")
}
}
258 changes: 258 additions & 0 deletions cmd/agentop/tui/key_grammar_test.go
Original file line number Diff line number Diff line change
@@ -0,0 +1,258 @@
package tui

import (
"go/ast"
"go/parser"
"go/token"
"os"
"slices"
"strconv"
"strings"
"testing"
)

// The key grammar: docs/superpowers/specs/2026-11-19-agentop-key-grammar-design.md.

// realGlobalKeys may act on every pane without checking it (rule 5).
var realGlobalKeys = []string{
"q", "ctrl+c", "p", "?", "/", "n", "N", "$",
"u", "T", "P", "A",
"g", "G", "b", "f", "pgup", "pgdown", "pgdn",
"esc", "left", "h", "enter", "right", "l",
}

// sharedPaneKeys are the letters that more than one pane's `?` table may list, each with
// the one meaning it keeps there.
var sharedPaneKeys = map[string]string{
"h": "back on a list, the axis on a chart (rule 4)",
"l": "open on a list, the axis on a chart (rule 4)",
"j": "down", "k": "up",
"r": "reload the agent list, on the two pickers",
"x": "erase the row under the cursor",
"S": "choose the inference server for the row",
"w": "cycle the pane's window",
}

func parseTUI(t *testing.T) (*token.FileSet, map[string]*ast.FuncDecl) {
t.Helper()
fset := token.NewFileSet()
pkgs, err := parser.ParseDir(fset, ".", func(fi os.FileInfo) bool {
return !strings.HasSuffix(fi.Name(), "_test.go")
}, 0)
if err != nil {
t.Fatal(err)
}
funcs := map[string]*ast.FuncDecl{}
for _, pkg := range pkgs {
for _, f := range pkg.Files {
for _, d := range f.Decls {
if fd, ok := d.(*ast.FuncDecl); ok {
funcs[fd.Name.Name] = fd
}
}
}
}
return fset, funcs
}

// isKeySwitch reports whether s is `switch msg.String()` or `switch key` style: a switch on a
// call to String() or on an identifier named msg or key.
func isKeySwitch(s *ast.SwitchStmt) bool {
switch tag := s.Tag.(type) {
case *ast.CallExpr:
sel, ok := tag.Fun.(*ast.SelectorExpr)
return ok && sel.Sel.Name == "String"
case *ast.Ident:
return tag.Name == "msg" || tag.Name == "key"
}
return false
}

func caseKeys(cc *ast.CaseClause) []string {
var out []string
for _, e := range cc.List {
if lit, ok := e.(*ast.BasicLit); ok && lit.Kind == token.STRING {
if s, err := strconv.Unquote(lit.Value); err == nil {
out = append(out, s)
}
}
}
return out
}

// keysHandledIn lists the case keys of every key switch below n.
func keysHandledIn(n ast.Node) []string {
var out []string
ast.Inspect(n, func(n ast.Node) bool {
if s, ok := n.(*ast.SwitchStmt); ok && isKeySwitch(s) {
for _, st := range s.Body.List {
out = append(out, caseKeys(st.(*ast.CaseClause))...)
}
}
return true
})
return out
}

func refersToMField(n ast.Node, field string) bool {
found := false
ast.Inspect(n, func(n ast.Node) bool {
if sel, ok := n.(*ast.SelectorExpr); ok && sel.Sel.Name == field {
if id, ok := sel.X.(*ast.Ident); ok && id.Name == "m" {
found = true
}
}
return !found
})
return found
}

func stringLits(n ast.Node) string {
var b strings.Builder
ast.Inspect(n, func(n ast.Node) bool {
if lit, ok := n.(*ast.BasicLit); ok && lit.Kind == token.STRING {
b.WriteString(lit.Value)
}
return true
})
return b.String()
}

// Rule 1: a letter that two panes' `?` tables list keeps one meaning. A new letter on a
// second pane must join sharedPaneKeys with that meaning.
func TestKeyGrammar_OneMeaningPerKey(t *testing.T) {
panes := map[string][]string{} // letter -> "pane: desc"
for _, g := range paneKeys {
for _, kb := range g.bindings {
// "c then s": the second key belongs to the modal the first one opens.
first, _, _ := strings.Cut(kb.keys, " then ")
for _, tok := range strings.FieldsFunc(first, func(r rune) bool { return r == ' ' || r == '/' }) {
if len(tok) != 1 || !(tok[0] >= 'a' && tok[0] <= 'z' || tok[0] >= 'A' && tok[0] <= 'Z') {
continue
}
if !slices.ContainsFunc(panes[tok], func(u string) bool { return strings.HasPrefix(u, g.title+":") }) {
panes[tok] = append(panes[tok], g.title+": "+kb.desc)
}
}
}
}
for k, uses := range panes {
if len(uses) < 2 {
continue
}
if _, ok := sharedPaneKeys[k]; !ok {
t.Errorf("%q is listed on %d panes and is not in sharedPaneKeys:\n %s",
k, len(uses), strings.Join(uses, "\n "))
}
}
}

// Rule 5: a case of handleKey's global switch acts on one pane's state only after it checks
// the pane, unless its key is a real global key.
func TestKeyGrammar_GlobalCasesCheckThePane(t *testing.T) {
fset, funcs := parseTUI(t)
hk := funcs["handleKey"]
if hk == nil {
t.Fatal("handleKey not found")
}
var global *ast.SwitchStmt
for _, st := range hk.Body.List {
if s, ok := st.(*ast.SwitchStmt); ok && isKeySwitch(s) {
global = s
}
}
if global == nil {
t.Fatal("handleKey has no top-level key switch")
}
for _, st := range global.Body.List {
cc := st.(*ast.CaseClause)
keys := caseKeys(cc)
allGlobal := len(keys) > 0
for _, k := range keys {
if !slices.Contains(realGlobalKeys, k) {
allGlobal = false
}
}
if allGlobal {
continue
}
body := &ast.BlockStmt{List: cc.Body}
if !refersToMField(body, "pane") {
t.Errorf("%s: case %q acts without checking m.pane and is not a real global key",
fset.Position(cc.Pos()), keys)
}
}
}

// Rule 2: a modal names in its hint line each key it gives a meaning of its own, and it never
// takes `x`, the erase key.
func TestKeyGrammar_ModalHintsNameTheirKeys(t *testing.T) {
_, funcs := parseTUI(t)

// The column picker's keys are a block of handleKey; find it by its condition.
var picker ast.Node
ast.Inspect(funcs["handleKey"], func(n ast.Node) bool {
if is, ok := n.(*ast.IfStmt); ok && picker == nil {
cond := is.Cond
for {
b, ok := cond.(*ast.BinaryExpr)
if !ok {
break
}
cond = b.X
}
if sel, ok := cond.(*ast.SelectorExpr); ok && sel.Sel.Name == "colPicker" {
picker = is.Body
}
}
return picker == nil
})
if picker == nil {
t.Fatal("column picker block not found in handleKey")
}

modals := []struct {
name string
keys ast.Node
hints []string // functions whose string literals hold the hint line
opener string // the key that opened the modal also closes it
}{
{"column picker", picker, []string{"renderColumnPicker"}, "c"},
{"erase confirm", funcs["clearConfirmKey"], []string{"confirmText"}, ""},
{"edit overlay", funcs["handleEditKey"], []string{"renderEditOverlay"}, ""},
{"server picker", funcs["serverPickerKey"], []string{"renderServerPicker", "renderScopeStep"}, ""},
}
// Moving and leaving work the same in every modal, so a hint line need not repeat them.
common := []string{"up", "down", "k", "j", "home", "end", "g", "G", "esc", "q", "ctrl+c"}
for _, md := range modals {
if md.keys == nil {
t.Fatalf("%s: key handler not found", md.name)
}
var hint strings.Builder
for _, fn := range md.hints {
if funcs[fn] == nil {
t.Fatalf("%s: hint function %s not found", md.name, fn)
}
hint.WriteString(stringLits(funcs[fn]))
}
h := hint.String()
for _, k := range keysHandledIn(md.keys) {
if k == "x" {
t.Errorf("%s takes `x`, the erase key", md.name)
}
if slices.Contains(common, k) || k == md.opener {
continue
}
want := []string{"[" + strings.ToLower(k) + "]"}
switch k {
case " ":
want = []string{"[space]"}
case "enter":
want = []string{"[enter]", "[↵]"}
}
if !slices.ContainsFunc(want, func(w string) bool { return strings.Contains(h, w) }) {
t.Errorf("%s handles %q but its hint line does not name it (want one of %v)", md.name, k, want)
}
}
}
}
Loading
Loading