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
1 maintainer
Metadata
1 maintainer
Release files for kollabor-events 0.10.5
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | |
|---|---|---|---|
| kollabor_events-0.10.5.tar.gz | 25.8 kB | Details |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Reset |
|---|---|---|---|---|
| kollabor_events-0.10.5-py3-none-any.whl | Python 3 | none | any | Details |
Total release size: 55.9 kB
Release files / kollabor_events-0.10.5.tar.gz
| Download URL | kollabor_events-0.10.5.tar.gz |
|---|---|
| Size | 25.8 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
e1f2ef3e95c0322a3a9bdfa9ee53cf5832550c8266f445827cabcc444f484fb5
|
|
BLAKE2b-256 checksum How to use checksums |
8255f54b6a239112c97e1a3654a2bb9b24e74ffbce1e5d816fcda14179a49229
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/7.0.0 CPython/3.12.14
|
Release files / kollabor_events-0.10.5-py3-none-any.whl
| Download URL | kollabor_events-0.10.5-py3-none-any.whl |
|---|---|
| Size | 30.1 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
7b4074b1981c6f56a5a1c5ba52459c4e6b3557115ebb4d38b78d541fac29f2e1
|
|
BLAKE2b-256 checksum How to use checksums |
cef049e591d35fc2e40836415e276b38aab657f5ea017028bf636effff8e8280
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/7.0.0 CPython/3.12.14
|
