ExMCP.ACP.Types (ex_mcp v0.9.2)

View Source

Type specifications and builder functions for the Agent Client Protocol (ACP).

ACP uses JSON-RPC 2.0 as its wire format (same as MCP). All types are plain maps matching the ex_mcp convention — no structs for protocol types.

Content Blocks

ACP supports text and image content blocks in prompts and responses:

text_block("Hello, world!")
image_block("image/png", "base64data...")

Session Management

Sessions track agent conversations. Create with new_session_params/2, send prompts with prompt_params/2.

Summary

Types

agent_capabilities()
agent_info()
agent_message_chunk_update()
agent_thought_chunk_update()
audio_block()
auth_method()
available_commands_update()
client_capabilities()
client_info()
close_session_request()
config_option()
config_option_update()
content_block()
current_mode_update()
embedded_resource()
env_variable()
file_read_request()
file_write_request()
http_header()
http_mcp_server()
image_block()
initialize_request()
initialize_response()
list_sessions_request()
list_sessions_response()
load_session_request()
mcp_server()
mode()
new_session_request()
new_session_response()
permission_option()
permission_outcome()
permission_request()
plan()
plan_entry()
prompt_request()
prompt_response()
resource_block()
resource_link_block()
resume_session_request()
session_close_capabilities()
session_info()
session_info_update()
session_list_capabilities()
session_resume_capabilities()
session_update()
session_update_params()
sse_mcp_server()
status_update()
stdio_mcp_server()
text_block()
thinking_update()
tool_call()
tool_call_info()
tool_call_update()
user_message_chunk_update()

Functions

agent_capabilities(opts \\ [])

Creates ACP agent capabilities.

audio_block(mime_type, data, opts \\ [])

Creates an audio content block.

auth_method(id, name, opts \\ [])

Creates an authentication method advertised by an agent.

auth_required_code()

Error code indicating authentication is required.

available_commands_update(session_id, commands)

Creates an available_commands_update session update notification.

client_info(name, version, opts \\ [])

Creates client info for the initialize handshake.

config_option_update(session_id, config_options)

Creates a config_option_update session update notification.

config_option_value(value, name, opts \\ [])

Creates a config option value for select-style session config.

current_mode_update(session_id, current_mode_id)

Creates a current_mode_update session update notification.

env_variable(name, value)

Creates an environment variable entry for a stdio MCP server.

http_header(name, value)

Creates an HTTP header entry for an HTTP/SSE MCP server.

http_mcp_server(name, url, opts \\ [])

Creates an HTTP MCP server config for ACP session setup.

image_block(mime_type, data, opts \\ [])

Creates an image content block.

new_session_params(cwd \\ nil, opts \\ [])

Creates params for a new session request.

plan(session_id, entries)

Creates a stable ACP plan session update notification.

plan_entry(content, priority \\ "medium", status \\ "pending")

Creates a plan entry.

plan_update(session_id, entries)

Creates a stable ACP plan session update notification.

prompt_params(session_id, content)

Creates params for a prompt request.

resource_block(uri, opts \\ [])

Creates a resource content block.

resource_link_block(uri, opts \\ [])

Creates a resource link content block.

resource_not_found_code()

Error code indicating a resource was not found.

select_config_option(id, name, current_value, options, opts \\ [])

Creates a select-style session config option.

session_capabilities(opts \\ [])

Creates session capability metadata.

session_info(session_id, cwd, opts \\ [])

Creates a session info entry returned by session/list.

session_info_update(session_id, opts \\ [])

Creates a session_info_update session update notification.

sse_mcp_server(name, url, opts \\ [])

Creates an SSE MCP server config for ACP session setup.

stdio_mcp_server(name, command, opts \\ [])

Creates a stdio MCP server config for ACP session setup.

text_block(text, opts \\ [])

Creates a text content block.

Types

agent_capabilities()

@type agent_capabilities() :: %{
  optional(:auth) => %{optional(:logout) => map() | nil},
  optional(:loadSession) => boolean(),
  optional(:promptCapabilities) => %{
    optional(:image) => boolean(),
    optional(:audio) => boolean(),
    optional(:embeddedContext) => boolean()
  },
  optional(:mcpCapabilities) => %{
    optional(:http) => boolean(),
    optional(:sse) => boolean()
  },
  optional(:sessionCapabilities) => %{
    optional(:list) => session_list_capabilities() | nil,
    optional(:resume) => session_resume_capabilities() | nil,
    optional(:close) => session_close_capabilities() | nil
  }
}

agent_info()

@type agent_info() :: %{
  :name => String.t(),
  :version => String.t(),
  optional(:title) => String.t()
}

agent_message_chunk_update()

@type agent_message_chunk_update() :: %{
  sessionUpdate: :agent_message_chunk,
  content: content_block()
}

agent_thought_chunk_update()

@type agent_thought_chunk_update() :: %{
  sessionUpdate: :agent_thought_chunk,
  content: content_block()
}

audio_block()

@type audio_block() :: %{type: :audio, mimeType: String.t(), data: String.t()}

auth_method()

@type auth_method() :: %{
  :id => String.t(),
  :name => String.t(),
  optional(:description) => String.t(),
  optional(:type) => String.t()
}

available_commands_update()

@type available_commands_update() :: %{
  sessionUpdate: :available_commands_update,
  availableCommands: [map()]
}

client_capabilities()

@type client_capabilities() :: %{
  optional(:fs) => %{
    optional(:readTextFile) => boolean(),
    optional(:writeTextFile) => boolean()
  },
  optional(:terminal) => boolean()
}

client_info()

@type client_info() :: %{
  :name => String.t(),
  :version => String.t(),
  optional(:title) => String.t()
}

close_session_request()

@type close_session_request() :: %{sessionId: String.t()}

config_option()

@type config_option() :: %{
  :id => String.t(),
  :name => String.t(),
  :type => String.t(),
  :currentValue => String.t(),
  :options => list(),
  optional(:description) => String.t(),
  optional(:category) => String.t()
}

config_option_update()

@type config_option_update() :: %{
  sessionUpdate: :config_option_update,
  configOptions: [config_option()]
}

content_block()

@type content_block() ::
  text_block()
  | image_block()
  | audio_block()
  | resource_link_block()
  | resource_block()

current_mode_update()

@type current_mode_update() :: %{
  sessionUpdate: :current_mode_update,
  currentModeId: String.t()
}

embedded_resource()

@type embedded_resource() ::
  %{:uri => String.t(), :text => String.t(), optional(:mimeType) => String.t()}
  | %{
      :uri => String.t(),
      :blob => String.t(),
      optional(:mimeType) => String.t()
    }

env_variable()

@type env_variable() :: %{name: String.t(), value: String.t()}

file_read_request()

@type file_read_request() :: %{
  :sessionId => String.t(),
  :path => String.t(),
  optional(:line) => non_neg_integer(),
  optional(:limit) => non_neg_integer()
}

file_write_request()

@type file_write_request() :: %{
  sessionId: String.t(),
  path: String.t(),
  content: String.t()
}

http_header()

@type http_header() :: %{name: String.t(), value: String.t()}

http_mcp_server()

@type http_mcp_server() :: %{
  type: :http,
  name: String.t(),
  url: String.t(),
  headers: [http_header()]
}

image_block()

@type image_block() :: %{type: :image, mimeType: String.t(), data: String.t()}

initialize_request()

@type initialize_request() :: %{
  :clientInfo => client_info(),
  optional(:clientCapabilities) => client_capabilities(),
  optional(:protocolVersion) => pos_integer()
}

initialize_response()

@type initialize_response() :: %{
  :agentInfo => agent_info(),
  optional(:agentCapabilities) => agent_capabilities(),
  optional(:authMethods) => [auth_method()],
  optional(:protocolVersion) => pos_integer()
}

list_sessions_request()

@type list_sessions_request() :: %{
  optional(:cursor) => String.t(),
  optional(:cwd) => String.t()
}

list_sessions_response()

@type list_sessions_response() :: %{
  :sessions => [session_info()],
  optional(:nextCursor) => String.t()
}

load_session_request()

@type load_session_request() :: %{
  sessionId: String.t(),
  cwd: String.t(),
  mcpServers: [mcp_server()]
}

mcp_server()

@type mcp_server() :: stdio_mcp_server() | http_mcp_server() | sse_mcp_server()

mode()

@type mode() :: %{
  :id => String.t(),
  :name => String.t(),
  optional(:description) => String.t()
}

new_session_request()

@type new_session_request() :: %{cwd: String.t(), mcpServers: [mcp_server()]}

new_session_response()

@type new_session_response() :: %{sessionId: String.t()}

permission_option()

@type permission_option() :: %{
  :optionId => String.t(),
  :name => String.t(),
  :kind => String.t(),
  optional(:description) => String.t()
}

permission_outcome()

@type permission_outcome() :: %{
  :outcome => String.t(),
  optional(:optionId) => String.t()
}

permission_request()

@type permission_request() :: %{
  sessionId: String.t(),
  toolCall: tool_call_info(),
  options: [permission_option()]
}

plan()

@type plan() :: %{sessionUpdate: :plan, entries: [plan_entry()]}

plan_entry()

@type plan_entry() :: %{
  content: String.t(),
  priority: :high | :medium | :low,
  status: :pending | :in_progress | :completed
}

prompt_request()

@type prompt_request() :: %{sessionId: String.t(), prompt: [content_block()]}

prompt_response()

@type prompt_response() :: %{stopReason: String.t()}

resource_block()

@type resource_block() :: %{type: :resource, resource: embedded_resource()}

resume_session_request()

@type resume_session_request() :: %{
  :sessionId => String.t(),
  :cwd => String.t(),
  optional(:mcpServers) => [mcp_server()]
}

session_close_capabilities()

@type session_close_capabilities() :: map()

session_info()

@type session_info() :: %{
  :sessionId => String.t(),
  :cwd => String.t(),
  optional(:title) => String.t(),
  optional(:updatedAt) => String.t()
}

session_info_update()

@type session_info_update() :: %{
  :sessionUpdate => :session_info_update,
  optional(:title) => String.t(),
  optional(:updatedAt) => String.t()
}

session_list_capabilities()

@type session_list_capabilities() :: map()

session_resume_capabilities()

@type session_resume_capabilities() :: map()

session_update()

@type session_update() ::
  user_message_chunk_update()
  | agent_message_chunk_update()
  | agent_thought_chunk_update()
  | tool_call()
  | tool_call_update()
  | plan()
  | available_commands_update()
  | config_option_update()
  | current_mode_update()
  | session_info_update()
  | thinking_update()
  | status_update()

session_update_params()

@type session_update_params() :: %{sessionId: String.t(), update: session_update()}

sse_mcp_server()

@type sse_mcp_server() :: %{
  type: :sse,
  name: String.t(),
  url: String.t(),
  headers: [http_header()]
}

status_update()

@type status_update() :: %{
  :sessionUpdate => :status,
  :status => String.t(),
  optional(:message) => String.t()
}

stdio_mcp_server()

@type stdio_mcp_server() :: %{
  type: :stdio,
  name: String.t(),
  command: String.t(),
  args: [String.t()],
  env: [env_variable()]
}

text_block()

@type text_block() :: %{type: :text, text: String.t()}

thinking_update()

@type thinking_update() :: %{sessionUpdate: :thinking, content: String.t()}

tool_call()

@type tool_call() :: %{
  :sessionUpdate => :tool_call,
  :toolCallId => String.t(),
  :title => String.t(),
  optional(:status) => String.t(),
  optional(:content) => [map()]
}

tool_call_info()

@type tool_call_info() :: %{
  :toolName => String.t(),
  optional(:toolCallId) => String.t(),
  optional(:arguments) => map()
}

tool_call_update()

@type tool_call_update() :: %{
  :sessionUpdate => :tool_call_update,
  :toolCallId => String.t(),
  optional(:title) => String.t(),
  optional(:status) => String.t(),
  optional(:content) => [map()]
}

user_message_chunk_update()

@type user_message_chunk_update() :: %{
  sessionUpdate: :user_message_chunk,
  content: content_block()
}

Functions

agent_capabilities(opts \\ [])

@spec agent_capabilities(keyword()) :: map()

Creates ACP agent capabilities.

Supported options: :load_session, :http_mcp, :sse_mcp, :image, :audio, :embedded_context, :session_list, :session_resume, :session_close, and :logout.

audio_block(mime_type, data, opts \\ [])

@spec audio_block(String.t(), String.t(), keyword()) :: map()

Creates an audio content block.

auth_method(id, name, opts \\ [])

@spec auth_method(String.t(), String.t(), keyword()) :: map()

Creates an authentication method advertised by an agent.

auth_required_code()

@spec auth_required_code() :: integer()

Error code indicating authentication is required.

available_commands_update(session_id, commands)

@spec available_commands_update(String.t(), [map()]) :: map()

Creates an available_commands_update session update notification.

client_info(name, version, opts \\ [])

@spec client_info(String.t(), String.t(), keyword()) :: map()

Creates client info for the initialize handshake.

config_option_update(session_id, config_options)

@spec config_option_update(String.t(), [map()]) :: map()

Creates a config_option_update session update notification.

config_option_value(value, name, opts \\ [])

@spec config_option_value(String.t(), String.t(), keyword()) :: map()

Creates a config option value for select-style session config.

current_mode_update(session_id, current_mode_id)

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

Creates a current_mode_update session update notification.

env_variable(name, value)

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

Creates an environment variable entry for a stdio MCP server.

http_header(name, value)

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

Creates an HTTP header entry for an HTTP/SSE MCP server.

http_mcp_server(name, url, opts \\ [])

@spec http_mcp_server(String.t(), String.t(), keyword()) :: map()

Creates an HTTP MCP server config for ACP session setup.

image_block(mime_type, data, opts \\ [])

@spec image_block(String.t(), String.t(), keyword()) :: map()

Creates an image content block.

new_session_params(cwd \\ nil, opts \\ [])

@spec new_session_params(
  String.t() | nil,
  keyword()
) :: map()

Creates params for a new session request.

Options

plan(session_id, entries)

@spec plan(String.t(), [map()]) :: map()

Creates a stable ACP plan session update notification.

plan_entry(content, priority \\ "medium", status \\ "pending")

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

Creates a plan entry.

plan_update(session_id, entries)

@spec plan_update(String.t(), [map()]) :: map()

Creates a stable ACP plan session update notification.

prompt_params(session_id, content)

@spec prompt_params(String.t(), String.t() | [map()]) :: map()

Creates params for a prompt request.

Content can be a string (auto-wrapped as text block) or a list of content block maps.

resource_block(uri, opts \\ [])

@spec resource_block(
  String.t(),
  keyword()
) :: map()

Creates a resource content block.

resource_not_found_code()

@spec resource_not_found_code() :: integer()

Error code indicating a resource was not found.

select_config_option(id, name, current_value, options, opts \\ [])

@spec select_config_option(String.t(), String.t(), String.t(), [map()], keyword()) ::
  map()

Creates a select-style session config option.

session_capabilities(opts \\ [])

@spec session_capabilities(keyword()) :: map()

Creates session capability metadata.

session_info(session_id, cwd, opts \\ [])

@spec session_info(String.t(), String.t(), keyword()) :: map()

Creates a session info entry returned by session/list.

session_info_update(session_id, opts \\ [])

@spec session_info_update(
  String.t(),
  keyword()
) :: map()

Creates a session_info_update session update notification.

sse_mcp_server(name, url, opts \\ [])

@spec sse_mcp_server(String.t(), String.t(), keyword()) :: map()

Creates an SSE MCP server config for ACP session setup.

stdio_mcp_server(name, command, opts \\ [])

@spec stdio_mcp_server(String.t(), String.t(), keyword()) :: map()

Creates a stdio MCP server config for ACP session setup.

text_block(text, opts \\ [])

@spec text_block(
  String.t(),
  keyword()
) :: map()

Creates a text content block.