Files
pipelines/docs/notes/chat-shell-background-process.md
T
alan 7d9490bba1 chat: name the in-flight state, and surface background processes
Two gaps in the chat's in-flight feedback.

The turn indicator no longer reads a bare `Working…` for every state. A new
pure derivation (TurnPhase/turnPhase/turnPhaseLabel in ui/chat/ChatFormat.kt)
labels the headline from evidence already on the wire: `Thinking…` while text
or reasoning deltas are still arriving (within TURN_THINKING_WINDOW_MILLIS),
`Running a tool…` while calls are in flight, `Waiting…` otherwise. No
percentage, ETA or invented progress.

The agent's shell commands are now surfaced end to end as their own frame kind,
so a background process (a dev server, a watching build) that outlives its tool
call is visible and clears when it exits.

Server:
- protocol/chat.go adds ChatEventShell, ChatShell (id, status, command, *int
  exit — a pointer so exit 0 is not "absent") and ChatEventFrame.shell.
- opencode/chat.go maps shell.created/shell.exited through a new exported
  ChatStreamState, attributing created via info.metadata.sessionID and exit via
  the ids the stream already surfaced; another session's or an unattributed
  shell is ignored, an id-less shell fails the stream. No cwd/file/credential is
  carried.
- server/chat_hub.go retains still-running shells (chatShellLimit plus the
  shared byte cap) and drops them on exit; chat_stream.go replays them on
  chat_subscribe, the shell half of the resume (a shell is not a turn, so the
  message snapshot cannot carry it).

App:
- data/protocol/Chat.kt adds ChatShell, ChatEventFrame.shell, EVENT_SHELL,
  SHELL_RUNNING/SHELL_EXITED.
- ui/chat/ChatStore.kt stamps ChatThread.lastDeltaAt on each delta (cleared when
  the turn settles) and keeps ChatThread.shells across a chat switch; a shell
  never marks the thread running. streamResumed drops shells so the subscribe
  replay re-syncs the still-running ones.
- ui/chat/ChatTranscript.kt: RunningIndicator prints the phase label; a new
  always-visible BackgroundProcessBar names each running shell.
- ui/chat/ChatConversationPane.kt shows the bar whenever a shell is running,
  whether or not a turn is.

Tests extend the server's event mapping (opencode/chat_v2_test.go,
server/chat_test.go) and the app's pure folds (new
ui/chat/ChatInFlightStateTest.kt, 15 tests), pinning the shell mapping, the
other-session rejection and the "background process outlives the turn" state.

Checked and intentionally unchanged:
- No packaged OpenCode skill reference documents either surface.
  internal/author/skill/references/operations.md describes the brokered chat_*
  protocol in prose without naming frame kinds or the app indicator, so it stays
  correct as-is; no reference was added, so install.go's managed inventory needs
  no change.
- This repository has no packaged templates directory.
- Shared docs are not edited here per the map: docs/notes/chat-shell-background
  -process.md records what is now stale in docs/cli.md and android/README.md for
  the docs-fold writer.

Verification (this session): gofmt -l clean, go build ./... and go vet ./... OK.
Android unit suite and the on-device capture were run in the preceding review
stage; see the note for the live-verification limitation.
2026-10-18 09:45:28 +01:00

99 lines
5.3 KiB
Markdown

# Chat: an honest in-flight state and background processes
## What this item changed
Both areas, the chat's in-flight feedback.
**Server (`internal/`).**
- `protocol/chat.go` adds the `shell` frame kind (`ChatEventShell`), the
`ChatShell` payload (`id`, `status`, `command`, optional `exit` — a pointer so
exit `0` is not "absent"), the `ChatShellRunning`/`ChatShellExited` statuses and
the `ChatEventFrame.shell` field.
- `opencode/chat.go` maps the location-scoped `shell.created`/`shell.exited`
firehose events onto that frame. A shell belongs to the session that started it
only through `data.info.metadata.sessionID` (the agent's shell tool sets it);
the exit event carries no session at all, so it is emitted only for a shell id
the stream already surfaced. Another session's shell, and a shell with no
attributed session, are ignored; a shell event with no id fails the stream.
`NormalizeChatEvent` now folds a `ChatStreamState` (the retained last message id
plus the session's running shell ids) across frames instead of a bare
`*string`.
- `server/chat_hub.go` retains each session's still-running shells (bounded by
`chatShellLimit` and the per-session byte cap) and clears them on exit;
`server/chat_stream.go` replays them on `chat_subscribe`, the shell half of the
resume (the message snapshot cannot carry a shell, because a shell is not a
turn).
**App (`android/`).**
- `data/protocol/Chat.kt` adds `ChatShell`, `ChatEventFrame.shell`, `EVENT_SHELL`,
`SHELL_RUNNING`/`SHELL_EXITED`.
- `ui/chat/ChatFormat.kt` adds the one pure derivation of a running turn's phase
(`TurnPhase` + `turnPhase` + `turnPhaseLabel` + `TURN_THINKING_WINDOW_MILLIS`)
and of the background processes (`runningBackgroundShells`,
`shellCommandSummary`).
- `ui/chat/ChatStore.kt`: `ChatThread.lastDeltaAt` (stamped on every text/reasoning
delta, cleared when the turn settles) and `ChatThread.shells` (a shell joins on
its running frame and leaves on its exited frame, never marking the thread
running); `thread.phase(now)` and `thread.runningShells`; `streamResumed` drops
shells so the subscribe replay re-syncs the ones still running.
- `ui/chat/ChatTranscript.kt`: `RunningIndicator`'s headline is the phase label
(was the bare `Working…`); a new `BackgroundProcessBar` names each running
shell.
- `ui/chat/ChatConversationPane.kt` shows the bar whenever a shell is running,
whether or not a turn is.
No percentage, ETA or progress bar is invented on either side.
## Shared documents this change makes stale
`docs/cli.md` and `android/README.md`. The note is written here rather than edited
in place; the `docs-fold` writer should update them.
- `docs/cli.md`, the `chat_subscribe` bullet ("`chat_subscribe` attaches a
connection to one session's shared live stream (body `session_id`) and replays
the session's still-pending approval requests…") is now incomplete: attaching
also replays the session's still-running shell commands as `chat_event` frames
of the new kind `shell`, so a device that attaches after a background process
started is shown it.
- `docs/cli.md`, the chat-protocol type list, should name the new `chat_event`
kind `shell`: its payload carries the shell's `id`, `status`
(`running`/`exited`), the `command` it is running and, once it has exited, its
`exit` code. It carries no message id, because a background process outlives the
turn that started it.
- `android/README.md:4719` — the **Running indicator** bullet reads "The
transcript's indicator shows the spinner, `Working…` and the live elapsed
time…". It should say the headline is the turn's actual state — `Thinking…`
while text/reasoning deltas are still arriving, `Running a tool…` while calls
are in flight, `Waiting…` otherwise — derived purely from the tool calls and the
time since the last delta, never an invented percentage/ETA (the one-second
tick, the elapsed living on the thread, and the tool lines below it are still
true).
- `android/README.md` should also record the new always-visible background-process
strip: whenever a shell the agent started is still running it names the
command, it is independent of the turn (a background process can outlive the
turn and is shown then), it survives a chat switch, and it clears the moment the
shell exits.
Dates, counts and capture names in the dated README records are past evidence and
stay as they are; only the behaviour statements above are now stale.
## Not stale
- No packaged OpenCode skill reference documents either surface. The chat
references in `internal/author/skill/references/` document the server's
brokered `chat_*` protocol at a level this change extends additively; nothing
there names the frame kinds or the app indicator.
- `android/AGENTS.md` and `internal/server/AGENTS.md` already list the files
touched, so they need no change.
## Not verified live
The end-to-end behaviour on the operator's phone against a **changed** server was
not captured: the deployed server (`0.0.0.0:8080`) predates the shell mapping, and
redeploying it is forbidden while runs are in flight. The shell mapping itself was
checked against the installed OpenCode 2.0.20 service's own event stream (a
`shell.created` carries `metadata.sessionID`, a `shell.exited` carries only
`id`/`exit`/`status`); the app path is covered by unit tests only.