Hooks¶

HookEngine ¶

HookEngine()

Manages global and per-room hook registration and execution.

register(hook)

Register a global hook.

add_room_hook(room_id, hook)

Register a hook for a specific room.

remove_room_hook(room_id, name)

Remove a room hook by name.

run_sync_hooks(room_id, trigger, event, context)

Run sync hooks sequentially. Stops on block, passes modified events.

run_async_hooks(room_id, trigger, event, context)

Run async hooks concurrently. Errors are logged, never raised.

HookRegistration(trigger, execution, fn, priority=0, name='', timeout=30.0, channel_types=None, channel_ids=None, directions=None)

A registered hook function.

Attributes:

Name	Type	Description
`trigger`	`HookTrigger`	When the hook fires (BEFORE_BROADCAST, AFTER_BROADCAST, etc.)
`execution`	`HookExecution`	SYNC (can block/modify) or ASYNC (fire-and-forget)
`fn`	`SyncHookFn \| AsyncHookFn`	The hook function
`priority`	`int`	Lower numbers run first (default: 0)
`name`	`str`	Optional name for logging and removal
`timeout`	`float`	Max execution time in seconds (default: 30.0)
`channel_types`	`set[ChannelType] \| None`	Only run for events from these channel types (None = all)
`channel_ids`	`set[str] \| None`	Only run for events from these channel IDs (None = all)
`directions`	`set[ChannelDirection] \| None`	Only run for events with these directions (None = all)