Notes: permanent terminal panel

This commit is contained in:
2026-11-09 22:06:42 +00:00
parent 9cda79fa87
commit fcc5a81690
+208
View File
@@ -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-<id>` 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 <machine>
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
```