Metadata-Version: 2.4
Name: hummbl-bus
Version: 0.2.1
Summary: Secure append-only TSV coordination bus for multi-agent systems
Author-email: "HUMMBL, LLC" <dev@hummbl.io>
License: Apache-2.0
Project-URL: Homepage, https://github.com/hummbl-io/oss
Project-URL: Documentation, https://github.com/hummbl-io/oss/tree/main/packages/python/hummbl-bus/README.md
Project-URL: Repository, https://github.com/hummbl-io/oss
Project-URL: Issues, https://github.com/hummbl-io/oss/issues
Project-URL: PyPI, https://pypi.org/project/hummbl-bus/
Keywords: bus,coordination,multi-agent,append-only,tsv,hummbl,governance
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Requires-Python: >=3.11
Description-Content-Type: text/markdown
License-File: LICENSE
Provides-Extra: security
Requires-Dist: cryptography>=42.0; extra == "security"
Provides-Extra: test
Requires-Dist: pytest>=7.0; extra == "test"
Requires-Dist: coverage>=7.0; extra == "test"
Requires-Dist: cryptography>=42.0; extra == "test"
Requires-Dist: mypy>=1.8; extra == "test"
Dynamic: license-file

# hummbl-bus

Append-only TSV coordination bus for multi-agent systems.

[![Runtime Deps](https://img.shields.io/badge/runtime%20deps-zero-brightgreen)]()

**Tier:** 0 — Absolute Stdlib Only. Zero third-party runtime dependencies.

## What This Is

A lightweight, file-based message bus for coordinating multiple AI agents. Messages are appended to a TSV file with flock-based mutual exclusion, HMAC-SHA256 signing, and policy enforcement.

**Extraction status: IN PROGRESS** -- this repository contains the first standalone
bus extraction, but the HUMMBL internal workspace has newer bus modules that still need a drift
review before this package becomes the canonical implementation.

Latest drift snapshot:
[`docs/DRIFT_RECONCILIATION_2026-05-24.md`](docs/DRIFT_RECONCILIATION_2026-05-24.md).

## Features

- Append-only TSV message format (immutable audit trail)
- Flock-based mutual exclusion (safe concurrent writes)
- HMAC-SHA256 message signing and verification
- Bus policy enforcement (message type validation, identity validation)
- Bridge client/server for remote bus access (TCP)
- MCP server for tool-based bus interaction

## Message Format

```
timestamp_utc	from	to	type	message
2026-03-31T12:00:00Z	claude-code	*	STATUS	Health check passed
```

## Valid Message Types

PROPOSAL, ACK, STATUS, SITREP, BLOCKED, DECISION, QUESTION, MILESTONE, RECEIPT, COMPLETE, WIP_START, WIP_END, TASK_COMPLETE, HEARTBEAT, REVIEW

## Structure

```
src/
  hummbl_bus/
    bus_writer.py        # Core write path with file-lock mutex
    bus_manager.py       # Bus lifecycle management
    bus_policy.py        # Message type and identity validation
    bus_security.py      # Security enforcement
    bus_verifier.py      # Message integrity verification
    bus_integration.py   # Integration mixin for services
    message_signing.py   # HMAC-SHA256 signing
    secure_tsv.py        # Secure TSV read/write
    bridge_client.py     # Bridge client for remote bus
    bridge_server.py     # Bridge server for remote bus
    bridge_tcp_client.py # Legacy low-level TCP client
    mcp_server.py        # MCP tool interface
docs/
  protocol.md          # Bus protocol specification
  security-model.md    # Signing and verification
tests/
examples/
```

## Origin

Extracted from the HUMMBL internal workspace
`hummbl_governance/bus/`. The production HUMMBL internal bus is still the live integration
surface until this package has test coverage, drift reconciliation, and a migration
plan.

## License

MIT
