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.

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.