Client

Overview

ACP::Client is the core class that manages the ACP protocol lifecycle. It handles request correlation, dispatches incoming messages via a background fiber, and provides methods for all ACP protocol operations.

Constructor

.new

ACP::Client.new(
  transport : ACP::Transport,
  client_name : String = "acp-crystal",
  client_version : String = ACP::VERSION,
  client_capabilities : ACP::Protocol::ClientCapabilities = ACP::Protocol::ClientCapabilities.new
)

Lifecycle Methods

#initialize_connection

client.initialize_connection : ACP::Protocol::InitializeResult

Performs the ACP handshake with the agent. Transitions state from Created to Initialized. Returns agent info and capabilities.

#authenticate

client.authenticate(method_id : String) : Nil

Authenticates with the agent using the specified method. Call after initialize_connection if authentication is required.

#close

client.close : Nil

Closes the connection, stops the dispatcher fiber, and cleans up resources. Transitions state to Closed.

Session Methods

#session_new

client.session_new(
  cwd : String,
  mcp_servers : Array(ACP::Protocol::McpServerConfig)? = nil
) : ACP::Protocol::SessionNewResult

Creates a new session. Transitions state to SessionActive.

#session_load

client.session_load(
  session_id : String,
  cwd : String,
  mcp_servers : Array(ACP::Protocol::McpServerConfig)? = nil
) : ACP::Protocol::SessionLoadResult

Resumes a previous session by ID.

#session_prompt

client.session_prompt(
  blocks : Array(ACP::Protocol::ContentBlock),
  session_id : String? = nil
) : ACP::Protocol::SessionPromptResult

Sends content blocks as a prompt to the active session.

#session_prompt_text

client.session_prompt_text(
  text : String,
  session_id : String? = nil
) : ACP::Protocol::SessionPromptResult

Convenience method to send a single text prompt.

#session_cancel

client.session_cancel(session_id : String? = nil) : Nil

Cancels an in-progress generation.

#session_set_mode

client.session_set_mode(
  mode_id : String,
  session_id : String? = nil
) : Nil

Switches the session to a different mode.

#session_set_config_option

client.session_set_config_option(
  config_id : String,
  value : JSON::Any::Type,
  session_id : String? = nil
) : ACP::Protocol::SessionSetConfigOptionResult

Changes a configuration option in the active session.

Extension Methods

#ext_method

client.ext_method(
  method : String,
  params : Hash(String, JSON::Any::Type)? = nil,
  timeout : Float64? = nil
) : JSON::Any

Sends a custom extension request to the agent.

#ext_notification

client.ext_notification(
  method : String,
  params : Hash(String, JSON::Any::Type)? = nil
) : Nil

Sends a custom extension notification (no response expected).

State & Inspection

Configuration

Callbacks

Typed Client Method Handlers