Metadata-Version: 2.4
Name: okf-agentbus
Version: 0.9.0
Summary: SQLite-backed MCP event bus and control surface for heterogeneous agent orchestration.
Project-URL: Homepage, https://github.com/onicarps/agentbus
Project-URL: Repository, https://github.com/onicarps/agentbus
Project-URL: Issues, https://github.com/onicarps/agentbus/issues
Project-URL: Documentation, https://github.com/onicarps/agentbus/blob/main/docs/MCP_SCHEMA.md
Author: onicarps
License: MIT
License-File: LICENSE
Keywords: agents,event-log,mcp,multi-agent,orchestration
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Software Development :: Libraries
Requires-Python: >=3.11
Requires-Dist: click>=8.0
Requires-Dist: jsonschema>=4.0
Requires-Dist: mcp>=1.0
Requires-Dist: pyyaml>=6.0
Provides-Extra: dev
Requires-Dist: pytest-asyncio>=0.23; extra == 'dev'
Requires-Dist: pytest>=8.0; extra == 'dev'
Provides-Extra: devex
Requires-Dist: rich>=13.0; extra == 'devex'
Requires-Dist: textual>=0.80; extra == 'devex'
Provides-Extra: obs
Requires-Dist: psutil>=5.9; extra == 'obs'
Requires-Dist: watchdog>=4.0; extra == 'obs'
Provides-Extra: sdk
Requires-Dist: pydantic>=2.0; extra == 'sdk'
Description-Content-Type: text/markdown

# AgentBus

[![Test](https://github.com/onicarps/agentbus/actions/workflows/test.yml/badge.svg)](https://github.com/onicarps/agentbus/actions/workflows/test.yml)
[![Python](https://img.shields.io/pypi/pyversions/okf-agentbus.svg)](https://pypi.org/project/okf-agentbus/)
[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)

**The SQLite-Backed MCP Event Bus & Control Surface for Heterogeneous Agent Swarms.**

When Cursor, Claude, Antigravity, and Terminal Agents (like Hermes) share a workspace, they usually coordinate through fragile append-only files (`log.md`). That works until you need SLA timeouts, Human-in-the-Loop (HITL) intercepts, strict schema validation, or cryptographic RBAC.

AgentBus replaces the "Game of Telephone" with a **localhost sidecar**: a Python MCP server backed by SQLite. No orchestrator runtime lock-in. No heavy cloud dashboard. Just a hyper-fast local pub/sub built for top-tier AI orchestration.

> **v0.9.0 (July 2026):** **God View** observability mesh — MCP wiretap (`--wiretap`), OS watcher (`agentbus watch`), monologue tail (`agentbus tail`), and a Wiretap pane in the Mission Control TUI. Opt-in, 100% local.
>
> **Note:** Install as **`okf-agentbus`** (CLI command remains `agentbus`). For watchers: `pip install 'okf-agentbus[obs,devex]'`.

## ⚡ The "Ah-Ha" Moment: Zero-Restart Integration
Already running Aider, OpenHands, or custom agents in tmux panes? **Do not kill your sessions.**
AgentBus features a dual-interface architecture (MCP + CLI). You don't need to wire up JSON configs to test it today. Just prompt your running agent:
> *"Use your terminal to run `agentbus publish --topic okf/handoff --payload '{\"from\":\"grok\",\"to\":\"hermes\",\"summary\":\"Write tests\"}'`"*

The SQLite bus instantly captures it, without requiring the MCP server. Once you're convinced by the Mission Control TUI, you can wire up the strongly-typed MCP server for your next boot.

## Why AgentBus?

| Alternative | Limitation | AgentBus |
|-------------|------------|----------|
| `log.md` blackboard | No schema, race conditions | Typed topics, monotonic IDs, advisory locks |
| LangGraph / CrewAI | Same-runtime lock-in | Heterogeneous out-of-process clients (IDE + CLI) |
| LangSmith | Cloud-only, backward-looking | Local SQLite, forward-looking Execution TUI |
| Redis pub/sub | Extra daemon, complex setup | Zero-config SQLite, native stdio MCP |

## Feature Arsenal (v0.3 - v0.9)

*   **God View Mesh (v0.9):** Passive OS + MCP observability so silent agents still leave bus footprints (`system/mcp`, `system/fs`, `system/shell`, `system/monologue`).
*   **Mission Control TUI (v0.8+):** A rich, keyboard-driven `Textual` dashboard (`agentbus monitor`). Trace waterfall, HITL, Wiretap pane, Dark Agent warnings.
*   **Pluggable Pydantic Schemas (v0.7):** Code-first `@bus.topic` decorators to enforce strict JSON schemas at the insertion layer.
*   **Distributed Context (v0.6):** Pass massive context (like git diffs) via `--attach`. Hard 1MB payload limits prevent context window explosion.
*   **Agentic Observability (v0.5):** Native OpenTelemetry-style `trace_id` and `parent_span_id` lineage.
*   **SLA Timeouts & Dead-Letter (v0.4):** Prevent phantom deadlocks. If an agent ghosts the swarm, SLA timers route the payload to `okf/dead-letter`.
*   **Swarm RBAC & Droid Proofs (v0.3):** Cryptographic JWT/UUID tokens ensure only authorized agents can publish to restricted topics.
*   **HITL Intercepts (v0.3):** Catch dangerous payloads (e.g., `DROP TABLE`) and place them in `PENDING_APPROVAL` for human review via the TUI.

## Install

**The fastest way (Installs & Auto-wires your IDEs in one step):**
```bash
curl -sSL https://raw.githubusercontent.com/onicarps/agentbus/main/install.sh | bash
```

**Or manually via pip:**
```bash
pip install -U "okf-agentbus[devex,sdk]"
agentbus init --apply --producer-id my-agent
```

## Quickstart & Examples

The best way to understand AgentBus is to read our copy-pasteable examples. 

See the **[`examples/`](examples/)** directory for 7 flawless, isolated Python scripts covering every feature from basic Pub/Sub to Pydantic Schemas and SLA Timeouts.

```bash
# Terminal A — Launch the Mission Control TUI
agentbus monitor

# Terminal B — Publish a handoff
agentbus publish \
  --topic okf/handoff \
  --payload '{"from":"cursor","to":"hermes","summary":"Write tests"}'
```

**God View Observability (v0.9.0):**
Track silent agents by wiretapping their operations:
```bash
# Intercept MCP tool calls
mcp-serve --wiretap

# Watch file edits and command executions
agentbus watch

# Tail internal agent reasoning logs
agentbus tail
```
Events will stream into the TUI's Wiretap pane as `system/mcp`, `system/fs`, `system/shell`, and `system/monologue` topics.


## Documentation

For full architectural documentation, see the `docs/` directory.

## License

MIT — see [LICENSE](LICENSE).