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@v0.1.0

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 caller owns launching the process and implementing the filesystem, terminal, and permission handlers it advertises. Capabilities default to disabled. Authentication, modes, model selection and reasoning effort are supported. Use SetModel before SetEffort: models may expose different effort choices. Explicit selections must be acknowledged by the agent; they never silently fall back.

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 and Notify permit extensions. ACP v2 is not supported.

Run go test -race ./... and go vet ./.... No agent credentials are needed.

Apache-2.0. Originally developed in BrokkAi/release-bot; license terms are retained in LICENSE. Tagged Go modules are the distribution format.

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.

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
• type Capabilities
• type ClientInfo
• type ConfigOption
• type ConfigValue
• 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) Close() 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) NewSession(ctx context.Context, directory string) (Session, error)
  • func (c *Connection) Notify(ctx context.Context, method string, params any) error
  • func (c *Connection) Prompt(ctx context.Context, s Session, text string) (string, error)
  • func (c *Connection) SetEffort(ctx context.Context, s *Session, effort string) error
  • func (c *Connection) SetMode(ctx context.Context, s *Session, mode string) error
  • func (c *Connection) SetModel(ctx context.Context, s *Session, model string) error
• type Content
• type Handler
• type Initialization
• type Notifications
• type RPCError
  • func (e *RPCError) Error() string
• type Session
• type Update

Constants

const Version = 1

Types

type Capabilities

type Capabilities struct {
	FS struct {
		Read  bool `json:"readTextFile"`
		Write bool `json:"writeTextFile"`
	} `json:"fs"`
	Terminal bool `json:"terminal"`
}

type ClientInfo

type ClientInfo struct {
	Name    string `json:"name"`
	Version string `json:"version"`
}

ClientInfo identifies the application to the agent.

type ConfigOption

type ConfigOption struct {
	ID           string          `json:"id"`
	Name         string          `json:"name"`
	Category     string          `json:"category,omitempty"`
	Type         string          `json:"type"`
	CurrentValue json.RawMessage `json:"currentValue"`
	Options      []ConfigValue   `json:"options,omitempty"`
}

ConfigOption describes an agent-advertised session selector. Unknown option types and their values are preserved without requiring client support.

type ConfigValue

type ConfigValue struct {
	Value string `json:"value"`
	Name  string `json:"name"`
}

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) Close

func (c *Connection) Close() 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) NewSession

func (c *Connection) NewSession(ctx context.Context, directory string) (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, s Session, text string) (string, error)

func (*Connection) SetEffort

func (c *Connection) SetEffort(ctx context.Context, s *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.

func (*Connection) SetMode

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

func (*Connection) SetModel

func (c *Connection) SetModel(ctx context.Context, s *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.

type Content

type Content struct {
	Type string `json:"type"`
	Text string `json:"text"`
}

type Handler

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

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

type Initialization

type Initialization struct {
	ProtocolVersion   int             `json:"protocolVersion"`
	AgentCapabilities json.RawMessage `json:"agentCapabilities"`
	AuthMethods       []struct {
		ID   string `json:"id"`
		Type string `json:"type"`
	} `json:"authMethods"`
}

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.

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 struct {
	ID            string         `json:"sessionId"`
	ConfigOptions []ConfigOption `json:"configOptions,omitempty"`
}

type Update

type Update struct {
	SessionID string `json:"sessionId"`
	Update    struct {
		Kind       string          `json:"sessionUpdate"`
		Content    json.RawMessage `json:"content"`
		Title      string          `json:"title"`
		MessageID  string          `json:"messageId"`
		ToolCallID string          `json:"toolCallId"`
		Status     string          `json:"status"`
		RawOutput  json.RawMessage `json:"rawOutput"`
		Meta       struct {
			TerminalOutput *struct {
				Data string `json:"data"`
			} `json:"terminal_output_delta"`
		} `json:"_meta"`
	} `json:"update"`
}