> ## Documentation Index
> Fetch the complete documentation index at: https://codexceed.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# avatar.events

Lifecycle event emitter — observation only (§13).

Synchronous, fire-and-forget. Subscribers react to what happened; they can
*never* block or redirect the loop. `emit` returns `None` by design: there
is no value a caller could branch on. This is the deliberate, narrow line that
keeps control out of the emitter — permission and context are awaited control
hooks elsewhere, not subscribers here.

## Classes

### `Emitter`

Fans lifecycle events out to observation-only subscribers (§13).

Args:
session\_id: Stamped on every emitted event to group a run's events. A run is
one process invocation; in a future REPL it is the long-lived process, so
grouping is intentional rather than incidental. `None` omits the key.

```python theme={null}
Emitter(session_id: str | None = None) -> None
```

#### `Emitter.emit(self, event_type: str, **payload: object) -> None`

Build the event and deliver it to every subscriber, isolating failures.

Args:
event\_type: The event's `type` tag.
\*\*payload: Extra event fields merged after `type` and `ts`.

#### `Emitter.subscribe(self, subscriber: Callable[[dict[str, object]], None]) -> None`

Register a subscriber to receive every subsequent event.

Args:
subscriber: Callable invoked with each emitted event.