colibri/docs/GLASSPANE-TUI-ENHANCEMENTS.md

Glasspane / colibri-tui — operator usability enhancements (working doc)

Working/design notes for the operator-facing supervision surface. The published summary lives in wiki/glasspane.md (Usability roadmap); this doc is the scratch space where we collect references and shape the work before it lands.

Premise: make "does this agent need me right now?" the primary, impossible-to-miss object. We already have the spine — the glasspane state machine (Idle → Working → Done / Error / Stalled), the snapshot API, and the colibri-tui dashboard. The open work is surfacing and pushing attention, not new machinery. Ideas are drawn from agent-cockpit terminal UIs; all wiring is our own (no external code, no dependency).

Current colibri-tui keybindings (baseline)

Key	Action
q / Esc	Quit, or close detail pane if open
r	Refresh snapshot now
s	Spawn a local colibri-test-agent
x	Kill the selected pane
Enter	Open/close the detail pane for the selected row
Tab / Shift-Tab	Cycle through distinct sessions
j / k or ↓ / ↑	Navigate the pane table

→ crates/colibri-glasspane-tui/src/main.rs

Reference: agent-cockpit shortcut vocabulary (example, not a spec)

Captured as an example of the interaction vocabulary a mature agent cockpit settles on. Most of it is GUI-only (canvas, embedded browser, diff viewer, split panes) and irrelevant to a terminal dashboard — kept here only so we can see the shape. The transferable clusters for colibri-tui are marked ★.

Legend: ⌘ Cmd · ⌥ Option · ⌃ Control · ⇧ Shift · ↩ Enter.

Notifications ★ — the "attention" model we care about

• ⌘I — show notifications
• ⌘⇧U — jump to latest unread
• ⌃⌘U — mark oldest-unread and jump to next
• ⌥⌘U — toggle current item unread
• ⌘⇧H — flash focused panel

Navigation ★

• J/K (+ ⌃N/P, H/L) — vim-style row/pane movement (we already do j/k)
• ⌘1…9 / ⌃1…9 — jump directly to workspace / surface N

Workspaces / surfaces (GUI tab model — mostly N/A to a TUI)

• ⌘N new workspace · ⌘T new surface · ⌘W close · ⌘⇧R rename · ⌘⇧O reopen previous session
• ⌃⌘] / ⌃⌘[ next/prev workspace · ⌘⇧] / ⌘⇧[ next/prev surface

Input / focus ★ (relevant once we add "answer a blocked agent")

• ⌘⇧A — switch focus between terminal and a text-input box
• ⌥⌘⇧A — attach file to the input box

GUI-only (canvas, browser, diff, find, splits) — out of scope for the TUI; listed for completeness only: ⌘D/⌘⇧D splits, ⌃⌘C canvas, ⌘⇧L browser, ⌃⌘⇧D diff viewer, ⌘F find, ⌥⌘= / ⌥⌘- zoom, etc.

Proposed colibri-tui keymap (draft — to be refined as we build)

Additive to the baseline; nothing here collides with existing keys.

Key	Proposed action	Roadmap item
n / N	Jump to next / previous attention pane (Error/Stalled/waiting)	jump-to-next-attention
a	Toggle the attention filter (show only panes needing the operator)	attention signal
i	Send input / answer the selected pane (when it is blocked on input)	answer-from-dashboard
t	Toggle Telegram/desktop notification mute for the session	outbound notifications

(Mnemonics provisional — next-attention, attention-filter, input, toggle-notify.)

Open design questions

• Attention as flag vs. state: keep the AgentState enum small and derive an attention boolean over it, rather than adding a sixth state. Where does "waiting for input" come from — inferred from stall + a prompt marker, or an explicit agent-emitted event?
• Outbound notify transport: a colibri notify subcommand, or a glasspane event type a zot/Pi hook fires? Desktop (XFCE) + Telegram (token already provisioned) are the two sinks.
• Interactive write path: "send input to pane N" turns the daemon socket from read-only supervision into interactive control — needs its own design pass (auth, which panes accept input, echo/confirmation).
• Persisted pane history: how much timeline to keep across daemon restarts so "what happened while I was away" survives a reboot, without growing unbounded.

See also

• wiki/glasspane.md — state machine + published roadmap
• wiki/tui.md — the dashboard client and its current keybindings