From fcc5a81690615e2e7b00f4497c0d7a779534fda4 Mon Sep 17 00:00:00 2001 From: Alan Silva Date: Mon, 9 Nov 2026 22:06:42 +0000 Subject: [PATCH] Notes: permanent terminal panel --- app/notes/terminal-panel.md | 208 ++++++++++++++++++++++++++++++++++++ 1 file changed, 208 insertions(+) create mode 100644 app/notes/terminal-panel.md diff --git a/app/notes/terminal-panel.md b/app/notes/terminal-panel.md new file mode 100644 index 00000000..dc09a5ed --- /dev/null +++ b/app/notes/terminal-panel.md @@ -0,0 +1,208 @@ +# Permanent terminal (bottom panel / floating window) + +A full terminal available from every destination, independent of chats. It +keeps running when the panel is hidden, the app navigates or reloads, and +(where tmux is installed) across Pipelines server restarts. + +## Behaviour + +- **Modes** (Settings → Appearance → Terminal, or the terminal's own ⋮ + menu): *Bottom panel* docks under the app (the app shrinks above it, + never hidden under it); *Floating window* is a window over the app. Both + are toggled by the bar's Terminal button (every destination's bar ends + with it) and **Ctrl+`** (Cmd+` is the macOS window switcher). The + shortcut is a global key handler, so it toggles even while the terminal + has the keyboard. +- **Bottom panel:** resized by dragging its top edge (the app's + `AdaptiveResizeGrip`; arrow keys too, slider semantics); its height is + remembered. The panel always leaves the app at least 160 px. +- **Floating window:** dragged by its title bar, resized from its lower + right corner, double-click or Maximise fills the app (8 px margin), + Minimise collapses it to its title bar, × hides it. Frame and state are + remembered. +- **Narrow windows (< 600 px):** the terminal opens as a full-screen page + (Material/Cupertino route) with the chat terminal's key toolbar (Paste, + Enter, Ctrl-C, Tab, Esc, arrows, and the typing field on Android/iOS). +- **Tabs:** one per terminal; the title is the shell's OSC 0/2 title + (followed by the emulator, also recorded by the server for the list), + else the start folder (`~` for home). Ended terminals are italic and show + why they ended with a Close tab button. With more than one machine + connected (or tabs from several) each tab names its machine, and New + terminal (+) asks which machine. ⨯ on a tab closes it, which kills the + shell (and its tmux session). +- **Open in terminal:** the chat header's More menu (the chat's folder, + on the chat's machine) and a folder's ⋮ menu in the Files panel open a + new terminal there and show the surface. +- **Permanence:** the app's `TerminalHub` lives as long as the app; hiding + or minimising never closes a shell. Reopening redraws the same emulator. + The layout (mode, shown, height, frame) is saved per device, so a reload + reopens the terminal, lists the machine's terminals and resumes each + from its retained output. A dropped connection resumes after the last + byte held; a restarted server (new stream) is read again from its start. +- **Keyboard:** a focused terminal gets every key (Ctrl-C, Esc, Tab, arrows, + Ctrl-letters); paste is Cmd-V (Apple) or Ctrl-V/Ctrl-Shift-V. Clicking + elsewhere moves focus away normally. +- No terminal request is sent until the terminal is first shown (or a + terminal is opened): each connection sends one request at a time, so the + first screen's read is never queued behind `terminal_list`. + +## Protocol (server) + +`internal/protocol/terminal.go`; documented in `docs/cli.md` ("Machine +terminals"). Body `terminal_request {terminal_id?, cwd?, cols?, rows?, +data?, after?}`. + +- `terminal_open {cwd, cols, rows}` → `terminal` (subscribes the + connection to its output first). +- `terminal_list` → `terminals` (running and ended, oldest first; live + records carry their current title, size and `stream`). +- `terminal_input {terminal_id, data}` (UTF-8, ≤ 16 KiB, 64-request queue), + `terminal_resize {terminal_id, cols, rows}` (clamped 20–500 × 4–200). +- `terminal_output {terminal_id, after}` → `terminal` with `output`, + `output_start`, `output_end`, `stream`; subscribes the connection. +- `terminal_close {terminal_id}` → the closed record (runs off the read + loop: it waits up to 3 s for the shell). +- Pushed `terminal_event`: output `{terminal_id, output, offset, end}` to + subscribed connections, lifecycle `{terminal_id, terminal}` (opened, + title, exited, closed) to every connection. A slow connection's queue + (256 frames) drops output; the client sees the offset gap and re-reads. + +## Persistence + +- **tmux present** (looked up on PATH, then /opt/homebrew/bin, + /usr/local/bin, /usr/bin): each shell is `$SHELL -l` (else `/bin/sh`) as + the only pane of session `pipelines-` on a Pipelines-owned tmux + server, `tmux -L pipelines -f /dev/null` (never the operator's own server + or config; `TMUX`/`TMUX_PANE` are stripped). Options: status off, mouse + on (wheel scrolls tmux history), history-limit 10000, escape-time 10, + set-titles on with the pane title. The server shows it through an + ordinary `attach-session` client in a PTY (creack/pty, the chat shell's + `startChatShellTerminal`). On shutdown the client gets SIGHUP and the + session stays; on start `recover` lists the DB's running terminals and + reattaches each whose session is alive (a fresh output stream: tmux + redraws the screen). A client that exits while its session lives is + replaced (up to 5 times). +- **No tmux:** the shell is a direct child; it ends with the server and is + listed as ended with the reason ("tmux is not installed on this + machine"); running tabs say "This shell ends if the server on + restarts (tmux is not installed there)". +- DB table `terminals` (additive): id, title, cwd, shell, created_at, tmux, + status, ended_at, exit_code, reason, cols, rows. Ended records beyond 16 + are pruned. Output stays in memory (1 MiB tail per terminal). + +## Security + +- Only reachable through the authenticated `/connect` websocket, like chat + shell commands; any connection of that server may list, type into or + close its terminals. +- The start folder must exist inside the operator's home after resolving + symlinks (the Files panel's containment); `~`, `~/sub` and absolute paths + are accepted, `~user` and relative paths refused. +- Input is never logged or stored: the server skips its request log line + for `terminal_input`/`terminal_resize`, nothing is written to the DB, and + the client's input pipe (`ChatShellInputPipe`, shared with chat shells) + keeps nothing once sent. + +## Limits and known gaps + +- 8 running terminals per machine; 1 MiB retained output per terminal. +- A tmux shell's exit status is not reported (only direct shells have it). +- The client transport sends one request at a time per connection, so a + keystroke waits behind any slower request on the same machine (as chat + shell input already does). +- Opening a terminal elsewhere (another device) adds its tab here too: the + tabs are the machine's terminals. +- After a server restart the reattached output starts with tmux's redraw + of the screen; older lines are in tmux's history (mouse wheel), not in + the emulator's own scrollback. +- Mobile (narrow page, soft-keyboard field) is verified by widget tests and + a narrow Chrome capture only; no device test ran. Android/Linux builds + were not run. +- `test/application` and `test/features/settings` have 51 failures that are + identical on the base commit 8f06f12d (pending `LaunchUpdateChecker` + timers etc.); none is new. + +## Files + +- Server: `internal/protocol/terminal.go`, `message.go`; + `internal/pipeline/terminals.go`, `store.go`; + `internal/server/terminal_{manager,supervise,process,tmux,clients,title,cwd,handlers}.go`, + `websocket.go`; tests `terminal_ws_test.go`, `terminal_restart_test.go`, + `internal/pipeline/terminals_test.go`; `docs/cli.md`. +- App: `lib/features/terminal/` (`terminal_{info,stream,tab,hub,machines,layout,scope,surface,panel,float,page,body,tab_strip,menu,toggle_button,open_action}.dart`), + `lib/application/app_terminals.dart`, `pipelines_app.dart`, + `bootstrap.dart`, `lib/shell/adaptive_shell.dart` (`barActions`), + `lib/features/settings/settings_terminal_section.dart` (+ screen/topic + pages), `lib/features/chat/conversation/chat_thread_view.dart` (Open in + terminal), `lib/features/chat/files/files_panel.dart` (folder action), + `lib/features/chat/shell/chat_shell_terminals.dart` (`ChatShellInputPipe` + made public). Tests `test/features/terminal/`. Probe fixture + `tool/perf/terminal_fixture.dart` (`?terminals=1`, `?terminal=panel|float`). + +## Verification + +Go 1.x / Flutter 3.44.6, macOS host, tmux 3.7c (/opt/homebrew/bin/tmux). + +- `go test ./internal/protocol ./internal/pipeline ./internal/server -count=1`: + `ok …/protocol 0.188s`, `ok …/pipeline 8.193s`, `ok …/server 69.120s`. + Terminal tests: open/list/input/resize/output-resume/close over the + websocket with two clients; shell exit status; cwd containment, input + bounds, unknown ids, the 8-terminal limit; tmux survives a manager + restart (list running, screen redrawn, shell variable kept, close kills + the session); a killed tmux client is replaced; without tmux the stop and + a crashed record are listed as ended with their reasons; OSC titles. + `-race -count=4` on the terminal tests: ok. Each tmux test uses its own + socket and removes it. `go vet`, `gofmt -l`: clean. + `GOOS=freebsd go build ./internal/server`, `GOOS=linux go test -c`: ok. +- `tool/memwatch/full.sh test/features/terminal`: `PASS: 15 passed` + (hub: lazy activation, ordered output + gap re-read, reconnect resume + and new-stream re-read, open/select/close, foreign open/close frames, + titles and ended reason, input, multi-machine, refusals; surface: Ctrl+` + and button toggle while the terminal has focus, hiding keeps shells, + panel drag-resize remembered and app shrinks, float drag/resize/ + minimise/maximise, tabs select/close/new, mode switch from the menu, + Settings mode choice, narrow full-screen page with key toolbar). +- `tool/memwatch/full.sh test/features/chat`: `PASS: 1137 passed, 0 failed`. +- `test/application test/shell test/features/settings`: 129 passed, 51 + failed — the same 51 failing tests as the base commit (compared by name). +- `tool/analyze.sh`: clean. `flutter build web`: built. + `FLUTTER_XCODE_ARCHS=arm64 flutter build macos`: built (35.0MB). +- Real Chrome (`tool/capture`, probe `?terminals=1`, 1280x820), inspected: + `/tmp/terminal-panel/panel-{light,dark}/01-panel.png`, + `03-panel-three-tabs.png`, `04-panel-taller.png` (dragged up 200 px); + `/tmp/terminal-panel/typed-{light,dark}/01-panel-tab2-typed.png` (second + tab, `pwd`+Enter typed as key events, focused cursor); + `/tmp/terminal-panel/float-{light,dark}/01-float.png`, + `02-float-moved-resized.png`, `03-float-minimised.png`, + `04-float-maximised.png`; + `/tmp/terminal-panel/settings-light/0{1,2,3}-*.png` (Appearance → + Terminal, choosing Floating window, then the bar button); + `/tmp/terminal-panel/narrow-light/01-narrow-page.png` (560 px page with + key toolbar); `/tmp/terminal-panel/cupertino-dark/0{1,2}-*.png` + (Cupertino, two machines: tabs name their machine, New terminal asks + which); `/tmp/terminal-panel/chat-open/02-chat-opened-terminal.png` + (chat More → Open in terminal opened `/workspace/demo`). +- Scratch server end to end (`go build ./cmd/pipelines-server`; `env -i` + with HOME, XDG_DATA_HOME, DB and `TMUX_TMPDIR` under `/tmp/term-e2e`, + OS-chosen loopback port, `SHELL=/bin/bash`; Node websocket driver + `/tmp/term-e2e/drive.mjs`, script `/tmp/term-e2e/run.sh`; server stopped + and tmux server gone afterwards): + + ``` + opened term_c76697ebb5a10ce7 cwd=/tmp/term-e2e/home shell=/bin/bash tmux=pipelines-term_c76697ebb5a10ce7 size=100x30 + typed command ran: before-restart-42 seen + server 94915 stopped + tmux sessions while the server is down: + pipelines-term_c76697ebb5a10ce7 pane_pid=94934 + tmux scrollback while the server is down: + line-1 / line-2 / line-3 / before-restart-42 + server pid 94951 port 62223 + list after restart: term_c76697ebb5a10ce7 running tmux=pipelines-term_c76697ebb5a10ce7 stream=e5cca0de2a86 + reattached output (1463 bytes) has earlier lines: line-1=true line-3=true before-restart-42=true + shell state survived: KEEP=kept-across-restart + close: terminal_close status=closed + list after close: 0 terminals + tmux sessions after close: no server running on /private/tmp/term-e2e/tmux/tmux-501/pipelines + input lines logged: 0 + KEEP in log: 0 + ```