# `Jido.Messaging.Signal`
[🔗](https://github.com/agentjido/jido_messaging/blob/v1.0.0/lib/jido_messaging/signal.ex#L1)

Signal emission for messaging events using dual-emission pattern.

Emits both:
- `:telemetry` events for metrics and instrumentation
- `Jido.Signal` CloudEvents for domain events with causality tracking

## Telemetry Events

- `[:jido_messaging, :message, :received]` - when a message is ingested
- `[:jido_messaging, :message, :sent]` - when a message is delivered successfully
- `[:jido_messaging, :message, :failed]` - when delivery fails

## Jido.Signal CloudEvents

- `jido.messaging.message.received` - message ingested
- `jido.messaging.message.sent` - message delivered
- `jido.messaging.message.failed` - delivery failed
- `jido.messaging.agent.triggered` - agent trigger detected
- `jido.messaging.agent.started` - agent execution started
- `jido.messaging.agent.completed` - agent execution completed
- `jido.messaging.agent.failed` - agent execution failed
- `jido.messaging.instance.*` - instance lifecycle events

## Usage

To attach a telemetry handler:

    :telemetry.attach(
      "my-handler",
      [:jido_messaging, :message, :received],
      &MyHandler.handle_event/4,
      nil
    )

To subscribe to Jido.Signal events:

    Jido.Signal.Bus.subscribe(MyApp.Messaging.SignalBus, "jido.messaging.message.*")

## Standard Metadata Keys

All signals include a consistent set of metadata keys for correlation and tracing.
See `@metadata_keys` for the standard keys included in all events.

# `emit`

```elixir
@spec emit(atom(), module(), String.t(), map()) :: :ok
```

Generic emit function for room-level events.

Used by RoomServer to emit signals for various events like:
- `:presence_changed` - participant presence updated
- `:typing` - typing indicator changed
- `:reaction_added` - reaction added to message
- `:reaction_removed` - reaction removed from message
- `:message_delivered` - message marked as delivered
- `:message_read` - message marked as read
- `:thread_created` - thread created from message
- `:thread_reply_added` - reply added to thread

# `emit_agent`

```elixir
@spec emit_agent(atom(), module(), String.t(), String.t(), map()) :: :ok
```

Emits an agent lifecycle signal.

## Events
- `:triggered` - agent trigger condition matched
- `:started` - agent execution began
- `:completed` - agent execution finished successfully
- `:failed` - agent execution failed

# `emit_failed`

```elixir
@spec emit_failed(String.t(), term(), map()) :: :ok
```

Emits a `:failed` signal when message delivery has failed.

## Metadata
- `:room_id` - the room ID where delivery was attempted
- `:reason` - the failure reason
- `:channel` - the channel module used for delivery attempt
- `:external_room_id` - the external room identifier
- `:instance_module` - the messaging module
- `:bridge_id` - the bridge ID
- `:timestamp` - when the event occurred
- `:correlation_id` - message ID or generated ID for tracing

# `emit_instance`

```elixir
@spec emit_instance(atom(), module(), String.t(), map()) :: :ok
```

Emits an instance lifecycle signal.

## Events
- `:started` - instance started
- `:connecting` - instance connecting to external service
- `:connected` - instance connected
- `:disconnected` - instance disconnected
- `:stopped` - instance stopped
- `:error` - instance error

# `emit_received`

```elixir
@spec emit_received(Jido.Messaging.Message.t(), map()) :: :ok
```

Emits a `:received` signal when a message has been ingested.

## Metadata
- `:message` - the ingested `Jido.Messaging.Message` struct
- `:room_id` - the room ID where the message was received
- `:participant_id` - the sender's participant ID
- `:channel` - the channel module that received the message
- `:bridge_id` - the bridge ID of the channel
- `:instance_module` - the messaging module
- `:timestamp` - when the event occurred
- `:correlation_id` - message ID or generated ID for tracing

# `emit_sent`

```elixir
@spec emit_sent(Jido.Messaging.Message.t(), map()) :: :ok
```

Emits a `:sent` signal when a message has been delivered successfully.

## Metadata
- `:message` - the sent `Jido.Messaging.Message` struct
- `:room_id` - the room ID where the message was sent
- `:channel` - the channel module used for delivery
- `:external_room_id` - the external room identifier
- `:instance_module` - the messaging module
- `:bridge_id` - the bridge ID
- `:timestamp` - when the event occurred
- `:correlation_id` - message ID or generated ID for tracing

# `metadata_keys`

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

Returns the list of standard metadata keys included in all signals.

---

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