Files
pipelines/docs/notes/chat-transcript-turn-fold.md
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

80 lines
4.7 KiB
Markdown

# 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.