Files
pipelines/internal/protocol/chat.go
T
alan 18398dfa5b chat: give the operator their own sessions, separate from run sessions
chat_sessions used to list exactly the OpenCode sessions the pipelines own,
filtered through pipeline.SessionOwner (run_steps/run_session_owners), so an
operator-created chat was an accident of the run-ownership table and the
operator's working sessions were mixed with the internals of running pipelines.

Add a first-class operator session:

- internal/pipeline/operator_sessions.go: a dedicated operator_sessions table
  (session_id PK, directory, title, tag, created_at, last_used_at) with
  RecordOperatorSession (upsert preserving created_at), a one-statement
  TouchOperatorSession (no-op for a non-operator id), OperatorSessions bounded to
  128 rows most-recently-used first, and OperatorDirectories (bounded MRU,
  deduped). run_steps/run_session_owners and SessionOwner/OwnedSessions are
  untouched.
- internal/server/chat.go: chat_sessions returns operator sessions only - it
  reads the registry once, intersects it with one broker session-list call, fills
  directory/tag/created/updated from the registry, sets busy for a session held
  by another connection, keeps MRU order, and stays fail-closed (empty list, never
  the endpoint's whole list). A pipeline stage session and an untagged row can
  never be listed. chat_create resolves the directory (empty/'~'/'~/...' ->
  operator home; relative or missing rejected before any OpenCode call), calls
  broker.Create(title, resolved) and records the row with the operator tag.
  chat_directories returns home first then bounded (8) deduped recents. A
  successful prompt touches the operator session without affecting pipeline
  prompts.
- internal/opencode, internal/protocol, internal/server/websocket.go and
  message.go: unscoped session list, Create posts {"title":...,
  "location":{"directory":...}} to POST /api/session, additive protocol fields
  (omitempty) and the ChatDirectories request/response, plus the OperatorRegistry
  option defaulting to the first store. One OpenCode transport per server is
  unchanged.

Docs and references: docs/cli.md gains a "Chat sessions" section documenting the
operator-only fail-closed list, directory defaulting/rejection, chat_directories
(home first, deduped, bounded 8) and why a dedicated request was chosen.
internal/author/skill/references/operations.md's stale "Brokered OpenCode chat"
text (chat_create unbrokered, run_steps filtering, "listed the owned scratch
session" evidence) is rewritten to the operator-session registry, the fail-closed
filter, directory defaulting and the corrected live-test wording. No new
reference file, so internal/author/install.go's inventory is unchanged.

Checked for staleness elsewhere: README.md, the docs/ topic pages and the
packaged server/TUI templates carry no chat-session ownership claims, so none
needed updating.

Verified: gofmt -l clean; go vet and go build ./... clean; go test -count=1
./internal/pipeline/... ./internal/protocol/... ./internal/opencode/...
./internal/server/... and the full go test -count=1 ./... pass.
2026-10-17 11:14:25 +01:00

269 lines
11 KiB
Go

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: <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"
ChatPrompt = "chat_prompt"
ChatMessages = "chat_messages"
ChatInterrupt = "chat_interrupt"
ChatReply = "chat_reply"
// 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.
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"
)
// 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 marks a session another client currently holds (or one the server
// itself owns as an active run), so the phone can show it read-only instead
// of letting two clients silently write the same conversation. It is
// additive and optional: older peers ignore it.
Busy bool `json:"busy,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"`
}
// 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"`
}
// 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.
type ChatReplyRequest struct {
SessionID string `json:"session_id"`
RequestID string `json:"request_id"`
Decision string `json:"decision"`
Message string `json:"message,omitempty"`
}