Files
pipelines/docs/notes/chat-transcript-turn-fold.md
T
alan 798e958cb7 chat: fold an agent turn into one reply, split reasoning from answer, keep tool name/input
The phone's chat transcript rendered one agent reply as ~36 bubbles, each with
its own thinking block, and a finished tool call lost its name and its input.

- Turn fold (android): ChatFormat.kt gains the pure ChatTurn / TranscriptRow /
  transcriptRows fold - each run of consecutive assistant messages between two of
  the operator's messages is one agent turn - and ChatTranscript renders one
  bubble per turn: the turn's single collapsible thinking block (all its
  reasoning, in order, growing live while it streams), then its tool-call chips,
  then one answer block of just the turn's text parts. AssistantParts/MessagePart
  are replaced by AgentTurnItem/UserMessageItem; ChatConversationPane counts the
  folded rows.
- Delta part ids (server + client): internal/protocol/chat.go adds
  ChatDeltaPartID(messageID, kind, ordinal), mirrored as ChatProtocol.deltaPartId
  in data/protocol/Chat.kt, and NormalizeChatEvent keys a text or reasoning delta
  on it. OpenCode numbers a message's text and reasoning parts independently from
  0, so the old "%s#%d" gave the first text delta and first reasoning part the
  same id: the answer was appended into the thinking block, and the server's
  retained state (chat_hub.go) re-collided on resume. ChatStore's upsert now
  routes a delta through the kind-aware deltaPartId fold, so it stays robust even
  against a peer that still shares one id.
- Tool fields (server + client): NormalizeChatEvent takes a call's arguments from
  session.tool.input.ended's text as well as session.tool.called's input object
  (toolInput), and chat_hub.go's new mergeChatToolPart folds each tool frame onto
  the retained part so the progress/success frames that omit name and input never
  blank them. ChatFormat.kt's mergeToolPart mirrors that on the client, so the
  chip and panel header keep the real tool name and the panel shows INPUT beside
  OUTPUT.

Tests: chat_v2_test.go and chat_test.go add the text/reasoning id-collision and
the tool name+input retention cases; ChatReasoningTurnTest, ChatTranscriptTest
and ChatRunningWorkTest cover the turn fold, the collision and the tool lifecycle.

Checks: Go build, vet, gofmt and the package tests pass (go build ./... &&
go vet ./...; gofmt -l . empty; go test ./internal/server ./internal/opencode
./internal/protocol ./internal/stage ./internal/pipeline; go test ./...).
Android passes offline with --no-daemon (assembleDebug and the full
testDebugUnitTest suite, 660 tests). The on-phone observation was not performed:
the device lock was held by another run and adb was not available here.

Documentation inventory checked: no packaged OpenCode skill reference in
internal/author/skill/references/ and no packaged template documents the app's
chat transcript, this delta part-id derivation or the tool-field retention, and
no internal/author/ managed file inventory entry names any touched file, so none
of them needs updating. The shared android/README.md behaviour statements are
made stale by this change and are recorded instead in
docs/notes/chat-transcript-turn-fold.md for the docs-fold writer, per the repo
rule that an item never edits a shared document itself.
2026-10-18 01:47:52 +01:00

4.7 KiB

Chat transcript: one agent reply is one bubble

What this item changed

internal/ and android/, the brokered chat transcript. Three defects measured against the operator's own OpenCode (127.0.0.1:49374):

  • Server, delta part ids. internal/protocol/chat.go adds ChatDeltaPartID(messageID, kind, ordinal) (mirrored as ChatProtocol.deltaPartId in android/.../data/protocol/Chat.kt), and internal/opencode/chat.go's NormalizeChatEvent keys a text or reasoning delta on it. OpenCode numbers one message's text and reasoning parts independently from 0, so the old "%s#%d" gave a message's first text delta and its first reasoning part the same id — the client appended the answer into the thinking block and the server's retained state re-collided on resume.
  • Server, tool fields. NormalizeChatEvent now takes a tool call's arguments from session.tool.input.ended's text as well as session.tool.called's input object (toolInput), and internal/server/chat_hub.go's new mergeChatToolPart folds each tool frame onto the retained part so a later progress/success frame that omits the name or the input never blanks it.
  • Android, transcript. ui/chat/ChatFormat.kt adds the pure ChatTurn / TranscriptRow / transcriptRows fold (each run of assistant messages between two of the operator's messages is one agent turn), the kind-aware deltaPartId net and mergeToolPart; ChatStore folds deltas and tool frames through them; ChatTranscript renders one bubble per turn — one thinking block over all the turn's reasoning, then its tool chips, then one answer block of its text parts — replacing AssistantParts/MessagePart with AgentTurnItem/UserMessageItem.

Tests: internal/opencode/chat_v2_test.go and internal/server/chat_test.go add the id-collision and tool name+input retention cases; ChatReasoningTurnTest, ChatTranscriptTest and ChatRunningWorkTest cover the turn fold, the text/reasoning collision and the tool lifecycle on the client.

Shared documents this change makes stale

android/README.md describes the surfaces this item changed. The note is written here rather than edited in place; the docs-fold writer should update it.

  • android/README.md:6021 — the Reasoning collapsed by default bullet reads "ReasoningBlock is now one compact, muted line per part". It should say one block per agent turn: the transcript folds every consecutive assistant message between two of the operator's messages into one ChatTurn, so all the turn's reasoning is one collapsible block (labelled with its step count when it reasoned more than once) and the reply is one bubble, not one per model step.
  • android/README.md:4669 — "ChatScreen.MessagePart now calls MarkdownText(part.text) for PART_TEXT; the assistant message stays one SelectionContainer". MessagePart no longer exists; the answer is MarkdownText(turn.answer) inside AgentTurnItem, where turn.answer is the turn's text parts joined in order. The one-SelectionContainer-per-bubble fact is still true.
  • android/README.md:6040 — the test paragraph's "ChatTranscriptTest, 7 cases" is now 9 (the fold tests); ChatReasoningTurnTest and ChatRunningWorkTest gained the collision and tool-lifecycle cases.
  • android/README.md:4786 — the Grouped chips bullet says "a run of consecutive tool parts in one assistant turn is now one FlowRow". The chips still group in one FlowRow, but the calls shown are now the whole folded turn's (ChatTurn.tools), across every step of the reply, not one assistant message's parts.

Dates, counts and capture names in those dated records are past evidence and stay as they are; only the behaviour statements above are now stale.

Not stale

  • docs/cli.md's and internal/author/skill/references/operations.md's brokered chat sections describe the chat_* surface and its retained per-session/per-message state and resync; that remains true. Neither documents the delta part-id derivation or the tool-field retention, so neither gains a wrong statement — the derivation now lives in the internal/protocol/chat.go comment. The docs-fold writer may add one sentence to the reference's retained-state paragraph if it documents part ids there, but nothing there is now false.
  • No packaged OpenCode skill reference documents the app's chat transcript, and no packaged template or internal/author/ managed file names it.
  • android/AGENTS.md and internal/server/AGENTS.md list the files this item touched (ui/chat/, internal/server/chat_*.go, internal/protocol/, internal/opencode/chat.go); no file moved and no build/test step changed, so both maps stay correct.