Add an opt-in way to broker chat from an operator-supplied OpenCode service
instead of the instance the server spawns for itself, and a way to adopt a
session that already exists on that endpoint so it appears in chat_sessions and
can be continued from the app.
- Endpoint selection: the `-opencode-endpoint` server flag (defaulting to
`PIPELINES_OPENCODE_ENDPOINT`) opts in; precedence is explicit flag >
explicit environment > the endpoint recorded on a previous run, with the
spawned instance as the default. opencode.OpenEndpoint validates the
reference once (http(s), host, no userinfo/query/fragment/path), detects the
backend from its own /api/info (v2) or /global/health (v1) contract, and
requires a streamable text/event-stream event path. It owns no process
(Close is a no-op) and never calls startServe; every failure names the
endpoint and disables chat rather than silently falling back. An
authenticated endpoint takes an optional password only through the private
file PIPELINES_OPENCODE_ENDPOINT_PASSWORD_FILE, with
PIPELINES_OPENCODE_ENDPOINT_USERNAME overriding the detected default.
- Persistence: the validated choice is recorded in an additive single-row
server_settings table so a restart with no flag/environment reuses it; an
unreachable recorded endpoint disables chat with a clear message and no
fallback.
- chat_adopt: a new protocol request (ChatAdoptRequest) with handleChatAdopt in
internal/server/chat.go. It refuses a nil broker/registry/payload and a
blank or foreign-shaped id before any endpoint call, reads the endpoint via
the shared Chat.Session (which reuses Sessions/decodeChatSessions), records
through the existing RecordOperatorSession with the endpoint's directory and
title verbatim, and echoes the adopted session plus its registry row like
chat_create. A missing id is refused naming the id and records nothing; an
endpoint record with an empty directory is refused rather than substituting
the server's working directory or home.
- CLI: `pipelines chat-adopt <session-id> [--json]` (usage, notes, help
inventory, dispatch) with docs/cli.md updated under Chat sessions.
- Autostart preserves the endpoint variables (and the password-file reference,
never an inline secret) via serviceEnvironmentKeys.
Checks before committing:
- Package location: the change is user-facing chat behaviour, so the packaged
authoring skill reference internal/author/skill/references/operations.md is
updated in the same change (Brokered OpenCode chat section) with a dated
verification-evidence entry and the not-deployed state. No new reference file
is added, so internal/author/install.go's managed inventory is unchanged.
- Packaged templates: this repository packages no template set for this
behaviour and none references the chat endpoint, so no template needs
updating.
- Verification: `go build ./...`, `go vet` on the touched packages, `gofmt -l`
clean and `go test ./...` all pass. The unit tests cover the endpoint
validation/precedence, the adopt happy path and refusals, the recorded
endpoint round-trip, the protocol round-trip and the CLI dispatch. The live
scratch-server check against the operator's real endpoint was not run in this
change.
Nothing unrelated is staged; docs left stale (README and other shared documents)
are not edited here and are for a single folding writer.
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.
chat_sessions now brokers GET /api/session but filters the global list to
the sessions this server recorded in run_steps, deduped by session id, and
fails closed to an empty list when no ownership source is configured. A
session another client holds (in-server claim, released on stream end or
disconnect) or an active run is marked busy; a second client's chat_prompt
for a held session is rejected before any OpenCode call. chat_create stays
unbrokered.
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.