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.10.1

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.10.1
File	Size	Uploaded
kollabor_events-0.10.1.tar.gz	25.8 kB	Sep 28, 2026	Details

Built distribution (wheel)

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

Total release size: 55.9 kB

Release files / kollabor_events-0.10.1.tar.gz

Download URL	kollabor_events-0.10.1.tar.gz
Size	25.8 kB
Tags	Source
SHA-256 checksum How to use checksums	`4c648e3f36828435f83fb43fd9ca26395e1df326f58c62e844a7a485ee87ef7b`
BLAKE2b-256 checksum How to use checksums	`ec162469274d3bd2b81f5d6d0e1418343f0cdb9c8544ae28198932767cf35013`
Upload date	Sep 28, 2026
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.1-py3-none-any.whl

Download URL	kollabor_events-0.10.1-py3-none-any.whl
Size	30.1 kB
Tags	Python 3
SHA-256 checksum How to use checksums	`63293690b1d52120bcb70c546e369b897ddd79aa530efd8237e6eb40294265f3`
BLAKE2b-256 checksum How to use checksums	`b9d2b8fc34e0aa29cd08c7c3fa335bcbfc949d9675a9a16d9284f27dbbe9ae07`
Upload date	Sep 28, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	No
Uploaded via	`twine/7.0.0 CPython/3.12.14`