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
- func ExtractTextContent(raw json.RawMessage) string
- type AgentCapabilities
- type Client
- func (c *Client) Cancel(ctx context.Context) error
- func (c *Client) Initialize(ctx context.Context) error
- func (c *Client) Listen(ctx context.Context) error
- func (c *Client) NewSession(ctx context.Context, cwd string, mcpServers []McpServer) error
- func (c *Client) PermissionRequests() <-chan PermissionRequest
- func (c *Client) Prompt(ctx context.Context, text string) (StopReason, error)
- func (c *Client) SessionID() string
- func (c *Client) Updates() <-chan SessionUpdate
- type ClientCapabilities
- type ConfigOption
- type ContentBlock
- type ContentBlockText
- type ContentBlockType
- type FilesystemCapability
- type FsReadTextFileParams
- type FsReadTextFileResult
- type FsWriteTextFileParams
- type FsWriteTextFileResult
- type InitializeParams
- type InitializeResult
- type McpServer
- type PermissionOption
- type PermissionRequest
- type PlanEntry
- type PromptParams
- type PromptResult
- type RequestPermissionOutcome
- type RequestPermissionParams
- type RequestPermissionResult
- type RequestPermissionToolCall
- type SessionCancelParams
- type SessionInfo
- type SessionListResult
- type SessionMode
- type SessionModeState
- type SessionNewParams
- type SessionNewResult
- type SessionSetModeParams
- type SessionUpdate
- type SessionUpdateKind
- type SessionUpdateNotification
- type StopReason
- type TerminalCapability
- type ToolCallStatus
Constants ¶
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 ¶
NewClient creates an ACP client using the given reader (agent stdout) and writer (agent stdin).
func (*Client) Initialize ¶
Initialize performs the ACP handshake. Must be called before any other method.
func (*Client) Listen ¶
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 ¶
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 ¶
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) 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 ¶
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 ¶
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 ¶
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 ¶
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. |