From 9fa09e6ce8953e8b0ecb281684648b77fd64b378 Mon Sep 17 00:00:00 2001 From: Alan Silva Date: Fri, 16 Oct 2026 03:01:55 +0100 Subject: [PATCH] Add brokered OpenCode chat wire types Add the internal/protocol types the phone needs to talk to OpenCode chat through the Pipelines server (route B): the chat_* request/response type constants (sessions, create, prompt, messages, interrupt, reply) and the server-pushed chat_event frame, plus the part/status/role/tool-state/decision constant sets and payload structs modelled on the verified OpenCode shapes - an assistant turn is a list of parts (text | reasoning | tool), and a tool part carries name, executed, state.status (streaming | running | completed | error), state.input, state.content, state.metadata, state.error and epoch-millisecond timings. Add eight optional omitempty chat fields to the shared Message envelope, so older peers ignore them, and a golden round-trip test covering every new type, an exact-JSON pin of a tool chat_event frame, envelope preservation and omitempty. go test ./internal/protocol/... passes. --- internal/protocol/chat.go | 211 +++++++++++++++++++++++++++++++++ internal/protocol/chat_test.go | 163 +++++++++++++++++++++++++ internal/protocol/message.go | 10 ++ 3 files changed, 384 insertions(+) create mode 100644 internal/protocol/chat.go create mode 100644 internal/protocol/chat_test.go diff --git a/internal/protocol/chat.go b/internal/protocol/chat.go new file mode 100644 index 00000000..9d411210 --- /dev/null +++ b/internal/protocol/chat.go @@ -0,0 +1,211 @@ +package protocol + +import "encoding/json" + +// 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: } 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" + ChatPrompt = "chat_prompt" + ChatMessages = "chat_messages" + ChatInterrupt = "chat_interrupt" + ChatReply = "chat_reply" + // ChatEvent is the server-pushed frame; it is the only type the server + // sends without a matching request. + ChatEvent = "chat_event" +) + +// 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. +const ( + ChatEventText = ChatPartText + ChatEventReasoning = ChatPartReasoning + ChatEventTool = ChatPartTool + ChatEventStep = "step" + ChatEventUsage = "usage" +) + +// 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" +) + +// 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"` + CreatedAt int64 `json:"created_at,omitempty"` + UpdatedAt int64 `json:"updated_at,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"` +} + +// 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. +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"` +} + +// 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"` + Parts []ChatPart `json:"parts"` +} + +// 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. +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. +// 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"` +} + +// 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"` +} + +// ChatReplyRequest is the chat_reply request body: the phone's decision on a +// pending permission request, mirroring +// POST /api/session/{id}/permission/{requestID}/reply. +type ChatReplyRequest struct { + SessionID string `json:"session_id"` + RequestID string `json:"request_id"` + Decision string `json:"decision"` + Message string `json:"message,omitempty"` +} diff --git a/internal/protocol/chat_test.go b/internal/protocol/chat_test.go new file mode 100644 index 00000000..f4dbc4bd --- /dev/null +++ b/internal/protocol/chat_test.go @@ -0,0 +1,163 @@ +package protocol + +import ( + "encoding/json" + "reflect" + "strings" + "testing" +) + +// chatSamples covers every new chat type with a populated value, plus a text and +// a tool chat_event, so a round-trip loss in any field fails the test. +func chatSamples() []struct { + name string + value any +} { + return []struct { + name string + value any + }{ + {"session", ChatSession{ + ID: "ses_1", Title: "demo", Agent: "build", Model: "deepseek-v4.1-flash", + Directory: "/work", ParentID: "ses_0", CreatedAt: 1792112366711, UpdatedAt: 1792112367999, + }}, + {"create", ChatCreateRequest{Title: "demo", Directory: "/work"}}, + {"query", ChatQuery{SessionID: "ses_1", Limit: 50}}, + {"prompt", ChatPromptRequest{SessionID: "ses_1", Text: "hello", Model: "m", Agent: "build", Files: []string{"file:///tmp/a.png"}}}, + {"message", ChatMessage{ + ID: "msg_1", SessionID: "ses_1", Role: ChatRoleAssistant, Model: "m", Agent: "build", CreatedAt: 1792112366711, + Parts: []ChatPart{ + {Type: ChatPartText, ID: "p1", Text: "done"}, + {Type: ChatPartReasoning, ID: "p2", Text: "thinking"}, + {Type: ChatPartTool, ID: "call_1", Name: "shell", Executed: true, + State: &ChatToolState{ + Status: ChatToolCompleted, + Input: json.RawMessage(`{"command":"ls"}`), + Content: []ChatToolContent{{Type: "text", Text: "app-debug.apk"}, {Type: "file", URI: "file:///tmp/x.png", Mime: "image/png", Name: "x.png"}}, + Metadata: map[string]any{"exit": "0"}, + }, + Time: &ChatTime{Created: 1, Ran: 2, Completed: 3}, + }, + {Type: ChatPartTool, ID: "call_2", Name: "edit", + State: &ChatToolState{Status: ChatToolError, Input: json.RawMessage(`{}`), Error: &ChatError{Type: "tool", Message: "boom"}}, + }, + }, + }}, + {"event_text", ChatEventFrame{ + SessionID: "ses_1", MessageID: "msg_1", Kind: ChatEventText, Delta: "hel", + Part: &ChatPart{Type: ChatPartText, ID: "p1"}, + }}, + {"event_tool", ChatEventFrame{ + SessionID: "ses_1", MessageID: "msg_1", Kind: ChatEventTool, + Part: &ChatPart{Type: ChatPartTool, ID: "call_1", Name: "shell", Executed: true, + State: &ChatToolState{Status: ChatToolRunning, Input: json.RawMessage(`{"command":"ls"}`)}, + }, + }}, + {"event_step", ChatEventFrame{SessionID: "ses_1", Kind: ChatEventStep, Step: &ChatStep{Status: ChatStepEnded, Index: 2}}}, + {"event_usage", ChatEventFrame{SessionID: "ses_1", Kind: ChatEventUsage, Usage: &ChatUsage{InputTokens: 12, OutputTokens: 34, Cost: 0.001}}}, + {"reply", ChatReplyRequest{SessionID: "ses_1", RequestID: "req_1", Decision: ChatDecisionOnce, Message: "ok"}}, + } +} + +func TestChatTypesGoldenRoundTrip(t *testing.T) { + for _, sample := range chatSamples() { + encoded, err := json.Marshal(sample.value) + if err != nil { + t.Fatalf("%s: marshal: %v", sample.name, err) + } + target := reflect.New(reflect.TypeOf(sample.value)) + if err := json.Unmarshal(encoded, target.Interface()); err != nil { + t.Fatalf("%s: unmarshal: %v", sample.name, err) + } + decoded := target.Elem().Interface() + if !reflect.DeepEqual(decoded, sample.value) { + t.Fatalf("%s: fields lost\n got %+v\nwant %+v", sample.name, decoded, sample.value) + } + again, err := json.Marshal(decoded) + if err != nil { + t.Fatalf("%s: re-marshal: %v", sample.name, err) + } + if string(again) != string(encoded) { + t.Fatalf("%s: wire shape not stable\n got %s\nwant %s", sample.name, again, encoded) + } + } +} + +// TestChatEventGoldenJSON pins the exact wire shape of a pushed frame so a JSON +// tag change cannot silently alter what the phone parses. +func TestChatEventGoldenJSON(t *testing.T) { + event := ChatEventFrame{ + SessionID: "ses_1", MessageID: "msg_1", Kind: ChatEventTool, + Part: &ChatPart{Type: ChatPartTool, ID: "call_1", Name: "shell", Executed: true, + State: &ChatToolState{ + Status: ChatToolStreaming, + Input: json.RawMessage(`"{\"command\":\"ls\""`), + Content: nil, + }, + Time: &ChatTime{Created: 10, Ran: 11, Completed: 12}, + }, + } + encoded, err := json.Marshal(event) + if err != nil { + t.Fatal(err) + } + want := `{"session_id":"ses_1","message_id":"msg_1","kind":"tool","part":{"type":"tool","id":"call_1","name":"shell","executed":true,"state":{"status":"streaming","input":"{\"command\":\"ls\""},"time":{"created":10,"ran":11,"completed":12}}}` + if string(encoded) != want { + t.Fatalf("golden mismatch\n got %s\nwant %s", encoded, want) + } + var decoded ChatEventFrame + if err := json.Unmarshal([]byte(want), &decoded); err != nil { + t.Fatal(err) + } + if !reflect.DeepEqual(decoded, event) { + t.Fatalf("golden did not decode back: %+v", decoded) + } +} + +func TestChatEnvelopeRoundTrip(t *testing.T) { + session := ChatSession{ID: "ses_1", Title: "demo"} + message := Message{ + Type: ChatSessions, ID: "r1", + ChatSessions: []ChatSession{session}, + ChatSession: &session, + ChatCreate: &ChatCreateRequest{Title: "new"}, + ChatQuery: &ChatQuery{SessionID: "ses_1", Limit: 10}, + ChatPrompt: &ChatPromptRequest{SessionID: "ses_1", Text: "hi"}, + ChatMessages: []ChatMessage{{ID: "msg_1", SessionID: "ses_1", Role: ChatRoleUser, Parts: []ChatPart{{Type: ChatPartText, Text: "hi"}}}}, + ChatEvent: &ChatEventFrame{SessionID: "ses_1", Kind: ChatEventText, Delta: "hi"}, + ChatReply: &ChatReplyRequest{SessionID: "ses_1", RequestID: "req_1", Decision: ChatDecisionReject}, + } + encoded, err := json.Marshal(message) + if err != nil { + t.Fatal(err) + } + var decoded Message + if err := json.Unmarshal(encoded, &decoded); err != nil { + t.Fatal(err) + } + if decoded.Type != ChatSessions || decoded.ID != "r1" { + t.Fatalf("envelope lost: %+v", decoded) + } + if !reflect.DeepEqual(decoded.ChatSessions, message.ChatSessions) || + !reflect.DeepEqual(decoded.ChatSession, message.ChatSession) || + !reflect.DeepEqual(decoded.ChatCreate, message.ChatCreate) || + !reflect.DeepEqual(decoded.ChatQuery, message.ChatQuery) || + !reflect.DeepEqual(decoded.ChatPrompt, message.ChatPrompt) || + !reflect.DeepEqual(decoded.ChatMessages, message.ChatMessages) || + !reflect.DeepEqual(decoded.ChatEvent, message.ChatEvent) || + !reflect.DeepEqual(decoded.ChatReply, message.ChatReply) { + t.Fatalf("chat payloads lost: %+v", decoded) + } +} + +func TestChatFieldsOmittedWhenUnused(t *testing.T) { + minimal, err := json.Marshal(Message{Type: List, ID: "r1"}) + if err != nil { + t.Fatal(err) + } + for _, absent := range []string{"chat_sessions", "chat_session", "chat_create", "chat_query", "chat_prompt", "chat_messages", "chat_event", "chat_reply"} { + if strings.Contains(string(minimal), absent) { + t.Fatalf("absent %q must be omitted: %s", absent, minimal) + } + } +} diff --git a/internal/protocol/message.go b/internal/protocol/message.go index da7c2925..f80556fa 100644 --- a/internal/protocol/message.go +++ b/internal/protocol/message.go @@ -133,4 +133,14 @@ type Message struct { WritePaths []string `json:"write_paths,omitempty"` RequestKey string `json:"request_key,omitempty"` Workspace string `json:"workspace,omitempty"` + // Chat is the brokered OpenCode chat traffic (route B). See chat.go for the + // per-type payload structs and the wire shapes they mirror. + ChatSessions []ChatSession `json:"chat_sessions,omitempty"` + ChatSession *ChatSession `json:"chat_session,omitempty"` + ChatCreate *ChatCreateRequest `json:"chat_create,omitempty"` + ChatQuery *ChatQuery `json:"chat_query,omitempty"` + ChatPrompt *ChatPromptRequest `json:"chat_prompt,omitempty"` + ChatMessages []ChatMessage `json:"chat_messages,omitempty"` + ChatEvent *ChatEventFrame `json:"chat_event,omitempty"` + ChatReply *ChatReplyRequest `json:"chat_reply,omitempty"` }