diff --git a/app/lib/features/chat/shell/chat_shell_card_actions.dart b/app/lib/features/chat/shell/chat_shell_card_actions.dart index 3d7571f1..e5ddff8e 100644 --- a/app/lib/features/chat/shell/chat_shell_card_actions.dart +++ b/app/lib/features/chat/shell/chat_shell_card_actions.dart @@ -4,6 +4,7 @@ import 'package:flutter/cupertino.dart'; import 'package:flutter/material.dart'; import 'package:flutter/services.dart'; +import 'chat_shell_metrics.dart'; import 'chat_shell_run.dart'; import 'chat_shell_runs_controller.dart'; @@ -113,7 +114,7 @@ class _ChatShellCardActionsState extends State { ? () => unawaited(controller.share(run.id)) : null, ), - if (run.output.isNotEmpty) + if (widget.expanded || chatShellOutputMayOverflow(run.output)) _button( key: const Key('chat-shell-run-expand'), label: widget.expanded diff --git a/app/lib/features/chat/shell/chat_shell_metrics.dart b/app/lib/features/chat/shell/chat_shell_metrics.dart index f1232372..c375c7c9 100644 --- a/app/lib/features/chat/shell/chat_shell_metrics.dart +++ b/app/lib/features/chat/shell/chat_shell_metrics.dart @@ -16,6 +16,17 @@ const double kChatShellOutputLineHeight = 1.35; /// part, and Copy output still copies everything the server kept. const int kChatShellRenderedOutputLimit = 64 * 1024; +/// Whether [output] may be taller than the collapsed area, so Expand is worth +/// offering. Counted in lines, with long lines counted as wrapping. +bool chatShellOutputMayOverflow(String output) { + var lines = 0; + for (final line in output.split('\n')) { + lines += 1 + line.length ~/ 80; + if (lines > kChatShellOutputCollapsedLines) return true; + } + return false; +} + /// The output area's maximum height for this window, text scale and font. double chatShellOutputMaxHeight( BuildContext context, { diff --git a/app/lib/features/chat/shell/chat_shell_output_view.dart b/app/lib/features/chat/shell/chat_shell_output_view.dart index f7b1d354..6e5421d7 100644 --- a/app/lib/features/chat/shell/chat_shell_output_view.dart +++ b/app/lib/features/chat/shell/chat_shell_output_view.dart @@ -51,6 +51,8 @@ class _ChatShellOutputViewState extends State { if (clipped) { text = text.substring(text.length - kChatShellRenderedOutputLimit); } + // The final newline ends the last line; it is not an empty line to draw. + if (text.endsWith('\n')) text = text.substring(0, text.length - 1); final notes = [ if (run.truncated) 'Earlier output was dropped.', if (clipped) diff --git a/app/notes/chat-shell-commands.md b/app/notes/chat-shell-commands.md new file mode 100644 index 00000000..d276a991 --- /dev/null +++ b/app/notes/chat-shell-commands.md @@ -0,0 +1,195 @@ +# Chat shell commands + +The operator can run their own shell commands inside a chat, like Codex's +`!cmd` or Claude Code's `!` bash mode. A command runs in the chat's working +directory on the chat's machine (the Pipelines server that owns the chat). It +is Pipelines' own feature and does not go through the harness. The model never +sees a command or its output unless the operator chooses **Send to agent**. + +## Behaviour + +- **Composer.** If a draft starts with `!` (leading blanks allowed), the + composer shows a **Shell** indicator: "Runs in this chat's folder on its + machine. The agent does not see it." The primary control's name changes to + "Run command". Enter or the button runs the text after the `!` through + `chat_shell_run`. Such a draft is never sent as a prompt. The draft is + cleared once the server has started the command. If the server refuses it + (limit reached, missing folder), the draft stays and the reason appears as + a failed command notice. A bare `!` reports "Type a command after !." and + sends nothing. `/help` lists `!` after the slash commands. +- **Actions menu.** The conversation's More menu has **Run command…**. It + opens a small Material or Cupertino dialog with a monospace field and the + same hint. A refusal appears as the conversation's failed notice. +- **Transcript card.** Each run is a card in the normal reading column. Runs + are placed by start time among the timed turns, and a run newer than every + turn comes last. The card shows: + - `$ command` in monospace, with the resolved folder under it. + - The host's activity indicator and **Stop** while the command runs. + "Stopping…" shows until the final frame arrives. + - A status chip when it ends: `Exit 0 · 37 ms`, `Exit 1 · 4.2 s`, + `Stopped · 15.2 s`, `Interrupted` or `Killed (signal)`. The words carry + the state and colour only repeats it. + - Live output in the host's monospace on an inset surface. It scrolls + inside a bounded height, stays anchored at the newest line, and has + **Expand**/**Collapse** when it can overflow. + - **Copy output**, which copies the server's whole retained output and + reads it first when the card holds only a tail. + - **Send to agent**: Sending…, then Sent to agent. A second tap does + nothing. + - A line saying when earlier output was dropped. +- **Several clients.** Output and lifecycle frames go to every client + watching the chat (`chat_subscribe` room). A reload or reconnect reads the + runs back with `chat_shell_runs`. + +## Wire (internal/protocol/chat_shell_run.go) + +| request | body | reply | +| --- | --- | --- | +| `chat_shell_run` | `chat_shell_run_request{session_id, command}` | `chat_shell_run` (the running record) | +| `chat_shell_stop` | `chat_shell_run_request{session_id, run_id}` | `chat_shell_run` | +| `chat_shell_runs` | `chat_query{session_id}` | `chat_shell_runs` (oldest first, ≤64 KiB tail each) | +| `chat_shell_run_output` | `chat_shell_run_request{session_id, run_id}` | `chat_shell_run` with the full retained output | +| `chat_shell_share` | `chat_shell_run_request{session_id, run_id[, operation_id]}` | the ordinary `chat_prompt` ack | + +Pushed: `chat_shell_run_event{session_id, run_id, run}` for each lifecycle +change, and `{session_id, run_id, output, offset, end}` for output chunks. +`offset` and `end` are absolute byte offsets. A client whose copy ends before +`offset` marks a gap instead of joining unrelated text. + +## Server (internal/server/chat_shell_*.go) + +- The server runs `$SHELL -lc `. It uses `/bin/sh` when `$SHELL` is + not an absolute path to an existing file. The command gets the server's + environment, stdin `/dev/null` and its own process group (`Setpgid`), with + stdout and stderr merged into one pipe. +- The working directory is the chat session's recorded directory from the + operator-session registry. Symlinks are resolved, and the directory must + still exist and be a directory. Otherwise the run is refused ("the chat's + directory … is not available"). +- Output is sent in batches every 100 ms, at most 64 KiB per frame. If more + is waiting, the newest bytes are sent and the client sees a gap. A + character is never split. Invalid UTF-8 is replaced by U+FFFD on the wire. +- **Stop** sends SIGINT to the group, then SIGKILL after 3 s. After the shell + itself exits, output from its descendants is still read for 1 s, then + anything left in the group is killed. Nothing in the group outlives the run + (use `setsid`/`nohup` from a terminal for daemons). +- **Statuses:** + - `exited` with `exit_code`, or with `signal` if a signal killed it. + - `stopped`: an operator Stop. This status wins over the exit it caused. + - `failed`: a wait error. + - `interrupted`: the server stopped while the command ran. A server + shutdown kills running groups and records them as interrupted. A starting + server also marks any run still recorded as running as `interrupted` + ("The server stopped while this command was running."). +- **Persistence:** the `chat_shell_runs` table in the server store. It holds + the command, folder, status, exit code or signal, start and end times, + duration, the retained output tail, its start offset and total bytes. The + row is written at start, every 2 s while the command runs, and at the end. + The 50 newest runs per session are kept, and a running run is never + pruned. +- **Share:** `chat_shell_share` refuses a run that is still running. It then + composes an ordinary prompt: the folder, the command in a fence, how the run + ended, and at most the last 16 KiB of output. Fences are longer than any + backtick run in the content. The prompt goes through the normal admission + path (queue, steer, durable queue). The user turn is echoed to the sender + too, because the sender has no local copy. + +## Limits + +| limit | value | +| --- | --- | +| concurrent runs per chat | 4 | +| command length | 16 KiB | +| retained/persisted output per run | 1 MiB (tail) | +| output per readback list entry | 64 KiB (tail) | +| live frame | 64 KiB, 100 ms batching | +| shared with the agent | last 16 KiB | +| runs kept per chat | 50 | +| Stop grace before SIGKILL | 3 s | +| client live text per card | 256 K chars; 64 K chars drawn | + +## Security + +- This is a terminal for the authenticated operator, with the server user's + full privileges. It is reachable only through the existing authenticated + `/connect` websocket. No new HTTP endpoint or listener was added. +- Every request must name a syntactically valid chat session id that the + operator-session registry records. Other requests are refused before + anything runs: unknown ids, pipeline stage sessions, and requests with + malformed ids or no body. Runs are looked up by session and id. Another + session cannot stop, read or share a run, even with its id. +- The command runs on the server that owns the chat, in that chat's + recorded directory, and nowhere else. No remote host is ever named. A + command can still `cd` anywhere the server user may, as in any terminal. + The directory is not restricted to the home folder because chats may + legitimately live outside it (`chat_create` accepts any absolute + directory). Restricting only the starting folder would not contain a + shell, so the honest boundary is the authenticated session. +- Commands and output never reach the model implicitly. Only an explicit + `chat_shell_share` queues a prompt, and it is bounded. +- The process group is killed on Stop, on server shutdown and after the + command exits, so a run cannot leave an orphan holding the server's pipe. + +## Files + +- Server: `internal/protocol/chat_shell_run.go`, + `internal/pipeline/chat_shell_runs.go`, + `internal/server/chat_shell_{runner,supervise,run_output,run_handlers,share}.go`, + and small hooks in `chat.go`, `chat_hub.go`, `chat_stream.go` + (`admitChatPrompt`, `echoSender`) and `websocket.go`. +- App: `lib/features/chat/shell/`: the model, controller, repository, card, + output view, status, actions, dialog, mode indicator and metrics. The + centralized height bound is `chat_shell_metrics.dart`. There are small + hooks in `conversation/chat_thread_view.dart` (controller, rows, card, menu + entry), `conversation/chat_composer_bar.dart` (`runShell`, Shell indicator, + Run label) and `domain/chat_commands.dart` (`/help` line). +- Capture fixture: `tool/perf/chat_shell_fixture.dart` (`?shell=1` with + `?chats=N`). + +## Verification + +- `go test ./internal/protocol ./internal/pipeline ./internal/server`: + `ok …/internal/protocol 0.327s`, `ok …/internal/pipeline 8.092s`, + `ok …/internal/server 82.708s`. +- The new tests also pass under `go test -race -run 'ChatShell(Run|Stop|Share|Retains|Shutdown|Output|SharePrompt)'`. + The race failures in that pattern are the pre-existing + `TestChatShellOutputRealHandler*` tests, which race in + `internal/opencode/connection.go`. They are unrelated to these files. +- New Go tests: + - streaming to two watchers plus persistence (`pwd; echo; >&2; exit 3`); + - Stop reaching the child `sleep` in the group; + - the 4-run limit, blank, oversized, unknown-session, malformed and + foreign-stop refusals, and refusing to share a running run; + - a deleted folder refused; + - share echoing the composed prompt to both clients; + - SIGKILL after the grace period for a SIGINT-ignoring command; + - the 1 MiB tail with a 64 KiB list tail, and no frame over 64 KiB; + - shutdown and restart marking runs interrupted; + - UTF-8 boundaries in chunking; + - share fencing; + - store persistence, pruning and interruption. +- `tool/memwatch/full.sh test/features/chat`: + `memwatch: PASS: 1079 passed, 0 failed, 0 skipped; peak 2206 MB; 186s; exit 0 (test/features/chat)`. +- New widget tests in `test/features/chat/shell/`: + - `!` detection, the Shell indicator and Run label, and that Enter runs + without a `chat_prompt`; + - a refusal keeping the draft, and a bare `!`; + - Run command… from the More menu; + - card states (running with streamed output, stopped, failed with Exit 1, + succeeded with Exit 0) in Material and Cupertino; + - Stop, Send to agent (once), Copy output, and a 2× text scale with + Expand. +- `tool/analyze.sh`: `analyze: 0 errors, 8 warnings, 0 infos`. All 8 + warnings are pre-existing, in the untouched + `integration_test/discovery_probe_test.dart`. +- Real Chrome captures used `tool/capture` over + `tool/search_selection_probe_entry.dart` with `chats=1&msgs=2&shell=1`. + There were two sets: Material light at 880x1000 and Cupertino dark at + 560x1000. Each set has the recorded cards, the Shell indicator with + `!git status --short`, the run started by Enter and finished by its + frames, the More menu with Run command…, and the dialog. The PNGs were + inspected. + +Not verified: a live server and browser session running a real command +end to end. The Go websocket tests cover the server with real processes, and +the browser captures use the fixture channel. Mobile devices were not tested. diff --git a/app/test/features/chat/shell/chat_shell_run_card_test.dart b/app/test/features/chat/shell/chat_shell_run_card_test.dart index 0fe94039..292076fd 100644 --- a/app/test/features/chat/shell/chat_shell_run_card_test.dart +++ b/app/test/features/chat/shell/chat_shell_run_card_test.dart @@ -27,7 +27,7 @@ void main() { expect(find.byKey(const Key('chat-shell-run-running')), findsOneWidget); gateway.emitOutput('run_a', 'line 2\n', 7); await tester.pump(); - expect(find.text('line 1\nline 2\n'), findsOneWidget); + expect(find.text('line 1\nline 2'), findsOneWidget); expect(find.byKey(const Key('chat-shell-run-share')), findsNothing); await tester.tap(find.byKey(const Key('chat-shell-run-stop'))); @@ -43,7 +43,7 @@ void main() { expect(find.text('Stopped · 2.4 s'), findsOneWidget); expect(find.byKey(const Key('chat-shell-run-stop')), findsNothing); // The streamed output stays after the lifecycle frame. - expect(find.text('line 1\nline 2\n'), findsOneWidget); + expect(find.text('line 1\nline 2'), findsOneWidget); }); testWidgets('$host: finished commands show their exit status', ( diff --git a/app/tool/perf/chat_shell_fixture.dart b/app/tool/perf/chat_shell_fixture.dart new file mode 100644 index 00000000..f2a87c5a --- /dev/null +++ b/app/tool/perf/chat_shell_fixture.dart @@ -0,0 +1,185 @@ +// Operator shell commands for the full-app probe (`?shell=1`, with +// `?chats=N`): every fixture chat lists four recorded runs (succeeded, failed, +// stopped and one still running), and chat_shell_run/stop/share answer as the +// server does, with the frames that follow. +import 'package:pipelines_app/core/api_gateway.dart'; + +bool _enabled = false; +DateTime _base = DateTime.now(); + +void configureChatShellFixture(Map params) { + _enabled = params['shell'] == '1'; + _base = DateTime.now().subtract(const Duration(minutes: 3)); +} + +int _at(int seconds) => + _base.add(Duration(seconds: seconds)).millisecondsSinceEpoch; + +String _session(JsonMap request) { + final body = request['chat_shell_run_request'] ?? request['chat_query']; + return body is Map ? '${body['session_id'] ?? ''}' : ''; +} + +JsonMap _run( + String session, + String id, + String command, + int started, { + String status = 'exited', + int? exitCode, + int duration = 0, + String output = '', +}) => { + 'id': id, + 'session_id': session, + 'command': command, + 'directory': '/Users/operator/src/pipelines', + 'status': status, + 'exit_code': ?exitCode, + 'started_at': _at(started), + if (status != 'running') 'ended_at': _at(started) + duration, + 'duration_ms': duration, + 'output': output, + 'output_bytes': output.length, +}; + +List _runs(String session) => [ + _run( + session, + 'run_status', + 'git status --short', + 0, + exitCode: 0, + duration: 84, + output: + ' M app/lib/features/chat/shell/chat_shell_run_card.dart\n' + '?? app/notes/chat-shell-commands.md\n', + ), + _run( + session, + 'run_tests', + 'go test ./internal/server -run ChatShell', + 20, + exitCode: 1, + duration: 4210, + output: + '${[for (final name in _tests) '=== RUN TestChatShell$name\n--- PASS: TestChatShell$name (0.0${name.length % 9}s)\n'].join()}' + '--- FAIL: TestChatShellStopInterruptsTheGroup (0.21s)\n' + ' chat_shell_run_test.go:112: stopped record = {Status:exited}\n' + 'FAIL\n' + 'FAIL\tgit.a-wan.net/alan/pipelines/internal/server\t0.611s\n' + 'FAIL\n', + ), + _run( + session, + 'run_watch', + 'tail -f /var/log/system.log', + 40, + status: 'stopped', + duration: 15200, + output: 'Nov 9 15:58:01 host kernel[0]: wake reason: EC.LidOpen\n', + ), + _run( + session, + 'run_build', + 'flutter build web --target tool/search_selection_probe_entry.dart', + 60, + status: 'running', + output: + 'Compiling lib/main.dart for the Web...\n' + 'Font asset "CupertinoIcons.ttf" was tree-shaken.\n', + ), +]; + +JsonMap? chatShellReply(JsonMap request) { + if (!_enabled) return null; + final id = request['id']; + final session = _session(request); + final body = request['chat_shell_run_request']; + final runId = body is Map ? '${body['run_id'] ?? ''}' : ''; + switch ('${request['type']}') { + case 'chat_shell_runs': + return { + 'id': id, + 'type': 'chat_shell_runs', + 'chat_shell_runs': _runs(session), + }; + case 'chat_shell_run': + return { + 'id': id, + 'type': 'chat_shell_run', + 'chat_shell_run': _run( + session, + 'run_new', + body is Map ? '${body['command'] ?? ''}' : '', + 180, + status: 'running', + ), + }; + case 'chat_shell_stop': + return {'id': id, 'type': 'chat_shell_stop'}; + case 'chat_shell_run_output': + return { + 'id': id, + 'type': 'chat_shell_run_output', + 'chat_shell_run': _runs(session).firstWhere( + (run) => run['id'] == runId, + orElse: () => _runs(session).first, + ), + }; + case 'chat_shell_share': + return {'id': id, 'type': 'chat_prompt'}; + } + return null; +} + +/// The frames the server pushes after a run starts or is stopped. +List chatShellFollowUps(JsonMap request) { + if (!_enabled) return const []; + final session = _session(request); + JsonMap frame(JsonMap body) => { + 'type': 'chat_shell_run_event', + 'chat_shell_run_event': {'session_id': session, ...body}, + }; + switch ('${request['type']}') { + case 'chat_shell_run': + const text = 'hello from the fixture shell\n'; + final body = request['chat_shell_run_request']; + return [ + frame({ + 'run_id': 'run_new', + 'output': text, + 'offset': 0, + 'end': text.length, + }), + frame({ + 'run_id': 'run_new', + 'run': _run( + session, + 'run_new', + body is Map ? '${body['command'] ?? ''}' : '', + 180, + exitCode: 0, + duration: 37, + ), + }), + ]; + case 'chat_shell_stop': + final run = _runs(session).last + ..['status'] = 'stopped' + ..['duration_ms'] = 9100; + return [ + frame({'run_id': run['id'], 'run': run}), + ]; + } + return const []; +} + +const _tests = [ + 'RunStreamsToEveryWatcherAndPersists', + 'RunLimitsAndRefusals', + 'ShareQueuesAnOrdinaryPrompt', + 'RetainsBoundedTail', + 'ShutdownAndRestartInterrupt', + 'OutputKeepsCharactersWhole', +]; diff --git a/app/tool/perf/perf_fixture.dart b/app/tool/perf/perf_fixture.dart index cdde9334..76a5f2f4 100644 --- a/app/tool/perf/perf_fixture.dart +++ b/app/tool/perf/perf_fixture.dart @@ -16,12 +16,15 @@ // `?msgs=`, `?rich=1`, `?older=1`, `?live=N` vary the chat transcripts for // scroll captures (tool/perf/chat_scroll_fixture.dart). // `?question=` pushes an agent question (tool/perf/chat_question_fixture.dart). +// `?shell=1` lists operator shell commands in every chat +// (tool/perf/chat_shell_fixture.dart). // `/new` in a fixture chat moves it to a fresh, empty session // (tool/perf/chat_new_session_fixture.dart). import 'package:pipelines_app/core/api_gateway.dart'; import 'chat_new_session_fixture.dart'; import 'chat_question_fixture.dart'; +import 'chat_shell_fixture.dart'; import 'chat_scroll_fixture.dart'; Map _params = const {}; @@ -35,6 +38,7 @@ void configurePerfFixture(Map params) { ); configureChatScrollFixture(params); configureChatQuestionFixture(params); + configureChatShellFixture(params); } int get _hits => int.tryParse(_params['hits'] ?? '') ?? 0; @@ -126,6 +130,8 @@ bool get _scrollVariety => ['msgs', 'rich', 'older'].any(_params.containsKey); List perfChatFollowUps(JsonMap request) { final answered = chatQuestionFollowUps(request); if (answered.isNotEmpty) return answered; + final shell = chatShellFollowUps(request); + if (shell.isNotEmpty) return shell; final quota = _params['quota']; if (_chats == 0 || quota == null || request['type'] != 'chat_subscribe') { return const []; @@ -226,6 +232,8 @@ JsonMap? perfChatReply(JsonMap request) { if (_chats == 0) return null; final question = chatQuestionReply(request); if (question != null) return question; + final shell = chatShellReply(request); + if (shell != null) return shell; final id = request['id']; switch ('${request['type']}') { case 'chat_sessions':