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

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

kollabor_events-0.5.22.tar.gz (25.8 kB view details)

Uploaded Jul 21, 2026 Source

Built Distribution

If you're not sure about the file name format, learn more about wheel file names.

The dropdown lists show the available interpreters, ABIs, and platforms. Enable javascript to be able to filter the list of wheel files.

kollabor_events-0.5.22-py3-none-any.whl (30.1 kB view details)

Uploaded Jul 21, 2026 Python 3

File details

Details for the file kollabor_events-0.5.22.tar.gz.

File metadata

Download URL: kollabor_events-0.5.22.tar.gz
Upload date: Jul 21, 2026
Size: 25.8 kB
Tags: Source
Uploaded using Trusted Publishing? No
Uploaded via: twine/6.2.0 CPython/3.12.13

File hashes

Hashes for kollabor_events-0.5.22.tar.gz
Algorithm	Hash digest
SHA256	`4219915b00f340fbbd4a17c610436adb7cc3d46cf803716cd0d7c97b648e47af`
MD5	`281d986cf9d27b03006e790894910871`
BLAKE2b-256	`83dbd1ca66285d29f571bab5d3327e3ee6ea820427bb99f1b00a48d55f09f796`

See more details on using hashes here.

File details

Details for the file kollabor_events-0.5.22-py3-none-any.whl.

File metadata

Download URL: kollabor_events-0.5.22-py3-none-any.whl
Upload date: Jul 21, 2026
Size: 30.1 kB
Tags: Python 3
Uploaded using Trusted Publishing? No
Uploaded via: twine/6.2.0 CPython/3.12.13

File hashes

Hashes for kollabor_events-0.5.22-py3-none-any.whl
Algorithm	Hash digest
SHA256	`9d9db840373aa3f50bb58e8a1c45aba3d43635956d5c08bc7235d897b9cf0990`
MD5	`15b44d61bc92eec674474d02382c3a65`
BLAKE2b-256	`65a3120a2dcaa9ff7d3976f0c8b8006651791fcacbf393b581231c6480486d23`