// 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 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 } // 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 } 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{ Backend, URL, Password, Directory, CredentialFile string } if err = json.Unmarshal(data, &reference); err != nil { return nil, err } if reference.Backend == "v2" { if !filepath.IsAbs(reference.CredentialFile) { return nil, fmt.Errorf("invalid V2 service credential reference") } 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 } 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) } // 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 }