Files
pipelines/app/notes/chat-shell-commands.md
T
alan cf9f71f27c Show dismissed commands as an answer footer chip; move Copy to the left gutter
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.
2026-11-09 23:47:14 +00:00

309 lines
18 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# 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.