@spec clear_default_agent(pid()) :: :ok

Clear any default agent override for a session.

After clearing, the session will use whatever agent the backend selects by default or infers from session metadata.

@spec current_agent(pid()) :: {:ok, binary()} | {:error, :not_set}

Return the currently selected default agent for a session.

Returns {:ok, agent_id} if one has been set or inferred, or {:error, :not_set} when no agent is active.

@spec get_agent(pid(), binary()) :: {:ok, map()} | {:error, :not_found | term()}

Look up a single agent by its id, name, or path.

Returns {:error, :not_found} when no agent matches the given identifier.

@spec get_plugin(pid(), binary()) :: {:ok, map()} | {:error, :not_found | term()}

Look up a single plugin by its id, name, or path.

Returns {:error, :not_found} when no plugin matches the given identifier.

@spec get_skill(pid(), binary()) :: {:ok, map()} | {:error, :not_found | term()}

Look up a single skill by its id, name, or path.

Returns {:error, :not_found} when no skill matches the given identifier.

@spec get_tool(pid(), binary()) :: {:ok, map()} | {:error, :not_found | term()}

Look up a single tool by its id, name, or path.

Returns {:error, :not_found} when no tool matches the given identifier.

Example

case BeamAgent.Catalog.get_tool(session, "file_read") do
  {:ok, %{name: name, description: desc}} -> IO.puts("Found " <> name <> ": " <> desc)
  {:error, :not_found} -> IO.puts("Tool not available")
end

@spec list_agents(pid()) :: {:ok, [map()]} | {:error, term()}

List all agents available to a session.

Prefers native agent listings from the backend (e.g., Copilot's list_server_agents) when available, falling back to agents extracted from session metadata.

@spec list_commands(pid()) :: {:ok, [map()]} | {:error, term()}

List commands available for the session using native-first routing.

Attempts the backend's native command listing first. Falls back to supported_commands/1 if the backend does not support dynamic listing. The result may include commands added at runtime (e.g., via plugins or MCP servers).

Parameters

• session -- pid of a running session.

Returns

• {:ok, commands} where commands is a list of command maps.
• {:error, reason} on failure.

@spec list_mcp_servers(pid()) :: {:ok, [map()]} | {:error, term()}

List all MCP servers connected to a session.

Returns metadata about each MCP server, including server names, capabilities, and connection status as reported by the backend.

@spec list_plugins(pid()) :: {:ok, [map()]} | {:error, term()}

List all plugins available to a session.

Returns plugin entries from the session's metadata. Plugin availability depends on the backend's extension model.

@spec list_skills(pid()) :: {:ok, [map()]} | {:error, term()}

List all skills available to a session.

Prefers native skill listings from the backend when available, falling back to skills extracted from session metadata.

@spec list_tools(pid()) :: {:ok, [map()]} | {:error, term()}

List all tools available to a session.

Returns catalog entries from the session's tool listing. The exact contents depend on the backend and any MCP servers connected to the session.

Example

{:ok, tools} = BeamAgent.Catalog.list_tools(session)
Enum.each(tools, fn %{name: name} -> IO.puts("Tool: #{name}") end)

@spec model_list(pid()) :: {:ok, [map()]} | {:error, term()}

List models available for the session using native-first routing.

Convenience wrapper that calls model_list/2 with empty options. Attempts the backend's native model listing first; falls back to supported_models/1 if the backend does not support dynamic listing.

Parameters

• session -- pid of a running session.

Returns

• {:ok, models} where models is a list of model maps.
• {:error, reason} on failure.

@spec model_list(pid(), map()) :: {:ok, [map()]} | {:error, term()}

List models with backend-specific filter options.

Filters are backend-specific and may include capabilities, context window size, or model family. Uses native-first routing with a fallback to supported_models/1.

Parameters

• session -- pid of a running session.
• opts -- backend-specific filter options map.

Returns

• {:ok, models} or {:error, reason}.

@spec set_default_agent(pid(), binary()) :: :ok

Set the default agent for future queries on a session.

The agent ID is stored in the runtime state and merged into future query options automatically. Allows switching between agents without restarting the session.

Example

:ok = BeamAgent.Catalog.set_default_agent(session, "claude-sonnet-4-6")
{:ok, "claude-sonnet-4-6"} = BeamAgent.Catalog.current_agent(session)

@spec supported_agents(pid()) :: {:ok, [map()]} | {:error, term()}

Return the static list of sub-agents that the session's backend exposes.

Sub-agents are specialized assistants that handle focused tasks such as code review, test generation, or documentation writing.

Parameters

• session -- pid of a running session.

Returns

• {:ok, agents} where agents is a list of agent maps, each containing :name, :description, and :capabilities.
• {:error, reason} on failure.

@spec supported_commands(pid()) :: {:ok, [map()]} | {:error, term()}

Return the static list of CLI commands that the session's backend supports.

Each backend advertises a fixed set of commands it can handle (e.g., "query", "interrupt", "config"). Use this to discover what operations are available before attempting them, or to build dynamic command palettes.

Parameters

• session -- pid of a running session.

Returns

• {:ok, commands} where commands is a list of command maps, each containing :name and :description.
• {:error, reason} on failure.

@spec supported_models(pid()) :: {:ok, [map()]} | {:error, term()}

Return the static list of LLM models available for the session's backend.

Use this to present model selection options or validate a model identifier before passing it to BeamAgent.Runtime.set_model/2.

Parameters

• session -- pid of a running session.

Returns

• {:ok, models} where models is a list of model maps, each containing :name and :capabilities.
• {:error, reason} on failure.