class ACP::Session

Defined in:

acp/session.cr

Constructors

Class Method Summary

Instance Method Summary

Constructor Detail

def self.create(client : Client, cwd : String, mcp_servers : Array(JSON::Any) | Nil = nil) : Session #

Creates a new session via session/new.

  • #client — an initialized ACP::Client.
  • cwd — the absolute path to the working directory.
  • mcp_servers — optional MCP server references (as JSON::Any).

The client must be in the Initialized (or SessionActive) state. Returns a new Session instance bound to the created session.


[View source]
def self.load(client : Client, session_id : String, cwd : String, mcp_servers : Array(JSON::Any) | Nil = nil) : Session #

Loads (resumes) a previous session via session/load.

  • #client — an initialized ACP::Client.
  • session_id — the ID of the session to resume.
  • cwd — the absolute path to the working directory.
  • mcp_servers — optional MCP server references (as JSON::Any).

Returns a Session instance bound to the loaded session.


[View source]
def self.new(client : Client, id : String, modes : Protocol::SessionModeState | Nil = nil, config_options : Array(Protocol::ConfigOption) | Nil = nil) #

Direct constructor. Prefer Session.create or Session.load.


[View source]

Class Method Detail

def self.list(client : Client, cwd : String | Nil = nil, cursor : String | Nil = nil) : Protocol::SessionListResult #

Lists available sessions from the agent.

This is a class method because it operates at the client level, not within a specific session.

  • #client — an initialized ACP::Client.
  • cwd — optional filter: only return sessions with this working directory.
  • cursor — optional pagination cursor.

Requires the agent to advertise sessionCapabilities.list. See: https://agentclientprotocol.com/protocol/session-setup#listing-sessions


[View source]

Instance Method Detail

def available_mode_ids : Array(String) #

Returns the list of available mode IDs, or an empty array if the agent doesn't support modes.


[View source]
def cancel : Nil #

Sends a session/cancel notification to abort the current operation in this session. This is fire-and-forget.


[View source]
def client : Client #

The underlying client this session communicates through.


[View source]
def close : Nil #

Marks this session as closed. Further prompt/cancel calls will raise an error. Note: there is no explicit "session/close" method in ACP; this is a client-side state flag.


[View source]
def closed? : Bool #

Whether this session has been explicitly cancelled or closed.


[View source]
def config_options : Array(Protocol::ConfigOption) | Nil #

Config options exposed by the agent for this session.


[View source]
def ext_method(method : String, params : JSON::Any = JSON::Any.new(nil)) : JSON::Any #

Sends a custom extension request to the agent and waits for a response.

  • method — the custom method name (WITHOUT the _ prefix).
  • params — the request parameters as raw JSON.

Returns the raw JSON response from the agent.

Example:

result = session.ext_method("my_custom_method", JSON.parse(%({"key": "value"})))

[View source]
def ext_notification(method : String, params : JSON::Any = JSON::Any.new(nil)) : Nil #

Sends a custom extension notification to the agent (fire-and-forget).

  • method — the custom method name (WITHOUT the _ prefix).
  • params — the notification parameters as raw JSON.

Example:

session.ext_notification("my_custom_event", JSON.parse(%({"status": "ok"})))

[View source]
def id : String #

The unique session ID assigned by the agent.


[View source]
def inspect(io : IO) : Nil #

Same as #to_s but for #inspect.


[View source]
def mode=(mode_id : String) : Nil #

Switches the session to the specified mode.

  • mode_id — the ID of the mode to activate.

[View source]
def modes : Protocol::SessionModeState | Nil #

Mode state for this session (may be nil if agent doesn't support modes).


[View source]
def prompt(content_blocks : Array(Protocol::ContentBlock)) : Protocol::SessionPromptResult #

Sends a prompt with an array of content blocks and waits for the agent's response. Session update notifications will be dispatched through the client's on_update callback while the prompt is being processed.

Returns the prompt result containing the stop reason.

Raises ACP::Error if the session is closed.


[View source]
def prompt(text : String) : Protocol::SessionPromptResult #

Convenience: sends a simple text prompt.

  • text — the text to send as a single TextContentBlock.

Returns the prompt result containing the stop reason.


[View source]
def prompt(*texts : String) : Protocol::SessionPromptResult #

Sends a prompt with multiple text strings, each as a separate TextContentBlock.


[View source]
def prompt(& : PromptBuilder -> ) : Protocol::SessionPromptResult #

Sends a prompt built from a block. The block receives a PromptBuilder for ergonomic content block construction.

Example:

session.prompt do |b|
b.text "Explain this file:"
b.resource_link "/path/to/file.cr"
end

[View source]
def set_config_option(config_id : String, value : String) : Protocol::SessionSetConfigOptionResult #

Changes a session configuration option.

  • config_id — the ID of the config option to change.
  • value — the new value to set.

Returns the full set of config options and their current values. See: https://agentclientprotocol.com/protocol/session-config-options


[View source]
def to_s(io : IO) : Nil #

Returns a human-readable summary of the session for debugging.


[View source]