Files
pipelines/internal/protocol/chat.go
T

643 lines
30 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"
// ChatRename records the operator's shared chat title on the server. Unlike
// a local override, every browser and device then lists the same name.
ChatRename = "chat_rename"
// ChatBackends lists the installed chat harnesses the server can create a
// session on. The reply is a bounded array of backend names.
ChatBackends = "chat_backends"
// ChatModels lists the models the chat's harness can switch to; its request
// body is ChatQuery (the session id).
ChatModels = "chat_models"
// ChatModelSelect switches one session's model for subsequent turns.
ChatModelSelect = "chat_model"
// ChatStar records the operator's star on the server, so every browser and
// device shows the same starred group. It takes a ChatQuery with SessionID
// and Starred, and echoes the updated session like close/reopen.
ChatStar = "chat_star"
// 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"
// ChatShells lists current, verified shells belonging to one operator chat
// session. ChatShellOutput reads a bounded page from one such shell.
ChatShells = "chat_shells"
ChatShellOutput = "chat_shell_output"
// ChatEvent and ChatPermission are the server-pushed frames; they are the
// only types the server sends without a matching request.
ChatEvent = "chat_event"
// ChatEventForm carries an OpenCode form (the agent's question tool uses a
// form with kind=question). It is a ChatEvent kind, not a separate request:
// the same frame stream that carries text and tools carries the question.
ChatEventForm = "form"
// ChatAnswer is the client's answer to a ChatEventForm. Answers is keyed by
// field key and mirrors OpenCode's form.reply answer object.
ChatAnswer = "chat_answer"
// 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"
ChatPartFile = "file"
)
// 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"
ChatEventResync = "resync"
ChatEventUsage = "usage"
ChatEventUser = "user"
ChatEventCompaction = "compaction"
// 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"
ChatShellOutputLimit = 64 << 10
ChatShellOutputMaxCursor = int64(1 << 62)
)
// 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"
)
// ChatModel is one model the current chat harness can switch to. ID is the
// provider's model id, Provider its provider id, Name the harness's display name.
type ChatModel struct {
ID string `json:"id"`
Provider string `json:"provider"`
Name string `json:"name,omitempty"`
}
// ChatModelRequest switches the model for one session's subsequent turns.
type ChatModelRequest struct {
// Selection is reply-only: next_turn means a durable local override was saved.
Selection string `json:"selection,omitempty"`
SessionID string `json:"session_id"`
Provider string `json:"provider"`
Model string `json:"model"`
}
// 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"`
// ModelSelection == next_turn denotes a durable Pipelines override, not an
// acknowledgement that a remote thread's current configuration changed.
ModelSelection string `json:"model_selection,omitempty"`
// InstructionStatus is the observed create-time preload outcome: applied,
// unsupported, failed, or not_requested. Ordinary list rows omit it.
InstructionStatus string `json:"instruction_status,omitempty"`
InstructionError string `json:"instruction_error,omitempty"`
// Backend names the harness that owns this session: opencode, codex or
// claude. Empty on older peers and for legacy OpenCode rows.
Backend string `json:"backend,omitempty"`
Title string `json:"title,omitempty"`
Agent string `json:"agent,omitempty"`
Model string `json:"model,omitempty"`
ModelProvider string `json:"model_provider,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"`
// Starred is the operator's shared star, stored in the operator-session
// registry so every client sees the same Starred group. StarredAt is the
// epoch-millisecond time it was set, 0 while unstarred.
Starred bool `json:"starred,omitempty"`
StarredAt int64 `json:"starred_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"`
// Backend selects the chat harness for a new session. Empty means opencode,
// preserving older clients and the default.
Backend string `json:"backend,omitempty"`
OperationID string `json:"operation_id,omitempty"`
// Instructions preloads the session's durable behavior instruction, when the
// harness supports session instruction entries (OpenCode does). The reply's
// instruction_status explicitly reports applied, unsupported or failed.
Instructions string `json:"instructions,omitempty"`
// Ephemeral creates a chat for automated verification: the session is created,
// bootstrapped and usable exactly like a normal one, but no operator-registry
// row is written, so it can never appear in chat_sessions. It exists because a
// verification client drives the real UI and would otherwise leave a permanent
// "New chat" in the operator's list for every run. The flag is client-supplied
// and only ever *removes* a chat from the shared list, so a buggy or hostile
// client can hide its own chat but cannot reveal or alter another one.
Ephemeral bool `json:"ephemeral,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"`
// Starred is set by chat_star; nil means the command did not name a state.
Starred *bool `json:"starred,omitempty"`
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"`
// NativeMessageID is the caller-supplied OpenCode message identity. It is
// sent with the prompt so history can be reconciled without guessing from
// text, time, order or page boundaries.
NativeMessageID string `json:"native_message_id,omitempty"`
// Attachments carries the bytes of files picked or pasted in the browser.
// Files are local to the browser, so a reference string alone is not enough
// for a server on another machine; Data is standard base64 and the server
// writes it to a private temporary file before prompting the agent.
Attachments []ChatAttachment `json:"attachments,omitempty"`
}
// ChatAttachment is one browser attachment carried by a chat prompt. Data is
// standard base64 (no data: prefix); Name is a display name and Mime is the
// browser's content type. The server derives the on-disk name and never trusts
// either for path construction.
type ChatAttachment struct {
Name string `json:"name"`
Mime string `json:"mime,omitempty"`
Data string `json:"data"`
}
// 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"`
URI string `json:"uri,omitempty"`
Mime string `json:"mime,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 {
// NativeTurnID scopes session activity to a harness turn when available.
NativeTurnID string `json:"native_turn_id,omitempty"`
Compaction *ChatCompaction `json:"compaction,omitempty"`
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"`
// Attachments carries the file parts of a user turn another client sent.
// A frame has one Part, so the prompt's files travel alongside its text.
Attachments []ChatPart `json:"attachments,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"`
// Form is the payload of a ChatEventForm frame: the agent's pending question
// (or another OpenCode form), and the resolved/cancelled terminal state.
Form *ChatForm `json:"form,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"`
}
// ChatCompaction is session activity, never a transcript message or tool.
// ID is optional: OpenCode V2 compaction events have no shared lifecycle id.
type ChatCompaction struct {
Status string `json:"status"` // running | completed | failed
ID string `json:"id,omitempty"`
}
// ChatStep is a progress marker for the current step of a turn.
type ChatStep struct {
Status string `json:"status"`
TurnID string `json:"turn_id,omitempty"`
Index int `json:"index,omitempty"`
// Intermediate distinguishes a provider step from authoritative turn completion.
Intermediate bool `json:"intermediate,omitempty"`
}
// ChatUsage carries native usage snapshots. Rich metrics are pointers so zero
// reported by a harness remains distinguishable from an unavailable value.
// Session snapshots replace previous values; consumers must not sum updates.
type ChatUsage struct {
InputTokens int `json:"input_tokens,omitempty"`
OutputTokens int `json:"output_tokens,omitempty"`
Cost float64 `json:"cost,omitempty"`
Scope string `json:"scope,omitempty"`
TotalTokens *int64 `json:"total_tokens,omitempty"`
ContextTokens *int64 `json:"context_tokens,omitempty"`
ContextWindow *int64 `json:"context_window,omitempty"`
CostUSD *float64 `json:"cost_usd,omitempty"`
OutputTokensPerSecond *float64 `json:"output_tokens_per_second,omitempty"`
// RateBasis distinguishes a generation interval from a whole turn (which
// can include tools/waits). Never estimate tokens from text/character counts.
RateBasis string `json:"rate_basis,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.
// ChatForm is the agent's structured question/form. OpenCode emits these as
// form.created / form.replied / form.cancelled; the question tool uses
// Kind=="question". A client answers with ChatAnswerRequest. Answers is kept as
// JSON values because a field may be a string, a list (multiselect), a number or
// a boolean.
type ChatForm struct {
ID string `json:"id"`
SessionID string `json:"session_id,omitempty"`
Title string `json:"title,omitempty"`
Kind string `json:"kind,omitempty"`
Fields []ChatFormField `json:"fields,omitempty"`
Resolved bool `json:"resolved,omitempty"`
Cancelled bool `json:"cancelled,omitempty"`
Answers map[string]any `json:"answers,omitempty"`
Actions []string `json:"actions,omitempty"`
}
// ChatFormField is one question/input in a form. Type is OpenCode's field type
// (string, multiselect, number, integer, boolean, external); Options is present
// when the question offers choices.
type ChatFormField struct {
Key string `json:"key"`
Title string `json:"title,omitempty"`
Description string `json:"description,omitempty"`
Type string `json:"type,omitempty"`
Options []ChatFormOption `json:"options,omitempty"`
Custom bool `json:"custom,omitempty"`
Required bool `json:"required,omitempty"`
Secret bool `json:"secret,omitempty"`
URL string `json:"url,omitempty"`
Default any `json:"default,omitempty"`
Minimum any `json:"minimum,omitempty"`
Maximum any `json:"maximum,omitempty"`
MinLength *int `json:"min_length,omitempty"`
MaxLength *int `json:"max_length,omitempty"`
MinItems *int `json:"min_items,omitempty"`
MaxItems *int `json:"max_items,omitempty"`
Format string `json:"format,omitempty"`
Pattern string `json:"pattern,omitempty"`
Placeholder string `json:"placeholder,omitempty"`
Hidden bool `json:"hidden,omitempty"`
When []ChatFormWhen `json:"when,omitempty"`
}
type ChatFormWhen struct {
Key string `json:"key"`
Op string `json:"op"`
Value any `json:"value"`
}
// ChatFormOption is one selectable choice in a ChatFormField.
type ChatFormOption struct {
Value string `json:"value"`
Label string `json:"label"`
Description string `json:"description,omitempty"`
}
// ChatRenameRequest is the chat_rename body: the session id and the trimmed
// shared title. An empty title is refused rather than clearing the name.
type ChatRenameRequest struct {
SessionID string `json:"session_id"`
Title string `json:"title"`
}
// ChatAnswerRequest is the chat_answer body: the form id and a field-keyed
// answer object. It is deliberately separate from ChatQuery because its payload
// is structured answers, not a session-scoped read.
type ChatAnswerRequest struct {
Action string `json:"action,omitempty"`
SessionID string `json:"session_id"`
FormID string `json:"form_id"`
Answers map[string]any `json:"answers"`
}
type ChatShell struct {
ID string `json:"id"`
Status string `json:"status,omitempty"`
Command string `json:"command,omitempty"`
Exit *int `json:"exit,omitempty"`
}
// ChatShellOutputQuery names one selected shell and a bounded absolute-byte
// output page. Cursor is decimal so it can be passed directly to OpenCode.
type ChatShellOutputQuery struct {
SessionID string `json:"session_id"`
ShellID string `json:"shell_id"`
Cursor int64 `json:"cursor,omitempty"`
Limit int `json:"limit,omitempty"`
}
// ChatShellOutputPage is a bounded, lazy output read. Unavailable is explicit when
// an exited shell is no longer directly verifiable upstream.
type ChatShellOutputPage struct {
Shell ChatShell `json:"shell"`
Output string `json:"output,omitempty"`
Cursor int64 `json:"cursor,omitempty"`
Size int64 `json:"size,omitempty"`
Truncated bool `json:"truncated,omitempty"`
Unavailable bool `json:"unavailable,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"`
AlwaysLabel string `json:"always_label,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"`
}