798e958cb7
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.
363 lines
16 KiB
Go
363 lines
16 KiB
Go
package protocol
|
|
|
|
import (
|
|
"encoding/json"
|
|
"fmt"
|
|
)
|
|
|
|
// Chat requests and responses are brokered by the Pipelines server (route B in
|
|
// the OpenCode chat research): the phone keeps talking only to /connect and the
|
|
// server holds the OpenCode credentials, translating each type below to the
|
|
// native service. Like every other exchange, a client sends
|
|
// Message{Type: ChatXxx, ID: <opaque>} and the server echoes the ID on the
|
|
// response.
|
|
//
|
|
// The payloads mirror the verified OpenCode shapes: an assistant turn is a list
|
|
// of parts (text | reasoning | tool), and a tool part carries name, state.status,
|
|
// state.input, state.content, state.metadata, state.error and epoch-millisecond
|
|
// timings. Timings stay integer milliseconds rather than RFC3339 strings so the
|
|
// brokered values match the service exactly; all list fields are optional so
|
|
// older peers ignore them.
|
|
const (
|
|
ChatSessions = "chat_sessions"
|
|
ChatCreate = "chat_create"
|
|
// ChatAdopt records a session that already exists on the configured OpenCode
|
|
// endpoint in the operator-session registry, using the endpoint's own
|
|
// directory and title, so it appears in chat_sessions and can be continued.
|
|
ChatAdopt = "chat_adopt"
|
|
ChatPrompt = "chat_prompt"
|
|
ChatMessages = "chat_messages"
|
|
ChatInterrupt = "chat_interrupt"
|
|
ChatReply = "chat_reply"
|
|
// ChatClose finishes an operator session and records it as closed on the
|
|
// server: any in-flight turn is interrupted through the existing interrupt,
|
|
// nothing is deleted (the session, its transcript and its history survive) and
|
|
// the closed state is shared by every client because it lives in the
|
|
// operator-session registry. ChatReopen clears the closed state again, so a
|
|
// finished chat can be resumed. Both take a ChatQuery (the session id) and
|
|
// echo the updated session like chat_create/chat_adopt. Neither ever touches
|
|
// the pipeline-owned run sessions, and a closed session stays watchable: close
|
|
// only records the finished state, it never detaches a client.
|
|
ChatClose = "chat_close"
|
|
ChatReopen = "chat_reopen"
|
|
// ChatSubscribe attaches a connection to one session's shared live stream so
|
|
// it receives every frame any client's turn produces (its own and the other
|
|
// devices'), not only the frames of a turn it prompted itself. Any number of
|
|
// clients may watch one session; the session is never read-only. The request
|
|
// body is a ChatQuery naming the session and the response echoes the request
|
|
// id once the subscription is attached.
|
|
ChatSubscribe = "chat_subscribe"
|
|
// ChatDirectories is the request/response type for the operator's directory
|
|
// choices: the home directory plus the directories of previous operator
|
|
// sessions, most recently used first, deduplicated and bounded. It is a
|
|
// dedicated request (not a field on chat_sessions) so the create dialog can
|
|
// load the choices without first listing sessions and chat_sessions stays a
|
|
// pure, fail-closed operator-session list.
|
|
ChatDirectories = "chat_directories"
|
|
// ChatEvent and ChatPermission are the server-pushed frames; they are the
|
|
// only types the server sends without a matching request.
|
|
ChatEvent = "chat_event"
|
|
// ChatPermission carries one pending OpenCode approval request the phone
|
|
// answers with chat_reply.
|
|
ChatPermission = "chat_permission"
|
|
)
|
|
|
|
// Content part types carried by ChatPart.Type and ChatEvent.Kind.
|
|
const (
|
|
ChatPartText = "text"
|
|
ChatPartReasoning = "reasoning"
|
|
ChatPartTool = "tool"
|
|
)
|
|
|
|
// ChatEvent.Kind values pushed on the chat_event stream. Step and usage carry
|
|
// no ChatPart; they report turn progress and the turn's totals. User carries the
|
|
// text of a prompt another client sent, so a transcript can show it live; it is
|
|
// never sent back to the client that sent the prompt.
|
|
const (
|
|
ChatEventText = ChatPartText
|
|
ChatEventReasoning = ChatPartReasoning
|
|
ChatEventTool = ChatPartTool
|
|
ChatEventStep = "step"
|
|
ChatEventUsage = "usage"
|
|
ChatEventUser = "user"
|
|
)
|
|
|
|
// ChatStep.Status values, mirroring the OpenCode session.step events.
|
|
const (
|
|
ChatStepStarted = "started"
|
|
ChatStepStreamed = "streamed"
|
|
ChatStepEnded = "ended"
|
|
)
|
|
|
|
// ChatToolState.Status values, mirroring OpenCode's ToolState union.
|
|
const (
|
|
ChatToolStreaming = "streaming"
|
|
ChatToolRunning = "running"
|
|
ChatToolCompleted = "completed"
|
|
ChatToolError = "error"
|
|
)
|
|
|
|
// ChatReplyRequest.Decision values, mirroring the OpenCode permission reply body.
|
|
const (
|
|
ChatDecisionOnce = "once"
|
|
ChatDecisionAlways = "always"
|
|
ChatDecisionReject = "reject"
|
|
)
|
|
|
|
// ChatSession.Tag values. The stored tag vocabulary is exactly
|
|
// ChatSessionTagOperator; the display label the app shows is
|
|
// ChatSessionTagOperatorDisplay, derived from the wire tag rather than carried
|
|
// as a second field so there is no duplicate mapping to drift.
|
|
const (
|
|
ChatSessionTagOperator = "operator"
|
|
ChatSessionTagOperatorDisplay = "Operator"
|
|
)
|
|
|
|
// ChatMessage.Role values.
|
|
const (
|
|
ChatRoleUser = "user"
|
|
ChatRoleAssistant = "assistant"
|
|
)
|
|
|
|
// ChatSession is one createable/listed OpenCode session, flattened for the
|
|
// phone: the nested location.directory and time{created,updated} fields are
|
|
// lifted to Directory, CreatedAt and UpdatedAt.
|
|
type ChatSession struct {
|
|
ID string `json:"id"`
|
|
Title string `json:"title,omitempty"`
|
|
Agent string `json:"agent,omitempty"`
|
|
Model string `json:"model,omitempty"`
|
|
Directory string `json:"directory,omitempty"`
|
|
ParentID string `json:"parent_id,omitempty"`
|
|
// Tag marks the session kind. The only stored value is "operator" (a chat
|
|
// the person created); pipeline stage sessions are never tagged and are never
|
|
// listed by chat_sessions. Additive/omitempty so older peers ignore it.
|
|
Tag string `json:"tag,omitempty"`
|
|
CreatedAt int64 `json:"created_at,omitempty"`
|
|
UpdatedAt int64 `json:"updated_at,omitempty"`
|
|
// Busy is retained for wire compatibility only: it is never set by this
|
|
// server. A session is never read-only, any number of clients may watch and
|
|
// write it, and only a turn is serialised (a waiting prompt is acknowledged
|
|
// as queued on its own client instead of marking the session Busy). Older
|
|
// peers still parse the field; newer ones ignore it.
|
|
Busy bool `json:"busy,omitempty"`
|
|
// Closed records that the operator finished with this session: the server
|
|
// keeps the session, its transcript and its history, but the closed state is
|
|
// shared by every client (it lives in the operator-session registry, not on
|
|
// one device). ClosedAt is the epoch-millisecond close time, 0 while open.
|
|
// Additive/omitempty so older peers ignore them.
|
|
Closed bool `json:"closed,omitempty"`
|
|
ClosedAt int64 `json:"closed_at,omitempty"`
|
|
}
|
|
|
|
// ChatCloseResult reports the outcome of a chat_close: the session id, the
|
|
// epoch-millisecond time the closed state was recorded, and whether an
|
|
// in-flight turn was interrupted to stop it. It is the record that a running
|
|
// turn was stopped, so a stream is never left running into nothing.
|
|
type ChatCloseResult struct {
|
|
SessionID string `json:"session_id"`
|
|
ClosedAt int64 `json:"closed_at"`
|
|
Interrupted bool `json:"interrupted,omitempty"`
|
|
}
|
|
|
|
// ChatCreateRequest is the chat_create request body: a title and an optional
|
|
// working directory (the server's configured location when empty). The response
|
|
// carries the created session in Message.ChatSession.
|
|
type ChatCreateRequest struct {
|
|
Title string `json:"title,omitempty"`
|
|
Directory string `json:"directory,omitempty"`
|
|
}
|
|
|
|
// ChatAdoptRequest is the chat_adopt request body: the id of a session that
|
|
// already exists on the configured endpoint. The server records it in the
|
|
// operator-session registry with the endpoint's own directory and title and
|
|
// echoes the adopted session (and the registry list row) like chat_create.
|
|
type ChatAdoptRequest struct {
|
|
SessionID string `json:"session_id"`
|
|
}
|
|
|
|
// ChatQuery is the session-scoped request body for chat_messages and
|
|
// chat_interrupt, which name their target session through it; Limit caps the
|
|
// returned history (server default when zero).
|
|
type ChatQuery struct {
|
|
SessionID string `json:"session_id"`
|
|
Limit int `json:"limit,omitempty"`
|
|
}
|
|
|
|
// ChatPromptRequest is the chat_prompt request body: the text to send, with an
|
|
// optional model/agent override and attached file URIs. The matching response is
|
|
// the inbox envelope, which the server folds into a ChatMessage. Client is the
|
|
// sending device's human-readable label so every other client can attribute the
|
|
// message; the server sanitises it and falls back to a generic label when it is
|
|
// blank.
|
|
type ChatPromptRequest struct {
|
|
SessionID string `json:"session_id"`
|
|
Text string `json:"text"`
|
|
Model string `json:"model,omitempty"`
|
|
Agent string `json:"agent,omitempty"`
|
|
Files []string `json:"files,omitempty"`
|
|
Client string `json:"client,omitempty"`
|
|
}
|
|
|
|
// ChatMessage is one stored turn returned by chat_messages. A user turn is a
|
|
// single text part; an assistant turn holds the text, reasoning and tool parts
|
|
// the phone renders. Parts corresponds to the OpenCode content array.
|
|
type ChatMessage struct {
|
|
ID string `json:"id"`
|
|
SessionID string `json:"session_id"`
|
|
Role string `json:"role"`
|
|
Model string `json:"model,omitempty"`
|
|
Agent string `json:"agent,omitempty"`
|
|
CreatedAt int64 `json:"created_at,omitempty"`
|
|
// Client is the sending device's label on a user turn the server echoed, so a
|
|
// resumed transcript still says who sent the message. It is empty on an
|
|
// assistant turn.
|
|
Client string `json:"client,omitempty"`
|
|
Parts []ChatPart `json:"parts"`
|
|
}
|
|
|
|
// ChatDeltaPartID is the stable part id an incremental text or reasoning delta
|
|
// stream addresses. OpenCode numbers one message's text and reasoning parts
|
|
// independently from 0, so the kind is part of the id: for a single message its
|
|
// first text delta and its first reasoning delta are distinct ids and a delta can
|
|
// never be appended into the other kind's part. The derivation is deterministic,
|
|
// so a reconnect or a resume re-addresses the same part, and it is mirrored in
|
|
// the client's ChatProtocol.deltaPartId (data/protocol/Chat.kt).
|
|
func ChatDeltaPartID(messageID, kind string, ordinal int) string {
|
|
return fmt.Sprintf("%s#%s#%d", messageID, kind, ordinal)
|
|
}
|
|
|
|
// ChatPart is one element of a ChatMessage. Type selects the meaning: text and
|
|
// reasoning use Text and ID, tool uses ID, Name, Executed, State and Time. A text
|
|
// or reasoning part's ID is ChatDeltaPartID(message id, kind, ordinal), so the two
|
|
// kinds never share an id within a message.
|
|
type ChatPart struct {
|
|
Type string `json:"type"`
|
|
ID string `json:"id,omitempty"`
|
|
Text string `json:"text,omitempty"`
|
|
Name string `json:"name,omitempty"`
|
|
Executed bool `json:"executed,omitempty"`
|
|
State *ChatToolState `json:"state,omitempty"`
|
|
Time *ChatTime `json:"time,omitempty"`
|
|
}
|
|
|
|
// ChatToolState is the lifecycle of a tool call. Input is a raw JSON value: a
|
|
// partial-JSON string while streaming, an object once running or completed.
|
|
// OpenCode spreads one call across several frames (name in input.started, the
|
|
// arguments in input.ended's text or called's input, then progress/success
|
|
// carrying neither), so Input is absent on the frames that do not carry it and
|
|
// every consumer retains the value it already learned instead of blanking it.
|
|
// Content is the tool's textual/file result, Metadata its provider stats,
|
|
// Error the structured failure for status "error".
|
|
type ChatToolState struct {
|
|
Status string `json:"status"`
|
|
Input json.RawMessage `json:"input,omitempty"`
|
|
Content []ChatToolContent `json:"content,omitempty"`
|
|
Metadata map[string]any `json:"metadata,omitempty"`
|
|
Error *ChatError `json:"error,omitempty"`
|
|
}
|
|
|
|
// ChatToolContent is one returned tool result: either text or a file/uri pair
|
|
// (so a tool can return an image the phone renders).
|
|
type ChatToolContent struct {
|
|
Type string `json:"type"`
|
|
Text string `json:"text,omitempty"`
|
|
URI string `json:"uri,omitempty"`
|
|
Mime string `json:"mime,omitempty"`
|
|
Name string `json:"name,omitempty"`
|
|
}
|
|
|
|
// ChatError is the structured error attached to a failed tool call.
|
|
type ChatError struct {
|
|
Type string `json:"type,omitempty"`
|
|
Message string `json:"message,omitempty"`
|
|
}
|
|
|
|
// ChatTime is the epoch-millisecond timing envelope of a tool call.
|
|
type ChatTime struct {
|
|
Created int64 `json:"created,omitempty"`
|
|
Ran int64 `json:"ran,omitempty"`
|
|
Completed int64 `json:"completed,omitempty"`
|
|
}
|
|
|
|
// ChatEventFrame is the server-pushed chat_event frame. Kind selects the
|
|
// payload: text and reasoning carry an incremental Delta plus the target Part,
|
|
// tool carries a full Part with its state, step marks turn progress and usage
|
|
// reports the turn's totals.
|
|
type ChatEventFrame struct {
|
|
SessionID string `json:"session_id"`
|
|
MessageID string `json:"message_id,omitempty"`
|
|
Kind string `json:"kind"`
|
|
Delta string `json:"delta,omitempty"`
|
|
Part *ChatPart `json:"part,omitempty"`
|
|
Step *ChatStep `json:"step,omitempty"`
|
|
Usage *ChatUsage `json:"usage,omitempty"`
|
|
// Client is the sending device's label on a user frame (ChatEventUser), so a
|
|
// transcript can say who sent the message. It is empty on assistant frames.
|
|
Client string `json:"client,omitempty"`
|
|
}
|
|
|
|
// ChatStep is a progress marker for the current step of a turn.
|
|
type ChatStep struct {
|
|
Status string `json:"status"`
|
|
Index int `json:"index,omitempty"`
|
|
}
|
|
|
|
// ChatUsage is the token and cost total of a turn.
|
|
type ChatUsage struct {
|
|
InputTokens int `json:"input_tokens,omitempty"`
|
|
OutputTokens int `json:"output_tokens,omitempty"`
|
|
Cost float64 `json:"cost,omitempty"`
|
|
}
|
|
|
|
// ChatPermissionFrame is the server-pushed chat_permission payload: one pending
|
|
// OpenCode permission request the phone must approve or reject. It is a distinct
|
|
// Message field (like ChatEvent) rather than a ChatEvent.Kind, so it does not
|
|
// overload the turn-progress kinds. Its field names match the service's
|
|
// Permission.Request schema, verified against the installed service's
|
|
// /openapi.json (id, sessionID, action and resources required; save, metadata,
|
|
// source and message optional), with id -> RequestID and sessionID -> SessionID.
|
|
// The wire shape is spec-verified; a live pending request has not been observed.
|
|
// Every optional field is omitempty so older peers ignore it.
|
|
type ChatPermissionFrame struct {
|
|
SessionID string `json:"session_id"`
|
|
RequestID string `json:"request_id"`
|
|
Action string `json:"action,omitempty"`
|
|
Resources []string `json:"resources,omitempty"`
|
|
Save []string `json:"save,omitempty"`
|
|
Metadata map[string]any `json:"metadata,omitempty"`
|
|
Source *ChatPermissionSource `json:"source,omitempty"`
|
|
Message string `json:"message,omitempty"`
|
|
// Resolved, Decision and ResolvedBy report the shared, exactly-once outcome
|
|
// of a request any client may answer: once the first answer is recorded the
|
|
// server pushes the same frame back to every watching client with Resolved
|
|
// set, the Decision it recorded and the label of the client that gave it, so
|
|
// their cards clear and show the outcome instead of offering a stale choice.
|
|
// They are empty on a still-pending request.
|
|
Resolved bool `json:"resolved,omitempty"`
|
|
Decision string `json:"decision,omitempty"`
|
|
ResolvedBy string `json:"resolved_by,omitempty"`
|
|
}
|
|
|
|
// ChatPermissionSource identifies what raised a permission request, matching the
|
|
// Permission.Source union (currently only a tool call: type "tool" plus the
|
|
// message and call id) verified against the service's /openapi.json.
|
|
type ChatPermissionSource struct {
|
|
Type string `json:"type,omitempty"`
|
|
MessageID string `json:"message_id,omitempty"`
|
|
ID string `json:"id,omitempty"`
|
|
}
|
|
|
|
// ChatReplyRequest is the chat_reply request body: the phone's decision on a
|
|
// pending permission request, mirroring
|
|
// POST /api/session/{id}/permission/{requestID}/reply. Client is the answering
|
|
// device's label, recorded with the resolution so every other client can see
|
|
// which device answered.
|
|
type ChatReplyRequest struct {
|
|
SessionID string `json:"session_id"`
|
|
RequestID string `json:"request_id"`
|
|
Decision string `json:"decision"`
|
|
Message string `json:"message,omitempty"`
|
|
Client string `json:"client,omitempty"`
|
|
}
|