opencodeacp

package module
v0.2.0 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Oct 11, 2026 License: MIT Imports: 41 Imported by: 0

README

acp-go-opencode

acp-go-opencode exposes OpenCode as an Agent Client Protocol agent. One opencode serve process handles the Agent's sessions through authenticated loopback HTTP and a shared event stream.

Sessions retain OpenCode's native storage. After closing the adapter, continue a session in the same directory and native home:

opencode run --session NATIVE_SESSION_ID "Continue the task"

New, load, and resume responses and session-list entries expose the current native ID as _meta.opencode.nativeSessionId. Use it for native CLI continuation. ACP requests continue to use the stable ACP sessionId. The store's configuration record saves both IDs with the matching native history.

Install and run

go install github.com/savid/acp-go-opencode/cmd/acp-go-opencode@latest
acp-go-opencode [-path opencode] [-home DIR] [-scratch-dir DIR] [-model provider/id] [-seed-file rel=host]... [-debug]

A bare -path is resolved on the inherited PATH. -home maps DIR/data, DIR/config, DIR/cache, and DIR/state to the four XDG home variables; omit it to use native home resolution. Native CLI continuation uses those same variables when a home was supplied. -seed-file writes a relative file inside OpenCode's configuration directory. -scratch-dir holds the temporary environment plugin. -version prints the adapter version. Standard OTEL_* variables configure telemetry exporters.

Embed

err := opencodeacp.Serve(ctx, os.Stdin, os.Stdout,
    opencodeacp.WithHome("/srv/opencode"),
    opencodeacp.WithSessionStore(store),
)

Options: WithExecutablePath, WithHome, WithScratchDir, WithInputHandoffRoot, WithDefaultModel, WithConfiguredModels, WithEnv, WithSeedFiles, WithSessionStore, WithConcurrencyLimits, WithImageLimits, WithLogger, WithTracerProvider, WithMeterProvider, WithTextMapPropagator, WithAgentName, WithAgentTitle, WithAgentVersion.

Session options

Pass _meta.opencode.options on new, load, or resume, or use WithSessionOpenCodeOptions from Go.

Field Meaning
model Provider-qualified model ID
mode Native agent name, such as build or plan
effort Native model variant, forwarded unchanged
permission Native tool policy: ask, allow, or deny; default ask
env Environment overlay for tools in this session
extraPathDirs Absolute directories prepended to the session's PATH in order
outputSchema Nonempty JSON Schema passed through native structured output

The environment plugin reads the addressed session's metadata through OpenCode's API once, and again after the adapter changes any session's carrier. Child sessions inherit that carrier through their native parent. OpenCode keeps its native authentication and configuration. Nonempty mcpServers and unknown owned options are invalid parameters.

session/set_config_option accepts nonempty model, mode, and effort values. The native provider catalog supplies model names, image capabilities, context windows, and available variants. Configured and selected models are included even when absent from the catalog. Structured results appear at _meta.opencode.structuredOutput on the prompt response.

Native permission requests use ACP permissions; native questions use ACP form elicitation. Missing or cancelled answers reject the native request. Commands come from OpenCode's command catalog. An exact /name match against an advertised command uses the native command endpoint; other text uses the message endpoint.

Images enter as inline base64 or validated file handoffs. Output supports native file parts and tool attachments, with bounded local reads and image limits. Remote URLs become resource links. _meta.opencode.rawEvent.enabled enables _opencode/rawEvent; image bytes are omitted from that diagnostic channel. Optional lifecycle negotiation supplies ordered session and turn updates.

Each model call reports a usage_update with its token breakdown when its step-finish part arrives. Agent message and thought chunks carry no messageId, and the breakdown carries no responseId: OpenCode keeps none of the gateway's response ids, and its own message and part ids are not response ids.

Persistence and runtime

SessionStoreFormat is opencode-sync-events-v2. The main subpath holds native sync events for one conversation and its descendants. The config sidecar holds accepted options, the session title, and captured local image bytes. A session's title is its first prompt's first non-empty text; listing reads stored sessions from their config record alone.

The first commit publishes the whole conversation graph. Each settled turn then reads the events added since the last commit with a scoped opencode db query, with the graph idle before and after the read, and appends them before the prompt returns. Each read selects about 8 MiB of event data, so a long history reads in several queries. A graph that starts running during a read is read again once it is idle. Events OpenCode writes after a turn reports idle, such as a generated title, join the next commit. A configuration change appends only the new configuration and reads no native history; a commit with neither writes nothing. A turn reads its own messages a page at a time from the newest, never the whole session. The native CLI opens its own database files.

Load imports missing events through the native sync API, one conversation at a time with parents first, and replays ACP history. Resume imports without replay. Restore adopts the stored history and commits only newer native events and the configuration. Existing native history must agree at every shared sequence; newer native events are adopted after the stored ones, which stay an exact prefix of the restored history. Local image replay remains available after its original file is removed. The default store is in memory; supply a durable store to restore across adapter restarts.

Close releases one session while peers retain the shared server. A server crash fails affected work, and the next operation starts a replacement and rebinds the addressed session. Delete tombstones the store entry. Native state remains available to OpenCode's CLI. A native-home file lock prevents two adapter servers from owning the same home concurrently.

Native memory settings

OpenCode reads these variables from its environment; the adapter leaves them to the host. Hosts that bound memory can set them with WithEnv or in the adapter's environment:

Variable Effect
OPENCODE_EXPERIMENTAL_DISABLE_FILEWATCHER=true No recursive file watcher
OPENCODE_DISABLE_FFF=true File search runs ripgrep instead of keeping an in-process index
OPENCODE_DISABLE_MODELS_FETCH=true No models.dev download or hourly refresh; the catalog comes from the cached or built-in snapshot, so a binary without either has an empty catalog
OPENCODE_DISABLE_AUTOUPDATE=true No update check

Development

make test
make lint
make audit
make test-integration-smoke
ACP_GO_OPENCODE_MODEL=provider/model make test-integration-live

Unit tests use a scripted native HTTP server inside the test binary and require no installed OpenCode or credentials. Smoke tests use the installed CLI without model calls. Live tests copy native auth into temporary homes and spend tokens.

Account usage

AccountUsageMethod (_opencode/accountUsage) accepts sessionId and providerId (opencode-go, openrouter, anthropic, or openai-codex). Initialization advertises the method, session scope, and supported providers. A provider the catalog routes through a gateway that publishes a usage report is read from that report with the catalog's key for it. Reads hold the session's foreground gate and spend no model tokens.

The adapter resolves the directory's effective API key and route through the native server. Only official endpoints and verified API-key routes are read; authentication plugins for the requested provider or unverified authentication overrides yield not_reported. Plugins for other providers do not block reads. Credentials stay local. Provider HTTP reads come from github.com/savid/acp-go-core/usage.

OpenCode Go reports rolling, weekly, and monthly percentage windows. OpenRouter reports key spending caps, lifetime spend, free-model request counts, and any account credit balance accessible with the same key. Dollar amounts are USD; a missing cap is explicitly uncapped, zero is a real value, and a negative remaining balance is preserved. Account credits and key caps remain separate. Each measurement retains its own observation and expiry times. Unavailable optional account credits do not discard key data.

Claude and ChatGPT subscription usage require effective OAuth credentials from the native runtime. The provider catalog exposes API-key routes only; plugin credentials are private, so subscription usage is not advertised.

Context compaction

Reports summary creation as progress, summary errors as failure or cancellation, and the native compaction success event as completion. The parent compaction part identifies the automatic or manual trigger when present. Context counts are unavailable.

Notifications carry acp-go.dev/compaction on the notification’s _meta, with an otherwise empty session_info_update. The value is acp-go-core wire.Compaction: a required compactionId and status, and optional trigger, contextBefore, and contextAfter. A start and its outcome share an ID. Unknown facts are omitted. These are live notifications; historical replay emits none. Usage accounting is independent.

Documentation

Overview

Package opencodeacp exposes OpenCode as an Agent Client Protocol agent.

Serve starts one authenticated loopback OpenCode server for all sessions. The harness inherits the adapter environment and keeps its native state in its XDG home, so the conversation can also continue through OpenCode's CLI.

WithSessionStore supplies durable per-conversation snapshots. Load restores and replays history; resume restores without replay. The adapter preserves native state when sessions close.

Hosts supply telemetry providers through WithTracerProvider and WithMeterProvider; the package never configures global providers.

Index

Examples

Constants

View Source
const (
	// RawEventMethod is the notification carrying one raw opencode event when a
	// session opted in through _meta.opencode.rawEvent.enabled.
	RawEventMethod = "_opencode/rawEvent"
	// AccountUsageMethod reads the addressed native provider's account usage.
	AccountUsageMethod = "_opencode/accountUsage"
	// SessionStoreFormat identifies the store layout this package writes: the
	// native sync-event graph under main plus the adapter's session record
	// under the config subpath.
	SessionStoreFormat = "opencode-sync-events-v2"
)

Variables

This section is empty.

Functions

func Serve

func Serve(ctx context.Context, input io.Reader, output io.Writer, opts ...Option) (returnErr error)

Serve runs an ACP agent over the provided streams. It blocks until the context is cancelled or the peer closes the connection, then closes the agent.

Example (Initialize)

ExampleServe_initialize embeds the agent over a pair of pipes, the same wiring a host uses for stdio, and reads the capabilities the handshake advertises.

package main

import (
	"bufio"
	"context"
	"encoding/json"
	"fmt"
	"io"

	opencodeacp "github.com/savid/acp-go-opencode"
)

func main() {
	ctx, cancel := context.WithCancel(context.Background())
	defer cancel()

	clientToAgentReader, clientToAgentWriter := io.Pipe()
	agentToClientReader, agentToClientWriter := io.Pipe()

	done := make(chan error, 1)

	go func() {
		done <- opencodeacp.Serve(ctx, clientToAgentReader, agentToClientWriter)
	}()

	_, _ = fmt.Fprintln(clientToAgentWriter,
		`{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":1}}`)

	line, _ := bufio.NewReader(agentToClientReader).ReadString('\n')

	cancel()
	_ = clientToAgentWriter.Close()
	<-done

	var response struct {
		Result struct {
			AuthMethods       []any `json:"authMethods"`
			AgentCapabilities struct {
				LoadSession         bool           `json:"loadSession"`
				SessionCapabilities map[string]any `json:"sessionCapabilities"`
			} `json:"agentCapabilities"`
		} `json:"result"`
	}

	_ = json.Unmarshal([]byte(line), &response)

	fmt.Println(len(response.Result.AuthMethods))
	fmt.Println(response.Result.AgentCapabilities.LoadSession)
	fmt.Println(len(response.Result.AgentCapabilities.SessionCapabilities))
}
Output:
0
true
5

func SetModelRequest

func SetModelRequest(sessionID acp.SessionId, model string) acp.SetSessionConfigOptionRequest

SetModelRequest constructs a model selector update as "provider/id".

func ValidateOpenCodeSessionMeta added in v0.2.0

func ValidateOpenCodeSessionMeta(meta map[string]any) error

ValidateOpenCodeSessionMeta runs the owned-namespace parsing of a session lifecycle request's _meta without an Agent and returns the same refusal.

func WithSessionOpenCodeOptions

func WithSessionOpenCodeOptions(options OpenCodeOptions) wire.SessionRequestOption

WithSessionOpenCodeOptions merges opencode-specific options into _meta.opencode.options.

func WithSessionOutputSchema

func WithSessionOutputSchema(schema map[string]any) wire.SessionRequestOption

WithSessionOutputSchema sets the native structured-output JSON schema. An empty schema is refused at session start.

func WithSessionRawEvents

func WithSessionRawEvents(enabled bool) wire.SessionRequestOption

WithSessionRawEvents toggles raw opencode event emission for the session.

Types

type Agent

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

Agent exposes the opencode coding agent through ACP.

func NewAgent

func NewAgent(opts ...Option) *Agent

NewAgent creates an ACP agent for the opencode coding agent CLI. Construction never fails; a refused option is reported by Initialize and every session-establishing method as opencode_invalid_options.

func (*Agent) Authenticate

func (a *Agent) Authenticate(_ context.Context, params acp.AuthenticateRequest) (acp.AuthenticateResponse, error)

Authenticate exists because the SDK interface requires it. The harness authenticates itself in its own home, outside ACP.

func (*Agent) Cancel

func (a *Agent) Cancel(ctx context.Context, params acp.CancelNotification) (err error)

Cancel interrupts the session's in-flight turn. It is wire-silent on an unknown session or with no turn in flight.

func (*Agent) Close

func (a *Agent) Close() error

Close runs the shutdown ladder for every session and refuses every later request.

func (*Agent) CloseSession

func (a *Agent) CloseSession(ctx context.Context, params acp.CloseSessionRequest) (resp acp.CloseSessionResponse, err error)

CloseSession runs the shutdown ladder for one session.

func (*Agent) HandleExtensionMethod

func (a *Agent) HandleExtensionMethod(ctx context.Context, method string, params json.RawMessage) (any, error)

HandleExtensionMethod serves the account-usage read; every other extension method is method-not-found.

func (*Agent) Initialize

func (a *Agent) Initialize(ctx context.Context, params acp.InitializeRequest) (resp acp.InitializeResponse, err error)

Initialize implements ACP initialize.

func (*Agent) ListSessions

func (a *Agent) ListSessions(ctx context.Context, params acp.ListSessionsRequest) (resp acp.ListSessionsResponse, err error)

ListSessions lists live sessions and stored sessions, newest first.

func (*Agent) LoadSession

func (a *Agent) LoadSession(ctx context.Context, params acp.LoadSessionRequest) (resp acp.LoadSessionResponse, err error)

LoadSession restores a session and replays its history.

func (*Agent) Logout

func (a *Agent) Logout(_ context.Context, params acp.LogoutRequest) (acp.LogoutResponse, error)

Logout exists because the SDK interface requires it.

func (*Agent) NewSession

func (a *Agent) NewSession(ctx context.Context, params acp.NewSessionRequest) (resp acp.NewSessionResponse, err error)

NewSession creates and starts a opencode session.

func (*Agent) Prompt

func (a *Agent) Prompt(ctx context.Context, params acp.PromptRequest) (resp acp.PromptResponse, err error)

Prompt sends one turn to opencode and streams updates until it settles.

func (*Agent) ResumeSession

func (a *Agent) ResumeSession(ctx context.Context, params acp.ResumeSessionRequest) (resp acp.ResumeSessionResponse, err error)

ResumeSession restores a session without replaying its history.

func (*Agent) SetSessionConfigOption

func (a *Agent) SetSessionConfigOption(ctx context.Context, params acp.SetSessionConfigOptionRequest) (resp acp.SetSessionConfigOptionResponse, err error)

SetSessionConfigOption applies one select value.

func (*Agent) SetSessionMode

SetSessionMode exists because the SDK interface requires it. Native modes are config options, never ACP session modes.

func (*Agent) UnstableDeleteSession

func (a *Agent) UnstableDeleteSession(ctx context.Context, params acp.UnstableDeleteSessionRequest) (resp acp.UnstableDeleteSessionResponse, err error)

UnstableDeleteSession tombstones the session first, then closes any live session with the same id. Native state stays in opencode's home.

type ConcurrencyLimits

type ConcurrencyLimits struct {
	MaxActiveSessions        int
	MaxConcurrentClientCalls int
}

ConcurrencyLimits controls per-agent backpressure. Zero fields use defaults.

type ImageLimits

type ImageLimits struct {
	MaxInputBytesPerImage     int64
	MaxInputBytesPerPrompt    int64
	MaxOutputBytesPerImage    int64
	MaxOutputBytesPerToolCall int64
}

ImageLimits bounds decoded image bytes. A zero field disables that policy limit; the frame clamp still applies.

type OpenCodeOption

type OpenCodeOption func(*OpenCodeOptions)

OpenCodeOption configures OpenCodeOptions values.

func WithOpenCodeEffort added in v0.2.0

func WithOpenCodeEffort(level string) OpenCodeOption

WithOpenCodeEffort configures the reasoning level passed to opencode.

func WithOpenCodeEnv

func WithOpenCodeEnv(env map[string]string) OpenCodeOption

WithOpenCodeEnv configures the session environment overlay.

func WithOpenCodeExtraPathDirs

func WithOpenCodeExtraPathDirs(dirs ...string) OpenCodeOption

WithOpenCodeExtraPathDirs configures the directories prepended to the session PATH.

func WithOpenCodeMode

func WithOpenCodeMode(mode string) OpenCodeOption

WithOpenCodeMode selects a native agent.

func WithOpenCodeModel

func WithOpenCodeModel(model string) OpenCodeOption

WithOpenCodeModel configures the session model as "provider/id".

func WithOpenCodeOutputSchema

func WithOpenCodeOutputSchema(schema map[string]any) OpenCodeOption

WithOpenCodeOutputSchema configures native structured output.

func WithOpenCodePermission

func WithOpenCodePermission(permission string) OpenCodeOption

WithOpenCodePermission selects native tool permission behavior.

type OpenCodeOptions

type OpenCodeOptions struct {
	// Mode selects a native agent.
	Mode string `json:"mode,omitempty"`
	// Permission selects ask, allow, or deny for native tools.
	Permission string `json:"permission,omitempty"`
	// Model selects the opencode model for this session as "provider/id".
	Model string `json:"model,omitempty"`
	// Env overlays the session's opencode process environment.
	Env map[string]string `json:"env,omitempty"`
	// ExtraPathDirs are absolute directories prepended, in order, to the PATH
	// of this session's opencode process.
	ExtraPathDirs []string `json:"extraPathDirs,omitempty"`
	// OutputSchema requests native structured output.
	OutputSchema map[string]any `json:"outputSchema,omitempty"`
	// Effort is a reasoning-level value passed unchanged to opencode.
	Effort string `json:"effort,omitempty"`
}

OpenCodeOptions is the per-session options struct carried at _meta.opencode.options.

func NewOpenCodeOptions

func NewOpenCodeOptions(opts ...OpenCodeOption) OpenCodeOptions

NewOpenCodeOptions constructs OpenCodeOptions from functional options.

Example
package main

import (
	"fmt"

	opencodeacp "github.com/savid/acp-go-opencode"
)

func main() {
	options := opencodeacp.NewOpenCodeOptions(
		opencodeacp.WithOpenCodeModel("provider/model"),
		opencodeacp.WithOpenCodeEffort("high"),
	)

	fmt.Println(options.Model)
	fmt.Println(options.Effort)
}
Output:
provider/model
high

func (OpenCodeOptions) Meta

func (options OpenCodeOptions) Meta() map[string]any

Meta returns exactly {"opencode": {"options": {...}}} with the selected fields.

type Option

type Option func(*Options)

Option configures the opencode ACP agent.

func WithAgentName

func WithAgentName(name string) Option

WithAgentName sets the protocol identifier advertised during ACP initialize.

func WithAgentTitle

func WithAgentTitle(title string) Option

WithAgentTitle sets the human-readable agent name advertised during ACP initialize.

func WithAgentVersion

func WithAgentVersion(version string) Option

WithAgentVersion sets the agent version advertised during ACP initialize.

func WithConcurrencyLimits

func WithConcurrencyLimits(limits ConcurrencyLimits) Option

WithConcurrencyLimits sets process-local backpressure limits.

func WithConfiguredModels added in v0.2.0

func WithConfiguredModels(ids []string) Option

WithConfiguredModels names the models the host lists explicitly.

func WithDefaultModel

func WithDefaultModel(model string) Option

WithDefaultModel selects the model for new sessions as "provider/id".

func WithEnv

func WithEnv(env map[string]string) Option

WithEnv sets the static agent-scoped environment overlay applied to every opencode process after the inherited environment and before the session env.

func WithExecutablePath

func WithExecutablePath(path string) Option

WithExecutablePath selects the opencode executable.

func WithHome

func WithHome(path string) Option

WithHome sets opencode's native config root, passed to every session as the four XDG home variables.

func WithImageLimits

func WithImageLimits(limits ImageLimits) Option

WithImageLimits bounds decoded image bytes. A zero field disables that policy limit; a negative field fails construction.

func WithInputHandoffRoot

func WithInputHandoffRoot(dir string) Option

WithInputHandoffRoot sets the absolute directory under which handoff-form prompt images are read. The adapter never writes there.

func WithLogger

func WithLogger(logger *slog.Logger) Option

WithLogger configures structured diagnostic logging.

func WithMeterProvider

func WithMeterProvider(provider metric.MeterProvider) Option

WithMeterProvider configures the OpenTelemetry meter provider.

func WithScratchDir

func WithScratchDir(dir string) Option

WithScratchDir sets the parent directory for ephemeral adapter state.

func WithSeedFiles

func WithSeedFiles(files map[string]string) Option

WithSeedFiles registers files written into opencode's config root before each launch. Keys are paths relative to that root; values are the contents.

func WithSessionStore

func WithSessionStore(store acpcore.SessionStore) Option

WithSessionStore configures the session store.

func WithTextMapPropagator

func WithTextMapPropagator(propagator propagation.TextMapPropagator) Option

WithTextMapPropagator configures trace-context extraction from ACP _meta.

func WithTracerProvider

func WithTracerProvider(provider trace.TracerProvider) Option

WithTracerProvider configures the OpenTelemetry tracer provider.

type Options

type Options struct {
	// AgentName is the protocol identifier advertised during ACP initialize.
	AgentName string
	// AgentTitle is the human-readable agent name advertised during ACP initialize.
	AgentTitle string
	// AgentVersion is the agent version advertised during ACP initialize.
	AgentVersion string

	// ExecutablePath selects the opencode executable. A bare name is searched on the
	// base PATH; a path containing a separator is used as given. Empty means
	// "opencode".
	ExecutablePath string
	// Home contains data, config, cache, and state directories mapped to the
	// corresponding XDG home variables. Empty leaves opencode to resolve its home from
	// the inherited environment exactly as it would from a shell.
	Home string
	// ScratchDir is the parent directory for ephemeral adapter state. Empty
	// means the system temp directory.
	ScratchDir string
	// InputHandoffRoot is the absolute directory under which handoff-form
	// prompt images are read. Empty rejects the handoff form.
	InputHandoffRoot string
	// DefaultModel selects the model for new sessions as "provider/id".
	DefaultModel string
	// ConfiguredModels are the model ids the host lists explicitly, each as
	// "provider/id".
	ConfiguredModels []string
	// Env is the static agent-scoped overlay on the inherited process
	// environment every opencode process runs with.
	Env map[string]string

	// Logger receives structured diagnostic logs. If nil, the default logger is used.
	Logger *slog.Logger
	// TracerProvider records adapter spans. If nil, tracing is a no-op.
	TracerProvider trace.TracerProvider
	// MeterProvider records adapter metrics. If nil, metrics are no-ops.
	MeterProvider metric.MeterProvider
	// TextMapPropagator extracts trace context from ACP _meta. If nil, W3C
	// trace context plus baggage propagation is used.
	TextMapPropagator propagation.TextMapPropagator

	// SessionStore is the durability boundary for session rows. Nil installs a
	// fresh in-memory store.
	SessionStore acpcore.SessionStore
	// ConcurrencyLimits controls process-local backpressure.
	ConcurrencyLimits ConcurrencyLimits
	// SeedFiles maps paths relative to opencode's config root to file contents
	// written there before each launch.
	SeedFiles map[string]string
	// ImageLimits bounds decoded image bytes on prompt input and emitted
	// output. Every field defaults to 6 MiB when the option is omitted.
	ImageLimits ImageLimits
	// contains filtered or unexported fields
}

Options configures the ACP agent process and the shared OpenCode HTTP server.

Directories

Path Synopsis
cmd
acp-go-opencode command
Package integration holds the tests that run against an installed OpenCode.
Package integration holds the tests that run against an installed OpenCode.
internal

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL