acp

README

acp-go

A small, standard-library-only Go client for Agent Client Protocol v1, extracted from release-bot for reuse by release-bot and issue-bot.

go get github.com/BrokkAi/acp-go@master

The generated-schema API below is the v0.2 surface.

connection := acp.Connect(stdout, stdin, handleRequest, handleNotification)
defer connection.Close()
_, err := connection.InitializeWithInfo(ctx, acp.Capabilities{}, acp.ClientInfo{
    Name: "my-app", Version: "1.0.0",
})
// Handle err, then create a session and send prompts.
session, err := connection.NewSession(ctx, absoluteWorkingDirectory)
reason, err := connection.Prompt(ctx, session, "Inspect the project")

The import path is github.com/BrokkAi/acp-go; its package name is acp. The runtime now uses the generated schema types directly: Capabilities, Initialization, Session, Content, Update, and ClientInfo are aliases into that package. This is an intentional v0.x API break. Use acp.WorkspaceCapabilities(readFiles, writeFiles, terminal) for the former boolean FS/terminal fields, Session.SessionID instead of Session.ID, and the content constructors (for example acp.NewTextContent) instead of hand-written discriminator fields.

The caller owns launching the process and implementing the filesystem, terminal, and permission handlers it advertises. Capabilities default to disabled. Authentication, modes (including generated mode state), model and boolean config selection, reasoning effort, prompt content blocks, MCP servers, additional directories, session load/resume/list/close/delete, logout, and typed error classification are supported. Optional methods and prompt content are checked against the agent's advertised capabilities before a request is sent. Use SetModel before SetEffort: models may expose different effort choices. Explicit selections must be acknowledged by the agent; they never silently fall back.

acp.SessionUpdates adapts session/update notifications to the generated discriminated union. acp.HandleElicitation, the elicitation response constructors, ElicitationComplete, and CombineNotifications provide typed form/URL host support, including the agent's URL-completion notification. NewSessionWithOptions, LoadSession, and ResumeSession validate MCP transports and additional workspace roots against initialization capabilities.

Connect owns and closes both streams. Notifications run in wire order before responses and must return promptly without calling back into the connection. Requests run concurrently and must honor cancellation. Frames are bounded at 8 MiB and incoming requests at 32. Close cancels and joins handlers. Generic Call, CallBatch, and Notify permit extensions. CancelRequest sends a typed $/cancel_request for a single outstanding request, preserving the peer's string or numeric ID. Inbound and outgoing JSON-RPC batches retain member order where Rust does; request-bearing inbound batches receive one grouped response array, response batches route by ID, and malformed response-shaped members are ignored. This root transport is also used by the draft-v2 package, while its typed v1 facade remains v1-only.

Run go test -race ./... and go vet ./.... No agent credentials are needed. The fuzz seed corpus runs as part of that command; see CONTRIBUTING.md for longer campaigns and opt-in tests against real ACP agents.

github.com/BrokkAi/acp-go/acptest is the standard-library-only test harness. acptest.NewPair returns an in-memory duplex transport that either a v1 acp.Connection or a draft-v2 v2.Connection can drive; acptest.TestAgent executes deterministic typed prompt commands (acptest.Command), and the package also ships v1/draft-v2 fake agents plus framing helpers (Serve, WriteRequest, ReadResponse) for protocol-router tests. The router tests themselves consume it, so the harness cannot drift.

Agent runtime

github.com/BrokkAi/acp-go/agent serves an agent over stdio. Implement the mandatory agent.Agent interface (Initialize, NewSession, and Prompt); optional lifecycle and config methods are discovered as narrow interfaces such as SessionLoader, SessionCloser, and ConfigOptionSetter. During a prompt, call SessionUpdater.Update to emit typed session/update notifications. The runtime enforces protocol initialization, dispatches generated request/response types, maps session/cancel to prompt-context cancellation, and rejects optional methods omitted from the agent's advertised capabilities.

The same package gives agents typed agent.Client methods for filesystem, permission, terminal, and elicitation callbacks. Client applications can compose typed hosts with agent.HandleFilesystem, HandleTerminal, HandlePermissions, and HandleElicitation. github.com/BrokkAi/acp-go/clienthost is the reference workspace-confined host used by the runner: rooted filesystem access, process-group terminals, bounded output, opt-in auto-approval, slog streaming, and JSONL transcripts. Text-file reads accept only regular files; FIFOs and other special files are rejected without waiting for data.

Runnable examples are included:

go run ./examples/minimal-client -agent-command 'go run ./examples/minimal-agent' -prompt hello
go run ./examples/drive-cli -command 'go run ./examples/minimal-agent' -prompt hello

drive-cli accepts the same mode/model/effort/auth options commonly needed by external CLI adapters; substitute the real agent command for the minimal agent.

github.com/BrokkAi/acp-go/cookbook is a guide to common client, proxy, and agent patterns, ported from the reference Rust cookbook. Each recipe is a runnable example that go test ./... executes: one-shot v1 and draft-v2 prompts, building an agent, ordered application dispatch, draft-v2 session coordination, a proxyrouter proxy component, and attaching MCP servers. Read it with go doc github.com/BrokkAi/acp-go/cookbook.

Wire schema

github.com/BrokkAi/acp-go/schema provides typed constants, request and response structs, notifications, and a method registry for every message in the pinned ACP JSON Schema release (schema-v1.24.1 at the time of writing), including session updates, content blocks, tool calls and their programmatic names, permissions, terminals, elicitation, and config options. The package is generated by cmd/acpgen and guarded by round-trip parity tests, so tracking a new schema release is a reviewed regeneration rather than hand transcription. See CONTRIBUTING.md for the update workflow.

schema/unstable and schema/v2/unstable are separate opt-in packages generated from Rust schema crate 1.10.2's unstable artifacts. They expose the combined optional feature surface, including LLM providers, MCP-over-ACP, NES, plan operations, session fork/compaction/notices, and end-turn token usage. The stable schema and schema/v2 packages do not import or expose those generated types.

Trace context

github.com/BrokkAi/acp-go/tracecontext sets and extracts the root-level _meta keys traceparent, tracestate, and baggage that the ACP extensibility conventions reserve for W3C Trace Context, so MCP and OpenTelemetry integrations can correlate ACP requests, responses, and notifications with the surrounding trace. IntoMeta and FromMeta operate on the generated schema.Meta and v2.Meta maps (and the draft-v2 Nullable[Meta] field that wraps them), while ValidTraceparent checks the fixed W3C grammar without parsing the opaque tracestate or baggage values. The package is standard-library only.

Draft ACP v2

github.com/BrokkAi/acp-go/v2 is a separate draft client for ACP v2, pinned to the official schema-v2.0.0-alpha.7 artifacts in schema/v2. It supports initialization and version selection, auth/login/auth/logout, session creation/resume/list/delete/close, prompt acceptance, cancellation, additional-directory capability checks, and typed session/update dispatch. There is intentionally no v1/v2 conversion layer. The artifacts match Rust schema crate 1.10.2 byte for byte. The generated v2 types use Nullable[T] where the draft distinguishes omitted fields from explicit JSON null, such as message-content patches.

ACP v2 changes prompt semantics: session/prompt returns once the agent inserts the user message into the conversation, while completion is reported later through an idle state_update. The response carries the required messageId of that user message; Prompt and PromptContent return it, the matching user_message update may arrive before or after the response, and the agent runtime refuses to answer session/prompt when an implementation leaves it empty. The v1 runner and agent runtime remain under the root package for stable applications. Draft v2 agents can use github.com/BrokkAi/acp-go/v2/agent; its Agent interface covers the baseline session methods, prompt acceptance, cancellation, and typed permission and elicitation callbacks.

go run ./examples/minimal-agent-v2

github.com/BrokkAi/acp-go/v2 also provides typed host adapters with HandlePermissions, HandleElicitation, and HandleClientHost; install them before session/new because updates and interactive requests can arrive before setup responses. github.com/BrokkAi/acp-go/v2/runner mirrors the reference SDK's one-shot client: it ignores queued updates until the matching session reports running, projects subsequent agent-message chunks and patch snapshots, completes at the next idle update, and cancels permission requests by default. Run the reference-shaped example with:

go run ./examples/v2-one-shot-client \
  -command 'go run ./examples/minimal-agent-v2' \
  -prompt 'Say hello using draft ACP v2.'

MCP-over-ACP remains an explicit draft opt-in through github.com/BrokkAi/acp-go/v2/mcp (draft v2) and github.com/BrokkAi/acp-go/mcp (v1), matching the Rust SDK's separately gated unstable_mcp_over_acp feature; the v1 package is what carries the native acp server transport that the stable v1 schema does not model. Both packages carry the request-scoped mcp/message mover: MessageClient drives an agent-to-provider request and routes its request-scoped notifications, and MessageRouter serves registered server IDs on the provider side, keeping inner MCP errors in the response carrier. Generated protocol versions and error codes use the schema's exact integer widths; in particular, ProtocolVersion is a uint16, so strings and values above 65535 fail to decode.

github.com/BrokkAi/acp-go/agentrouter serves one endpoint with explicit v1 and v2 implementations. It selects the highest configured implementation compatible with the first initialize request, canonicalizes only that initialize frame, and does not convert subsequent traffic.

github.com/BrokkAi/acp-go/clientrouter owns the transport needed for explicit client-side selection. It starts the highest configured implementation and follows the Rust fallback rules: reuse an existing v1-negotiated agent connection only for losslessly identical initialization, otherwise reconnect with fresh factories, and never turn a v2 rejection into a silent v1 retry. github.com/BrokkAi/acp-go/proxyrouter requires an exact configured _proxy/initialize version and hands the complete initial frame to the selected implementation without downgrading or cross-version conversion.

Draft-v2 sessions can use acpv2.NewSessionHandle for Rust-shaped prompt, configuration, cancellation, and close commands. acpv2.SessionTracker owns connection-scoped update projections and active-work state; install it before session setup. acpv2.CancellablePermissions resolves pending permission requests as cancelled when active work is cancelled. ResumeSessionFromStart requires handlers to be installed before the resume request and returns only after replay updates have been applied in wire order.

Process runner

github.com/BrokkAi/acp-go/runner adds a process lifecycle, confined client file operations, terminal callbacks, streaming slog output and private JSONL transcripts. Runner.Execute(ctx, prompt) returns the complete agent text; applications own receipt parsing and workflow policy. Set Config.AutoApprove explicitly to allow permission requests for unattended operation. It defaults to false. This is not an OS sandbox: agents and terminal commands inherit the caller's permissions. SetupError distinguishes failures before a prompt from failures during work, and its Phase field names the step that failed (runner.PhaseSelectModel, runner.PhaseSelectEffort, and so on). Some selection failures are typed for errors.As: *acp.UnknownSelectionError (the value is not offered; Available lists the advertised values), *acp.UnsupportedSelectionError (the agent advertises no such selector), and *acp.RPCError (the agent returned a JSON-RPC error). Other failures stay untyped, including an agent that does not confirm the selection, malformed selector options, transport and context errors, and the legacy unknown session mode error, so a failure that matches none of these is not necessarily an agent rejection.

Terminal-type authentication methods run outside the protocol connection: advertise them with acp.TerminalAuthCapabilities(), resolve the advertised method with runner.TerminalAuthMethod, run the configured agent program interactively with runner.RunTerminalAuth (the method's args are appended and its env overrides the configured environment), then reconnect and initialize again before Runner.Execute. Never pass a terminal method ID to Connection.Authenticate.

Trace viewer

github.com/BrokkAi/acp-go/traceviewer and cmd/acp-trace-viewer render a JSONL transcript (the files clienthost writes) as an ordered sequence diagram over net/http, with an embedded page and no external assets:

go run ./cmd/acp-trace-viewer -addr 127.0.0.1:8787 session.jsonl

FileSource re-reads the transcript on every poll, so a live session updates in place, and Memory serves events pushed by a host. This is a developer tool, not a transport: the SDK still speaks stdio by default.

Draft HTTP transport

github.com/BrokkAi/acp-go/transport/http is an explicit, opt-in binding for the draft Streamable HTTP transport: POST with application/json for frames, Acp-Connection-Id and Acp-Session-Id headers, and a text/event-stream GET for server-to-client messages. Dial returns a normal acp.Connection, so callers drive it with the usual methods, and any agent.Runtime can be served with acphttp.Server. Stdio stays the default and the transport never falls back between bindings; see docs/http-transport.md for the binding and its draft limits (no WebSocket, CORS, per-session streams, or batch bodies yet).

Contributing

See CONTRIBUTING.md and our Code of Conduct. Report vulnerabilities privately using SECURITY.md.

License

Licensed under Apache-2.0. See NOTICE for project attribution and licenses/README.md for dependency terms, third-party notices, and the license review process.

Documentation

Overview

Package acp implements the ACP v1 stdio client protocol using only Go's standard library. Specification: https://agentclientprotocol.com/protocol/v1/overview

Index

• Constants
• func AcceptElicitation(content map[string]schema.ElicitationContentValue) schema.CreateElicitationResponse
• func CancelElicitation() schema.CreateElicitationResponse
• func ConfigOptionsClientCapabilities(boolean bool) *schema.ClientSessionCapabilities
• func DeclineElicitation() schema.CreateElicitationResponse
• func ElicitationClientCapabilities(form, url bool) *schema.ElicitationCapabilities
• func IsAuthRequired(err error) bool
• func IsResourceNotFound(err error) bool
• func NewHTTPMCPServer(name, url string, headers ...schema.HttpHeader) schema.McpServer
• func NewSSEMCPServer(name, url string, headers ...schema.HttpHeader) schema.McpServer
• func NewStdioMCPServer(name, command string, args []string, env map[string]string) schema.McpServer
• func TerminalAuthCapabilities() *schema.AuthCapabilities
• type BatchCall
• type Capabilities
  • func WorkspaceCapabilities(readFiles, writeFiles, terminal bool) Capabilities
• type ClientInfo
• type Connection
  • func Connect(in io.ReadCloser, out io.WriteCloser, h Handler, n Notifications) *Connection
  • func (c *Connection) Authenticate(ctx context.Context, init Initialization, method string) error
  • func (c *Connection) Call(ctx context.Context, method string, params, result any) error
  • func (c *Connection) CallBatch(ctx context.Context, calls []BatchCall) []error
  • func (c *Connection) CancelRequest(ctx context.Context, requestID any) error
  • func (c *Connection) CancelSession(ctx context.Context, sessionID SessionID) error
  • func (c *Connection) Close() error
  • func (c *Connection) CloseSession(ctx context.Context, init Initialization, sessionID SessionID) error
  • func (c *Connection) DeleteSession(ctx context.Context, init Initialization, sessionID SessionID) error
  • func (c *Connection) Done() <-chan struct{}
  • func (c *Connection) Err() error
  • func (c *Connection) Initialize(ctx context.Context, caps Capabilities) (Initialization, error)
  • func (c *Connection) InitializeWithInfo(ctx context.Context, caps Capabilities, info ClientInfo) (Initialization, error)
  • func (c *Connection) ListSessions(ctx context.Context, init Initialization, request schema.ListSessionsRequest) (schema.ListSessionsResponse, error)
  • func (c *Connection) LoadSession(ctx context.Context, init Initialization, request schema.LoadSessionRequest) (schema.LoadSessionResponse, error)
  • func (c *Connection) Logout(ctx context.Context, init Initialization) error
  • func (c *Connection) NewSession(ctx context.Context, directory string) (Session, error)
  • func (c *Connection) NewSessionWithOptions(ctx context.Context, init Initialization, directory string, ...) (Session, error)
  • func (c *Connection) Notify(ctx context.Context, method string, params any) error
  • func (c *Connection) Prompt(ctx context.Context, session Session, text string) (schema.StopReason, error)
  • func (c *Connection) PromptContent(ctx context.Context, init Initialization, session Session, prompt []Content) (schema.StopReason, error)
  • func (c *Connection) ResumeSession(ctx context.Context, init Initialization, request schema.ResumeSessionRequest) (schema.ResumeSessionResponse, error)
  • func (c *Connection) SetBooleanConfig(ctx context.Context, session *Session, configID string, value bool) error
  • func (c *Connection) SetEffort(ctx context.Context, session *Session, effort string) error
  • func (c *Connection) SetMode(ctx context.Context, session *Session, mode string) error
  • func (c *Connection) SetModel(ctx context.Context, session *Session, model string) error
• type Content
  • func NewAudioContent(mimeType, base64Data string) Content
  • func NewBlobResourceContent(uri, base64Data string) Content
  • func NewImageContent(mimeType, base64Data string) Content
  • func NewResourceLinkContent(name, uri string) Content
  • func NewTextContent(text string) Content
  • func NewTextResourceContent(uri, text string) Content
• type ElicitationHandler
• type Handler
  • func HandleElicitation(next Handler, elicitation ElicitationHandler) Handler
• type Initialization
• type NewSessionOptions
• type Notifications
  • func CombineNotifications(callbacks ...Notifications) Notifications
  • func ElicitationComplete(handler func(schema.CompleteElicitationNotification) error) Notifications
  • func SessionUpdates(handler func(Update) error) Notifications
• type RPCError
  • func (e *RPCError) Error() string
• type Session
• type SessionID
• type UnknownSelectionError
  • func (e *UnknownSelectionError) Error() string
• type UnsupportedSelectionError
  • func (e *UnsupportedSelectionError) Error() string
• type Update
  • func NewAgentMessageChunkUpdate(sessionID SessionID, chunk schema.ContentChunk) Update
  • func NewAgentThoughtChunkUpdate(sessionID SessionID, chunk schema.ContentChunk) Update
  • func NewAvailableCommandsUpdate(sessionID SessionID, commands []schema.AvailableCommand) Update
  • func NewConfigOptionUpdate(sessionID SessionID, options []schema.SessionConfigOption) Update
  • func NewCurrentModeUpdate(sessionID SessionID, modeID schema.SessionModeId) Update
  • func NewPlanUpdate(sessionID SessionID, plan schema.Plan) Update
  • func NewSessionInfoUpdate(sessionID SessionID, info schema.SessionInfoUpdate) Update
  • func NewToolCallChangedUpdate(sessionID SessionID, update schema.ToolCallUpdate) Update
  • func NewToolCallUpdate(sessionID SessionID, call schema.ToolCall) Update
  • func NewUsageUpdate(sessionID SessionID, used, size uint64) Update
  • func NewUserMessageChunkUpdate(sessionID SessionID, chunk schema.ContentChunk) Update

Constants

const (
	ErrorCodeAuthRequired     = -32000
	ErrorCodeResourceNotFound = -32002
)

ACP-specific JSON-RPC error codes.

const Version = schema.ProtocolVersion(1)

Version is the ACP protocol version implemented by this module.

Functions

func AcceptElicitation

func AcceptElicitation(content map[string]schema.ElicitationContentValue) schema.CreateElicitationResponse

func CancelElicitation

func CancelElicitation() schema.CreateElicitationResponse

func ConfigOptionsClientCapabilities

func ConfigOptionsClientCapabilities(boolean bool) *schema.ClientSessionCapabilities

ConfigOptionsClientCapabilities advertises support for session config options. Boolean support is an extension beyond flat selectors.

func DeclineElicitation

func DeclineElicitation() schema.CreateElicitationResponse

func ElicitationClientCapabilities

func ElicitationClientCapabilities(form, url bool) *schema.ElicitationCapabilities

ElicitationClientCapabilities advertises support for form and URL modes.

func IsAuthRequired

func IsAuthRequired(err error) bool

func IsResourceNotFound

func IsResourceNotFound(err error) bool

func NewHTTPMCPServer

func NewHTTPMCPServer(name, url string, headers ...schema.HttpHeader) schema.McpServer

func NewSSEMCPServer

func NewSSEMCPServer(name, url string, headers ...schema.HttpHeader) schema.McpServer

func NewStdioMCPServer

func NewStdioMCPServer(name, command string, args []string, env map[string]string) schema.McpServer

func TerminalAuthCapabilities

func TerminalAuthCapabilities() *schema.AuthCapabilities

TerminalAuthCapabilities advertises support for terminal-type authentication methods through clientCapabilities.auth.terminal.

Advertise it only when the application can reproduce the configured agent invocation in an interactive terminal, because the agent may then answer initialize with a method whose authentication happens outside this connection. See https://agentclientprotocol.com/protocol/v1/authentication and runner.RunTerminalAuth, which runs that interactive login and leaves the application to reconnect and initialize again.

Types

type BatchCall

type BatchCall struct {
	Method string
	Params any
	Result any
}

BatchCall is one request in an outgoing JSON-RPC batch.

type Capabilities

type Capabilities = schema.ClientCapabilities

The exported names below are intentional aliases into the generated schema package. Client code can use the small acp facade without losing access to fields introduced by future pinned schema releases.

func WorkspaceCapabilities

func WorkspaceCapabilities(readFiles, writeFiles, terminal bool) Capabilities

WorkspaceCapabilities advertises the filesystem and terminal host methods used by unattended clients. Every argument defaults to disabled when false.

type ClientInfo

type ClientInfo = schema.Implementation

The exported names below are intentional aliases into the generated schema package. Client code can use the small acp facade without losing access to fields introduced by future pinned schema releases.

type Connection

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

func Connect

func Connect(in io.ReadCloser, out io.WriteCloser, h Handler, n Notifications) *Connection

Connect owns both streams until Close. Frames are limited to 8 MiB; at most 32 incoming requests run concurrently. Unknown notifications can be ignored.

func (*Connection) Authenticate

func (c *Connection) Authenticate(ctx context.Context, init Initialization, method string) error

func (*Connection) Call

func (c *Connection) Call(ctx context.Context, method string, params, result any) error

func (*Connection) CallBatch

func (c *Connection) CallBatch(ctx context.Context, calls []BatchCall) []error

CallBatch sends requests as one JSON-RPC array and waits for their matching responses. Responses may be returned individually or in a response batch.

func (*Connection) CancelRequest

func (c *Connection) CancelRequest(ctx context.Context, requestID any) error

CancelRequest asks the peer to cancel one outstanding request by sending a $/cancel_request notification. Either side may cancel the other's in-flight request; the peer answers the original request with a -32800 error or a valid response, and both outcomes are normal completion.

requestID identifies the request exactly as the peer saw it on the wire: a JSON string or number, supplied as a Go string, an integer, or a json.RawMessage for exact bytes. Call and CallBatch number their own outbound requests from 1, so those IDs are integers. Null, empty, and non-scalar IDs are rejected.

func (*Connection) CancelSession

func (c *Connection) CancelSession(ctx context.Context, sessionID SessionID) error

func (*Connection) Close

func (c *Connection) Close() error

func (*Connection) CloseSession

func (c *Connection) CloseSession(ctx context.Context, init Initialization, sessionID SessionID) error

func (*Connection) DeleteSession

func (c *Connection) DeleteSession(ctx context.Context, init Initialization, sessionID SessionID) error

func (*Connection) Done

func (c *Connection) Done() <-chan struct{}

func (*Connection) Err

func (c *Connection) Err() error

func (*Connection) Initialize

func (c *Connection) Initialize(ctx context.Context, caps Capabilities) (Initialization, error)

func (*Connection) InitializeWithInfo

func (c *Connection) InitializeWithInfo(ctx context.Context, caps Capabilities, info ClientInfo) (Initialization, error)

InitializeWithInfo negotiates ACP v1 with the calling application's identity.

func (*Connection) ListSessions

func (c *Connection) ListSessions(ctx context.Context, init Initialization, request schema.ListSessionsRequest) (schema.ListSessionsResponse, error)

func (*Connection) LoadSession

func (c *Connection) LoadSession(ctx context.Context, init Initialization, request schema.LoadSessionRequest) (schema.LoadSessionResponse, error)

func (*Connection) Logout

func (c *Connection) Logout(ctx context.Context, init Initialization) error

func (*Connection) NewSession

func (c *Connection) NewSession(ctx context.Context, directory string) (Session, error)

func (*Connection) NewSessionWithOptions

func (c *Connection) NewSessionWithOptions(ctx context.Context, init Initialization, directory string, options NewSessionOptions) (Session, error)

func (*Connection) Notify

func (c *Connection) Notify(ctx context.Context, method string, params any) error

func (*Connection) Prompt

func (c *Connection) Prompt(ctx context.Context, session Session, text string) (schema.StopReason, error)

func (*Connection) PromptContent

func (c *Connection) PromptContent(ctx context.Context, init Initialization, session Session, prompt []Content) (schema.StopReason, error)

func (*Connection) ResumeSession

func (c *Connection) ResumeSession(ctx context.Context, init Initialization, request schema.ResumeSessionRequest) (schema.ResumeSessionResponse, error)

func (*Connection) SetBooleanConfig

func (c *Connection) SetBooleanConfig(ctx context.Context, session *Session, configID string, value bool) error

SetBooleanConfig sets an advertised boolean session configuration option and verifies the agent's returned current value.

func (*Connection) SetEffort

func (c *Connection) SetEffort(ctx context.Context, session *Session, effort string) error

SetEffort uses the current model's advertised reasoning levels. Call after SetModel because model selection may replace the available effort options. Errors follow SetModel, with Category SessionConfigOptionCategoryThoughtLevel.

func (*Connection) SetMode

func (c *Connection) SetMode(ctx context.Context, session *Session, mode string) error

SetMode selects an advertised session mode, using the legacy modes state when present and otherwise a mode config option. It returns *UnsupportedSelectionError when the agent advertises neither, and *UnknownSelectionError when a mode config option does not offer mode.

func (*Connection) SetModel

func (c *Connection) SetModel(ctx context.Context, session *Session, model string) error

SetModel selects an advertised model and verifies the agent acknowledged it. A rejected or unavailable selection must not silently use the default model. It returns *UnsupportedSelectionError when the agent advertises no model selector and *UnknownSelectionError when model is not an advertised value; agent-side rejections wrap the underlying RPC or transport error.

type Content

type Content = schema.ContentBlock

The exported names below are intentional aliases into the generated schema package. Client code can use the small acp facade without losing access to fields introduced by future pinned schema releases.

func NewAudioContent

func NewAudioContent(mimeType, base64Data string) Content

func NewBlobResourceContent

func NewBlobResourceContent(uri, base64Data string) Content

func NewImageContent

func NewImageContent(mimeType, base64Data string) Content

func NewResourceLinkContent

func NewResourceLinkContent(name, uri string) Content

func NewTextContent

func NewTextContent(text string) Content

func NewTextResourceContent

func NewTextResourceContent(uri, text string) Content

type ElicitationHandler

type ElicitationHandler func(context.Context, schema.CreateElicitationRequest) (schema.CreateElicitationResponse, error)

ElicitationHandler serves typed elicitation/create requests.

type Handler

type Handler func(context.Context, string, json.RawMessage) (any, error)

Handler serves agent-to-client requests. It must honor cancellation.

func HandleElicitation

func HandleElicitation(next Handler, elicitation ElicitationHandler) Handler

HandleElicitation composes typed elicitation support with another agent-to-client request handler. Pass nil for next when elicitation is the only hosted method.

type Initialization

type Initialization = schema.InitializeResponse

The exported names below are intentional aliases into the generated schema package. Client code can use the small acp facade without losing access to fields introduced by future pinned schema releases.

type NewSessionOptions

type NewSessionOptions struct {
	AdditionalDirectories []string
	MCPServers            []schema.McpServer
}

NewSessionOptions carries optional fields for session/new.

type Notifications

type Notifications func(string, json.RawMessage) error

Notifications run in wire order, before a subsequent response is delivered. They must return promptly and must not call back into this Connection.

func CombineNotifications

func CombineNotifications(callbacks ...Notifications) Notifications

CombineNotifications fans an incoming notification out to typed adapters in order. The first error terminates the connection, matching Connection semantics.

func ElicitationComplete

func ElicitationComplete(handler func(schema.CompleteElicitationNotification) error) Notifications

ElicitationComplete adapts the agent's elicitation/complete notification to the generated notification type. Other notifications are ignored.

func SessionUpdates

func SessionUpdates(handler func(Update) error) Notifications

SessionUpdates adapts the raw connection notification callback to the generated, discriminated-union SessionNotification type. Other ACP notifications are ignored, as required by the transport layer.

type RPCError

type RPCError struct {
	Code    int             `json:"code"`
	Message string          `json:"message"`
	Data    json.RawMessage `json:"data,omitempty"`
}

RPCError preserves the peer's JSON-RPC error, including extension data.

func (*RPCError) Error

func (e *RPCError) Error() string

type Session

type Session = schema.NewSessionResponse

The exported names below are intentional aliases into the generated schema package. Client code can use the small acp facade without losing access to fields introduced by future pinned schema releases.

type SessionID

type SessionID = schema.SessionId

The exported names below are intentional aliases into the generated schema package. Client code can use the small acp facade without losing access to fields introduced by future pinned schema releases.

type UnknownSelectionError

type UnknownSelectionError struct {
	Category  schema.SessionConfigOptionCategory
	ConfigID  schema.SessionConfigId
	Name      string
	Value     string
	Available []string
}

UnknownSelectionError reports that a requested session config option value is not among the values the agent advertised for that selector. Category is the selector the caller asked for (for example schema.SessionConfigOptionCategoryModel from SetModel), which also covers selectors matched by their conventional ID rather than an advertised category. Available lists the advertised values in order and is nil when the selector offers none. No request is sent to the agent when this error is returned.

func (*UnknownSelectionError) Error

func (e *UnknownSelectionError) Error() string

type UnsupportedSelectionError

type UnsupportedSelectionError struct {
	Category schema.SessionConfigOptionCategory
	Value    string
}

UnsupportedSelectionError reports that the agent advertises no selector for the requested category, so the value could not be selected at all. Category is schema.SessionConfigOptionCategoryMode, SessionConfigOptionCategoryModel, or SessionConfigOptionCategoryThoughtLevel (reasoning effort). Value is the requested value; the mode message does not include it.

func (*UnsupportedSelectionError) Error

func (e *UnsupportedSelectionError) Error() string

type Update

type Update = schema.SessionNotification

The exported names below are intentional aliases into the generated schema package. Client code can use the small acp facade without losing access to fields introduced by future pinned schema releases.

func NewAgentMessageChunkUpdate

func NewAgentMessageChunkUpdate(sessionID SessionID, chunk schema.ContentChunk) Update

func NewAgentThoughtChunkUpdate

func NewAgentThoughtChunkUpdate(sessionID SessionID, chunk schema.ContentChunk) Update

func NewAvailableCommandsUpdate

func NewAvailableCommandsUpdate(sessionID SessionID, commands []schema.AvailableCommand) Update

func NewConfigOptionUpdate

func NewConfigOptionUpdate(sessionID SessionID, options []schema.SessionConfigOption) Update

func NewCurrentModeUpdate

func NewCurrentModeUpdate(sessionID SessionID, modeID schema.SessionModeId) Update

func NewPlanUpdate

func NewPlanUpdate(sessionID SessionID, plan schema.Plan) Update

func NewSessionInfoUpdate

func NewSessionInfoUpdate(sessionID SessionID, info schema.SessionInfoUpdate) Update

func NewToolCallChangedUpdate

func NewToolCallChangedUpdate(sessionID SessionID, update schema.ToolCallUpdate) Update

func NewToolCallUpdate

func NewToolCallUpdate(sessionID SessionID, call schema.ToolCall) Update

func NewUsageUpdate

func NewUsageUpdate(sessionID SessionID, used, size uint64) Update

func NewUserMessageChunkUpdate

func NewUserMessageChunkUpdate(sessionID SessionID, chunk schema.ContentChunk) Update