kollabor-events

kollabor-events is Kollabor's event bus and hook foundation.

It provides the shared event models, hook registry, hook executor, event processor, permission models, ready-message aggregation, and small utility helpers used by the CLI, plugins, engine, agent runtime, and TUI.

Current Role

Register and execute hooks for core and plugin-defined event types.
Order hook execution by priority and preserve hook status/error metadata.
Provide event, command, permission, and conversation data models.
Store cross-package services on the event bus for loose coupling.
Provide utility helpers for safe execution and nested dict access.

Architecture

Module	Responsibility
`bus.py`	`EventBus`, service registry, hook registration, event emission
`models.py`	event types, hooks, command definitions, UI models
`registry.py`	hook storage and enable/disable/status lookup
`executor.py`	hook execution, timeout/retry/error behavior
`processor.py`	event phase mapping and ordered processing
`hook_adapter.py`	sync/async hook compatibility
`permissions_models.py` / `permissions_config.py`	approval and risk models
`data_models.py`	conversation/session metadata models
`ready_message.py`	startup/ready message collection
`dict_utils.py` / `error_utils.py`	safe utility helpers

Hook Priorities

Priority	Value	Purpose
`SYSTEM`	`1000`	core lifecycle/system hooks
`SECURITY`	`900`	permission and policy hooks
`PREPROCESSING`	`500`	input/request transforms
`LLM`	`100`	LLM orchestration hooks
`POSTPROCESSING`	`50`	response/result transforms
`DISPLAY`	`10`	display/UI hooks

Usage

from kollabor_events import EventBus, EventType, Hook, HookPriority

bus = EventBus()


async def on_tool_pre(data, event):
    data["checked"] = True
    return data


await bus.register_hook(Hook(
    plugin_name="example",
    name="check_tool",
    event_type=EventType.TOOL_CALL_PRE,
    priority=HookPriority.SECURITY.value,
    callback=on_tool_pre,
))

result = await bus.emit_with_hooks(
    EventType.TOOL_CALL_PRE,
    {"tool_data": {"type": "terminal"}},
    source="example",
)

Known Gaps

The event model is broad and shared across many packages; event ownership and schema expectations should be documented closer to each event type.
String-based custom events are supported, but typed contracts are stronger for core events.
Hook error/timeout behavior is configurable, so callers should test important security and lifecycle hooks under failure conditions.

Roadmap

Phase 1: Event contract docs

Document core event payload schemas and expected mutation behavior.
Add examples for common hook categories: security, display, LLM, and plugins.
Link event types to the package that owns their primary behavior.

Phase 2: Safer extension points

Add optional typed payload helpers for high-risk events.
Expand tests for cancellation, timeout, retry, and hook ordering behavior.
Make plugin-defined event naming conventions explicit.

Phase 3: Observability

Improve hook status snapshots for diagnostics and UI display.
Add structured hook execution traces for debugging event-heavy flows.

Development

Targeted validation examples:

python -m py_compile packages/kollabor-events/src/kollabor_events/*.py
python -m pytest tests/unit/test_hub_native_param_compat.py -q

Dependencies

None. This package is intentionally stdlib-only.

License

MIT

Metadata

Release files for kollabor-events 0.14.0

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for kollabor-events 0.14.0
File	Size	Uploaded
kollabor_events-0.14.0.tar.gz	26.0 kB	Oct 9, 2026	Details

Built distribution (wheel)

Table of built distributions (wheels) for kollabor-events 0.14.0
File	Interpreter	ABI	Platform	Reset
kollabor_events-0.14.0-py3-none-any.whl 30.1 kB Oct 9, 2026	Python 3	none	any	Details

Total release size: 56.1 kB

Release files / kollabor_events-0.14.0.tar.gz

Download URL	kollabor_events-0.14.0.tar.gz
Size	26.0 kB
Tags	Source
SHA-256 checksum How to use checksums	`0882dea6816d1ac36d1b937bfd9392901c279fed19de3ae35b549e24b1a74965`
BLAKE2b-256 checksum How to use checksums	`aade63ac2486c2e7e395473c63cfbac3b342f24ac8e938737009fe22ff162fd0`
Upload date	Oct 9, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	No
Uploaded via	`twine/7.0.0 CPython/3.12.15`

Release files / kollabor_events-0.14.0-py3-none-any.whl

Download URL	kollabor_events-0.14.0-py3-none-any.whl
Size	30.1 kB
Tags	Python 3
SHA-256 checksum How to use checksums	`cdc00bbab04710c182cb447b0e1b6c84fd98119cc5e0e0a0f93138438bf0c8cb`
BLAKE2b-256 checksum How to use checksums	`a96c8cb175c486f1297ca4b5f744553bdc917435bc08e7ee67231aada4a10fa1`
Upload date	Oct 9, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	No
Uploaded via	`twine/7.0.0 CPython/3.12.15`