Returns a specification to start this module under a supervisor.

See Supervisor.

@spec get_or_spawn(GenServer.server(), agent_id(), agent_module(), keyword()) ::
  {:ok, agent_pid(), boolean()} | {:error, term()}

Gets or spawns an agent, ensuring only one instance exists.

Returns {:ok, pid, started?} where started? is true when a new agent process was launched and false when an existing agent was reused. Returns {:error, reason} if spawning failed.

Examples

{:ok, pid} = AgentRegistry.get_or_spawn(registry, "security_specialist", SecurityAgent)
{:ok, ^pid} = AgentRegistry.get_or_spawn(registry, "security_specialist", SecurityAgent)

@spec list_agents(GenServer.server()) :: [{agent_id(), agent_pid()}]

Lists all registered agents.

Returns a list of {agent_id, pid} tuples.

@spec lookup(GenServer.server(), agent_id()) ::
  {:ok, agent_pid()} | {:error, :not_found}

Looks up an agent by ID.

Returns {:ok, pid} if found, {:error, :not_found} otherwise.

@spec register(GenServer.server(), agent_id(), agent_pid()) ::
  :ok | {:error, :already_registered}

Registers an already-started agent.

Returns :ok if successful, {:error, :already_registered} if agent_id is taken.

Starts the agent registry.

@spec unregister(GenServer.server(), agent_id()) :: :ok

Unregisters an agent.