opencode

Documentation

Overview

Package opencode is a registration-only stub for the OpenCode local agent (https://opencode.ai/, github.com/sst/opencode).

OpenCode is local-first: operators run `opencode serve` and the daemon points at the resulting localhost HTTP server (default port 7700). The server exposes REST + WebSocket endpoints today, but the shape is still pre-1.0 and the maintainers reserve the right to break it between minor releases. Wiring the daemon to it without a stable contract risks silent regressions whenever opencode ships, so v0.1 of this provider stops at probe-and-register: we confirm the server is reachable, advertise the capability matrix conservatively, and fail Spawn with a clear "runner not yet implemented" error.

Operators selecting opencode via a resolved profile see a deterministic agent.ErrSpawnFailed instead of agent.ErrNoProvider — same UX as the amp provider — and the daemon stays usable for the providers that ARE wired (claude / codex / stub / gemini).

When the OpenCode REST contract stabilizes (or when we ship a CLI shell-out runner equivalent to provider/claude), drop the placeholder Spawn and follow the provider/claude or provider/gemini layout (probe.go, spec_translation.go, event_mapping.go, handle.go).

Auth model: OpenCode's local server is unauthenticated by default; the optional OPENCODE_API_KEY env var is forwarded as a Bearer token for future hosted variants.

Tracked in REN-1501 (OpenCode runner) on the Rensei Linear team.

Index

• Constants
• type Options
• type Provider
  • func New(opts Options) (*Provider, error)
  • func (*Provider) Capabilities() agent.Capabilities
  • func (*Provider) Name() agent.ProviderName
  • func (*Provider) Resume(_ context.Context, _ string, _ agent.Spec) (agent.Handle, error)
  • func (*Provider) Shutdown(_ context.Context) error
  • func (p *Provider) Spawn(ctx context.Context, spec agent.Spec) (agent.Handle, error)

Constants

const DefaultBinary = "opencode"

DefaultBinary is the executable name probed on $PATH at construction. OpenCode can be run as a standalone CLI with `opencode run`.

const DefaultEndpoint = "http://localhost:7700"

DefaultEndpoint is the URL probed at construction when no explicit endpoint or env var is supplied. Mirrors the OpenCode CLI's default server bind address.

const DefaultProbeTimeout = 2 * time.Second

DefaultProbeTimeout caps the probe HTTP GET at construction when not in CLI-binary mode.

const EnvAPIKey = "OPENCODE_API_KEY" //nolint:gosec // G101: env-var name, not a credential

EnvAPIKey is the optional bearer-token env var NAME. Forwarded for future hosted variants; not required for the default localhost server.

const EnvEndpoint = "OPENCODE_ENDPOINT"

EnvEndpoint overrides DefaultEndpoint when set.

Types

type Options

type Options struct {
	// Binary names the opencode CLI executable to invoke. When empty,
	// DefaultBinary is used. Tests inject a fake-CLI script path here.
	// When set (or when DefaultBinary is on PATH), the provider uses
	// CLI-spawn mode (opencode run --format json) rather than the HTTP
	// server mode.
	Binary string

	// Endpoint overrides the OpenCode server URL for HTTP-server mode.
	// Empty falls back to $OPENCODE_ENDPOINT then DefaultEndpoint.
	// Ignored when BinaryMode is true or a binary is found.
	Endpoint string

	// APIKey is an optional bearer token. Empty falls back to
	// $OPENCODE_API_KEY (which may also be empty).
	APIKey string

	// HTTPClient is used for the probe call in HTTP-server mode.
	// Defaults to a client with DefaultProbeTimeout.
	HTTPClient *http.Client

	// Getenv overrides the environment lookup. Defaults to os.Getenv.
	Getenv func(string) string

	// LookPath overrides the binary-resolution function. Defaults to
	// exec.LookPath.
	LookPath func(name string) (string, error)

	// SkipProbe disables the construction-time liveness check in
	// HTTP-server mode. Tests use this when the goal is to assert
	// capability / Spawn behavior without standing up a server.
	SkipProbe bool
}

Options configures Provider construction.

type Provider

type Provider struct {
	// contains filtered or unexported fields
}

Provider is the agent.Provider implementation for OpenCode. It supports two execution modes:

1. CLI mode (preferred): Spawn execs `opencode run --format json` which streams NDJSON events to stdout.
2. HTTP-server mode (legacy/fallback): operator runs `opencode serve`; the provider posts tasks to the REST API and streams WebSocket events. Not yet wired — Spawn returns ErrSpawnFailed in this mode until the REST client lands.

func New

func New(opts Options) (*Provider, error)

New constructs a Provider.

Construction order:

1. Probe for the `opencode` CLI binary on PATH. If found, use CLI mode — no HTTP probe needed.
2. If the binary is not on PATH, fall back to HTTP-server mode: probe the OpenCode HTTP server at the configured endpoint. Connection refused or 5xx → wrapped agent.ErrProviderUnavailable.

func (*Provider) Capabilities

func (*Provider) Capabilities() agent.Capabilities

Capabilities returns the v1.0.0 capability matrix for the OpenCode CLI runner.

func (*Provider) Name

func (*Provider) Name() agent.ProviderName

Name returns ProviderOpenCode. Stable for the lifetime of the Provider.

func (*Provider) Resume

func (*Provider) Resume(_ context.Context, _ string, _ agent.Spec) (agent.Handle, error)

Resume always fails with agent.ErrUnsupported.

func (*Provider) Shutdown

func (*Provider) Shutdown(_ context.Context) error

Shutdown is a no-op. There are no long-lived resources.

func (*Provider) Spawn

func (p *Provider) Spawn(ctx context.Context, spec agent.Spec) (agent.Handle, error)

Spawn starts a new OpenCode session.

In CLI mode (opencode binary on PATH):

opencode run --format json --dangerously-skip-permissions
             [--dir <cwd>]
             [--model <id>]
             [--variant <effort>]

The prompt is delivered via stdin. OpenCode's --format json mode streams NDJSON events that are translated to agent.Event values by mapOpenCodeLine.

In HTTP-server mode: returns ErrSpawnFailed (not yet wired).

On any pre-spawn failure (exec start) the provider returns an error wrapping agent.ErrSpawnFailed.