acp

package
v1.4.4 Latest Latest
Warning

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

Go to latest
Published: Feb 17, 2026 License: GPL-3.0 Imports: 11 Imported by: 0

Documentation

Overview

Package acp provides types aligned with the Agent Client Protocol (ACP) specification. ACP standardizes communication between clients and AI agents. See: https://agentclientprotocol.com/

These types are used internally by gsh to provide consistent interfaces across the interpreter and REPL, without requiring full ACP protocol compliance.

Index

Constants

View Source
const (
	MethodInitialize    = "initialize"
	MethodSessionNew    = "session/new"
	MethodSessionLoad   = "session/load"
	MethodSessionPrompt = "session/prompt"
	MethodSessionUpdate = "session/update"
)

ACP Method names

View Source
const (
	SessionUpdateAgentMessageChunk = "agent_message_chunk"
	SessionUpdateToolCall          = "tool_call"
	SessionUpdateToolCallUpdate    = "tool_call_update"
)

SessionUpdateType constants for the sessionUpdate field.

View Source
const JSONRPCVersion = "2.0"

JSONRPCVersion is the JSON-RPC version used by ACP.

Variables

This section is empty.

Functions

This section is empty.

Types

type ACPSession added in v1.1.0

type ACPSession interface {
	SendPrompt(ctx context.Context, text string, onUpdate func(*SessionUpdateParams)) (*SessionPromptResult, error)
	GetMessages() []Message
	GetLastMessage() *Message
	SessionID() string
	Close() error
}

ACPSession is the interface for ACP session operations. This interface allows for mocking in tests.

type AgentCapabilities added in v1.1.0

type AgentCapabilities struct {
	LoadSession        bool                `json:"loadSession,omitempty"`
	PromptCapabilities *PromptCapabilities `json:"promptCapabilities,omitempty"`
	MCP                *MCPCapabilities    `json:"mcp,omitempty"`
}

AgentCapabilities represents the agent's capabilities.

type AgentResult

type AgentResult struct {
	// StopReason indicates why the agent stopped.
	StopReason StopReason `json:"stopReason"`

	// Content is the final response content from the agent.
	Content string `json:"content,omitempty"`

	// Usage contains token usage statistics.
	Usage *TokenUsage `json:"usage,omitempty"`

	// Duration is the total execution time.
	Duration time.Duration `json:"duration"`

	// Error contains any error that occurred (when StopReason is error).
	Error error `json:"error,omitempty"`
}

AgentResult represents the result of an agent execution.

type AuthMethod added in v1.4.0

type AuthMethod struct {
	ID          string `json:"id"`
	Name        string `json:"name"`
	Description string `json:"description,omitempty"`
}

AuthMethod represents an authentication method advertised by the agent.

type Client added in v1.1.0

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

Client is an ACP client that manages communication with an ACP agent.

func NewClient added in v1.1.0

func NewClient(config ClientConfig) *Client

NewClient creates a new ACP client but does not start the agent process.

func (*Client) AgentCapabilities added in v1.1.0

func (c *Client) AgentCapabilities() AgentCapabilities

AgentCapabilities returns the agent's capabilities after initialization.

func (*Client) Close added in v1.1.0

func (c *Client) Close() error

Close shuts down the client and the agent process.

func (*Client) Connect added in v1.1.0

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

Connect starts the agent process and performs the initialization handshake.

func (*Client) IsConnected added in v1.1.0

func (c *Client) IsConnected() bool

IsConnected returns whether the client is connected and initialized.

func (*Client) NewSession added in v1.1.0

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

NewSession creates a new ACP session.

func (*Client) ProtocolVersion added in v1.1.0

func (c *Client) ProtocolVersion() int

ProtocolVersion returns the negotiated protocol version.

type ClientCapabilities added in v1.1.0

type ClientCapabilities struct {
	FS       *FSCapabilities `json:"fs,omitempty"`
	Terminal bool            `json:"terminal,omitempty"`
}

ClientCapabilities represents the client's capabilities.

type ClientConfig added in v1.1.0

type ClientConfig struct {
	Command string
	Args    []string
	Env     map[string]string
	Cwd     string

	// Timeout for initialization
	InitTimeout time.Duration

	// Logger for ACP activity logging. If nil, a no-op logger is used.
	Logger *zap.Logger
}

ClientConfig contains configuration for an ACP client.

type FSCapabilities added in v1.1.0

type FSCapabilities struct {
	ReadTextFile  bool `json:"readTextFile,omitempty"`
	WriteTextFile bool `json:"writeTextFile,omitempty"`
}

FSCapabilities represents file system capabilities.

type InitializeParams added in v1.1.0

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

InitializeParams represents the parameters for the initialize request.

type InitializeResult added in v1.1.0

type InitializeResult struct {
	ProtocolVersion   int               `json:"protocolVersion"`
	AgentCapabilities AgentCapabilities `json:"agentCapabilities,omitempty"`
	AuthMethods       []AuthMethod      `json:"authMethods,omitempty"`
}

InitializeResult represents the result of the initialize request.

type JSONRPCError added in v1.1.0

type JSONRPCError struct {
	Code    int         `json:"code"`
	Message string      `json:"message"`
	Data    interface{} `json:"data,omitempty"`
}

JSONRPCError represents a JSON-RPC 2.0 error.

type JSONRPCNotification added in v1.1.0

type JSONRPCNotification struct {
	JSONRPC string          `json:"jsonrpc"`
	Method  string          `json:"method"`
	Params  json.RawMessage `json:"params,omitempty"`
}

JSONRPCNotification represents a JSON-RPC 2.0 notification (no ID).

type JSONRPCRequest added in v1.1.0

type JSONRPCRequest struct {
	JSONRPC string      `json:"jsonrpc"`
	ID      int         `json:"id"`
	Method  string      `json:"method"`
	Params  interface{} `json:"params,omitempty"`
}

JSONRPCRequest represents a JSON-RPC 2.0 request.

func NewInitializeRequest added in v1.1.0

func NewInitializeRequest(id int) *JSONRPCRequest

NewInitializeRequest creates a new initialize request.

func NewSessionNewRequest added in v1.1.0

func NewSessionNewRequest(id int, cwd string, mcpServers []MCPServer) *JSONRPCRequest

NewSessionNewRequest creates a new session/new request.

func NewSessionPromptRequest added in v1.1.0

func NewSessionPromptRequest(id int, sessionID string, text string) *JSONRPCRequest

NewSessionPromptRequest creates a new session/prompt request.

type JSONRPCResponse added in v1.1.0

type JSONRPCResponse struct {
	JSONRPC string          `json:"jsonrpc"`
	ID      *int            `json:"id"`
	Result  json.RawMessage `json:"result,omitempty"`
	Error   *JSONRPCError   `json:"error,omitempty"`
}

JSONRPCResponse represents a JSON-RPC 2.0 response.

type MCPCapabilities added in v1.1.0

type MCPCapabilities struct {
	HTTP bool `json:"http,omitempty"`
	SSE  bool `json:"sse,omitempty"`
}

MCPCapabilities represents MCP-related capabilities.

type MCPServer added in v1.1.0

type MCPServer struct {
	Name    string            `json:"name"`
	Command string            `json:"command,omitempty"`
	Args    []string          `json:"args,omitempty"`
	Env     map[string]string `json:"env,omitempty"`
	URL     string            `json:"url,omitempty"`
}

MCPServer represents an MCP server configuration for the agent.

type Message added in v1.1.0

type Message struct {
	Role       string         `json:"role"`
	Content    string         `json:"content"`
	Name       string         `json:"name,omitempty"`
	ToolCallID string         `json:"toolCallId,omitempty"`
	ToolCalls  []ToolCallInfo `json:"toolCalls,omitempty"`
}

Message represents a message in the session history.

type MessageContent added in v1.1.0

type MessageContent struct {
	Type string `json:"type"`
	Text string `json:"text,omitempty"`
}

MessageContent represents content in a message.

type MockClient added in v1.1.0

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

MockClient is a mock ACP client for testing

func NewMockClient added in v1.1.0

func NewMockClient() *MockClient

NewMockClient creates a new mock client for testing

func (*MockClient) Close added in v1.1.0

func (m *MockClient) Close() error

Close implements mock close

func (*MockClient) Connect added in v1.1.0

func (m *MockClient) Connect(ctx context.Context) error

Connect implements a mock connect that succeeds by default

func (*MockClient) IsConnected added in v1.1.0

func (m *MockClient) IsConnected() bool

IsConnected returns the connection state

func (*MockClient) NewSession added in v1.1.0

func (m *MockClient) NewSession(ctx context.Context, cwd string, mcpServers []MCPServer) (*Session, error)

NewSession returns the pre-configured mock session

func (*MockClient) SetConnectError added in v1.1.0

func (m *MockClient) SetConnectError(err error)

SetConnectError sets an error to return from Connect

func (*MockClient) SetNextSession added in v1.1.0

func (m *MockClient) SetNextSession(session *MockSession)

SetNextSession sets the session to return from the next NewSession call

func (*MockClient) SetSessionError added in v1.1.0

func (m *MockClient) SetSessionError(err error)

SetSessionError sets an error to return from NewSession

type MockSession added in v1.1.0

type MockSession struct {

	// Test configuration
	SendPromptFunc func(ctx context.Context, text string, onUpdate func(*SessionUpdateParams)) (*SessionPromptResult, error)
	Updates        []*SessionUpdateParams // Updates to send during SendPrompt
	PromptResult   *SessionPromptResult   // Result to return from SendPrompt
	PromptError    error                  // Error to return from SendPrompt
	// contains filtered or unexported fields
}

MockSession is a mock implementation of ACPSession for testing.

func NewMockSession added in v1.1.0

func NewMockSession(sessionID string) *MockSession

NewMockSession creates a new mock session for testing.

func (*MockSession) AddChunkUpdate added in v1.1.0

func (m *MockSession) AddChunkUpdate(text string)

AddChunkUpdate is a helper to add a text chunk update

func (*MockSession) AddToolCallEndUpdate added in v1.1.0

func (m *MockSession) AddToolCallEndUpdate(toolCallID, toolName, status, output string)

AddToolCallEndUpdate is a helper to add a tool call completion update

func (*MockSession) AddToolCallUpdate added in v1.1.0

func (m *MockSession) AddToolCallUpdate(toolCallID, toolName, arguments string)

AddToolCallUpdate is a helper to add a tool call update

func (*MockSession) AddUpdate added in v1.1.0

func (m *MockSession) AddUpdate(update *SessionUpdateParams)

AddUpdate adds an update to send during the next SendPrompt call

func (*MockSession) Close added in v1.1.0

func (m *MockSession) Close() error

Close implements ACPSession.Close

func (*MockSession) GetLastMessage added in v1.1.0

func (m *MockSession) GetLastMessage() *Message

GetLastMessage implements ACPSession.GetLastMessage

func (*MockSession) GetMessages added in v1.1.0

func (m *MockSession) GetMessages() []Message

GetMessages implements ACPSession.GetMessages

func (*MockSession) IsClosed added in v1.1.0

func (m *MockSession) IsClosed() bool

IsClosed returns whether the session is closed (for testing)

func (*MockSession) SendPrompt added in v1.1.0

func (m *MockSession) SendPrompt(ctx context.Context, text string, onUpdate func(*SessionUpdateParams)) (*SessionPromptResult, error)

SendPrompt implements ACPSession.SendPrompt

func (*MockSession) SessionID added in v1.1.0

func (m *MockSession) SessionID() string

SessionID implements ACPSession.SessionID

type Process added in v1.1.0

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

Process manages an ACP agent subprocess.

func SpawnProcess added in v1.1.0

func SpawnProcess(ctx context.Context, config ProcessConfig, logger *zap.Logger) (*Process, error)

SpawnProcess starts an ACP agent subprocess.

func (*Process) Close added in v1.1.0

func (p *Process) Close() error

Close shuts down the process.

func (*Process) Errors added in v1.1.0

func (p *Process) Errors() <-chan error

Errors returns the channel for receiving errors.

func (*Process) IsClosed added in v1.1.0

func (p *Process) IsClosed() bool

IsClosed returns whether the process has been closed.

func (*Process) Notifications added in v1.1.0

func (p *Process) Notifications() <-chan *JSONRPCNotification

Notifications returns the channel for receiving notifications.

func (*Process) ReadStderr added in v1.4.0

func (p *Process) ReadStderr() string

ReadStderr reads available stderr content from the process with a short timeout. This is useful for capturing diagnostic output when the process fails. The read is non-blocking to avoid hanging when the process has no stderr output.

func (*Process) Responses added in v1.1.0

func (p *Process) Responses() <-chan *JSONRPCResponse

Responses returns the channel for receiving responses.

func (*Process) SendRequest added in v1.1.0

func (p *Process) SendRequest(req *JSONRPCRequest) error

SendRequest sends a JSON-RPC request to the agent.

type ProcessConfig added in v1.1.0

type ProcessConfig struct {
	Command string
	Args    []string
	Env     map[string]string
	Cwd     string
}

ProcessConfig contains configuration for spawning an ACP agent process.

type PromptCapabilities added in v1.1.0

type PromptCapabilities struct {
	Image           bool `json:"image,omitempty"`
	Audio           bool `json:"audio,omitempty"`
	EmbeddedContext bool `json:"embeddedContext,omitempty"`
}

PromptCapabilities represents capabilities for prompts.

type PromptContent added in v1.1.0

type PromptContent struct {
	Type     string          `json:"type"`
	Text     string          `json:"text,omitempty"`
	Resource *PromptResource `json:"resource,omitempty"`
}

PromptContent represents a content block in a prompt.

type PromptResource added in v1.1.0

type PromptResource struct {
	URI      string `json:"uri"`
	MimeType string `json:"mimeType,omitempty"`
	Text     string `json:"text,omitempty"`
}

PromptResource represents a resource in a prompt.

type Session added in v1.1.0

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

Session represents an active ACP session.

func (*Session) Close added in v1.1.0

func (s *Session) Close() error

Close closes the session. Note: ACP doesn't have a session/close method, so this just marks the session as closed locally.

func (*Session) GetLastMessage added in v1.1.0

func (s *Session) GetLastMessage() *Message

GetLastMessage returns the last message in the history.

func (*Session) GetMessages added in v1.1.0

func (s *Session) GetMessages() []Message

GetMessages returns a copy of the local message history.

func (*Session) SendPrompt added in v1.1.0

func (s *Session) SendPrompt(ctx context.Context, text string, onUpdate func(*SessionUpdateParams)) (*SessionPromptResult, error)

SendPrompt sends a prompt to the session and streams updates via the callback.

func (*Session) SessionID added in v1.1.0

func (s *Session) SessionID() string

SessionID returns the session ID.

type SessionNewParams added in v1.1.0

type SessionNewParams struct {
	Cwd        string      `json:"cwd"`
	MCPServers []MCPServer `json:"mcpServers"` // Required, can be empty array
}

SessionNewParams represents the parameters for session/new request. Both Cwd and MCPServers are required fields per the ACP protocol.

type SessionNewResult added in v1.1.0

type SessionNewResult struct {
	SessionID string `json:"sessionId"`
}

SessionNewResult represents the result of session/new request.

type SessionPromptParams added in v1.1.0

type SessionPromptParams struct {
	SessionID string          `json:"sessionId"`
	Prompt    []PromptContent `json:"prompt"`
}

SessionPromptParams represents the parameters for session/prompt request.

type SessionPromptResult added in v1.1.0

type SessionPromptResult struct {
	StopReason string `json:"stopReason"`
}

SessionPromptResult represents the result of session/prompt request.

type SessionUpdate

type SessionUpdate struct {
	// Type indicates what kind of update this is.
	Type SessionUpdateType `json:"type"`

	// Content is the text content (for message chunks).
	Content string `json:"content,omitempty"`

	// ToolCall is set for tool_call updates.
	ToolCall *ToolCall `json:"toolCall,omitempty"`

	// ToolCallUpdate is set for tool_call_update updates.
	ToolCallUpdate *ToolCallUpdate `json:"toolCallUpdate,omitempty"`

	// StopReason is set when the agent stops.
	StopReason StopReason `json:"stopReason,omitempty"`
}

SessionUpdate represents a real-time update during agent execution. This is a simplified version of ACP's session/update notification.

type SessionUpdateParams added in v1.1.0

type SessionUpdateParams struct {
	SessionID string               `json:"sessionId"`
	Update    SessionUpdatePayload `json:"update"`
}

SessionUpdateParams represents the parameters for session/update notification.

type SessionUpdatePayload added in v1.1.0

type SessionUpdatePayload struct {
	SessionUpdate string `json:"sessionUpdate"`

	// For agent_message_chunk - Content is *MessageContent
	// For tool_call_update - Content is []ToolCallContent (parsed via ContentArray)
	Content json.RawMessage `json:"content,omitempty"`

	// For tool_call
	ToolCallID string                 `json:"toolCallId,omitempty"`
	Name       string                 `json:"name,omitempty"`
	Title      string                 `json:"title,omitempty"`
	Kind       string                 `json:"kind,omitempty"`
	Arguments  map[string]interface{} `json:"arguments,omitempty"`

	// For tool_call_update
	Status    string      `json:"status,omitempty"`
	RawInput  interface{} `json:"rawInput,omitempty"`
	RawOutput interface{} `json:"rawOutput,omitempty"`
}

SessionUpdatePayload represents the update payload in a session/update notification. The Content field is polymorphic based on SessionUpdate type: - For "agent_message_chunk": Content is a MessageContent object - For "tool_call_update": Content is an array of ToolCallContent objects

func (*SessionUpdatePayload) GetMessageContent added in v1.1.0

func (p *SessionUpdatePayload) GetMessageContent() *MessageContent

GetMessageContent parses Content as a MessageContent (for agent_message_chunk).

func (*SessionUpdatePayload) GetToolCallContent added in v1.1.0

func (p *SessionUpdatePayload) GetToolCallContent() []ToolCallContent

GetToolCallContent parses Content as []ToolCallContent (for tool_call_update).

func (*SessionUpdatePayload) GetToolName added in v1.1.0

func (p *SessionUpdatePayload) GetToolName() string

GetToolName returns the tool name, preferring Name but falling back to Title. Some ACP agents (like Rovo Dev) use Title for human-readable tool names.

type SessionUpdateType

type SessionUpdateType string

SessionUpdateType indicates the type of session update.

const (
	// SessionUpdateTypeMessageChunk is a streaming content chunk from the agent.
	SessionUpdateTypeMessageChunk SessionUpdateType = "message_chunk"

	// SessionUpdateTypeToolCall indicates a new tool call is being made.
	SessionUpdateTypeToolCall SessionUpdateType = "tool_call"

	// SessionUpdateTypeToolCallUpdate is an update to an existing tool call.
	SessionUpdateTypeToolCallUpdate SessionUpdateType = "tool_call_update"

	// SessionUpdateTypePlan indicates the agent's execution plan (if supported).
	SessionUpdateTypePlan SessionUpdateType = "plan"

	// SessionUpdateTypeComplete indicates the agent has finished.
	SessionUpdateTypeComplete SessionUpdateType = "complete"
)

type StopReason

type StopReason string

StopReason represents why an agent stopped processing a prompt turn. Aligned with ACP's StopReason enum.

const (
	// StopReasonEndTurn indicates the agent finished its turn successfully.
	// The language model completed responding without requesting more tools.
	StopReasonEndTurn StopReason = "end_turn"

	// StopReasonMaxTokens indicates the maximum token limit was reached.
	StopReasonMaxTokens StopReason = "max_tokens"

	// StopReasonMaxIterations indicates the maximum number of agentic loop
	// iterations was exceeded. This is gsh-specific (ACP uses max_turn_requests).
	StopReasonMaxIterations StopReason = "max_iterations"

	// StopReasonRefusal indicates the agent refused to continue.
	// The agent declined to process the request.
	StopReasonRefusal StopReason = "refusal"

	// StopReasonCancelled indicates the turn was cancelled by the client.
	// This is returned when context cancellation occurs.
	StopReasonCancelled StopReason = "cancelled"

	// StopReasonError indicates an error occurred during processing.
	// This is gsh-specific for general errors.
	StopReasonError StopReason = "error"
)

type TokenUsage

type TokenUsage struct {
	// PromptTokens is the number of tokens in the input/prompt.
	PromptTokens int `json:"promptTokens"`

	// CompletionTokens is the number of tokens in the output/completion.
	CompletionTokens int `json:"completionTokens"`

	// CachedTokens is the number of prompt tokens that were cache hits.
	CachedTokens int `json:"cachedTokens"`

	// TotalTokens is the sum of prompt and completion tokens.
	TotalTokens int `json:"totalTokens"`
}

TokenUsage tracks token consumption during agent execution.

type ToolCall

type ToolCall struct {
	// ID is a unique identifier for this tool call within the session.
	// Maps to ACP's toolCallId.
	ID string `json:"id"`

	// Name is the name of the tool being invoked.
	Name string `json:"name"`

	// Title is a human-readable description of what the tool is doing.
	// Optional - if empty, clients should use the tool name.
	Title string `json:"title,omitempty"`

	// Kind is the category of tool being invoked.
	Kind ToolKind `json:"kind,omitempty"`

	// Arguments are the parameters passed to the tool.
	Arguments map[string]interface{} `json:"arguments,omitempty"`

	// Status is the current execution status.
	Status ToolCallStatus `json:"status"`
}

ToolCall represents a tool call that the language model has requested. This is a simplified version of ACP's ToolCall for internal use.

type ToolCallContent added in v1.1.0

type ToolCallContent struct {
	Type    string          `json:"type"`
	Content *MessageContent `json:"content,omitempty"`
	// For diff type
	Path    string `json:"path,omitempty"`
	OldText string `json:"oldText,omitempty"`
	NewText string `json:"newText,omitempty"`
}

ToolCallContent represents content produced by a tool call.

type ToolCallInfo added in v1.1.0

type ToolCallInfo struct {
	ID        string                 `json:"id"`
	Name      string                 `json:"name"`
	Arguments map[string]interface{} `json:"arguments,omitempty"`
}

ToolCallInfo represents information about a tool call in a message.

type ToolCallStatus

type ToolCallStatus string

ToolCallStatus represents the execution status of a tool call. Aligned with ACP's ToolCallStatus enum.

const (
	// ToolCallStatusPending indicates the tool call is waiting to be executed.
	// In ACP: the tool call has been created but not yet started.
	ToolCallStatusPending ToolCallStatus = "pending"

	// ToolCallStatusInProgress indicates the tool is currently executing.
	// In ACP: the tool call is actively running.
	ToolCallStatusInProgress ToolCallStatus = "in_progress"

	// ToolCallStatusCompleted indicates the tool finished successfully.
	// In ACP: the tool call completed without errors.
	ToolCallStatusCompleted ToolCallStatus = "completed"

	// ToolCallStatusFailed indicates the tool encountered an error.
	// In ACP: the tool call failed during execution.
	ToolCallStatusFailed ToolCallStatus = "failed"
)

type ToolCallUpdate

type ToolCallUpdate struct {
	// ID identifies which tool call this update is for.
	ID string `json:"id"`

	// Status is the new execution status, if changed.
	Status ToolCallStatus `json:"status,omitempty"`

	// Content is any output produced by the tool so far.
	Content string `json:"content,omitempty"`

	// Duration is how long the tool has been running.
	Duration time.Duration `json:"duration,omitempty"`

	// Error contains error information if the tool failed.
	Error error `json:"error,omitempty"`
}

ToolCallUpdate represents an update to an ongoing tool call. Sent during tool execution to report progress.

type ToolKind

type ToolKind string

ToolKind represents the category of tool being invoked. Helps clients choose appropriate icons and UI treatment. Aligned with ACP's ToolKind enum.

const (
	// ToolKindRead indicates a tool that reads data (files, APIs, etc.)
	ToolKindRead ToolKind = "read"

	// ToolKindWrite indicates a tool that writes/modifies data
	ToolKindWrite ToolKind = "write"

	// ToolKindExecute indicates a tool that executes commands
	ToolKindExecute ToolKind = "execute"

	// ToolKindSearch indicates a tool that searches for information
	ToolKindSearch ToolKind = "search"

	// ToolKindOther indicates a tool that doesn't fit other categories
	ToolKindOther ToolKind = "other"
)

Jump to

Keyboard shortcuts

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