Files
pipelines/internal/protocol/chat.go
T

416 lines
19 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"
// ChatEventShell reports the lifecycle of one shell the agent started. It
// carries no ChatPart and no message id: a shell can outlive the tool call
// that started it, so it is a frame of its own rather than a tool part.
ChatEventShell = "shell"
)
// ChatShell.Status values, mirroring the OpenCode shell events. A running shell
// is one whose command has started and not yet exited; exited is final.
const (
ChatShellRunning = "running"
ChatShellExited = "exited"
)
// 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). OperationID
// is the durable idempotency key for this create intent; it is deliberately
// separate from Message.ID, which remains connection-local response
// correlation. Clients retrying a create across reconnects must retain it. The
// response carries the created session in Message.ChatSession.
type ChatCreateRequest struct {
Title string `json:"title,omitempty"`
Directory string `json:"directory,omitempty"`
OperationID string `json:"operation_id,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"`
// Cursor is the opaque continuation returned by OpenCode's descending
// message listing. It is deliberately not interpreted by the broker.
Cursor string `json:"cursor,omitempty"`
}
// ChatHistoryPage describes the bounded slice returned by chat_messages. The
// newest page has an empty Cursor request; NextCursor remains opaque and is
// supplied unchanged to fetch older turns.
type ChatHistoryPage struct {
Messages []ChatMessage `json:"messages"`
NextCursor string `json:"next_cursor,omitempty"`
HasMore bool `json:"has_more,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"`
OperationID string `json:"operation_id,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"`
OperationID string `json:"operation_id,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"`
// Truncated says Content is a bounded preview of a larger stored result.
// The turn remains usable; callers must not present the preview as complete.
Truncated bool `json:"truncated,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"`
// Shell is the payload of a ChatEventShell frame: the shell's id, its
// status, the command it is running and (once it has exited) its exit code.
// It is nil on every other kind.
Shell *ChatShell `json:"shell,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"`
OperationID string `json:"operation_id,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"`
}
// ChatShell is the state of one shell command the agent started, carried by a
// ChatEventShell frame. ID is the OpenCode shell id and is stable across its
// created and exited events, so a client keys a running process by it. Status is
// ChatShellRunning or ChatShellExited; Command is the command line the shell was
// given (present on the created event); Exit is the process exit code and is
// present only once the shell has exited — it is a pointer so an exit of 0 is
// distinguishable from "not exited yet". No credential, environment or output is
// carried: the command line is the only text, and only so the operator can name
// what is running.
type ChatShell struct {
ID string `json:"id"`
Status string `json:"status,omitempty"`
Command string `json:"command,omitempty"`
Exit *int `json:"exit,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"`
}