// Package adapter provides protocol adapters for different agent communication protocols. // This abstraction allows agentctl to work with agents using ACP, REST, MCP, or custom protocols. // // Architecture: // - Transport layer (transport/*): Handles protocol-level communication (ACP, stream-json, codex, opencode) // - Factory: Creates the appropriate transport adapter based on agent's protocol // // Agent configuration (commands, discovery, models) is handled by the agent/registry package // using agents.json as the source of truth. This package only handles protocol communication. package adapter import ( "context" "io" "github.com/kandev/kandev/internal/agentctl/server/adapter/transport/shared" "github.com/kandev/kandev/internal/agentctl/types" "github.com/kandev/kandev/internal/agentctl/types/streams" v1 "github.com/kandev/kandev/pkg/api/v1" ) // Re-export permission types from the shared types package for convenience. // This allows users of the adapter package to access these types without // importing the types package directly. type ( PermissionRequest = types.PermissionRequest PermissionResponse = types.PermissionResponse PermissionOption = streams.PermissionOption PermissionHandler = types.PermissionHandler ) // Re-export stream types for convenience. type ( AgentEvent = streams.AgentEvent PlanEntry = streams.PlanEntry ) // Re-export agent event type constants from streams package. const ( EventTypeMessageChunk = streams.EventTypeMessageChunk EventTypeReasoning = streams.EventTypeReasoning EventTypeToolCall = streams.EventTypeToolCall EventTypeToolUpdate = streams.EventTypeToolUpdate EventTypePlan = streams.EventTypePlan EventTypeComplete = streams.EventTypeComplete EventTypeError = streams.EventTypeError EventTypePermissionRequest = streams.EventTypePermissionRequest EventTypePermissionCancelled = streams.EventTypePermissionCancelled EventTypeContextWindow = streams.EventTypeContextWindow EventTypeSessionStatus = streams.EventTypeSessionStatus EventTypeRateLimit = streams.EventTypeRateLimit ) // OneShotAdapter is an optional interface implemented by adapters that spawn // a new process per prompt (e.g., Amp). When an adapter is one-shot, the // process manager skips subprocess creation and the adapter manages its own // subprocess lifecycle internally. type OneShotAdapter interface { IsOneShot() bool } // OneShotConfig holds command configuration for one-shot adapters that manage // their own subprocess lifecycle. The adapter spawns a new process per prompt. type OneShotConfig struct { // InitialArgs is the command for the first prompt in a new session. InitialArgs []string // ContinueArgs is the command for follow-up prompts. // The thread/session ID is appended at runtime. ContinueArgs []string // Env is the environment variables for the subprocess. Env []string // WorkDir is the working directory for the subprocess. WorkDir string } // StderrProvider provides access to recent stderr output for error context. // This is used by adapters to include stderr in error events when the agent // reports an error without a detailed message (e.g., rate limit errors). type StderrProvider interface { // GetRecentStderr returns the most recent stderr lines from the agent process. GetRecentStderr() []string } // StderrProviderSetter is an optional interface implemented by adapters that can use // stderr output for error context. The process manager checks for this interface // and calls SetStderrProvider if available. type StderrProviderSetter interface { SetStderrProvider(provider StderrProvider) } // ModeSettableAdapter is an optional interface implemented by adapters that // support changing the session mode (e.g., ACP adapters with session/set_mode). type ModeSettableAdapter interface { SetMode(ctx context.Context, modeID string) error } // ModelSettableAdapter is an optional interface implemented by adapters that // support changing the session model (e.g., ACP adapters with session/set_model). type ModelSettableAdapter interface { SetModel(ctx context.Context, modelID string) error } // AuthenticatableAdapter is an optional interface implemented by adapters that // support ACP authentication (session/authenticate). type AuthenticatableAdapter interface { Authenticate(ctx context.Context, methodID string) error } // ConfigOptionSettableAdapter is an optional interface implemented by adapters // that support setting an arbitrary session config option (ACP // session/set_config_option). Useful for agent-specific runtime knobs that // aren't covered by mode/model. type ConfigOptionSettableAdapter interface { SetConfigOption(ctx context.Context, key, value string) error } // SessionResettableAdapter is an optional interface implemented by adapters that // can reset context by creating a new session on the same connection, without // restarting the agent subprocess. Only ACP adapters support this. type SessionResettableAdapter interface { ResetSession(ctx context.Context, mcpServers []types.McpServer) (string, error) } // AgentInfo contains information about the connected agent. type AgentInfo struct { Name string `json:"name"` Version string `json:"version"` } // AgentAdapter defines the interface for protocol adapters. // Each adapter translates a specific protocol (ACP, REST, MCP, etc.) into the // normalized AgentEvent format that agentctl exposes via its HTTP API. // // Lifecycle: // 1. Create adapter with New*Adapter(cfg, logger) // 2. Call PrepareEnvironment() before starting the agent process // 3. Call PrepareCommandArgs() to get extra command-line args // 4. Start the agent process and obtain stdin/stdout pipes // 5. Call Connect(stdin, stdout) to wire up communication // 6. Call Initialize() to establish protocol handshake // 7. Use NewSession/LoadSession/Prompt/Cancel for agent interactions // 8. Call Close() when done type AgentAdapter interface { // PrepareEnvironment performs protocol-specific setup before the agent process starts. // For ACP, this is a no-op (MCP servers are passed through the protocol). // For OpenCode, this returns environment variables for server authentication. // Must be called before the agent subprocess is started. // Returns a map of environment variables to add to the subprocess environment. PrepareEnvironment() (map[string]string, error) // PrepareCommandArgs returns extra command-line arguments for the agent process. // For Codex, this returns -c flags for MCP servers and sandbox config. // For other protocols, this returns nil (no extra args needed). // Must be called after PrepareEnvironment and before starting the subprocess. PrepareCommandArgs() []string // Connect wires up the stdin/stdout pipes from the running agent subprocess. // Must be called after the subprocess is started and before Initialize. Connect(stdin io.Writer, stdout io.Reader) error // Initialize establishes the connection with the agent and exchanges capabilities. // For subprocess-based agents (ACP), this sends the initialize request. // For HTTP-based agents (REST), this might do a health check. Initialize(ctx context.Context) error // GetAgentInfo returns information about the connected agent. // Returns nil if Initialize has not been called yet. GetAgentInfo() *AgentInfo // NewSession creates a new agent session and returns the session ID. NewSession(ctx context.Context, mcpServers []types.McpServer) (string, error) // LoadSession resumes an existing session by ID. // mcpServers contains the MCP servers to configure for the resumed session. // Agents that receive MCP configs via the protocol (e.g. ACP with AssumeMcpSse) // need these to reconnect to MCP servers on a new agentctl instance. LoadSession(ctx context.Context, sessionID string, mcpServers []types.McpServer) error // Prompt sends a prompt to the agent. // The agent's responses are streamed via the Updates channel. // Attachments (images) are passed to the agent if provided. Prompt(ctx context.Context, message string, attachments []v1.MessageAttachment) error // Cancel cancels the current operation. Cancel(ctx context.Context) error // Updates returns a channel that receives agent events. // The channel is closed when the adapter is closed. Updates() <-chan AgentEvent // GetSessionID returns the current session ID. GetSessionID() string // GetOperationID returns the current operation/turn ID. // Returns empty string if no operation is in progress or not supported by the protocol. // For Codex this is the turn ID, for ACP this may be empty. GetOperationID() string // SetPermissionHandler sets the handler for permission requests. SetPermissionHandler(handler PermissionHandler) // Close releases resources held by the adapter. Close() error // RequiresProcessKill returns true if the adapter's subprocess needs to be // explicitly killed during shutdown. Adapters that communicate via stdin/stdout // (ACP, Codex, Claude Code) return false because closing stdin causes the // subprocess to exit. HTTP-server-based adapters (OpenCode) return true because // they don't exit on stdin close. RequiresProcessKill() bool } // McpServerConfig holds configuration for an MCP server. type McpServerConfig struct { // Name is the human-readable name of the MCP server Name string `json:"name"` // URL is the URL for HTTP/SSE transport URL string `json:"url,omitempty"` // Type is the transport type: "stdio", "sse", "http", or "streamable_http" Type string `json:"type,omitempty"` // Command is the command for stdio transport Command string `json:"command,omitempty"` // Args are the arguments for stdio transport Args []string `json:"args,omitempty"` // Env holds environment variables for stdio transport Env map[string]string `json:"env,omitempty"` // Headers holds HTTP headers for SSE/HTTP transport Headers map[string]string `json:"headers,omitempty"` } // Config holds configuration for creating adapters type Config struct { // WorkDir is the working directory for the agent WorkDir string // AutoApprove automatically approves permission requests AutoApprove bool // ApprovalPolicy controls when the agent requests approval. // Valid values: "untrusted" (always), "on-failure", "on-request", "never". // Defaults to "on-request" if empty. ApprovalPolicy string // McpServers is a list of MCP servers to configure for the agent McpServers []McpServerConfig // AgentID is the agent identifier from the registry (e.g., "auggie", "amp", "claude-code"). // Used for logging and debug capture. Adapters should use this instead of hardcoded names. AgentID string // AgentName is the human-readable agent name (e.g., "Auggie", "AMP", "Claude Code"). // Used for display purposes. AgentName string // For HTTP-based adapters (REST) BaseURL string // Base URL of the agent's HTTP API AuthHeader string // Optional auth header name AuthValue string // Optional auth header value Headers map[string]string // Additional headers // Protocol-specific configuration Extra map[string]string // OneShotConfig is set for one-shot adapters that manage their own subprocess. // When non-nil, the process manager skips subprocess creation. OneShotConfig *OneShotConfig // AssumeMcpSse overrides MCP capability filtering to assume SSE support. AssumeMcpSse bool // AssumeMcpHttp overrides MCP capability filtering to assume HTTP support. AssumeMcpHttp bool // RequiresProcessKill is read by the transport adapter's RequiresProcessKill() // method. Set true for agents whose subprocess does not exit on stdin close // (opencode acp). The process manager uses the adapter's return value to // decide whether to kill the entire process group on shutdown. RequiresProcessKill bool } // ToSharedConfig converts this Config to the shared.Config used by transport adapters. func (c *Config) ToSharedConfig() *shared.Config { mcpServers := make([]shared.McpServerConfig, len(c.McpServers)) for i, srv := range c.McpServers { mcpServers[i] = shared.McpServerConfig{ Name: srv.Name, URL: srv.URL, Type: srv.Type, Command: srv.Command, Args: srv.Args, Env: srv.Env, Headers: srv.Headers, } } return &shared.Config{ WorkDir: c.WorkDir, AutoApprove: c.AutoApprove, ApprovalPolicy: c.ApprovalPolicy, McpServers: mcpServers, AgentID: c.AgentID, AgentName: c.AgentName, BaseURL: c.BaseURL, AuthHeader: c.AuthHeader, AuthValue: c.AuthValue, Headers: c.Headers, Extra: c.Extra, AssumeMcpSse: c.AssumeMcpSse, AssumeMcpHttp: c.AssumeMcpHttp, RequiresProcessKill: c.RequiresProcessKill, } }