# `Agentic.Protocol.ACP.Discovery`

Auto-discovery of ACP-compatible agents on the system.

Probes the filesystem for known ACP-capable CLIs and registers
discovered agents in the protocol registry.

The known agents database is derived from the acpx project
(https://github.com/openclaw/acpx) and covers 15+ agents.

## Discovery Sources

1. Built-in known agents database (this module)
2. `config :agentic, :acp_agents` (user overrides)
3. `ACP_AGENTS` environment variable (comma-separated)
4. `:discover_callback` in acp config (programmatic)

# `agent_entry`

```elixir
@type agent_entry() :: %{
  name: atom(),
  command: String.t(),
  args: [String.t()],
  display: String.t(),
  aliases: [atom()],
  cache_dirs: [String.t()],
  directories: %{
    linux: os_directories(),
    macos: os_directories(),
    windows: os_directories()
  },
  notes: String.t() | nil
}
```

# `os_directories`

```elixir
@type os_directories() :: %{
  config: [String.t()],
  logs: [String.t()],
  cache: [String.t()]
}
```

# `agent_directories`

```elixir
@spec agent_directories(atom()) :: os_directories() | nil
```

Return the resolved directories for an agent on the current OS.

Returns a map with `config`, `logs`, and `cache` keys containing
expanded absolute paths. Returns `nil` if the agent is unknown.

# `available?`

```elixir
@spec available?(atom()) :: boolean()
```

Check if a specific agent is available.

# `backend_config`

```elixir
@spec backend_config(
  atom(),
  keyword()
) :: map()
```

Get backend config for a named agent.

# `clear_cache`

```elixir
@spec clear_cache() :: :ok
```

Clear the discovery cache.

# `configured_agents`

```elixir
@spec configured_agents() :: [agent_entry()]
```

Parse configured agents from app config and ACP_AGENTS env var.

# `discover_all`

```elixir
@spec discover_all() :: [agent_entry()]
```

Discover all available ACP agents on the system.

Probes each known agent's command for filesystem presence,
merges with user-configured agents, and caches results.

# `discover_and_register`

```elixir
@spec discover_and_register() :: [atom()]
```

Discover agents and register them in the Protocol.Registry.

# `init`

```elixir
@spec init() :: :ok
```

Initialize the ETS table for discovery cache.

# `known_agents`

```elixir
@spec known_agents() :: [agent_entry()]
```

Return all known agent entries (before probing).

# `launch_command`

```elixir
@spec launch_command(atom()) :: {String.t(), [String.t()]} | nil
```

Get the launch command and args for a named agent.

# `lookup`

```elixir
@spec lookup(atom()) :: agent_entry() | nil
```

Look up an agent entry by name.

# `lookup_known`

```elixir
@spec lookup_known(atom()) :: agent_entry() | nil
```

Look up an agent in the built-in database by name or alias (no ETS required).

# `table_name`

Returns the ETS table name (for testing).

---

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