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
+4 -5
View File
@@ -17,11 +17,11 @@ import (
)
func TestNormalizeChatEvent(t *testing.T) {
last := "msg_prev"
prior := &ChatStreamState{LastMessageID: "msg_prev"}
cases := []struct {
name string
payload string
last *string
state *ChatStreamState
wantOK bool
wantKind string
wantMsg string
@@ -38,14 +38,13 @@ func TestNormalizeChatEvent(t *testing.T) {
{name: "tool completed", payload: `{"type":"session.tool.success","data":{"sessionID":"ses_1","assistantMessageID":"msg_1","id":"call_1","name":"shell","content":[{"type":"text","text":"ok"}]}}`, wantOK: true, wantKind: protocol.ChatEventTool, wantStatus: protocol.ChatToolCompleted},
{name: "tool failed", payload: `{"type":"session.tool.failed","data":{"sessionID":"ses_1","assistantMessageID":"msg_1","id":"call_1","name":"shell","error":{"type":"tool","message":"boom"}}}`, wantOK: true, wantKind: protocol.ChatEventTool, wantStatus: protocol.ChatToolError},
{name: "usage", payload: `{"type":"session.usage.updated","data":{"sessionID":"ses_1","assistantMessageID":"msg_1","tokens":{"input":12,"output":34},"cost":0.001}}`, wantOK: true, wantKind: protocol.ChatEventUsage, wantUsage: &protocol.ChatUsage{InputTokens: 12, OutputTokens: 34, Cost: 0.001}},
{name: "message id fallback", payload: `{"type":"session.step.started","data":{"sessionID":"ses_1","index":1}}`, last: &last, wantOK: true, wantKind: protocol.ChatEventStep, wantMsg: "msg_prev", wantStep: protocol.ChatStepStarted},
{name: "message id fallback", payload: `{"type":"session.step.started","data":{"sessionID":"ses_1","index":1}}`, state: prior, wantOK: true, wantKind: protocol.ChatEventStep, wantMsg: "msg_prev", wantStep: protocol.ChatStepStarted},
{name: "foreign session skipped", payload: `{"type":"session.text.delta","data":{"sessionID":"ses_other","delta":"x"}}`, wantOK: false},
{name: "unknown type skipped", payload: `{"type":"session.created","data":{"sessionID":"ses_1"}}`, wantOK: false},
}
for _, tc := range cases {
t.Run(tc.name, func(t *testing.T) {
lastID := tc.last
frame, ok, err := NormalizeChatEvent([]byte(tc.payload), "ses_1", lastID)
frame, ok, err := NormalizeChatEvent([]byte(tc.payload), "ses_1", tc.state)
if err != nil {
t.Fatalf("unexpected error: %v", err)
}
+118 -6
View File
@@ -137,8 +137,7 @@ func TestChatDeltaPartIDsNeverCollide(t *testing.T) {
}
ids := map[string]string{}
for kind, payload := range payloads {
last := ""
frame, ok, err := NormalizeChatEvent([]byte(payload), "ses_1", &last)
frame, ok, err := NormalizeChatEvent([]byte(payload), "ses_1", &ChatStreamState{})
if err != nil || !ok {
t.Fatalf("%s delta: ok=%v err=%v", kind, ok, err)
}
@@ -205,8 +204,7 @@ func TestChatToolLifecycleCarriesNameAndInput(t *testing.T) {
}
for _, tc := range frames {
t.Run(tc.name, func(t *testing.T) {
last := ""
frame, ok, err := NormalizeChatEvent([]byte(tc.payload), "ses_1", &last)
frame, ok, err := NormalizeChatEvent([]byte(tc.payload), "ses_1", &ChatStreamState{})
if err != nil || !ok {
t.Fatalf("ok=%v err=%v", ok, err)
}
@@ -246,8 +244,7 @@ func TestChatToolLifecycleCarriesNameAndInput(t *testing.T) {
// that is not yet a complete JSON value must still surface, carried as a JSON
// string so the frame stays valid and the client can show the partial arguments.
func TestChatToolInputFromPartialText(t *testing.T) {
last := ""
frame, ok, err := NormalizeChatEvent([]byte(`{"type":"session.tool.input.ended","data":{"sessionID":"ses_1","assistantMessageID":"msg_1","id":"call_1","text":"{\"command\":\"l"}}`), "ses_1", &last)
frame, ok, err := NormalizeChatEvent([]byte(`{"type":"session.tool.input.ended","data":{"sessionID":"ses_1","assistantMessageID":"msg_1","id":"call_1","text":"{\"command\":\"l"}}`), "ses_1", &ChatStreamState{})
if err != nil || !ok {
t.Fatalf("ok=%v err=%v", ok, err)
}
@@ -266,6 +263,121 @@ func TestChatToolInputFromPartialText(t *testing.T) {
}
}
// TestChatShellEventMapping pins the shell mapping: a shell.created belonging to
// the session surfaces a ChatEventShell frame carrying the shell's id, status and
// command, and the matching shell.exited carries its id, status and exit code.
// The frames carry no message id (a shell outlives the tool call that started
// it), and the exit is a pointer so an exit of 0 is not mistaken for "absent".
func TestChatShellEventMapping(t *testing.T) {
state := &ChatStreamState{}
created, ok, err := NormalizeChatEvent([]byte(`{"type":"shell.created","data":{"info":{"id":"sh_1","status":"running","command":"npm run dev","cwd":"/work","metadata":{"sessionID":"ses_1"}}}}`), "ses_1", state)
if err != nil || !ok {
t.Fatalf("shell.created: ok=%v err=%v", ok, err)
}
if created.Kind != protocol.ChatEventShell || created.Shell == nil {
t.Fatalf("created frame = %+v", created)
}
if created.MessageID != "" {
t.Fatalf("shell frame carried a message id: %q", created.MessageID)
}
if created.Shell.ID != "sh_1" || created.Shell.Status != protocol.ChatShellRunning || created.Shell.Command != "npm run dev" {
t.Fatalf("created shell = %+v", created.Shell)
}
exited, ok, err := NormalizeChatEvent([]byte(`{"type":"shell.exited","data":{"id":"sh_1","exit":0,"status":"exited"}}`), "ses_1", state)
if err != nil || !ok {
t.Fatalf("shell.exited: ok=%v err=%v", ok, err)
}
if exited.Shell == nil || exited.Shell.ID != "sh_1" || exited.Shell.Status != protocol.ChatShellExited {
t.Fatalf("exited shell = %+v", exited.Shell)
}
if exited.Shell.Exit == nil || *exited.Shell.Exit != 0 {
t.Fatalf("exit code = %v, want a present 0", exited.Shell.Exit)
}
// A second exit for the same shell is not this session's any more: the id was
// forgotten once its exit surfaced.
if _, ok, err := NormalizeChatEvent([]byte(`{"type":"shell.exited","data":{"id":"sh_1","exit":0,"status":"exited"}}`), "ses_1", state); err != nil || ok {
t.Fatalf("repeated exit produced a frame: ok=%v err=%v", ok, err)
}
}
// TestChatShellEventForeignSessionIgnored pins the session scoping the shell
// events need: they are location-scoped, so the session that started a shell is
// named only in the created event's metadata. A shell started by another session
// is ignored, and its exit — which names no session at all — is ignored too,
// because the id was never remembered for this session.
func TestChatShellEventForeignSessionIgnored(t *testing.T) {
state := &ChatStreamState{}
foreign := `{"type":"shell.created","data":{"info":{"id":"sh_foreign","status":"running","command":"sleep 120","metadata":{"sessionID":"ses_other"}}}}`
if frame, ok, err := NormalizeChatEvent([]byte(foreign), "ses_1", state); err != nil || ok {
t.Fatalf("another session's shell produced a frame: %+v ok=%v err=%v", frame, ok, err)
}
if _, ok, err := NormalizeChatEvent([]byte(`{"type":"shell.exited","data":{"id":"sh_foreign","exit":0,"status":"exited"}}`), "ses_1", state); err != nil || ok {
t.Fatalf("another session's shell exit produced a frame: ok=%v err=%v", ok, err)
}
// An unattributed shell (no metadata.sessionID) is not this session's either.
unattributed := `{"type":"shell.created","data":{"info":{"id":"sh_anon","status":"running","command":"ls","metadata":{}}}}`
if _, ok, err := NormalizeChatEvent([]byte(unattributed), "ses_1", state); err != nil || ok {
t.Fatalf("unattributed shell produced a frame: ok=%v err=%v", ok, err)
}
}
// TestChatMalformedShellEventFailsStream pins that a shell event which cannot be
// keyed (no shell id) fails the stream instead of producing a frame the client
// cannot attribute.
func TestChatMalformedShellEventFailsStream(t *testing.T) {
cases := []string{
`{"type":"shell.created","data":{"info":{"status":"running","metadata":{"sessionID":"ses_1"}}}}`,
`{"type":"shell.exited","data":{"exit":0,"status":"exited"}}`,
}
for _, payload := range cases {
if _, ok, err := NormalizeChatEvent([]byte(payload), "ses_1", &ChatStreamState{}); err == nil || ok {
t.Fatalf("malformed shell event %s: ok=%v err=%v", payload, ok, err)
}
}
}
// TestChatStreamSurfacesShellLifecycle drives the whole mapping through the SSE
// read loop: a shell started for the session surfaces as a shell frame, a shell
// started by another session is dropped, and the matching exit is surfaced only
// for the session's own shell. It pins that the shell context the exit needs is
// carried across frames by the stream's retained state, not by one payload.
func TestChatStreamSurfacesShellLifecycle(t *testing.T) {
frames := []string{
`{"id":"evt_1","type":"shell.created","data":{"info":{"id":"sh_1","status":"running","command":"npm run dev","metadata":{"sessionID":"ses_1"}}}}`,
`{"id":"evt_2","type":"shell.created","data":{"info":{"id":"sh_other","status":"running","command":"sleep 120","metadata":{"sessionID":"ses_other"}}}}`,
`{"id":"evt_3","type":"session.text.delta","data":{"sessionID":"ses_1","assistantMessageID":"msg_1","ordinal":0,"delta":"hi"}}`,
`{"id":"evt_4","type":"shell.exited","data":{"id":"sh_other","exit":0,"status":"exited"}}`,
`{"id":"evt_5","type":"shell.exited","data":{"id":"sh_1","exit":0,"status":"exited"}}`,
}
srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
w.Header().Set("Content-Type", "text/event-stream")
for _, frame := range frames {
_, _ = w.Write([]byte("data: " + frame + "\n\n"))
}
}))
defer srv.Close()
chat := NewChat(&Connection{Backend: "v2", URL: srv.URL})
ctx, cancel := context.WithTimeout(context.Background(), 5*time.Second)
defer cancel()
var got []protocol.ChatEventFrame
if err := chat.Stream(ctx, "ses_1", nil, func(frame protocol.ChatEventFrame) error {
got = append(got, frame)
return nil
}); err != nil {
t.Fatalf("stream: %v", err)
}
var shellIDs []string
for _, frame := range got {
if frame.Kind == protocol.ChatEventShell && frame.Shell != nil {
shellIDs = append(shellIDs, frame.Shell.ID+":"+frame.Shell.Status)
}
}
if len(shellIDs) != 2 || shellIDs[0] != "sh_1:running" || shellIDs[1] != "sh_1:exited" {
t.Fatalf("shell frames = %v, want only this session's created and exited", shellIDs)
}
}
// TestOpenStreamRejectsUnknownBackend pins that the shared construction path
// validates the backend before any process is started, so OpenStream never
// launches a serve for an unknown backend.