@spec all() :: [capability_info()]

Return the full capability matrix as a list of capability_info() maps.

Each entry contains the capability :id, a human-readable :title, and a :support map keyed by backend atom. This is the master data source consulted by all other functions in this module.

Example

all = BeamAgent.Capabilities.all()
[%{id: :session_lifecycle, title: _, support: s} | _] = all

@spec assert_capability(capability(), atom() | binary()) ::
  :ok
  | {:error,
     {:unsupported_capability, capability(), backend()}
     | {:unknown_capability, capability()}
     | {:unknown_backend, term()}}

Assert that a capability is supported for a given backend.

A pre-flight check wrapper around supports/2. Returns :ok when the capability is supported, or {:error, {:unsupported_capability, cap, backend}} when the capability is not available. Returns the underlying {:error, status_error()} tuple for unknown capability or backend atoms.

Use this before calling a feature to produce a clear error at the call site rather than a confusing failure inside the feature implementation.

Example

iex> BeamAgent.Capabilities.assert_capability(:checkpointing, :codex)
:ok

iex> BeamAgent.Capabilities.assert_capability(:bogus_feature, :claude)
{:error, {:unknown_capability, :bogus_feature}}

@spec backends() :: [:claude | :codex | :gemini | :opencode | :copilot, ...]

Return the list of all supported backend atoms.

The five backends are: :claude, :codex, :gemini, :opencode, :copilot.

Example

iex> BeamAgent.Capabilities.backends()
[:claude, :codex, :gemini, :opencode, :copilot]

@spec capabilities() :: [capability_info()]

Return the full capability matrix as a list of capability info maps.

Each entry describes one capability with its support level across all five backends. Equivalent to all/0 — this is the convenience name used by the top-level BeamAgent module.

Example

caps = BeamAgent.Capabilities.capabilities()
for cap <- caps, do: IO.puts(cap[:id])

@spec capabilities(pid() | atom() | binary()) ::
  {:ok, [map()]}
  | {:error,
     :backend_not_present
     | {:invalid_session_info, term()}
     | {:session_backend_lookup_failed, term()}
     | {:unknown_backend, term()}}

List capabilities for a specific session or backend.

When given a pid, queries the live session for its backend and returns that backend's capability set. When given a backend atom or binary, returns the static capability set for that backend without requiring a running session.

Parameters

• value -- a session pid, backend atom (e.g., :claude), or binary.

Returns

• {:ok, capabilities} -- list of capability maps.
• {:error, reason} on failure.

Examples

{:ok, caps} = BeamAgent.Capabilities.capabilities(:claude)
{:ok, caps} = BeamAgent.Capabilities.capabilities(session)

@spec capability_ids() :: [capability()]

Return the flat list of all 23 capability atom identifiers.

Useful for iterating over capabilities without loading the full matrix. The order matches the order of entries in all/0.

Example

ids = BeamAgent.Capabilities.capability_ids()
true = :checkpointing in ids

@spec for_backend(atom() | binary()) ::
  {:ok, [map()]} | {:error, {:unknown_backend, term()}}

Return the projected capability list for a specific backend.

backend_like may be a backend atom (:claude), a binary ("codex"), or any value accepted by :beam_agent_backend.normalize/1.

Each entry in the returned list is a flat map with :id, :title, :backend, :support_level, :implementation, and :fidelity, plus optional :available_paths and :notes where present.

Returns {:error, {:unknown_backend, backend}} for unrecognised backend values.

Example

{:ok, caps} = BeamAgent.Capabilities.for_backend(:claude)
[%{id: :session_lifecycle, support_level: :full} | _] = caps

@spec for_session(pid()) ::
  {:ok, [map()]}
  | {:error,
     :backend_not_present
     | {:unknown_backend, term()}
     | {:invalid_session_info, term()}
     | {:session_backend_lookup_failed, term()}}

Return the projected capability list for the backend of a live session.

Resolves the backend from the running session process and delegates to for_backend/1. This is the most convenient call during an active agent session when you do not know — or do not want to hard-code — the backend.

Returns {:error, :backend_not_present} if the session process is not registered, or {:error, {:session_backend_lookup_failed, reason}} for other lookup failures.

Example

{:ok, session} = BeamAgent.start_session(%{backend: :gemini})
{:ok, caps} = BeamAgent.Capabilities.for_session(session)

@spec status(capability(), atom() | binary()) ::
  {:ok, support_info()}
  | {:error, {:unknown_backend, term()} | {:unknown_capability, term()}}

Return the full support_info() map for a specific capability/backend pair.

The returned map always contains :support_level, :implementation, and :fidelity. It may also include :available_paths and :notes where the capability has backend-specific detail.

Returns {:error, {:unknown_capability, cap}} for an unrecognised capability atom, or {:error, {:unknown_backend, backend}} for an unrecognised backend.

Example

{:ok, %{support_level: :full, implementation: :universal}} =
  BeamAgent.Capabilities.status(:permission_mode, :gemini)

@spec supports(capability(), atom() | binary()) ::
  {:ok, true}
  | {:error, {:unknown_capability, capability()} | {:unknown_backend, term()}}

Check whether a capability is supported for a given backend.

A convenience wrapper around status/2. Because all 23 capabilities are at :full support level for all 5 backends, this returns {:ok, true} for every valid capability/backend combination. It exists to make guard-style checks readable and to surface {:error, ...} for typos.

Returns {:error, {:unknown_capability, cap}} or {:error, {:unknown_backend, backend}} for invalid inputs.

Example

iex> BeamAgent.Capabilities.supports(:checkpointing, :codex)
{:ok, true}

iex> BeamAgent.Capabilities.supports(:in_process_mcp, "gemini")
{:ok, true}

iex> BeamAgent.Capabilities.supports(:bogus, :claude)
{:error, {:unknown_capability, :bogus}}