# `AgentWorkshop.PubSub`
[🔗](https://github.com/joshrotenberg/agent_workshop/blob/main/lib/agent_workshop/pubsub.ex#L1)

Event bus for agent coordination.

Agents and processes subscribe to topics and receive messages when
events occur. Workshop auto-publishes lifecycle events; you can
also publish custom events.

## Auto-published events

    {:agent, :ask_complete, agent_name, result}
    {:agent, :cast_complete, agent_name, result}
    {:agent, :error, agent_name, reason}
    {:agent, :created, agent_name}
    {:agent, :dismissed, agent_name}
    {:agent, :reset, agent_name}
    {:store, :put, key}
    {:store, :delete, key}
    {:store, :clear}

## Usage from IEx

    # Subscribe the current process
    AgentWorkshop.PubSub.subscribe(:agent_events)

    # Publish a custom event
    AgentWorkshop.PubSub.broadcast(:deploy_ready, %{sha: "abc123"})

    # Receive (in IEx or a GenServer)
    receive do
      {:workshop_event, topic, event} -> IO.inspect(event)
    end

## Usage in agents

Agents don't subscribe directly (they're CLI subprocesses). Instead,
use periodic tasks (#9) or the work board (#16) for reactive patterns.
PubSub is primarily for BEAM processes: LiveView dashboards, custom
GenServers, telemetry handlers.

# `broadcast`

```elixir
@spec broadcast(term()) :: :ok
```

Broadcast an event to all subscribers of the `:all` topic
and to subscribers of the event's specific topic.

Events are tuples like `{:agent, :ask_complete, name, result}`.
The first element is used as the specific topic.

# `broadcast`

```elixir
@spec broadcast(term(), term()) :: :ok
```

Broadcast an event to a specific topic.

# `subscribe`

```elixir
@spec subscribe(term()) :: :ok
```

Subscribe the calling process to a topic.

The process will receive `{:workshop_event, topic, event}` messages.

# `unsubscribe`

```elixir
@spec unsubscribe(term()) :: :ok
```

Unsubscribe the calling process from a topic.

---

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