5946f1abc8
Use an explicit chat_create operation_id as the durable bootstrap key while retaining envelope IDs for reply correlation. Legacy requests receive fresh server-scoped identities, so independent cli-1/android-1 requests do not collide; clients that retry retain one operation_id. Update Android creation state and repository calls to preserve an operation identity across retries, and cover durable reconnect retries, duplicate barriers, changed input, legacy correlation reuse, and protocol serialization. Checked packaged templates: none describe chat_create. Checked packaged authoring-skill references: the existing description is stale, but shared references and README must not be edited by an item; docs/notes/bootstrap-create-identity.md records the required docs-fold update and rollout compatibility.
413 lines
19 KiB
Go
413 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"`
|
|
}
|
|
|
|
// 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"`
|
|
// 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"`
|
|
}
|
|
|
|
// 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"`
|
|
}
|