Agentic.Protocol.ACP.Types (agentic v0.2.2)

ACP (Agent Client Protocol) type definitions and conversions.

Defines the core types from the ACP specification and provides conversion functions between ACP wire format and Agentic internal format.

Wire format uses string keys (ACP is JSON-based). Agentic internal format uses atom keys in structs.

Reference: https://agentclientprotocol.com/protocol/schema.md

Summary

Types

agent_capabilities()

client_capabilities()

content_block()

json_rpc_message()

permission_kind()

permission_option()

protocol_version()

request_id()

session_id()

session_update()

session_update_type()

stop_reason()

tool_call_content()

tool_call_update()

tool_kind()

tool_status()

Functions

build_error(id, code, message, data \\ nil)

Builds a JSON-RPC error response.

build_notification(method, params)

Builds a JSON-RPC notification message (no id, no response expected).

build_request(id, method, params)

Builds a JSON-RPC request message.

build_response(id, result)

Builds a JSON-RPC success response.

content_block_to_text(arg1)

Extracts text content from an ACP ContentBlock.

messages_to_content_blocks(messages)

Converts Agentic messages to ACP ContentBlock[] format.

notification?(msg)

Returns true if the JSON-RPC message is a notification (no id).

parse_message(json)

Parses a JSON string into a JSON-RPC message.

parse_permission_kind(binary)

Parses a permission kind string from ACP wire format to atom.

parse_session_update_type(binary)

Parses a session update type string to atom.

parse_stop_reason(other)

Parses a stop reason string from ACP wire format to atom.

parse_tool_kind(arg1)

Parses a tool kind string from ACP wire format to atom.

parse_tool_status(arg1)

Parses a tool status string from ACP wire format to atom.

request?(msg)

Returns true if the JSON-RPC message is a request (has id and method).

response?(msg)

Returns true if the JSON-RPC message is a response (has id and result/error).

tool_call_to_agentic(map)

Converts an ACP tool_call_update to Agentic pending_tool_call format.

Types

agent_capabilities()

@type agent_capabilities() :: map()

client_capabilities()

@type client_capabilities() :: map()

content_block()

@type content_block() :: %{required(String.t()) => term()}

json_rpc_message()

@type json_rpc_message() :: %{required(String.t()) => term()}

permission_kind()

@type permission_kind() :: :allow_once | :allow_always | :reject_once | :reject_always

permission_option()

@type permission_option() :: %{required(String.t()) => String.t()}

protocol_version()

@type protocol_version() :: pos_integer()

request_id()

@type request_id() :: pos_integer()

session_id()

@type session_id() :: String.t()

session_update()

@type session_update() :: %{required(String.t()) => term()}

session_update_type()

@type session_update_type() ::
  :agent_message_chunk
  | :user_message_chunk
  | :tool_call
  | :tool_call_update
  | :plan
  | :available_commands_update
  | :config_option_update
  | :current_mode_update

stop_reason()

@type stop_reason() ::
  :end_turn | :max_tokens | :max_turn_requests | :refusal | :cancelled

tool_call_content()

@type tool_call_content() :: %{required(String.t()) => term()}

tool_call_update()

@type tool_call_update() :: %{required(String.t()) => term()}

tool_kind()

@type tool_kind() ::
  :read
  | :edit
  | :delete
  | :move
  | :search
  | :execute
  | :think
  | :fetch
  | :other

tool_status()

@type tool_status() :: :pending | :in_progress | :completed | :failed

Functions

build_error(id, code, message, data \\ nil)

@spec build_error(request_id(), integer(), String.t(), term()) :: map()

Builds a JSON-RPC error response.

build_notification(method, params)

@spec build_notification(String.t(), map()) :: map()

Builds a JSON-RPC notification message (no id, no response expected).

build_request(id, method, params)

@spec build_request(request_id(), String.t(), map()) :: map()

Builds a JSON-RPC request message.

build_response(id, result)

@spec build_response(request_id(), term()) :: map()

Builds a JSON-RPC success response.

content_block_to_text(arg1)

@spec content_block_to_text(content_block()) :: String.t()

Extracts text content from an ACP ContentBlock.

Returns the text string or empty string if not a text block.

messages_to_content_blocks(messages)

@spec messages_to_content_blocks([map()]) :: [content_block()]

Converts Agentic messages to ACP ContentBlock[] format.

Agentic messages use %{"role" => ..., "content" => ...} with string keys. ACP prompts use ContentBlock[] with type, text, etc.

notification?(msg)

@spec notification?(json_rpc_message()) :: boolean()

Returns true if the JSON-RPC message is a notification (no id).

parse_message(json)

@spec parse_message(String.t()) :: {:ok, json_rpc_message()} | {:error, term()}

Parses a JSON string into a JSON-RPC message.

parse_permission_kind(binary)

@spec parse_permission_kind(String.t()) :: permission_kind()

Parses a permission kind string from ACP wire format to atom.

parse_session_update_type(binary)

@spec parse_session_update_type(String.t()) :: session_update_type()

Parses a session update type string to atom.

parse_stop_reason(other)

@spec parse_stop_reason(String.t()) :: stop_reason()

Parses a stop reason string from ACP wire format to atom.

parse_tool_kind(arg1)

@spec parse_tool_kind(String.t()) :: tool_kind()

Parses a tool kind string from ACP wire format to atom.

parse_tool_status(arg1)

@spec parse_tool_status(String.t()) :: tool_status()

Parses a tool status string from ACP wire format to atom.

request?(msg)

@spec request?(json_rpc_message()) :: boolean()

Returns true if the JSON-RPC message is a request (has id and method).

response?(msg)

@spec response?(json_rpc_message()) :: boolean()

Returns true if the JSON-RPC message is a response (has id and result/error).

tool_call_to_agentic(map)

@spec tool_call_to_agentic(tool_call_update()) :: map()

Converts an ACP tool_call_update to Agentic pending_tool_call format.