Finished terminals are sized synchronously from their rows at the view's width (the post-frame fit made the transcript re-anchor forever); blank rows xterm.dart keeps when rewrapping are dropped; desktop typing uses key events; the composer leaves Cmd/Ctrl-V to a focused terminal; Ctrl-A reaches the process. The probe fixture gains coloured terminal runs and an interactive login. Notes record behaviour, protocol, security and verification.
10 KiB
Interactive chat shell commands (terminal)
Operator shell commands (!cmd, Run command…; see chat-shell-commands.md)
now run in a real pseudo-terminal and the card draws them with a terminal
emulator. Auth flows that print a link, wait for a pasted token and continue
(gh auth login, claude login, npm login, ssh prompts) work in the chat.
Behaviour
- Server (macOS, Linux): every
chat_shell_runstarts$SHELL -lc <cmd>inside a PTY (github.com/creack/ptyv1.1.24) as the leader of a new session with the PTY as controlling terminal (Setsid,Setctty), so the session id is the process group Stop signals (SIGINT, then SIGKILL after the grace period).TERM=xterm-256color; cwd and the rest of the environment are unchanged. Size comes from the request (cols,rows), clamped to 20–500 x 4–200, default 100x30. The PTY controller is closed when the command ends. Other platforms keep the previous pipe mode; input and resize answer "interactive terminals are not supported on this server". - Card: the output area is an
xterm4.0.0 (xterm.dart)TerminalViewfed the raw stream in order. One emulator per run lives in the controller (ChatShellTerminals), so scrolling a card away or opening Full screen keeps the same state.- Running: 12 rows in the reading column; click/tap to focus and type (hardware keys, Ctrl-C, arrows, Tab, Esc go to the process). Paste: Cmd-V on Apple platforms, Ctrl-V or Ctrl-Shift-V elsewhere, plus the toolbar's Paste button. Ctrl-A and other Ctrl keys reach the process. A key toolbar under the terminal: Paste, Enter, Ctrl-C, Tab, Esc, arrows. On Android/iOS the toolbar also has a text field ("Type input, then Enter") for the soft keyboard, with a Hide typing toggle; it is emptied when sent.
- The terminal is resized to its layout (debounced 150 ms); the process gets SIGWINCH. New runs start at the last laid-out size.
- Printed
http(s)links open in the browser on tap (wrapped links are joined). Other schemes are ignored. - Finished runs are drawn read-only, shrunk to the rows their output takes (at most 12), cursor hidden. Full screen opens the same terminal in a page.
- Colours: background/foreground/cursor/selection from the host theme; the 16 ANSI colours are xterm.dart's palette, darkened on light surfaces.
- Copy output copies the server's plain-text rendering; Send to agent shares a bounded plain-text tail (no escape codes).
- Pipe-mode and older runs (no
terminal) are drawn in the same emulator with\ndrawn as a new line, read-only.
Protocol
chat_shell_runrequest adds optionalcols,rows; records addterminal,cols,rows(current size) and, only inchat_shell_run_output,text(plain-text rendering).chat_shell_input {session_id, run_id, data}:datais UTF-8 text written byte-for-byte (its UTF-8 encoding). Control characters are JSON escapes: Ctrl-C\u0003, Enter\r, arrows\u001b[A… Paste is text (bracketed when the program asked). At most 16 KiB per request (clients split longer pastes at 4096 UTF-16 units); invalid UTF-8 is refused. Requests from one connection are applied in order through a 64-entry queue; a full queue is refused ("the command is not reading its input"). Reply has no body.chat_shell_resize {session_id, run_id, cols, rows}: reply echoes the run. The last resize from any client wins.- Output frames are unchanged: raw terminal bytes (UTF-8, partial characters
held back) with absolute byte offsets
[offset, end), which are the stream sequence numbers.chat_shell_run_outputtakesafter: the reply'soutput_startismax(after, retained start), so a reconnecting client fetches only what it missed and sees a gap if it fell out of the 1 MiB tail. The app does this on reconnect for runs it holds. - Persistence:
chat_shell_runsgainsterminal,cols,rows,output_text(additive columns).outputis the raw stream tail (1 MiB),output_textits rendering (bounded to 1 MiB). Rows recorded before this change get a rendering computed on read.
Security
- Any authenticated client watching the chat may type into or resize a running command, not only the one that started it (the same authority that can already start and stop commands in that chat). Input is checked against the chat's operator session like every other shell request.
- Input is never persisted or logged: the server does not log
chat_shell_input/chat_shell_resizerequest lines at all (keystrokes would otherwise be one log line each), and only what the terminal echoes becomes output. Password prompts disable echo, so hidden input never appears in output, frames,outputoroutput_text. - The client keeps no copy of typed input: keys go from the emulator straight into a send queue that is cleared as each request is sent (and discarded on a refusal); the mobile field is cleared on send and can hide its text.
- When the terminal has focus, the chat composer leaves Cmd/Ctrl-V alone
(
ChatComposerPasteFocus.registerInput), so a pasted token goes only to the process.
Limits and known gaps
- Plain-text rendering is not an emulator: it strips CSI/OSC/DCS sequences,
applies
\r, backspace and line erase; full-screen programs render as their last lines. The card's emulator draws them properly. - Every watching client's emulator answers terminal queries (e.g. cursor position) for a live run, so two open clients send two answers. xterm.dart 4.0.0 answers DSR 6 zero-based; the app overrides it to the correct one-based answer.
- xterm.dart 4.0.0 keeps blank rows when it rewraps; the app drops blank rows below the cursor after a resize so the top of the output stays in view.
- Desktop typing uses key events (no IME composition for CJK input). Touch platforms use the field.
- A descendant that keeps the PTY open after the command exits is read for 1 s; on macOS the PTY has no read deadline, so its reader goroutine ends only when that descendant closes it (the run itself is finished and the group killed).
- Mobile behaviour (soft keyboard field) is verified by widget tests only; no device test ran. Android/Linux builds were not run (web and macOS were).
Files
- Server:
internal/protocol/chat_shell_terminal.go,chat_shell_run.go;internal/server/chat_shell_terminal{,_unix,_other}.go,chat_shell_plain.go,chat_shell_runner.go,chat_shell_supervise.go,chat_shell_run_handlers.go,chat_shell_share.go,chat.go,websocket.go;internal/pipeline/chat_shell_runs.go;go.mod,go.sum. - App:
lib/features/chat/shell/chat_shell_terminal_{session,view,keys,theme,links,page}.dart,chat_shell_terminals.dart,chat_shell_output_view.dart,chat_shell_run{,_card}.dart,chat_shell_card_actions.dart,chat_shell_runs_{controller,repository}.dart,chat_shell_metrics.dart;lib/features/chat/conversation/chat_composer_paste_focus.dart;pubspec.yaml/pubspec.lock(xterm: ^4.0.0, pure Dart; pub.dev lists Android, iOS, Linux, macOS, web, Windows); probe fixturetool/perf/chat_shell_fixture.dart(?shell=1: coloured runs and an interactivegh auth loginthat hides the token and finishes on Enter).
Verification
Flutter 3.44.6 / Dart 3.12.2; macOS host.
-
go test ./internal/protocol ./internal/pipeline ./internal/server -count=1:ok …/protocol 0.205s,ok …/pipeline 15.838s,ok …/server 140.086s. Real-PTY tests (chat_shell_terminal_test.go,_ws_test.go): a typed line reachesread;stty -echoinput is in no frame, output or text;\x03interrupts;stty sizesees the start size and a resize; resume by offset over the websocket from a second client; raw + plain text persisted; input bounds (16 KiB, empty, invalid UTF-8, full queue); size clamping.go test -run ChatShell -count=5: ok.GOOS=freebsd go build ./internal/server(pipe fallback) andGOOS=linux GOARCH=amd64 go test -ccompile. (-raceshows an existing data race ininternal/opencodenativeRequest, unrelated to this change.) -
tool/memwatch/full.sh test/features/chat:PASS: 1124 passed, 0 failed. New:test/features/chat/shell/chat_shell_terminal_test.dart(desktop keys, Cmd-V paste not taken by the composer, Paste button, touch toolbar and hidden field cleared on send, resize sent, finished run read-only, colours, reconnect resume),chat_shell_terminal_session_test.dart(links incl. wrapped and non-http, query answers not resent on replay, one-based DSR, gap redraw, rewrap keeps first line, row fitting). -
tool/analyze.sh: clean.flutter build web: built.FLUTTER_XCODE_ARCHS=arm64 flutter build macos: built (34.9MB). -
Real Chrome (
tool/capture, probe?chats=2&shell=1, 880x1000, Material and Cupertino, light and dark):/tmp/chat-interactive-terminal/<platform>-<theme>/01-login-prompt.png(coloured output, underlined link, prompt and cursor),02-login-focused.png(focused cursor),03-login-done.png(5 typed keys and Enter reached the fixture: "received a 5-character token", nothing echoed; the card shrank to its output, read-only),04-full-screen.png. -
Scratch server end to end (
go build ./cmd/pipelines-server,env -iwith HOME/XDG_DATA_HOME/DB under/tmp/pty-e2e, OS-chosen loopback port, operator session inserted with sqlite3, Node websocket driver/tmp/pty-e2e/drive.mjs; server stopped afterwards, no processes left):started run_45be206dedb0454409c537b6 terminal=true size=90x20 resize reply: chat_shell_resize 120x40 input reply: chat_shell_input final: status=exited exit=0 bytes=145 "tty: xterm-256color\r\n20 90\r\n\u001b[1;32mOpen https://example.com/login\u001b[0m\r\nPaste token: \r\n40 120\r\ngot 13 characters\r\nName: operator\r\nhello operator\r\n" secret in stream: false resume after 119: output_start=119 output="operator\r\nhello operator\r\n" secret in text: false late input: error this command is not running run_…|exited|0|1|120|40|145|125|0 (sqlite: terminal, cols, rows, raw, text, SECRET offset)The server log has no
chat_shell_inputorchat_shell_resizelines.