0ba1204895
Brokered chat accepted an operator-supplied endpoint (-opencode-endpoint /
PIPELINES_OPENCODE_ENDPOINT) but failed closed against the operator's running
V2 service: that 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 and startup logged "OpenCode endpoint ... is unreachable or
is not an OpenCode service", disabling chat entirely.
Established from the installed binary (opencode v2.0.20), not from docs:
`opencode --help` advertises `api`, `pair`, `serve`, `service` and `auth`;
`GET /api/info` is unauthenticated-401 with www-authenticate Basic realm
"Secure Area"; Basic auth user `opencode` with the password from
~/.local/state/opencode/service.json answers 200; `POST /api/pair` returns a
code and `GET /auth/connect/{code}` returns a token that is then accepted as
the Basic password.
- internal/opencode/pair.go (new): PairEndpoint does the pair exchange over the
shared nativeRequest transport (same auth, bounds and JSON checks);
ReadServiceCredential reads the operator's local service password under the
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 owner-only and re-pairs once when a stored token is refused (401).
- internal/opencode/endpoint.go: OpenEndpoint wraps probeEndpoint, which returns
the connection even on failure; Connection.unauthorized (set on HTTP 401 by
the request paths, cleared per probe) distinguishes 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. 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. No credential
is ever placed there.
- Tests: internal/opencode/pair_test.go, internal/protocol/status_test.go and a
TestStatusReportsOpenCodeAttachment case in internal/server/status_test.go.
Repository checks: go build ./..., go vet ./... and gofmt -l . clean;
go test ./internal/... ./cmd/... green.
Packaged templates and skill references: the repository has no template tree
that mentions the OpenCode endpoint, and no packaged reference file is added, so
internal/author/install.go's managed inventory is unchanged. The packaged
authoring reference internal/author/skill/references/operations.md (the endpoint
paragraph around line 289, the "clear refusal and no fallback" wording and the
password-file/username-only credential story, and the missing opencode status
field) is now stale; per the maintenance convention the item does not edit the
shared document and instead records the stale points, with the exact wording
they should take, in docs/notes/chat-persistence.md for the docs-fold writer.
116 lines
6.7 KiB
Markdown
116 lines
6.7 KiB
Markdown
# 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.
|