launch

type ClaudeConnector ¶

type ClaudeConnector struct {
	// Models are the harness-facing model aliases SelectDefaultModel and
	// SelectSmallModel apply.
	Models ClaudeModels
	// Effort is the harness-facing reasoning effort SelectEffort applies via
	// the advertised thought_level config option. Empty leaves effort
	// selection to Claude Code.
	Effort string
	// CLIPath, if non-empty, must be an absolute path pinning the
	// underlying `claude` CLI claude-agent-acp drives (CLAUDE_CODE_EXECUTABLE
	// -- see claudecode.go's Configure). Empty omits the variable entirely.
	CLIPath string
}

ClaudeConnector adapts a launched ACP session to claude-agent-acp's specific conventions. Construct with ClaudeCode.

func ClaudeCode(models ClaudeModels) *ClaudeConnector

func (c *ClaudeConnector) ApplyPermissionMode(ctx context.Context, sess *client.Session, modeID protocol.SessionModeID) error

func (c *ClaudeConnector) Configure(cmd stdio.Command, binding ProxyBinding) (stdio.Command, error)

func (c *ClaudeConnector) ConfigureNative(cmd stdio.Command) (stdio.Command, error)

func (c *ClaudeConnector) SelectDefaultModel(ctx context.Context, sess *client.Session) error

func (c *ClaudeConnector) SelectEffort(ctx context.Context, sess *client.Session) error

func (c *ClaudeConnector) SelectSmallModel(ctx context.Context, sess *client.Session) error

type ClaudeModels ¶

type ClaudeModels struct {
	Default string
	Small   string
}

ClaudeModels selects the harness-facing aliases for Claude Code's default and lightweight ("small") model roles: the two values SelectDefaultModel and SelectSmallModel look up among the connected adapter's advertised "model" select config option. Gateway configuration requires both aliases; native no-proxy configuration permits either or both to be empty.

type CodexConnector ¶

type CodexConnector struct {
	// Model is the harness-facing model alias. Gateway Configure embeds it in
	// its provider argv; SelectModel applies it to an existing session's
	// advertised model select option. Native ConfigureNative retains it as
	// managed state and emits no model override. An empty value is a deliberate
	// no-op for session selection and native configuration.
	Model string
	// Effort is the neutral reasoning-effort selector SelectEffort applies to
	// the advertised thought_level option (codex-acp's config ID is currently
	// reasoning_effort). Native ConfigureNative retains it as managed state and
	// emits no model_reasoning_effort override. An empty value is a deliberate
	// no-op.
	Effort string

	// Posture is the sandbox/approval posture Configure applies. The
	// zero value resolves to sane, least-privilege defaults (see
	// CodexPosture.resolve).
	Posture CodexPosture
	// contains filtered or unexported fields
}

CodexConnector adapts a launched ACP session to codex-acp's specific conventions. Construct with Codex.

func Codex(model string) *CodexConnector

func (c *CodexConnector) Configure(cmd stdio.Command, binding ProxyBinding) (stdio.Command, error)

func (c *CodexConnector) ConfigureNative(cmd stdio.Command) (stdio.Command, error)

func (c *CodexConnector) SelectEffort(ctx context.Context, sess *client.Session) error

func (c *CodexConnector) SelectModel(ctx context.Context, sess *client.Session) error

func (c *CodexConnector) WithModel(model string) *CodexConnector

func (c *CodexConnector) WithModelEffort(model, effort string) *CodexConnector

type CodexPosture ¶

type CodexPosture struct {
	// ApprovalPolicy is codex-acp's approval_policy `-c` override (e.g.
	// "untrusted", "on-failure", "on-request", "never"). Empty resolves
	// to defaultCodexApprovalPolicy.
	ApprovalPolicy string
	// SandboxMode is codex-acp's sandbox_mode `-c` override (e.g.
	// "read-only", "workspace-write", "danger-full-access"). Empty
	// resolves to defaultCodexSandboxMode.
	SandboxMode string
	// SandboxNetworkAccess is codex-acp's
	// sandbox_workspace_write.network_access `-c` override: required
	// when the child must reach loopback HTTP MCP servers or the
	// gateway from inside Codex's sandbox (see the design doc). Its zero
	// value (false, deny) is already the least-privilege default and is
	// never substituted for.
	SandboxNetworkAccess bool
}

CodexPosture is the caller-chosen sandbox/approval posture codex-acp is launched under: an application-level choice this package never hardcodes (see codex.go's Configure/codexConfigArgs).

type CodexVersion ¶

type CodexVersion struct {
	Major, Minor, Patch int
}

CodexVersion is a parsed codex-acp "<major>.<minor>.<patch>" version.

func ParseCodexVersion(raw string) (CodexVersion, bool)

func (v CodexVersion) Less(other CodexVersion) bool

func (v CodexVersion) String() string

type CodexVersionClass ¶

type CodexVersionClass int

CodexVersionClass classifies a codex-acp version probe's outcome. Every value other than CodexVersionModern is a fail-closed rejection: an adapter is accepted only at CodexVersionModern, never on ambiguity.

const (
	// CodexVersionUnknown is CodexVersionClass's zero value: it is never
	// returned by ProbeCodexVersion, which always assigns one of the
	// named classes below.
	CodexVersionUnknown CodexVersionClass = iota
	// CodexVersionModern: parseable, >= MinCodexVersion. The only class
	// ProbeCodexVersion accepts (returns a nil error for).
	CodexVersionModern
	// CodexVersionBelowMinimum: parseable, but < MinCodexVersion.
	CodexVersionBelowMinimum
	// CodexVersionLegacyNoVersion: the probe exited successfully but
	// produced no recognizable version output at all (empty stdout) --
	// one plausible shape for a legacy binary that silently ignores
	// --version. (The historical @zed-industries/codex-acp 0.16.x binary
	// in practice exits non-zero for an unrecognized flag, which
	// classifies as CodexVersionNonzeroExit instead; both fail closed
	// identically, so the practical rejection outcome is the same either
	// way.)
	CodexVersionLegacyNoVersion
	// CodexVersionUnparseable: the probe produced non-empty output that
	// does not match the expected "<major>.<minor>.<patch>" shape (a
	// partial version, a prerelease/build suffix, or unrelated text).
	CodexVersionUnparseable
	// CodexVersionNonzeroExit: the probe process itself failed to run to
	// a clean, successful exit (a real invocation error, or a nonzero
	// exit status).
	CodexVersionNonzeroExit
	// CodexVersionTimeout: the probe did not complete within the bound
	// ProbeCodexVersion applied.
	CodexVersionTimeout
)

func (c CodexVersionClass) String() string

type CodexVersionError ¶

type CodexVersionError struct {
	Path   string
	Result CodexVersionResult
}

CodexVersionError reports that a codex-acp version probe (see ProbeCodexVersion in version.go) did not clear MinCodexVersion, for any reason: below the floor, a legacy binary with no recognizable version output, unparseable output, a nonzero exit, or a timeout. Every one of those classifications fails closed identically from a caller's perspective -- reject the adapter -- with Result carrying the specific CodexVersionClass a caller can inspect or log.

func (e *CodexVersionError) Error() string

type CodexVersionResult ¶

type CodexVersionResult struct {
	Class   CodexVersionClass
	Version CodexVersion
	Raw     string
}

CodexVersionResult is ProbeCodexVersion's outcome: a classification plus (when parseable) the actual version observed and the raw probe output, kept only for diagnosis -- callers must never parse Raw themselves; the only supported interpretation of a probe is Class (and Version, when Class is CodexVersionModern or CodexVersionBelowMinimum).

func ProbeCodexVersion(ctx context.Context, path string, timeout time.Duration, runner CodexVersionRunner) (CodexVersionResult, error)

type CodexVersionRunner ¶

type CodexVersionRunner func(ctx context.Context, path string) (stdout []byte, err error)

CodexVersionRunner runs one bounded codex-acp version probe and returns its raw stdout and the invocation's error (nil on a clean, successful exit). ctx is already bound to ProbeCodexVersion's own timeout; a real implementation (defaultCodexVersionRunner) must honor ctx's deadline/cancellation and must never block past it. Tests substitute a fake runner so no real codex-acp binary is ever spawned (see version_test.go / codex_test.go).

type Config ¶

type Config struct {
	// OwnedProxy, if set, is started before the ACP child is spawned and
	// closed when the resulting ManagedClient closes, or when its ACP child
	// dies unexpectedly. Mutually exclusive with SharedProxy: exactly one of
	// the two is required (see validateConfig).
	OwnedProxy ModelProxy
	// SharedProxy, if set, is borrowed data only: this package never starts
	// or closes it. The application that created the shared proxy owns its
	// lifecycle and is responsible for closing it once every borrower is
	// finished; this package has no opinion about that and, since
	// *ProxyBinding carries no lifecycle methods at all, no way to act on it
	// even if it wanted to. Mutually exclusive with OwnedProxy.
	SharedProxy *ProxyBinding
	// NoProxy explicitly selects a child-owned authentication path. It is
	// mutually exclusive with OwnedProxy and SharedProxy and requires Harness
	// to implement either NativeHarnessAdapter or the legacy internal no-proxy
	// connector seam. New callers should prefer DialNative.
	NoProxy bool
	// Harness configures Command for whichever ProxyBinding results from
	// OwnedProxy or SharedProxy.
	Harness HarnessAdapter
	// Command is the base stdio.Command Harness.Configure adapts. Its
	// executable Path is the caller's responsibility to supply (this
	// package never performs PATH lookup, invokes a shell, or installs
	// anything).
	Command stdio.Command
	// Client is passed through unchanged to the underlying acp/client
	// connection.
	Client client.Options
}

Config is Dial's complete configuration.

type ConfigError ¶

type ConfigError struct{ Reason string }

ConfigError reports an invalid Config discovered before Dial starts anything: neither or both of OwnedProxy/SharedProxy set, or no HarnessAdapter supplied. Caught here rather than surfacing as a nil-pointer panic or a wastefully-started proxy.

func (e *ConfigError) Error() string

type ConflictingEnvError ¶

type ConflictingEnvError struct{ Key string }

ConflictingEnvError reports that a caller-supplied stdio.Command.Env already contained a security-sensitive variable name a HarnessAdapter must exclusively own (either because the adapter sets it itself, or because the child's own contract requires it be absent) -- rejected rather than silently overwritten or stripped.

func (e *ConflictingEnvError) Error() string

type EffortAliasError ¶

type EffortAliasError struct {
	Effort string
	Alias  string
}

EffortAliasError reports that a requested reasoning-effort selector matched no value the connected adapter's advertised thought_level option exposed. Alias is retained as a compatibility spelling for callers that classify selector errors uniformly; Effort is the canonical field.

func (e *EffortAliasError) Error() string

type EffortSelectionError ¶

type EffortSelectionError = EffortAliasError

EffortSelectionError is a descriptive alias for EffortAliasError.

type GeminiAdapter ¶

type GeminiAdapter struct {
	// Model is the harness-facing model alias GEMINI_MODEL is set to.
	// Required.
	Model string
}

GeminiAdapter is a HarnessAdapter for the Gemini CLI harness. Construct with Gemini.

func Gemini(model string) *GeminiAdapter

func (g *GeminiAdapter) Configure(cmd stdio.Command, binding ProxyBinding) (stdio.Command, error)

type HarnessAdapter ¶

type HarnessAdapter interface {
	Configure(stdio.Command, ProxyBinding) (stdio.Command, error)
}

HarnessAdapter configures a stdio.Command for one specific foreign ACP agent's launch contract -- its executable, argument shape, and environment variables -- given the ProxyBinding it should be pointed at.

Configure must return a fresh Command derived from cmd, never mutate cmd (or its Env/Args backing arrays) in place, and must never inherit the ambient process environment or forward upstream provider credentials (see the design doc's "Environment safety" and acp/CLAUDE.md's own rule to the same effect).

type ManagedClient ¶

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

ManagedClient is one launched ACP connection together with whatever model proxy it owns, if any. Construct with Dial.

func Dial(ctx context.Context, cfg Config) (*ManagedClient, error)

func DialNative(ctx context.Context, cfg NativeConfig) (*ManagedClient, error)

func (m *ManagedClient) Client() *client.Client

func (m *ManagedClient) Close(ctx context.Context) error

type ModelAliasError ¶

type ModelAliasError struct{ Alias string }

ModelAliasError reports that a requested harness-facing model alias matched no value the connected adapter's "model" select config option advertised -- including the case where no such option was advertised at all. Model selection never silently no-ops: an unmatched alias is always a typed error.

func (e *ModelAliasError) Error() string

type ModelProxy ¶

type ModelProxy interface {
	// Start brings the proxy up. It must return before Binding is called.
	Start(context.Context) error
	// Binding reports the proxy's current connection info. ready is false
	// until the proxy has something callers can actually use; Dial treats a
	// false ready immediately after a successful Start as a startup-contract
	// violation (see ProxyNotReadyError) rather than proceeding with an
	// undefined binding.
	Binding() (baseURL, token string, ready bool)
	// Close tears the proxy down. Implementations must make Close safe to
	// call at most once in practice; ManagedClient itself also never calls
	// it more than once for a given owned proxy (see ManagedClient.Close's
	// doc), but a well-behaved ModelProxy should not depend on that.
	Close(context.Context) error
}

ModelProxy is a model proxy this package owns: started before the ACP child is spawned and closed when the resulting ManagedClient closes or its ACP child dies unexpectedly (see ManagedClient's doc).

Binding's three-plain-value return shape (rather than returning a ProxyBinding) is deliberate, not an oversight: Go requires identical method signatures for structural interface satisfaction, and a bare (string, string, bool) tuple is far more likely to already be exactly what an independently-built proxy server type naturally exposes than a package-specific struct type would be. That is what lets such a type satisfy ModelProxy with no import of, or coupling to, this package at all.

type NativeConfig ¶

type NativeConfig struct {
	Harness NativeHarnessAdapter
	Command stdio.Command
	Client  client.Options
}

NativeConfig is the proxy-free configuration accepted by DialNative. Its shape deliberately has no OwnedProxy, SharedProxy, or binding field, so a native launch cannot accidentally acquire gateway lifecycle or credentials.

type NativeHarnessAdapter ¶

type NativeHarnessAdapter interface {
	HarnessAdapter
	ConfigureNative(stdio.Command) (stdio.Command, error)
}

NativeHarnessAdapter configures a child to use the harness's own authentication and model selection. ConfigureNative must preserve the same command-copying, absolute-path, environment, and credential-safety rules as Configure. Explicit native model selection may produce a caller-selected model override (for example, Codex `-c model`), while ConfigureNative must never add gateway URL, gateway token, or gateway provider/base-url overrides. When the model is omitted, model selection remains harness-managed.

It embeds HarnessAdapter so one connector has an explicit, reviewable gateway path and native path rather than an ambiguous Configure call whose behavior depends on the binding value.

type PathError ¶

type PathError struct{ Field, Reason string }

PathError reports that a caller-supplied executable path -- the ACP adapter binary itself, or an underlying CLI a connector pins -- was not a clean, absolute path. Validated before any process is started; this package never resolves a path via PATH lookup or a shell.

func (e *PathError) Error() string

type ProxyBinding ¶

type ProxyBinding struct {
	BaseURL string
	Token   string
}

ProxyBinding is the connection info a model proxy exposes to whatever ACP adapter it fronts: a local base URL and bearer token the adapter's upstream-model client should be pointed at instead of a real provider.

It is plain data, never a lifecycle handle: a SharedProxy is borrowed (see Config.SharedProxy's doc), and *ProxyBinding deliberately has no Start or Close method at all, so there is no call path by which this package could ever start or stop a proxy it does not own.

type ProxyNotReadyError ¶

type ProxyNotReadyError struct{}

ProxyNotReadyError reports that an owned ModelProxy's Start returned successfully but its own Binding immediately reported ready=false -- a startup-contract violation Dial treats as a failure (closing the proxy it just started) rather than proceeding with an undefined binding.

func (e *ProxyNotReadyError) Error() string