acp

type Conn ¶

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

Conn is a bidirectional JSON-RPC 2.0 multiplexer over newline-delimited JSON.

Conn serializes outbound messages (Call, Notify) via a mutex-protected encoder and dispatches inbound messages (responses, notifications, method calls) in ReadLoop. All handlers must be registered before ReadLoop starts.

The synchronization model uses sync.Mutex + map[int64]chan for pending calls. On ReadLoop exit, all pending channels receive an error — preventing goroutine leaks.

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

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

func (c *Conn) Err() error

func (c *Conn) Notify(method string, params any) error

func (c *Conn) OnMethod(method string, h func(json.RawMessage) (any, error))

func (c *Conn) OnNotification(method string, h func(json.RawMessage))

func (c *Conn) ReadLoop()

type Engine ¶

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

Engine is an ACP engine that communicates with agents via JSON-RPC 2.0 over a persistent subprocess's stdin/stdout.

func NewEngine(opts ...EngineOption) *Engine

func (e *Engine) Start(ctx context.Context, session agentrun.Session, opts ...agentrun.Option) (agentrun.Process, error)

func (e *Engine) Validate() error

type EngineOption ¶

type EngineOption func(*EngineOptions)

EngineOption configures an Engine at construction time.

func WithArgs(args ...string) EngineOption

func WithBinary(binary string) EngineOption

func WithGracePeriod(d time.Duration) EngineOption

func WithHandshakeTimeout(d time.Duration) EngineOption

func WithMaxMessageSize(size int) EngineOption

func WithOutputBuffer(size int) EngineOption

func WithPermissionHandler(h PermissionHandler) EngineOption

func WithPermissionTimeout(d time.Duration) EngineOption

func WithStderrWriter(w io.Writer) EngineOption

type EngineOptions ¶

type EngineOptions struct {
	// Binary is the ACP agent executable name or path.
	Binary string

	// Args are additional arguments passed to the binary (e.g., ["acp"]).
	Args []string

	// OutputBuffer is the channel buffer size for process output messages.
	OutputBuffer int

	// GracePeriod is the duration to wait after SIGTERM before sending SIGKILL.
	GracePeriod time.Duration

	// HandshakeTimeout is the deadline for initialize + session/new during Start().
	HandshakeTimeout time.Duration

	// MaxMessageSize is the maximum JSON-RPC message size in bytes for the scanner.
	MaxMessageSize int

	// PermissionTimeout is the deadline for the PermissionHandler callback.
	PermissionTimeout time.Duration

	// PermissionHandler is called when the agent requests client-side permission.
	PermissionHandler PermissionHandler

	// StderrWriter receives subprocess stderr output when non-nil.
	// The writer's lifetime must span the entire engine lifecycle
	// (ACP uses a single persistent subprocess). When nil, subprocess
	// stderr is discarded (connected to os.DevNull by exec.Cmd).
	//
	// Concurrency: the subprocess stderr goroutine writes to this writer
	// concurrently with engine operations. Implementations must be safe
	// for concurrent use if the caller reads or resets the writer between
	// turns.
	StderrWriter io.Writer
}

EngineOptions holds resolved construction-time configuration for an ACP engine.

type PermissionHandler ¶

type PermissionHandler func(ctx context.Context, req PermissionRequest) (approved bool, err error)

PermissionHandler is called when the agent requests client-side permission. Runs in a dedicated goroutine (not blocking ReadLoop). Return true to approve. The engine maps the boolean to the ACP option-based wire format internally: true → allow_once (prefer) or allow_always; false → reject_once or reject_always.

This collapses ACP's richer option-based outcomes to binary approve/deny. A future version may expose the full option set via PermissionRequest if consumers need to distinguish allow_once from allow_always. If nil, permission requests are auto-denied (unless HITL is off).

type PermissionRequest ¶

type PermissionRequest struct {
	SessionID   string
	ToolName    string // from toolCallUpdate.Title
	ToolCallID  string // from toolCallUpdate.ToolCallID
	Description string // from toolCallUpdate.Kind
}

PermissionRequest carries the agent's permission request to the handler. The handler returns a simple approve/deny decision; the engine maps this to the ACP option-based wire format internally.

type RPCError ¶

type RPCError struct {
	Code    int
	Message string
}

RPCError is an exported error type for JSON-RPC errors returned by Call.

func (e *RPCError) Error() string