Files
pipelines/docs/notes/chat-shell-background-process.md
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

5.3 KiB

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.