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.
This commit is contained in:
2026-10-18 09:45:28 +01:00
parent 5a4cfc2e9c
commit 7d9490bba1
14 changed files with 1053 additions and 34 deletions
+142 -8
View File
@@ -325,7 +325,7 @@ func (c *Chat) Stream(ctx context.Context, id string, ready func(), emit func(pr
func scanChatEvents(ctx context.Context, body io.Reader, sessionID string, emit func(protocol.ChatEventFrame) error) error {
scanner := bufio.NewScanner(body)
scanner.Buffer(make([]byte, 0, 64<<10), MaxResponse)
lastMessageID := ""
state := &ChatStreamState{}
for scanner.Scan() {
if err := ctx.Err(); err != nil {
return err
@@ -338,7 +338,7 @@ func scanChatEvents(ctx context.Context, body io.Reader, sessionID string, emit
if len(payload) == 0 {
continue
}
frame, ok, err := NormalizeChatEvent(payload, sessionID, &lastMessageID)
frame, ok, err := NormalizeChatEvent(payload, sessionID, state)
if err != nil {
return err
}
@@ -346,7 +346,7 @@ func scanChatEvents(ctx context.Context, body io.Reader, sessionID string, emit
continue
}
if frame.MessageID != "" {
lastMessageID = frame.MessageID
state.LastMessageID = frame.MessageID
}
if err := emit(frame); err != nil {
return err
@@ -372,7 +372,8 @@ func isChatEventType(t string) bool {
"session.usage.updated",
"session.tool.input.started", "session.tool.input.ended",
"session.tool.called", "session.tool.progress",
"session.tool.success", "session.tool.failed":
"session.tool.success", "session.tool.failed",
"shell.created", "shell.exited":
return true
}
return false
@@ -403,13 +404,92 @@ type chatEvent struct {
Input int `json:"input"`
Output int `json:"output"`
} `json:"tokens"`
// The shell family. shell.created nests the started command under info;
// shell.exited carries the id, the final status and the exit code at the top
// level. Exit is a pointer so an exit of 0 is distinguishable from absent.
Status string `json:"status"`
Exit *int `json:"exit"`
Info *chatShellInfo `json:"info"`
}
// chatShellInfo is the Shell.Info envelope a shell.created event nests under
// "info". The session that started the shell is reported in metadata.sessionID
// (the agent's shell tool sets it); only the fields the protocol surfaces are
// read, and the shell's cwd/file are deliberately not carried so no path or
// credential leaks into a frame.
type chatShellInfo struct {
ID string `json:"id"`
Status string `json:"status"`
Command string `json:"command"`
Metadata map[string]any `json:"metadata"`
}
// shellSessionID reads the session that started a shell from the created event's
// metadata, or "" when the event carries none. The agent's shell tool sets
// metadata.sessionID; a shell started by anything else is unattributed and is
// ignored, so a shell that cannot be shown to belong to this session never
// becomes one of its frames.
func (i *chatShellInfo) shellSessionID() string {
if i == nil || i.Metadata == nil {
return ""
}
id, _ := i.Metadata["sessionID"].(string)
return id
}
// ChatStreamState is the per-session memory one event stream folds across its
// frames, so a frame that omits context can still be attributed. It is the
// single state NormalizeChatEvent reads and writes; a caller that maps a lone
// event passes an empty state (or nil when it needs no attribution).
//
// - LastMessageID is the most recent assistant message id, so a later tool or
// step event that omits it still attributes every frame to a stable message.
// - Shells holds the ids of the shells this session has started and not yet
// seen exit. shell.exited carries no session id, so the id remembered here is
// what attributes the exit to its session: another session's shell is an
// unknown id and is ignored.
type ChatStreamState struct {
LastMessageID string
Shells map[string]struct{}
}
// knowsShell reports whether id is a shell this stream has already surfaced for
// the session, and so is one this stream may now report the exit of.
func (s *ChatStreamState) knowsShell(id string) bool {
if s == nil || id == "" {
return false
}
_, ok := s.Shells[id]
return ok
}
// markShell remembers id as a shell of this session.
func (s *ChatStreamState) markShell(id string) {
if s == nil || id == "" {
return
}
if s.Shells == nil {
s.Shells = map[string]struct{}{}
}
s.Shells[id] = struct{}{}
}
// forgetShell drops id once its exit has been surfaced.
func (s *ChatStreamState) forgetShell(id string) {
if s == nil || s.Shells == nil {
return
}
delete(s.Shells, id)
}
// NormalizeChatEvent maps one OpenCode firehose `data:` payload to a
// protocol.ChatEventFrame. ok is false for an event type this adapter does not
// protocol.ChatEventFrame, folding the small per-session context ([stream]) it
// needs across frames. ok is false for an event type this adapter does not
// surface or one belonging to a different session, so the caller can skip it
// without emitting a frame. Malformed JSON returns an error and never a frame.
func NormalizeChatEvent(payload []byte, sessionID string, lastMessageID *string) (protocol.ChatEventFrame, bool, error) {
// stream may be nil when the caller maps a lone event and needs no attribution;
// a nil stream simply means no inherited message id and no remembered shell.
func NormalizeChatEvent(payload []byte, sessionID string, stream *ChatStreamState) (protocol.ChatEventFrame, bool, error) {
var outer struct {
Type string `json:"type"`
Data json.RawMessage `json:"data"`
@@ -432,6 +512,14 @@ func NormalizeChatEvent(payload []byte, sessionID string, lastMessageID *string)
if err := json.Unmarshal(outer.Data, &data); err != nil {
return protocol.ChatEventFrame{}, false, fmt.Errorf("malformed OpenCode event data: %w", err)
}
// The shell events are location-scoped, not session-scoped: the session that
// started a shell is reported in the created event's metadata, and the exit
// names no session at all, so it is attributed through the ids this stream
// already surfaced. They are mapped before the session check the other events
// use, which their absent data.sessionID could never pass.
if outer.Type == "shell.created" || outer.Type == "shell.exited" {
return normalizeShellEvent(outer.Type, data, sessionID, stream)
}
if data.SessionID != sessionID {
return protocol.ChatEventFrame{}, false, nil
}
@@ -439,8 +527,8 @@ func NormalizeChatEvent(payload []byte, sessionID string, lastMessageID *string)
if messageID == "" {
messageID = data.MessageIDAlt
}
if messageID == "" && lastMessageID != nil {
messageID = *lastMessageID
if messageID == "" && stream != nil {
messageID = stream.LastMessageID
}
// Every pushed frame must carry a stable message id so the client can
// attribute it; without one this is not a chat frame.
@@ -481,6 +569,52 @@ func NormalizeChatEvent(payload []byte, sessionID string, lastMessageID *string)
return frame, true, nil
}
// normalizeShellEvent maps one shell.created/shell.exited payload onto a
// protocol.ChatEventShell frame. A shell belongs to the session whose id the
// created event carries in info.metadata.sessionID, so a shell started by any
// other session is ignored (ok=false) rather than shown in this session. The
// exit event carries no session at all, so it is emitted only for a shell id
// this stream already surfaced for the session; any other id is another
// session's and is ignored. An event that carries no shell id at all cannot be
// keyed by the client and is malformed, so it fails the stream instead of
// producing a frame the client cannot attribute.
func normalizeShellEvent(eventType string, data chatEvent, sessionID string, stream *ChatStreamState) (protocol.ChatEventFrame, bool, error) {
if eventType == "shell.created" {
if data.Info == nil || data.Info.ID == "" {
return protocol.ChatEventFrame{}, false, fmt.Errorf("malformed OpenCode shell.created event")
}
if data.Info.shellSessionID() != sessionID {
return protocol.ChatEventFrame{}, false, nil
}
status := data.Info.Status
if status == "" {
status = protocol.ChatShellRunning
}
stream.markShell(data.Info.ID)
return protocol.ChatEventFrame{
SessionID: sessionID,
Kind: protocol.ChatEventShell,
Shell: &protocol.ChatShell{ID: data.Info.ID, Status: status, Command: data.Info.Command},
}, true, nil
}
if data.ID == "" {
return protocol.ChatEventFrame{}, false, fmt.Errorf("malformed OpenCode shell.exited event")
}
if !stream.knowsShell(data.ID) {
return protocol.ChatEventFrame{}, false, nil
}
stream.forgetShell(data.ID)
status := data.Status
if status == "" {
status = protocol.ChatShellExited
}
return protocol.ChatEventFrame{
SessionID: sessionID,
Kind: protocol.ChatEventShell,
Shell: &protocol.ChatShell{ID: data.ID, Status: status, Exit: data.Exit},
}, true, nil
}
// toolInput picks a tool call's arguments from whichever frame carries them:
// session.tool.called carries the parsed `input` object, session.tool.input.ended
// carries the same arguments as a `text` JSON string, and progress/success carry