# `Agentic.Protocol.ACP.Types`

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

# `agent_capabilities`

```elixir
@type agent_capabilities() :: map()
```

# `client_capabilities`

```elixir
@type client_capabilities() :: map()
```

# `content_block`

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

# `json_rpc_message`

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

# `permission_kind`

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

# `permission_option`

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

# `protocol_version`

```elixir
@type protocol_version() :: pos_integer()
```

# `request_id`

```elixir
@type request_id() :: pos_integer()
```

# `session_id`

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

# `session_update`

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

# `session_update_type`

```elixir
@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`

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

# `tool_call_content`

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

# `tool_call_update`

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

# `tool_kind`

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

# `tool_status`

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

# `build_error`

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

Builds a JSON-RPC error response.

# `build_notification`

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

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

# `build_request`

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

Builds a JSON-RPC request message.

# `build_response`

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

Builds a JSON-RPC success response.

# `content_block_to_text`

```elixir
@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`

```elixir
@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?`

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

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

# `parse_message`

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

Parses a JSON string into a JSON-RPC message.

# `parse_permission_kind`

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

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

# `parse_session_update_type`

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

Parses a session update type string to atom.

# `parse_stop_reason`

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

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

# `parse_tool_kind`

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

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

# `parse_tool_status`

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

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

# `request?`

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

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

# `response?`

```elixir
@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`

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

Converts an ACP tool_call_update to Agentic pending_tool_call format.

---

*Consult [api-reference.md](api-reference.md) for complete listing*