@spec encode_agent_message_chunk(String.t(), String.t() | map()) :: map()

Encodes an agent_message_chunk update notification.

@spec encode_agent_thought_chunk(String.t(), String.t() | map()) :: map()

Encodes an agent_thought_chunk update notification.

@spec encode_authenticate(String.t() | map()) :: map()

Encodes an authenticate request.

ACP v1 authentication uses a "methodId" selected from the agent's authMethods initialize response. A map may still be passed for adapter compatibility.

Parameters

• method_id_or_params — auth method ID string or full params map

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

Encodes an available_commands_update notification.

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

Encodes a config_option_update notification.

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

Encodes a current_mode_update notification.

Encodes a JSON-RPC error response.

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

Encodes an fs/read_text_file request from agent to client.

@spec encode_file_read_response(integer() | String.t(), String.t()) :: map()

Encodes a response to a fs/read_text_file request from the agent.

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

Encodes an fs/write_text_file request from agent to client.

@spec encode_file_write_response(integer() | String.t()) :: map()

Encodes a response to a fs/write_text_file request from the agent.

@spec encode_initialize(map(), map() | nil, pos_integer()) :: map()

Encodes an initialize request.

Parameters

• client_info — %{"name" => ..., "version" => ...}
• capabilities — client capabilities map (optional)
• protocol_version — integer (default: 1)

@spec encode_initialize_response(
  integer() | String.t(),
  map(),
  map() | nil,
  [map()] | nil,
  pos_integer()
) :: map()

Encodes an agent initialize response.

@spec encode_logout() :: map()

Encodes a logout request. Stabilized in ACP spec May 21, 2026.

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

Encodes a session/request_permission request from agent to client.

Each option's kind must be one of the spec enums allow_once, allow_always, reject_once, reject_always per https://agentclientprotocol.com/protocol/tool-calls. Non-spec values raise ArgumentError — a client receiving an unrecognized kind cannot render the correct UI affordance.

@spec encode_permission_response(integer() | String.t(), map()) :: map()

Encodes a response to a session/request_permission request from the agent.

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

Encodes an ACP plan update notification.

@spec encode_prompt_response(integer() | String.t(), String.t() | map()) :: map()

Encodes a session/prompt response.

Encodes a JSON-RPC success response.

@spec encode_session_cancel(String.t()) :: map()

Encodes a session/cancel notification (no id field).

@spec encode_session_close(String.t()) :: map()

Encodes a session/close request. Stabilized in ACP spec April 23, 2026.

@spec encode_session_delete(String.t()) :: map()

Encodes a session/delete request. Gated by sessionCapabilities.delete per https://agentclientprotocol.com/protocol/session-list.

@spec encode_session_fork(String.t(), String.t(), keyword() | map() | [map()] | nil) ::
  map()

Encodes an unstable session/fork request.

cwd is required and must be an absolute path at the client validation boundary. The request shape matches session/resume.

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

Encodes a session_info_update notification.

@spec encode_session_list(keyword()) :: map()

Encodes a session/list request. Stabilized in ACP spec March 9, 2026.

@spec encode_session_list_response(integer() | String.t(), [map()], String.t() | nil) ::
  map()

Encodes a session/list response.

@spec encode_session_load(String.t(), String.t(), keyword() | map() | [map()] | nil) ::
  map()

Encodes a session/load request to load an existing session and replay history.

cwd is required by the ACP spec (https://agentclientprotocol.com/protocol/session-setup) and must be an absolute path string. Passing nil raises FunctionClauseError.

@spec encode_session_new(String.t(), keyword() | map() | [map()] | nil) :: map()

Encodes a session/new request.

cwd is required by the ACP spec (https://agentclientprotocol.com/protocol/session-setup) and must be an absolute path string. Passing nil raises FunctionClauseError.

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

Encodes a session/prompt request.

@spec encode_session_response(integer() | String.t(), String.t() | map() | nil) ::
  map()

Encodes a session/new, session/load, or similar session ID response.

@spec encode_session_resume(String.t(), String.t(), keyword() | map() | [map()] | nil) ::
  map()

Encodes a session/resume request. Stabilized in ACP spec April 22, 2026.

cwd is required (same shape as session/load per https://agentclientprotocol.com/protocol/session-list). Passing nil raises FunctionClauseError.

@spec encode_session_set_config_option(String.t(), String.t(), any()) :: map()

Encodes a session/set_config_option request.

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

Encodes a session/set_mode request.

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

Encodes a session/set_model request.

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

Encodes a stable ACP session/update notification.

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

Encodes a stable terminal/* request from agent to client.

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

Encodes a tool_call update notification.

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

Encodes a tool_call_update notification.

@spec encode_usage_update(
  String.t(),
  non_neg_integer(),
  non_neg_integer(),
  map() | nil
) :: map()

Encodes a usage_update notification.

Generates a unique request ID.

@spec parse_message(String.t() | map()) ::
  {:request, String.t(), map(), integer() | String.t()}
  | {:notification, String.t(), map()}
  | {:result, any(), integer() | String.t()}
  | {:error, map(), integer() | String.t() | nil}
  | {:error, :invalid_message}

Parses a raw ACP JSON-RPC message with structural validation.