Files
pipelines/app/notes/chat-shell-commands.md
T
alan 5c3248a48d Record chat shell commands with fixture captures and a note
Show Expand only when output can overflow and drop the final newline from
the drawn output. The full-app probe lists shell runs with ?shell=1 so the
cards, Shell mode and Run command dialog can be captured in Chrome.
2026-11-09 16:21:15 +00:00

11 KiB
Raw Blame History

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.

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.