Metadata-Version: 2.4
Name: okf-agentbus
Version: 0.24.2
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: cryptography~=50.0
Requires-Dist: jsonschema>=4.0
Requires-Dist: mcp<3,>=2
Requires-Dist: pyyaml>=6.0
Requires-Dist: rfc8785==0.1.4
Requires-Dist: rich>=13.0
Requires-Dist: textual>=0.80
Provides-Extra: dev
Requires-Dist: ipython>=8.0; 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: jupyter
Requires-Dist: ipython>=8.0; extra == 'jupyter'
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)
[![PyPI](https://img.shields.io/pypi/v/okf-agentbus.svg)](https://pypi.org/project/okf-agentbus/)
[![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 Zero-Daemon, SQLite-Backed Event Bus & Visual Cockpit for Multi-Agent Coding.**

When Cursor, Claude Desktop, Antigravity, terminal bots (Hermes, Aider), and custom Python scripts work together in the same workspace, coordinating them usually devolves into messy, append-only `log.md` files or heavy cloud dashboards.

AgentBus gives your AI agents a fast, typed, local pub/sub highway backed by a single SQLite file (`.agentbus/events.db`) and gives *you* an interactive **God View Mission Control TUI** to watch every handoff, trace execution lineage, and approve dangerous actions in real time.

---

## ⚡ 30-Second Quickstart (The "Ah-Ha" Moment)

You don't need complex configurations or Docker daemons to see AgentBus in action.

### 1. Install

```bash
# Installs AgentBus, its isolated Python runtime, and verifies the CLI.
curl --proto '=https' --tlsv1.2 -LsSf https://raw.githubusercontent.com/onicarps/agentbus/main/install.sh | bash
```

The installer does not create a bus in whichever directory you happened to run
it from. It prints the direct command path for immediate use and adds its
command directory to new interactive shells (bash, zsh, and fish).

Create a project workspace and initialize your first agent:

```bash
mkdir -p ~/my-agent-workspace && cd ~/my-agent-workspace
~/.local/bin/agentbus init --apply --producer-id my-agent
```

*(Or via package manager in an existing environment: `pipx install okf-agentbus`
or `uv tool install okf-agentbus` — the interactive TUI monitor is bundled
out-of-the-box.)*

### 2. Launch the Visual Monitor (Terminal A)

```bash
~/.local/bin/agentbus monitor
```
*(Or use the standalone command: `agentbus-monitor`)*

You are now in the **God View TUI** dashboard:
* **Live Event Stream**: Watch real-time multi-agent activity as it occurs.
* **Trace Waterfall**: Inspect `trace_id` lineage and parent-span relationships.
* **HITL Approvals**: Review pending approvals with one-keystroke hotkeys (`[a]` approve / `[r]` reject).

### 3. Send Your First Message (Terminal B)

Open another terminal in the same folder and publish a handoff event:

```bash
~/.local/bin/agentbus publish \
  --topic okf/handoff \
  --producer-id my-agent \
  --payload '{"from":"my-agent","to":"reviewer","summary":"Added auth endpoints; please review and write tests."}'
```

👉 **Look back at Terminal A:** the event immediately pops up on your monitor!

---

## 🛠️ Why AgentBus?

| Approach | Limitations | How AgentBus Solves It |
|---|---|---|
| **Shared `log.md` file** | Race conditions, zero schemas, no delivery guarantees, unsearchable history | Typed topics, monotonic event IDs, SQLite transactional integrity, advisory file locks |
| **Cloud SaaS (e.g. LangSmith)** | Latency, cloud data egress, vendor lock-in, heavy setup for local development | 100% local SQLite storage, zero cloud egress by default, instant startup |
| **Heavy Brokers (Redis, Kafka)** | Background daemon requirements, port collisions, Docker overhead | Zero daemons: embedded SQLite sidecar per project directory (`.agentbus/events.db`) |
| **Framework Runtimes (LangGraph, CrewAI)** | Locked into a single Python runtime or process | Connects heterogeneous agents across IDEs (Cursor, Claude Desktop), CLI tools, and scripts via standard MCP and CLI |

---

## 📦 Fresh Boot & Installation Guide

AgentBus requires **Python 3.11+**. The one-command installer bootstraps an
isolated runtime automatically, including on a machine without Python. The God
View interactive monitor (`rich` + `textual`) is bundled with the base package.

### Option A: 1-Line Universal Installer (Recommended for fresh systems)

Handles fresh boots, non-root environments, and Linux PEP 668 (`externally-managed-environment`) automatically:

```bash
curl --proto '=https' --tlsv1.2 -LsSf https://raw.githubusercontent.com/onicarps/agentbus/main/install.sh | bash
```

### Option B: Standalone CLI Tool (pipx or uv)

If you prefer isolated CLI tools without creating project virtual environments:

```bash
# Using uv (fastest)
uv tool install okf-agentbus

# Using pipx
pipx install okf-agentbus
```

### Option C: In an existing virtual environment

If you have an active project virtual environment (`.venv`):

```bash
pip install -U okf-agentbus
```

> **💡 System Python:** On modern Linux (Ubuntu 24.04+, Debian 12+) and macOS
> Homebrew, system Python correctly rejects bare `pip install`. Use the
> one-command installer above, `uv tool install okf-agentbus`, or `pipx install
> okf-agentbus`; do not bypass the OS protection.

---

## 🔌 Connecting Your AI Coding Agents

AgentBus speaks standard **Model Context Protocol (MCP)** over stdio as well as standard CLI commands.

### 1-Click Auto-Configuration

Navigate to your project workspace and run:

```bash
agentbus init --apply --producer-id my-agent
```

For a fresh default workspace, `init` maps `my-agent` to the least-privileged
`engineer` role so its first `okf/handoff` publish works. It scans for installed
tools (Cursor, Claude Desktop, Antigravity) and automatically generates the
necessary MCP configuration without changing existing custom RBAC policies.

### Manual IDE Configurations

#### For Cursor (`~/.cursor/mcp.json` or `.cursor/mcp.json`)

```json
{
  "mcpServers": {
    "agentbus": {
      "command": "agentbus",
      "args": ["mcp-serve"],
      "env": {
        "AGENTBUS_WORKSPACE": "/path/to/your/project",
        "AGENTBUS_PRODUCER_ID": "cursor"
      }
    }
  }
}
```

#### For Claude Desktop (`claude_desktop_config.json`)

```json
{
  "mcpServers": {
    "agentbus": {
      "command": "agentbus",
      "args": ["mcp-serve"],
      "env": {
        "AGENTBUS_WORKSPACE": "/path/to/your/project",
        "AGENTBUS_PRODUCER_ID": "claude"
      }
    }
  }
}
```

Once connected, your AI agents will automatically see tools like:
* `agentbus_publish` — publish task updates, handoffs, and questions.
* `agentbus_poll` — check for incoming assignments.
* `agentbus_lock_acquire` / `agentbus_lock_release` — prevent file edit collisions.

---

## 💡 Practical Examples for Beginners & Intermediates

### Example 1: CLI Coordination (Zero Code)

Simulate two agents working together directly from the shell:

```bash
# Agent A publishes a completed task:
agentbus publish \
  --topic okf/handoff \
  --payload '{"from":"alice","to":"bob","summary":"Refactored database models"}'

# Agent B polls for new tasks:
agentbus poll --topic okf/handoff --since-id 0
```

### Example 2: Python Script (Publishing & Polling)

Integrate any custom Python agent or bot in 5 lines:

```python
from pathlib import Path
from agentbus.rbac import ensure_default_roles
from agentbus.store import EventStore

# Connect to current project workspace
workspace = Path.cwd()
ensure_default_roles(workspace)  # install the local role policy first
store = EventStore(workspace)

# Publish an event
event, _ = store.publish(
    topic="okf/handoff",
    producer_id="codex",
    schema_version="1.0",
    payload={"from": "codex", "to": "all", "summary": "Job completed successfully"},
)
print(f"Published event #{event.event_id}")

# Poll new events
messages = store.poll("okf/handoff", since_id=0)
for ev in messages["events"]:
    print(f"[{ev['event_id']}] {ev['payload']['summary']}")

store.close()
```

### Example 3: Human-in-the-Loop (HITL) Safety Intercepts

Catch dangerous AI operations (e.g. database migrations, shell scripts, deletions) before they execute:

```bash
# 1. Register an intercept rule: any handoff containing 'DROP' requires human approval
agentbus config set-intercept --topic okf/handoff --contains "DROP" --ttl-minutes 30

# 2. When an agent tries to publish:
agentbus publish \
  --topic okf/handoff \
  --payload '{"from":"agent","to":"db","summary":"DROP TABLE users"}'
# => Status becomes: PENDING_APPROVAL

# 3. View and approve/reject it in the TUI:
agentbus monitor
# Press [A] to approve or [R] to reject!
```

### Example 4: Preventing File Collisions with Advisory Locks

When multiple agents write code at the same time, they can accidentally overwrite each other. Use advisory leases:

```bash
# Agent 1 locks a file before editing:
agentbus lock acquire --resource src/models.py --owner-id agent-1 --ttl 300

# Agent 2 checks lock status:
agentbus lock status --resource src/models.py

# Agent 1 releases the lock when finished:
agentbus lock release --resource src/models.py --owner-id agent-1 --lease-id <LEASE_ID>
```

### Example 5: 1-Click Multi-Agent Swarm (`agentbus up`)

Instead of opening 5 terminal windows, orchestrate your agents, file watchers, and monitor together:

```bash
# 1. Generate default .agentbus/swarm.yaml
agentbus up --init

# 2. Start the swarm (daemons + God View monitor)
agentbus up

# 3. Check running background workers
agentbus ps

# 4. Tear down the swarm cleanly
agentbus down
```

---

## 📚 Complete Examples Catalog

Check out the **[`examples/`](examples/)** folder for fully isolated, executable Python scripts:

* **[`01_core_pub_sub.py`](examples/01_core_pub_sub.py)** — Fundamental publish and poll flow.
* **[`02_hitl_intercepts.py`](examples/02_hitl_intercepts.py)** — Catching sensitive payloads for human sign-off.
* **[`03_swarm_rbac.py`](examples/03_swarm_rbac.py)** — Swarm role-based topic permissions and identity tokens.
* **[`04_sla_timeouts.py`](examples/04_sla_timeouts.py)** — Automated dead-letter routing when an agent ghosts.
* **[`05_observability.py`](examples/05_observability.py)** — Distributed trace waterfall lineage (`trace_id`, `parent_span_id`).
* **[`06_distributed_context.py`](examples/06_distributed_context.py)** — Sharing large artifacts/diffs via content hashing.
* **[`07_pydantic_schemas.py`](examples/07_pydantic_schemas.py)** — Validating topic payloads with Pydantic models.
* **[`08_god_view.py`](examples/08_god_view.py)** — Passive OS filesystem, shell, and MCP call observation.
* **[`09_langgraph_bridge.py`](examples/09_langgraph_bridge.py)** — A LangGraph-node handoff skeleton.
* **[`10_crewai_bridge.py`](examples/10_crewai_bridge.py)** — A CrewAI-task handoff skeleton.

See the [Examples Guide](examples/README.md) for full documentation on each recipe.

---

## ⌨️ CLI Cheat Sheet

| Command | What it does |
|---|---|
| `agentbus monitor` | Launch the interactive God View TUI dashboard (`agentbus-monitor` also works) |
| `agentbus publish --topic <t> --payload '<json>'` | Publish an event to the local SQLite bus |
| `agentbus poll --topic <t> [--since-id <id>]` | Read published events from the bus |
| `agentbus init --apply --producer-id <id>` | Auto-discover MCP configs for Cursor/Claude/Antigravity |
| `agentbus doctor` | Run non-destructive diagnostic checks on SQLite, schema, and environment |
| `agentbus lock acquire --resource <path>` | Acquire an exclusive lease/lock on a file or resource |
| `agentbus lock release --resource <path>` | Release a previously held lease |
| `agentbus config set-intercept --topic <t>` | Create Human-in-the-Loop approval rules |
| `agentbus up` | Boot multi-agent swarm services declared in `swarm.yaml` |
| `agentbus ps` | View active swarm background services |
| `agentbus down` | Terminate all active swarm processes |

---

## 📖 Deep-Dive Documentation

* [End-to-End Walkthrough (Alice, Bob, & Charlie)](docs/WALKTHROUGH.md)
* [Model Context Protocol (MCP) Tool Schema](docs/MCP_SCHEMA.md)
* [AgentID Security Model & Identity System](docs/AGENTID.md)
* [Client Compatibility Matrix](docs/CLIENT_MATRIX.md)
* [PostHog Outbound Telemetry](docs/POSTHOG.md)
* [Release Runbook & Process](docs/RELEASE.md)
* [Roadmap](ROADMAP.md)

---

## 📄 License

MIT — see [LICENSE](LICENSE).
