Files
pipelines/internal/opencode/connection.go
T
alan 0ba1204895 chat: attach to the operator's own OpenCode by pairing, fall back honestly
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.
2026-10-18 00:55:26 +01:00

433 lines
14 KiB
Go

// Package opencode adapts the two published OpenCode API families without installing a CLI.
package opencode
import (
"bufio"
"bytes"
"context"
"crypto/rand"
"encoding/hex"
"encoding/json"
"fmt"
"io"
"net/http"
"net/url"
"os"
"os/exec"
"path/filepath"
"regexp"
"strings"
"syscall"
"time"
)
const MaxRequest = 64 << 10
const MaxResponse = 1 << 20
type Connection struct {
Backend, Executable, Directory string
URL string
password string
// username overrides the backend-default basic-auth user for an
// operator-supplied endpoint (PIPELINES_OPENCODE_ENDPOINT_USERNAME). It is
// empty for the owned serve connection, which keeps the detected default.
username string
process *exec.Cmd
done chan error
models map[string]map[string]string
responses map[string][]byte
formatChecked bool
formatSupported bool
FormatProbe *FormatProbe
LastHTTPStatus int
LastHTTPOperation string
MessageReadbackDiagnostic string
// unauthorized records that at least one request through this connection was
// refused with HTTP 401, so an attach that probed both backend families can
// tell an authentication refusal (worth re-pairing) from any other refusal.
// It is set only by the request path and cleared by the attach probe.
unauthorized bool
}
// Reference records only our ephemeral loopback service credentials, never provider auth.
// The private file lets crash recovery abort the same owned service, not a new instance.
func (c *Connection) Reference() (string, error) {
cache, err := os.UserCacheDir()
if err != nil {
return "", err
}
dir := filepath.Join(cache, "pipelines", "private")
if err = os.MkdirAll(dir, 0700); err != nil {
return "", err
}
f, err := os.CreateTemp(dir, "opencode-connection-*.json")
if err != nil {
return "", err
}
data, _ := json.Marshal(map[string]string{"url": c.URL, "password": c.password, "directory": c.Directory})
_, writeErr := f.Write(data)
closeErr := f.Close()
if writeErr != nil {
return "", writeErr
}
if closeErr != nil {
return "", closeErr
}
return f.Name(), nil
}
func FromReference(path string) (*Connection, error) {
info, err := os.Lstat(path)
if err != nil {
return nil, err
}
if !info.Mode().IsRegular() || info.Mode().Perm() != 0600 || info.Size() > MaxRequest {
return nil, fmt.Errorf("invalid private OpenCode connection reference")
}
if stat, ok := info.Sys().(*syscall.Stat_t); !ok || stat.Uid != uint32(os.Getuid()) {
return nil, fmt.Errorf("OpenCode reference belongs to another user")
}
data, err := os.ReadFile(path)
if err != nil {
return nil, err
}
var reference struct{ URL, Password, Directory string }
if err = json.Unmarshal(data, &reference); err != nil {
return nil, err
}
u, err := url.Parse(reference.URL)
if err != nil || u.Scheme != "http" || u.Hostname() != "127.0.0.1" || u.Port() == "" || u.Path != "" || u.User != nil || u.RawQuery != "" || u.Fragment != "" || len(reference.Password) != 64 {
return nil, fmt.Errorf("invalid owned OpenCode service endpoint")
}
return &Connection{Backend: "v1", URL: reference.URL, password: reference.Password, Directory: reference.Directory}, nil
}
func Executable() string {
if path := os.Getenv("PIPELINES_OPENCODE"); path != "" {
return path
}
return "opencode"
}
// Detect checks the advertised command interface, not an assumed release number.
func Detect(ctx context.Context, executable string) (string, error) {
cmd := CommandContext(ctx, executable, "--help")
data, err := cmd.CombinedOutput()
if err != nil {
// Preserve the caller's cancellation/deadline identity; a parent that
// exits 0 while a descendant still holds the combined-output pipe is
// never parsed from its partial stdout.
if ctx.Err() != nil {
return "", ctx.Err()
}
return "", fmt.Errorf("cannot run the selected OpenCode CLI: %w", err)
}
if regexp.MustCompile(`(?m)^\s*(?:opencode\s+)?api\s`).Match(data) {
return "v2", nil
}
if regexp.MustCompile(`(?m)^\s*(?:opencode\s+)?serve\s`).Match(data) {
return "v1", nil
}
return "", fmt.Errorf("selected OpenCode CLI advertises neither api nor serve")
}
func Open(ctx context.Context, executable, directory, backend string) (*Connection, error) {
c, err := newConnection(ctx, executable, directory, backend)
if err != nil {
return nil, err
}
// The V2 CLI talks to its own managed service, so stages reach it through the
// `api` subcommand and Open returns no owned process for them. Only
// OpenStream (brokered chat) opens the owned V2 endpoint.
if c.Backend == "v2" {
return c, nil
}
if err := c.startServe(ctx); err != nil {
return nil, err
}
return c, nil
}
// OpenStream opens the single owned `opencode serve` endpoint for either backend
// so a caller that needs a URL-bearing, SSE-capable connection (brokered chat)
// gets one on the installed V2 CLI too. The V2 server exposes the authenticated
// SSE event firehose at /api/event and the /api HTTP surface; the native serve
// exposes /event and the translated /api surface. Stage generation keeps using
// Open (the unstarted V2 connection plus its `api` subcommand), so this starts
// no process for it and there is never a second transport.
func OpenStream(ctx context.Context, executable, directory, backend string) (*Connection, error) {
c, err := newConnection(ctx, executable, directory, backend)
if err != nil {
return nil, err
}
if err := c.startServe(ctx); err != nil {
return nil, err
}
return c, nil
}
// OpenChat detects the installed backend and opens the owned, URL-bearing
// connection the brokered chat adapter streams from. main and the chat live test
// call this one selection function so their Detect/Open logic cannot drift.
func OpenChat(ctx context.Context, executable, directory string) (*Connection, error) {
if executable == "" {
executable = Executable()
}
backend, err := Detect(ctx, executable)
if err != nil {
return nil, err
}
return OpenStream(ctx, executable, directory, backend)
}
// newConnection resolves the executable/directory defaults, detects the backend
// when it is empty, and returns the bare, not-yet-opened connection. It is the
// shared construction path for Open and OpenStream so backend validation lives
// once.
func newConnection(ctx context.Context, executable, directory, backend string) (*Connection, error) {
if executable == "" {
executable = Executable()
}
if directory == "" {
var err error
directory, err = os.Getwd()
if err != nil {
return nil, err
}
}
if backend == "" {
var err error
backend, err = Detect(ctx, executable)
if err != nil {
return nil, err
}
}
if backend != "v1" && backend != "v2" {
return nil, fmt.Errorf("unknown OpenCode backend %q", backend)
}
return &Connection{Backend: backend, Executable: executable, Directory: directory, models: map[string]map[string]string{}, responses: map[string][]byte{}}, nil
}
// serverUser is the HTTP basic-auth username the owned serve process expects.
// The native serve authenticates the fixed "pipelines" user; the V2 API server
// authenticates the fixed "opencode" user regardless of
// OPENCODE_SERVER_USERNAME, verified against the installed 2.0.20 binary.
func (c *Connection) serverUser() string {
if c.username != "" {
return c.username
}
if c.Backend == "v2" {
return "opencode"
}
return "pipelines"
}
// startServe launches one owned `opencode serve` process on loopback, injects the
// ephemeral password, discovers the URL and verifies the backend-specific health
// contract. Close terminates it. It is idempotent so a connection only ever owns
// one process.
func (c *Connection) startServe(ctx context.Context) error {
if c.process != nil {
return nil
}
secret := make([]byte, 32)
if _, err := rand.Read(secret); err != nil {
return err
}
c.password = hex.EncodeToString(secret)
c.process = exec.Command(c.Executable, "serve", "--hostname", "127.0.0.1", "--port", "0")
c.process.Dir = c.Directory
for _, entry := range os.Environ() {
if !strings.HasPrefix(entry, "OPENCODE_SERVER_PASSWORD=") && !strings.HasPrefix(entry, "OPENCODE_SERVER_USERNAME=") {
c.process.Env = append(c.process.Env, entry)
}
}
c.process.Env = append(c.process.Env, "OPENCODE_SERVER_PASSWORD="+c.password, "OPENCODE_SERVER_USERNAME="+c.serverUser())
stdout, err := c.process.StdoutPipe()
if err != nil {
return err
}
c.process.Stderr = io.Discard
if err = c.process.Start(); err != nil {
return err
}
c.done = make(chan error, 1)
go func() { c.done <- c.process.Wait() }()
address := make(chan string, 1)
go func() {
scanner := bufio.NewScanner(stdout)
pattern := regexp.MustCompile(`http://127\.0\.0\.1:[0-9]+`)
sent := false
for scanner.Scan() {
if !sent {
if found := pattern.FindString(scanner.Text()); found != "" {
address <- found
sent = true
}
}
}
}()
startup, stop := context.WithTimeout(ctx, 20*time.Second)
defer stop()
select {
case c.URL = <-address:
case <-c.done:
c.process = nil
return fmt.Errorf("OpenCode serve exited before becoming ready")
case <-startup.Done():
c.Close()
return fmt.Errorf("OpenCode serve startup: %w", startup.Err())
}
if err := c.checkHealth(startup); err != nil {
c.Close()
return err
}
return nil
}
// checkHealth verifies the backend-specific readiness contract after the serve
// process prints its URL: the native serve answers /global/health, the V2 API
// server answers /api/info. Both use the same owned credentials the rest of the
// adapter uses, so a reachable but unauthorized endpoint is not mistaken for a
// healthy one.
func (c *Connection) checkHealth(ctx context.Context) error {
if c.Backend == "v2" {
if err := c.probeHealth(ctx, "v2"); err != nil {
return fmt.Errorf("OpenCode serve did not return the expected V2 info contract")
}
return nil
}
if err := c.probeHealth(ctx, "v1"); err != nil {
return fmt.Errorf("OpenCode serve did not return the expected native health contract")
}
return nil
}
func (c *Connection) Close() {
if c.process == nil {
return
}
_ = c.process.Process.Signal(syscall.SIGTERM)
select {
case <-c.done:
case <-time.After(5 * time.Second):
_ = c.process.Process.Kill()
<-c.done
}
c.process = nil
}
func (c *Connection) Native(ctx context.Context, method, path string, body any) ([]byte, error) {
return c.nativeRequest(ctx, method, path, body, c.Directory)
}
// nativeRequest is the shared Native request path. An empty directory omits the
// ?directory= query parameter; the V2 session list then returns sessions across
// every directory instead of only the connection's own.
func (c *Connection) nativeRequest(ctx context.Context, method, path string, body any, directory string) ([]byte, error) {
c.LastHTTPStatus = 0
c.LastHTTPOperation = strings.ToUpper(method) + " " + path
u, err := url.Parse(c.URL + path)
if err != nil {
return nil, err
}
if directory != "" {
query := u.Query()
query.Set("directory", directory)
u.RawQuery = query.Encode()
}
var data []byte
if body != nil {
data, err = json.Marshal(body)
if err != nil {
return nil, err
}
if len(data) > MaxRequest {
return nil, fmt.Errorf("OpenCode request exceeds 64 KiB")
}
}
request, err := http.NewRequestWithContext(ctx, strings.ToUpper(method), u.String(), bytes.NewReader(data))
if err != nil {
return nil, err
}
request.Header.Set("Content-Type", "application/json")
request.SetBasicAuth(c.serverUser(), c.password)
response, err := http.DefaultClient.Do(request)
if err != nil {
if ctx.Err() != nil {
return nil, ctx.Err()
}
return nil, fmt.Errorf("OpenCode native API request failed")
}
defer response.Body.Close()
c.LastHTTPStatus = response.StatusCode
if response.StatusCode == http.StatusUnauthorized {
c.unauthorized = true
}
if response.StatusCode < 200 || response.StatusCode >= 300 {
// The stage adapter stores bounded, redacted failure evidence separately;
// the public error string remains free of provider bodies and credentials.
evidence, _ := io.ReadAll(io.LimitReader(response.Body, 16<<10))
return evidence, fmt.Errorf("OpenCode %s %s failed (HTTP %d)", method, path, response.StatusCode)
}
// A successful no-content operation (the permission-reply endpoint returns
// 204) carries no JSON body to validate.
if response.StatusCode == http.StatusNoContent {
return nil, nil
}
if !strings.HasPrefix(response.Header.Get("Content-Type"), "application/json") {
return nil, fmt.Errorf("OpenCode %s %s returned a non-JSON API response", method, path)
}
data, err = io.ReadAll(io.LimitReader(response.Body, MaxResponse+1))
if err != nil {
return nil, err
}
if len(data) > MaxResponse {
return nil, fmt.Errorf("OpenCode response exceeds 1 MiB")
}
if !json.Valid(data) {
return nil, fmt.Errorf("OpenCode returned invalid JSON")
}
return data, nil
}
// EventStream opens the authenticated SSE firehose for the connection's owned
// endpoint using the same URL and credentials as Native, so chat never builds a
// parallel HTTP client. The path follows the backend surface: the native serve
// stream is /event, the V2 HTTP API is /api/event. The caller closes the body.
func (c *Connection) EventStream(ctx context.Context) (io.ReadCloser, error) {
if c == nil || c.URL == "" {
return nil, fmt.Errorf("OpenCode chat requires an event-stream endpoint")
}
path := "/api/event"
if c.Backend == "v1" {
path = "/event"
}
request, err := http.NewRequestWithContext(ctx, http.MethodGet, strings.TrimSuffix(c.URL, "/")+path, nil)
if err != nil {
return nil, err
}
request.Header.Set("Accept", "text/event-stream")
request.SetBasicAuth(c.serverUser(), c.password)
response, err := http.DefaultClient.Do(request)
if err != nil {
if ctx.Err() != nil {
return nil, ctx.Err()
}
return nil, fmt.Errorf("OpenCode event stream request failed")
}
if response.StatusCode < 200 || response.StatusCode >= 300 {
if response.StatusCode == http.StatusUnauthorized {
c.unauthorized = true
}
evidence, _ := io.ReadAll(io.LimitReader(response.Body, 16<<10))
response.Body.Close()
return nil, fmt.Errorf("OpenCode event stream failed (HTTP %d): %s", response.StatusCode, strings.TrimSpace(string(evidence)))
}
if !strings.HasPrefix(response.Header.Get("Content-Type"), "text/event-stream") {
response.Body.Close()
return nil, fmt.Errorf("OpenCode event stream returned a non-SSE response")
}
return response.Body, nil
}