Files
pipelines/internal/opencode/connection.go
T
alan cedfc22e45 Pipeline runs use the workspace's directory environment
Resolve the run workspace's environment with workenv (direnv, parent
.envrc, mise; same account rule as Claude chats) at run start and resume,
and apply it to Pi stage processes, a per-environment Pipelines-owned
OpenCode stage service (keyed by a hash of the change, reused across runs,
idle ones stopped after PIPELINES_OPENCODE_STAGE_IDLE_TIMEOUT, revived per
registration), delivery-gate checks and merges, plain-stage opencode CLI
calls and file-change capture git reads. Record the directory, .envrc
files, sources and variable names (never values) on the run detail; a
blocked .envrc becomes a run warning.
2026-11-04 18:08:42 +00:00

612 lines
21 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"
"errors"
"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
credentialFile string // V2 auth stays in the existing private service file
// 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
// configContent is the OPENCODE_CONFIG_CONTENT an owned serve process is
// started with; empty keeps the inherited environment unchanged.
configContent string
}
// Reference retains the execution service, never provider auth. V1 retains its
// ephemeral loopback password privately; V2 records only the existing credential
// file's path and endpoint identity, so rotation can never redirect recovery.
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
}
reference := map[string]string{"url": c.URL, "password": c.password, "directory": c.Directory}
if c.Backend == "v2" {
if c.credentialFile == "" || c.URL == "" {
_ = f.Close()
_ = os.Remove(f.Name())
return "", fmt.Errorf("V2 stage requires an existing service credential reference")
}
reference = map[string]string{"backend": "v2", "url": c.URL, "directory": c.Directory, "credentialFile": c.credentialFile}
}
data, _ := json.Marshal(reference)
_, writeErr := f.Write(data)
closeErr := f.Close()
if writeErr != nil {
return "", writeErr
}
if closeErr != nil {
return "", closeErr
}
return f.Name(), nil
}
type connectionReference struct{ Backend, URL, Password, Directory, CredentialFile string }
func readReference(path string) (connectionReference, error) {
var reference connectionReference
info, err := os.Lstat(path)
if err != nil {
return reference, err
}
if !info.Mode().IsRegular() || info.Mode().Perm() != 0600 || info.Size() > MaxRequest {
return reference, fmt.Errorf("invalid private OpenCode connection reference")
}
if stat, ok := info.Sys().(*syscall.Stat_t); !ok || stat.Uid != uint32(os.Getuid()) {
return reference, fmt.Errorf("OpenCode reference belongs to another user")
}
data, err := os.ReadFile(path)
if err != nil {
return reference, err
}
err = json.Unmarshal(data, &reference)
return reference, err
}
// ErrServiceNotRunning reports that a retained OpenCode service no longer
// answers: its process is gone, and with it any session turn it was running.
var ErrServiceNotRunning = errors.New("the OpenCode service is not running")
// ReferenceAlive reports whether the execution service a retained reference
// names is running right now, without starting or reviving it. Restart recovery
// uses it to tell a session that kept running across a Pipelines restart from
// one whose harness process is gone.
func ReferenceAlive(ctx context.Context, path string) error {
reference, err := readReference(path)
if err != nil {
return fmt.Errorf("retained OpenCode reference unreadable: %w", err)
}
if reference.Backend != "v2" {
return fmt.Errorf("the V1 OpenCode stage service belonged to the stopped server process")
}
if !filepath.IsAbs(reference.CredentialFile) {
return fmt.Errorf("invalid V2 service credential reference")
}
c, err := serviceConnection(reference.CredentialFile, reference.Directory)
if err != nil {
return err
}
if c.URL != reference.URL {
return fmt.Errorf("retained OpenCode service endpoint changed")
}
probe, cancel := context.WithTimeout(ctx, 3*time.Second)
defer cancel()
if err := c.probeHealth(probe, "v2"); err != nil {
return fmt.Errorf("%w at %s", ErrServiceNotRunning, c.URL)
}
return nil
}
func FromReference(path string) (*Connection, error) {
reference, err := readReference(path)
if err != nil {
return nil, err
}
if reference.Backend == "v2" {
if !filepath.IsAbs(reference.CredentialFile) {
return nil, fmt.Errorf("invalid V2 service credential reference")
}
// A retained reference to the owned stage service revives it on its
// recorded URL and password if it exited; it never selects another one.
if isOwnedStageRegistration(reference.CredentialFile) {
if err := reviveOwnedStageService(reference.CredentialFile, reference.Directory); err != nil {
return nil, err
}
}
c, err := serviceConnection(reference.CredentialFile, reference.Directory)
if err != nil {
return nil, err
}
if c.URL != reference.URL {
return nil, fmt.Errorf("retained OpenCode service endpoint changed")
}
return c, nil
}
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
}
// Executable resolves the OpenCode CLI without trusting the service's PATH
// alone. A launchd/systemd service often starts with a minimal PATH, so an
// installed Homebrew or local binary must still be found; the absolute
// PIPELINES_OPENCODE override wins when the operator wants a specific build.
func Executable() string {
if path := os.Getenv("PIPELINES_OPENCODE"); path != "" {
return path
}
if path, err := exec.LookPath("opencode"); err == nil {
return path
}
candidates := []string{"/opt/homebrew/bin/opencode", "/usr/local/bin/opencode", "/usr/bin/opencode"}
if home, err := os.UserHomeDir(); err == nil {
candidates = append(candidates, filepath.Join(home, ".local", "bin", "opencode"))
}
for _, candidate := range candidates {
if info, err := os.Stat(candidate); err == nil && !info.IsDir() && info.Mode()&0o111 != 0 {
return candidate
}
}
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
}
// V2 stages use the existing CLI-managed service, pinned before admission.
// Missing registration fails closed: never discover/start another service.
if c.Backend == "v2" {
managed, err := sessionExportConnection(c.Directory)
if err != nil {
return nil, err
}
managed.Executable = c.Executable
return managed, nil
}
if err := c.startServe(ctx); err != nil {
return nil, err
}
return c, nil
}
// PinCLI binds an api subprocess to this exact existing service, bypassing CLI
// discovery (which could otherwise start or select a different service). Auth is
// inherited privately, never passed in argv or persisted in ownership records.
func (c *Connection) PinCLI(cmd *exec.Cmd) {
if c.Backend != "v2" || c.URL == "" {
return
}
cmd.Args = append(cmd.Args, "--server", c.URL)
if cmd.Env == nil {
cmd.Env = os.Environ()
}
for _, key := range []string{"OPENCODE_PASSWORD", "OPENCODE_SERVER_PASSWORD"} {
filtered := cmd.Env[:0]
for _, entry := range cmd.Env {
if !strings.HasPrefix(entry, key+"=") {
filtered = append(filtered, entry)
}
}
cmd.Env = filtered
}
cmd.Env = append(cmd.Env, "OPENCODE_PASSWORD="+c.password)
}
// 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 pinned 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
}
c, err := newConnection(ctx, executable, directory, backend)
if err != nil {
return nil, err
}
// Chat-only limits apply to this spawned V2 process only; the operator's
// shared service and any attached endpoint keep their own configuration.
overrides, err := chatConfigOverrides()
if err != nil {
return nil, err
}
if overrides != nil && backend == "v2" {
if c.configContent, err = configContent(os.Getenv("OPENCODE_CONFIG_CONTENT"), overrides); err != nil {
return nil, err
}
}
if err := c.startServe(ctx); err != nil {
return nil, err
}
return c, nil
}
// 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
c.process.Env = serviceEnvironment(c.configContent)
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)
}
// HistoryNative performs an authenticated history read without Connection.Call's
// general 1 MiB response guard. Chat history is paged and projected before it is
// sent to a client; ordinary API calls keep their existing safeguard.
func (c *Connection) HistoryNative(ctx context.Context, path string) (io.ReadCloser, error) {
c.LastHTTPStatus = 0
c.LastHTTPOperation = "GET " + path
u, err := url.Parse(c.URL + path)
if err != nil {
return nil, err
}
if c.Directory != "" {
query := u.Query()
query.Set("directory", c.Directory)
u.RawQuery = query.Encode()
}
req, err := http.NewRequestWithContext(ctx, http.MethodGet, u.String(), nil)
if err != nil {
return nil, err
}
req.Header.Set("Accept", "application/json")
req.SetBasicAuth(c.serverUser(), c.password)
resp, err := http.DefaultClient.Do(req)
if err != nil {
if ctx.Err() != nil {
return nil, ctx.Err()
}
return nil, fmt.Errorf("OpenCode history request failed")
}
c.LastHTTPStatus = resp.StatusCode
c.LastHTTPOperation = "GET " + path
if resp.StatusCode == http.StatusUnauthorized {
c.unauthorized = true
}
if resp.StatusCode < 200 || resp.StatusCode >= 300 {
defer resp.Body.Close()
_, _ = io.Copy(io.Discard, io.LimitReader(resp.Body, 16<<10))
return nil, fmt.Errorf("OpenCode GET %s failed (HTTP %d)", path, resp.StatusCode)
}
if !strings.HasPrefix(resp.Header.Get("Content-Type"), "application/json") {
resp.Body.Close()
return nil, fmt.Errorf("OpenCode GET %s returned a non-JSON API response", path)
}
return resp.Body, nil
}
// 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
}