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.15.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.15.0
File	Size	Uploaded
kollabor_events-0.15.0.tar.gz	26.0 kB	Oct 10, 2026	Details

Built distribution (wheel)

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

Total release size: 56.1 kB

Release files / kollabor_events-0.15.0.tar.gz

Download URL	kollabor_events-0.15.0.tar.gz
Size	26.0 kB
Tags	Source
SHA-256 checksum How to use checksums	`9fa9a80600fbee2f5497ce8b586cf3b53b8ab3004865f10fa3df404cfe44ff7f`
BLAKE2b-256 checksum How to use checksums	`f962c18e811ed084b4d115a77427f0dc260c00915b6338d2d1b1d0a70cf41d36`
Upload date	Oct 10, 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.15.0-py3-none-any.whl

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