Merge main into wait-cmd: combine the wait command with chat-persistence pairing

Brings main (chat-persistence: OpenCode pairing, protocol status, server
websocket/status changes) up to date on this branch so it can land without
conflict. Auto-merged with no conflicts; no comment or intent from either side
was dropped. Re-ran build, vet, gofmt and the full test suite after the merge -
all pass.
This commit is contained in:
2026-10-18 01:11:31 +01:00
10 changed files with 880 additions and 41 deletions
+115
View File
@@ -0,0 +1,115 @@
# Chat persistence: attach to the operator's own OpenCode by pairing, and fall back honestly
## What this item changed
Brokered chat could already be pointed at an operator-supplied OpenCode endpoint
(`-opencode-endpoint` / `PIPELINES_OPENCODE_ENDPOINT`), but pointing it at the
operator's running V2 service failed closed: the V2 API authenticates every
request with HTTP Basic auth (fixed user `opencode` plus a password), the broker
had no credential, so the health probe answered 401, startup logged
`OpenCode chat unavailable: OpenCode endpoint … is unreachable or is not an
OpenCode service`, and chat was disabled entirely.
Established from the installed binary (`opencode v2.0.20`), not from docs:
- `opencode --help` lists `api`, `pair`, `serve`, `service`, `auth`; `pair` is
"Print one-time links to connect a browser or app".
- `GET /api/info` unauthenticated → `401`, `www-authenticate: Basic realm="Secure Area"`.
- Basic auth user `opencode` with the password from `~/.local/state/opencode/service.json`
(`opencode service start` writes it, mode 0600) → `200`.
- `POST /api/pair` (authenticated) → `{"code":"…","expires_in":300}`;
`GET /auth/connect/{code}` (unauthenticated, single use) → `{"token":"…"}`.
The returned token is then accepted as the Basic password with user
`opencode`; it is not a bearer token, a cookie or an api-key header.
Changes:
- `internal/opencode/pair.go` (new): `PairEndpoint` performs the pair exchange
(`POST /api/pair` then `GET /auth/connect/{code}`) over the shared
`nativeRequest` transport, so it keeps the same auth, bounds and JSON checks;
`ReadServiceCredential` reads the operator's local service password (private
file rule); `OpenEndpointAttached` resolves the credential in precedence order
— explicit password file, a paired token stored by an earlier run, then a
fresh pairing bootstrapped by the local service credential — stores the token
in an owner-only file and re-pairs once when a stored token is refused (401).
The paired token is written 0600 through a temp file and rename and is never
logged.
- `internal/opencode/endpoint.go`: `OpenEndpoint` now wraps `probeEndpoint`,
which returns the connection even on failure; `Connection.unauthorized`
(set by the request paths on HTTP 401, cleared per probe) lets the attach tell
an authentication refusal from any other refusal.
- `cmd/pipelines-server/main.go`: the endpoint attach uses
`OpenEndpointAttached` with the paired-credential file beside the pipeline
database (`<db dir>/opencode-endpoint.json`). An endpoint that cannot be
attached logs a line naming it and **falls back to the server's own OpenCode
instance** instead of leaving chat refused.
- `internal/protocol/status.go`, `internal/server/websocket.go`: `get_status`
gains an `opencode` object (`health` = `endpoint` | `fallback` | `spawned` |
`unavailable`, plus the endpoint `url`), the honest status evidence for the
fallback. `Options.OpenCodeStatus` carries it; no credential is ever placed
there.
- Tests: `internal/opencode/pair_test.go`, `internal/protocol/status_test.go`,
a `TestStatusReportsOpenCodeAttachment` case in `internal/server/status_test.go`.
## Verification (17 Oct 2026)
Scratch server only, deployed server untouched; `go build ./... && go vet ./...`
and `gofmt -l .` clean; `go test ./internal/... ./cmd/...` green. Live check with
`-addr 127.0.0.1:<free>` and `-db <scratch>/pipelines.db`,
`PIPELINES_OPENCODE_ENDPOINT=http://127.0.0.1:49374`:
- `get_status` → `{"opencode":{"health":"endpoint","url":"http://127.0.0.1:49374"}}`;
`<scratch>/opencode-endpoint.json` written mode `-rw-------`.
- `chat_sessions` (empty registry) → 0 sessions; `chat_adopt ses_eb3c685f0ffe…`
(an operator session) → recorded; `chat_create <scratch dir>` → a new operator
session; `chat_sessions` → both.
- `chat_prompt` on the created session → `turn completed: 4 frame(s), 1 text
frame(s)`; `chat_messages` → 2 turns.
- **Restart**: stopped the scratch server (SIGTERM), started it again on the
same database. `get_status` → `endpoint`; `chat_sessions` → the same 2
sessions; `chat_messages` → the same 2 turns; the paired-credential file's
mtime and size were unchanged, so the stored token was reused, not re-paired.
- Fallback: `PIPELINES_OPENCODE_ENDPOINT=http://127.0.0.1:1` → log
`OpenCode endpoint http://127.0.0.1:1 could not be attached (…); falling back
to the server's own OpenCode instance`, and `get_status` →
`{"opencode":{"health":"fallback","url":"http://127.0.0.1:1"}}` with chat
still served by the spawned instance.
Not verified: whether the V2 service rotates/invalidates paired tokens across a
restart of **the service itself** (the operator's service was never restarted);
whether a containerised/remote Pipelines server can reach the local
`service.json` bootstrap (it cannot, so it would need the password-file path).
## Shared documents this change makes stale
The note is written here rather than edited in place; the `docs-fold` writer
should update these when it next folds notes.
- `docs/cli.md:354` — the `### Choosing the endpoint` section says a failure
"disable[s] chat … never a silent fallback". It should now say: the broker
authenticates to a V2 endpoint by pairing (`POST /api/pair` then
`GET /auth/connect/{code}`) using the operator's local OpenCode service
credential as bootstrap, stores the paired token owner-only
(`opencode-endpoint.json` beside the database), reuses it across restarts and
re-pairs once when it is refused; an explicit
`PIPELINES_OPENCODE_ENDPOINT_PASSWORD_FILE` still wins; and an endpoint that
cannot be attached logs the reason and **falls back to the server's own
OpenCode instance** rather than disabling chat.
- `docs/cli.md` — the `get_status`/`status` description should document the new
`opencode` object (`health` = `endpoint`|`fallback`|`spawned`|`unavailable`,
`url`), which is where an unattachable endpoint is reported.
- `internal/author/skill/references/operations.md:289` — the endpoint paragraph
repeats the same "clear refusal and no fallback" wording and the
password-file/username-only credential story; update it for pairing, the
stored paired token and the honest fallback, and add the `opencode` status
field. Add a dated evidence bullet naming the new tests and the restart check.
## Not stale
- `internal/author/install.go`'s managed file inventory: no reference file is
added.
- `internal/installation/service.go`: no new environment variable, so the
autostart variable list and the credential-file handling are unchanged.
- `internal/server/AGENTS.md` already points at `cmd/pipelines-server/main.go`
for the endpoint choice and at `internal/server/chat_*.go`; no new area-map
entry is needed.