cf9f71f27c
Dismissed shell runs leave the transcript and fold into a "N commands" chip in the footer of the first answer at or after each run (the last answer for newer runs, or a row of its own without any answer). The chip opens the turn sheet (wide) or a full-screen page (narrow) listing the commands; each opens its output read-only with Copy output, Send to agent and Restore. On a wide conversation the answer's Copy button moves out of the footer into a 48 px gutter left of the reading column (chatCopyGutter), shown on hover or focus on desktops and always on touch; narrow widths keep it in the footer.
309 lines
18 KiB
Markdown
309 lines
18 KiB
Markdown
# 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 `!<command>` 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 <command>`. 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.
|
||
|
||
## Dismissing commands
|
||
|
||
- A finished card (exited, stopped, failed, interrupted) has a Dismiss
|
||
button: a close icon with the tooltip (Material) or semantics label
|
||
(Cupertino) "Dismiss". The card has no menu, so there is no menu entry.
|
||
- A running card has no Dismiss. Stop it first; once it ends, Dismiss
|
||
appears. This was chosen over "Stop and dismiss" because a command that
|
||
ignores SIGINT keeps running for the grace period, and hiding a live
|
||
process's card would be confusing.
|
||
- The chat's More menu has "Dismiss all finished commands" when at least one
|
||
run has finished. It dismisses every finished run and leaves running ones.
|
||
- Dismissal is per chat, for every client (not per device). The card goes at
|
||
once. A refusal brings the card back with the server's reason.
|
||
- History: a dismissed card is not lost. It moves into a "N commands" chip
|
||
in an answer's footer (see "Command history" below), which can restore it.
|
||
There is no Undo notice.
|
||
- Server design (since 2026-11-09): dismiss keeps the run.
|
||
`chat_shell_dismiss {session_id, run_ids}` sets `dismissed_at` on finished
|
||
runs and pushes `chat_shell_run_event {dismissed: true}` to every watcher.
|
||
The command, folder, status, exit code, times, output tail (1 MiB) and
|
||
plain-text rendering stay, within the usual 50-run history. Nothing is
|
||
purged: the undo window, its `AfterFunc` and the startup purge are gone.
|
||
`chat_shell_restore {session_id, run_ids}` clears `dismissed_at` at any
|
||
time. The reply carries the runs, and watchers get lifecycle frames.
|
||
- Readback: `chat_shell_runs` leaves dismissed runs out of
|
||
`chat_shell_runs`, lists their ids in `chat_shell_dismissed` (as before)
|
||
and the runs themselves in `chat_shell_dismissed_runs` (oldest first,
|
||
64 KiB tail each, `dismissed: true`, `dismissed_at`).
|
||
`chat_shell_run_output` and `chat_shell_share` work for a dismissed run.
|
||
- Older rows: a run an older server already purged keeps `purged = 1`. It is
|
||
listed with `purged: true` and no command or output. The app shows it as
|
||
"Command not kept" / "Output not kept" and offers no Restore (the server
|
||
refuses to restore it).
|
||
- Files: `internal/protocol/chat_shell_dismiss.go`,
|
||
`internal/pipeline/chat_shell_dismiss.go`,
|
||
`internal/server/chat_shell_dismiss.go`,
|
||
`lib/features/chat/shell/chat_shell_dismiss.dart` (button, menu entry)
|
||
and `chat_shell_runs_dismissal.dart` (controller part).
|
||
- Tests and verification of the first version (superseded where they
|
||
mention Undo or purging; see "Command history" below for the current
|
||
tests): `internal/pipeline/chat_shell_dismiss_test.go` covers dismiss,
|
||
readback, restore, purge and tombstones.
|
||
`internal/server/chat_shell_dismiss_test.go` covers the websocket dismiss
|
||
to two watchers, refusing a running or empty request, readback with
|
||
tombstones, refusing output for a dismissed run, Undo, and purge after the
|
||
window and on restart. `test/features/chat/shell/chat_shell_dismiss_test.dart`
|
||
covers the button, Undo and notice expiry (both hosts), a refused dismiss,
|
||
the menu entry's absence and dismiss-all, another client's dismissal and
|
||
restore, and tombstone readback.
|
||
- Verification (2026-11-09): `go test ./internal/protocol ./internal/pipeline
|
||
./internal/server` all ok. `tool/memwatch/full.sh test/features/chat`
|
||
gives `PASS: 1146 passed, 0 failed`. `tool/analyze.sh` is clean. Real
|
||
Chrome captures (`tool/capture`, `chats=1&msgs=2&shell=1`) covered Material
|
||
light 880x1000 and Cupertino dark 560x1000: cards with Dismiss, the Undo
|
||
notice, the restored card, the More menu entry, dismiss-all with its
|
||
notice, and (Cupertino) the notice gone after 5 s. The PNGs were inspected.
|
||
A live server and browser session was not exercised end to end.
|
||
|
||
## 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.
|
||
|
||
**Update:** dismissing no longer shows a notice or Undo; the card simply
|
||
goes away (operator request).
|
||
|
||
## Command history (2026-11-09)
|
||
|
||
Operator request: "when we dismiss a command, it should show in the bottom
|
||
like the files changes, model, etc, so that I can expand and see the
|
||
history."
|
||
|
||
- A dismissed run leaves the transcript and shows as a chip in an answer's
|
||
footer, in the same row and chip family (`ChatTurnChip`) as
|
||
"3 files changed +9 −2", the tool chips, the model and the time: a terminal
|
||
icon and "2 commands".
|
||
- Placement (`shell/chat_shell_history.dart`, `attachChatShellHistory`):
|
||
each run goes to the first assistant reply created at or after the run
|
||
started. A run newer than every reply goes to the last reply. A chat with
|
||
no reply shows the chip on its own row at the end of the transcript.
|
||
- Tapping the chip opens the turn sheet on a wide window (≥ 600 px) or a
|
||
full-screen page on a narrow one, like the diff chip. "Dismissed commands"
|
||
lists each command with its exit status chip and duration, its start time,
|
||
and Restore. Tapping a command opens its whole retained output read-only
|
||
in the card's terminal view (`chat_shell_run_output`), with Copy output,
|
||
Send to agent and Restore. Restore puts the card back in the transcript for
|
||
every client. A refusal shows the server's reason under the entry.
|
||
- Multi-machine: everything goes through the chat's own gateway, as cards do.
|
||
- Files: `lib/features/chat/shell/chat_shell_history.dart` (placement,
|
||
labels), `chat_shell_history_chip.dart`, `chat_shell_history_view.dart`,
|
||
`chat_shell_history_output_page.dart`; controller part
|
||
`chat_shell_runs_dismissal.dart` (`dismissedRuns`, `restore`,
|
||
`fullOutput`); hooks in `conversation/chat_thread_view.dart`. Server:
|
||
`internal/{protocol,pipeline,server}/chat_shell_dismiss.go`.
|
||
- Tests: `internal/pipeline/chat_shell_dismiss_test.go` (dismiss keeps
|
||
output, readback, restore without a time limit, older purged tombstones,
|
||
dismissed runs counting toward the 50-run history);
|
||
`internal/server/chat_shell_dismiss_test.go` (websocket dismiss to two
|
||
watchers, readback of dismissed runs with output, output read of a
|
||
dismissed run, restore, restore a day later after a restart);
|
||
`test/features/chat/shell/chat_shell_history_test.dart` (placement rules)
|
||
and `chat_shell_history_view_test.dart` (chip in the right answer's
|
||
footer, the no-reply row, dismiss moving a card into the chip, sheet,
|
||
output, Copy, Send to agent, Restore, narrow page, purged rows, a refused
|
||
restore).
|
||
- Capture fixture: `?shell_dismissed=run_status,run_tests` starts with those
|
||
runs dismissed (`tool/perf/chat_shell_fixture.dart`).
|
||
- Verification (2026-11-09): `go test ./internal/protocol ./internal/pipeline
|
||
./internal/server` all ok (server 74 s). `tool/memwatch/full.sh
|
||
test/features/chat`: `PASS: 1161 passed, 0 failed`. `tool/analyze.sh`:
|
||
clean. Real Chrome captures (`tool/capture`,
|
||
`chats=1&msgs=4&shell=1&rich=1&shell_dismissed=run_status,run_tests`),
|
||
Material light and dark: at 1400x900 the footer chip, the sheet and a
|
||
command's output page; at 560x1000 the footer chip, the full-screen list
|
||
and the list after Restore, plus (light) the restored card back in the
|
||
transcript with "1 command". The PNGs were inspected. Cupertino, a live
|
||
server end to end and mobile devices were not exercised.
|