acp

package
v1.376.0 Latest Latest
Warning

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

Go to latest
Published: Apr 14, 2026 License: MIT Imports: 8 Imported by: 0

Documentation

Overview

Package acp provides types and a client for the Agent Client Protocol (ACP). Spec: https://github.com/agentclientprotocol/agent-client-protocol

Index

Constants

View Source
const ProtocolVersion = 0

ProtocolVersion is the ACP version this client targets. Per spec: uint16, only bumped for breaking changes.

Variables

This section is empty.

Functions

func ExtractTextContent

func ExtractTextContent(raw json.RawMessage) string

ExtractTextContent extracts the text string from a raw ContentBlock JSON value. If the block is not a text block or is invalid, returns an empty string.

Types

type AgentCapabilities

type AgentCapabilities struct {
	// Session restore / load
	SessionLoad bool `json:"sessionLoad,omitempty"`
	// Image content blocks in prompts
	Image bool `json:"image,omitempty"`
	// Audio content blocks in prompts
	Audio bool `json:"audio,omitempty"`
}

AgentCapabilities describes what the agent supports.

type Client

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

Client is a high-level ACP client backed by a JSON-RPC 2.0 connection. It manages the lifecycle of a single ACP session.

func NewClient

func NewClient(r io.Reader, w io.Writer, verbose bool) *Client

NewClient creates an ACP client using the given reader (agent stdout) and writer (agent stdin).

func (*Client) Cancel

func (c *Client) Cancel(ctx context.Context) error

Cancel sends a session/cancel notification to abort the current turn.

func (*Client) Initialize

func (c *Client) Initialize(ctx context.Context) error

Initialize performs the ACP handshake. Must be called before any other method.

func (*Client) Listen

func (c *Client) Listen(ctx context.Context) error

Listen starts the read loop. It blocks until the context is cancelled or the underlying connection closes. Call this in a goroutine.

func (*Client) NewSession

func (c *Client) NewSession(ctx context.Context, cwd string, mcpServers []McpServer) error

NewSession creates a new ACP session and stores the session ID.

func (*Client) PermissionRequests

func (c *Client) PermissionRequests() <-chan PermissionRequest

PermissionRequests returns a channel that receives inbound permission requests from the agent.

func (*Client) Prompt

func (c *Client) Prompt(ctx context.Context, text string) (StopReason, error)

Prompt sends a user message and returns when the agent has finished the turn. While the agent is working, session/update notifications are dispatched to the channel returned by Updates().

func (*Client) SessionID

func (c *Client) SessionID() string

SessionID returns the current session ID (set after NewSession).

func (*Client) Updates

func (c *Client) Updates() <-chan SessionUpdate

Updates returns a channel that receives session/update notifications from the agent. The channel is closed when the client stops.

type ClientCapabilities

type ClientCapabilities struct {
	// Filesystem access (fs/read_text_file, fs/write_text_file)
	Filesystem *FilesystemCapability `json:"filesystem,omitempty"`
	// Terminal management
	Terminal *TerminalCapability `json:"terminal,omitempty"`
}

ClientCapabilities describes what the client supports.

type ConfigOption

type ConfigOption struct {
	Key         string      `json:"key"`
	Description string      `json:"description,omitempty"`
	Default     interface{} `json:"default,omitempty"`
}

ConfigOption is a runtime config option offered by the agent.

type ContentBlock

type ContentBlock struct {
	Type ContentBlockType `json:"type"`

	// type=text
	Text string `json:"text,omitempty"`

	// type=image
	MimeType string `json:"mimeType,omitempty"`
	Data     string `json:"data,omitempty"` // base64

	// type=resource_link
	URI   string `json:"uri,omitempty"`
	Title string `json:"title,omitempty"`
}

ContentBlock is a single element of a prompt.

type ContentBlockText

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

ContentBlockText is the text variant of a ContentBlock (type="text").

type ContentBlockType

type ContentBlockType string

ContentBlockType distinguishes prompt content blocks.

const (
	ContentBlockTypeText         ContentBlockType = "text"
	ContentBlockTypeImage        ContentBlockType = "image"
	ContentBlockTypeAudio        ContentBlockType = "audio"
	ContentBlockTypeResource     ContentBlockType = "resource"
	ContentBlockTypeResourceLink ContentBlockType = "resource_link"
)

type FilesystemCapability

type FilesystemCapability struct {
	Enabled bool `json:"enabled"`
}

FilesystemCapability indicates the client can handle fs requests.

type FsReadTextFileParams

type FsReadTextFileParams struct {
	Path string `json:"path"`
}

FsReadTextFileParams is the params for "fs/read_text_file".

type FsReadTextFileResult

type FsReadTextFileResult struct {
	Text string `json:"text"`
}

FsReadTextFileResult is the result of "fs/read_text_file".

type FsWriteTextFileParams

type FsWriteTextFileParams struct {
	Path string `json:"path"`
	Text string `json:"text"`
}

FsWriteTextFileParams is the params for "fs/write_text_file".

type FsWriteTextFileResult

type FsWriteTextFileResult struct{}

FsWriteTextFileResult is the result of "fs/write_text_file".

type InitializeParams

type InitializeParams struct {
	ProtocolVersion    int                `json:"protocolVersion"`
	ClientCapabilities ClientCapabilities `json:"clientCapabilities"`
}

InitializeParams is the params for the "initialize" request (client→agent).

type InitializeResult

type InitializeResult struct {
	ProtocolVersion   int               `json:"protocolVersion"`
	AgentCapabilities AgentCapabilities `json:"agentCapabilities"`
}

InitializeResult is the response to "initialize".

type McpServer

type McpServer struct {
	Name    string   `json:"name"`
	Command string   `json:"command"`
	Args    []string `json:"args,omitempty"`
}

McpServer describes an MCP server to connect to.

type PermissionOption

type PermissionOption struct {
	Kind     string `json:"kind,omitempty"` // "allow_always", "allow_once", "reject_once"
	Name     string `json:"name"`           // human-readable display label
	OptionId string `json:"optionId"`       // machine identifier sent back in the response
}

PermissionOption is one choice the user can make. Field names match the ACP spec: optionId (identifier) and name (display label).

type PermissionRequest

type PermissionRequest struct {
	Params RequestPermissionParams
	// Reply must be called exactly once to unblock the agent.
	Reply func(optionId string) error
}

PermissionRequest is an inbound permission request from the agent.

type PlanEntry

type PlanEntry struct {
	Content  string `json:"content"`
	Status   string `json:"status"`   // "pending", "in_progress", "completed", "cancelled"
	Priority string `json:"priority"` // "high", "medium", "low"
}

PlanEntry is a single entry in an ACP plan update. See ACP spec: sessionUpdate="plan" entries field.

type PromptParams

type PromptParams struct {
	SessionId string         `json:"sessionId"`
	Prompt    []ContentBlock `json:"prompt"`
}

PromptParams is the params for "session/prompt" (client→agent).

type PromptResult

type PromptResult struct {
	StopReason StopReason `json:"stopReason"`
}

PromptResult is the response to "session/prompt".

type RequestPermissionOutcome

type RequestPermissionOutcome struct {
	Outcome  string `json:"outcome"`            // "selected" or "cancelled"
	OptionId string `json:"optionId,omitempty"` // set when outcome="selected"
}

RequestPermissionOutcome is the inner outcome object of RequestPermissionResult.

type RequestPermissionParams

type RequestPermissionParams struct {
	SessionId string                    `json:"sessionId"`
	Options   []PermissionOption        `json:"options"`
	ToolCall  RequestPermissionToolCall `json:"toolCall"`
}

RequestPermissionParams is the params for "session/request_permission" (agent→client request).

type RequestPermissionResult

type RequestPermissionResult struct {
	Outcome RequestPermissionOutcome `json:"outcome"`
}

RequestPermissionResult is the response to "session/request_permission". The ACP spec requires: {outcome: {outcome: "selected", optionId: "<id>"}}

type RequestPermissionToolCall

type RequestPermissionToolCall struct {
	ToolCallId string          `json:"toolCallId"`
	Kind       string          `json:"kind,omitempty"`     // e.g. "switch_mode" for ExitPlanMode
	RawInput   json.RawMessage `json:"rawInput,omitempty"` // raw tool input JSON
}

RequestPermissionToolCall contains the tool call details nested in RequestPermissionParams.

type SessionCancelParams

type SessionCancelParams struct {
	SessionId string `json:"sessionId"`
}

SessionCancelParams is the params for "session/cancel" notification.

type SessionInfo

type SessionInfo struct {
	SessionId string    `json:"sessionId"`
	Cwd       string    `json:"cwd"`
	Title     string    `json:"title,omitempty"`
	UpdatedAt time.Time `json:"updatedAt,omitempty"`
}

SessionInfo describes a session returned by "session/list".

type SessionListResult

type SessionListResult struct {
	Sessions []SessionInfo `json:"sessions"`
}

SessionListResult is the response to "session/list".

type SessionMode

type SessionMode struct {
	Id          string  `json:"id"`
	Name        string  `json:"name"`
	Description *string `json:"description,omitempty"`
}

SessionMode is a single mode available in a session.

type SessionModeState

type SessionModeState struct {
	CurrentModeId  string        `json:"currentModeId"`
	AvailableModes []SessionMode `json:"availableModes"`
}

SessionModeState is the modes object returned in session/new response. Per spec: modes is an object with currentModeId and availableModes, not a flat array.

type SessionNewParams

type SessionNewParams struct {
	Cwd        string      `json:"cwd"`
	McpServers []McpServer `json:"mcpServers"`
}

SessionNewParams is the params for "session/new" (client→agent).

type SessionNewResult

type SessionNewResult struct {
	SessionId     string            `json:"sessionId"`
	Modes         *SessionModeState `json:"modes,omitempty"`
	ConfigOptions []ConfigOption    `json:"configOptions,omitempty"`
}

SessionNewResult is the response to "session/new".

type SessionSetModeParams

type SessionSetModeParams struct {
	SessionId string `json:"sessionId"`
	Mode      string `json:"mode"`
}

SessionSetModeParams is the params for "session/set_mode".

type SessionUpdate

type SessionUpdate struct {
	// Discriminant field
	Kind SessionUpdateKind `json:"sessionUpdate"`

	// agent_message_chunk / user_message_chunk / agent_thought_chunk
	// Content is a ContentBlock object (not a string) per ACP spec.
	Content json.RawMessage `json:"content,omitempty"`

	// tool_call
	ToolCallId string      `json:"toolCallId,omitempty"`
	ToolKind   string      `json:"kind,omitempty"` // e.g. "bash", "edit", ...
	RawInput   interface{} `json:"rawInput,omitempty"`

	// tool_call_update
	Status    ToolCallStatus `json:"status,omitempty"`
	RawOutput interface{}    `json:"rawOutput,omitempty"`

	// plan – ACP sends entries (structured list), not a plain string.
	Entries []PlanEntry `json:"entries,omitempty"`

	// session_info_update
	Title string `json:"title,omitempty"`

	// current_mode_update
	Mode string `json:"mode,omitempty"`
}

SessionUpdate is a discriminated union; Kind determines which fields apply.

type SessionUpdateKind

type SessionUpdateKind string

SessionUpdateKind is the discriminant for SessionUpdate.

const (
	SessionUpdateKindUserMessageChunk        SessionUpdateKind = "user_message_chunk"
	SessionUpdateKindAgentMessageChunk       SessionUpdateKind = "agent_message_chunk"
	SessionUpdateKindAgentThoughtChunk       SessionUpdateKind = "agent_thought_chunk"
	SessionUpdateKindToolCall                SessionUpdateKind = "tool_call"
	SessionUpdateKindToolCallUpdate          SessionUpdateKind = "tool_call_update"
	SessionUpdateKindPlan                    SessionUpdateKind = "plan"
	SessionUpdateKindAvailableCommandsUpdate SessionUpdateKind = "available_commands_update"
	SessionUpdateKindSessionInfoUpdate       SessionUpdateKind = "session_info_update"
	SessionUpdateKindCurrentModeUpdate       SessionUpdateKind = "current_mode_update"
)

type SessionUpdateNotification

type SessionUpdateNotification struct {
	SessionId string        `json:"sessionId"`
	Update    SessionUpdate `json:"update"`
}

SessionUpdateNotification is the params for the "session/update" notification sent from agent→client.

type StopReason

type StopReason string

StopReason describes why an agent turn ended.

const (
	StopReasonEndTurn         StopReason = "end_turn"
	StopReasonMaxTokens       StopReason = "max_tokens"
	StopReasonRefusal         StopReason = "refusal"
	StopReasonCancelled       StopReason = "cancelled"
	StopReasonMaxTurnRequests StopReason = "max_turn_requests"
)

type TerminalCapability

type TerminalCapability struct {
	Enabled bool `json:"enabled"`
}

TerminalCapability indicates the client can handle terminal requests.

type ToolCallStatus

type ToolCallStatus string

ToolCallStatus describes the lifecycle state of a tool call.

const (
	ToolCallStatusRunning   ToolCallStatus = "running"
	ToolCallStatusSuccess   ToolCallStatus = "success"
	ToolCallStatusError     ToolCallStatus = "error"
	ToolCallStatusCancelled ToolCallStatus = "cancelled"
)

Directories

Path Synopsis
Package bridge translates between the ACP client and an agentapi-compatible HTTP interface (compatible with takutakahashi/claude-agentapi).
Package bridge translates between the ACP client and an agentapi-compatible HTTP interface (compatible with takutakahashi/claude-agentapi).
Package jsonrpc implements a JSON-RPC 2.0 client over an io.ReadWriter (e.g.
Package jsonrpc implements a JSON-RPC 2.0 client over an io.ReadWriter (e.g.

Jump to

Keyboard shortcuts

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