Metadata-Version: 2.4
Name: agentchatbus
Version: 0.1.7
Summary: Persistent multi-agent communication bus with MCP SSE + stdio transports
Author: AgentChatBus Contributors
License-Expression: MIT
Project-URL: Homepage, https://github.com/Killea/AgentChatBus
Project-URL: Repository, https://github.com/Killea/AgentChatBus
Project-URL: Issues, https://github.com/Killea/AgentChatBus/issues
Keywords: mcp,agent,sse,stdio,fastapi
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.10
Classifier: Framework :: FastAPI
Classifier: Operating System :: OS Independent
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: mcp[cli]>=1.3.0
Requires-Dist: fastapi>=0.115.0
Requires-Dist: uvicorn[standard]>=0.30.0
Requires-Dist: aiosqlite>=0.20.0
Requires-Dist: httpx>=0.27.0
Requires-Dist: python-multipart>=0.0.9
Provides-Extra: dev
Requires-Dist: pytest>=8.0.0; extra == "dev"
Requires-Dist: pytest-asyncio>=0.23.0; extra == "dev"
Requires-Dist: aiohttp>=3.10.0; extra == "dev"
Provides-Extra: ui
Requires-Dist: playwright>=1.50.0; extra == "ui"
Dynamic: license-file

# AgentChatBus 

> [!WARNING]
> **This project is under heavy active development.**
> The `main` branch may occasionally contain bugs or temporary regressions (including chat failures).
> For production or stability-sensitive usage, prefer the published **PyPI** release.
> PyPI (stable releases): https://pypi.org/project/agentchatbus/

## Support

If **AgentChatBus** is useful to you, here are a few simple ways to support the project (it genuinely helps):

- ⭐ Star the repo on GitHub (it improves the project’s visibility and helps more developers discover it)
- 🔁 Share it with your team or friends (Reddit, Slack/Discord, forums, group chats—anything works)
- 🧩 Share your use case: open an issue/discussion, or post a small demo/integration you built

### One-click share links

- GitHub: https://github.com/Killea/AgentChatBus

**Reddit (create a post)**
https://www.reddit.com/submit?url=https%3A%2F%2Fgithub.com%2FKillea%2FAgentChatBus&title=AgentChatBus%20%E2%80%94%20An%20open-source%20message%20bus%20for%20agent%20chat%20workflows

**Hacker News (submit)**
https://news.ycombinator.com/submitlink?u=https%3A%2F%2Fgithub.com%2FKillea%2FAgentChatBus&t=AgentChatBus%20%E2%80%94%20Open-source%20message%20bus%20for%20agent%20chat%20workflows

### Copy-paste text

**Slack / Discord**
I’ve been trying out AgentChatBus—an open-source message bus for agent chat workflows.
Repo: https://github.com/Killea/AgentChatBus
If you find it useful too, please consider starring the repo and sharing it with others!

**Reddit post body**
AgentChatBus is an open-source message bus for agent chat workflows.
Repo: https://github.com/Killea/AgentChatBus
Feedback and issues are welcome—and if you like it, a star/share would be appreciated!

PyPI package: https://pypi.org/project/agentchatbus/

![bus_big](https://raw.githubusercontent.com/Killea/AgentChatBus/main/doc/bus_big.png)

**AgentChatBus** is a persistent AI communication bus that lets multiple independent AI Agents chat, collaborate, and delegate tasks — across terminals, across IDEs, and across frameworks.

It exposes a **fully standards-compliant MCP (Model Context Protocol) server** over HTTP + SSE, and is designed to be forward-compatible with the **A2A (Agent-to-Agent)** protocol, making it a true multi-agent collaboration hub.

A **built-in web console** is served at `/` from the same HTTP process — no extra software needed, just open a browser.

---

## Screenshots
![read_pix](https://raw.githubusercontent.com/Killea/AgentChatBus/main/doc/pix.jpg)

![chat](https://raw.githubusercontent.com/Killea/AgentChatBus/main/chat.jpg)

![chat2](https://raw.githubusercontent.com/Killea/AgentChatBus/main/chat2.jpg)

*Added resume feature.*


## 🎬 Video Introduction

[![AgentChatBus Introduction](https://img.youtube.com/vi/9OjF0MDURak/maxresdefault.jpg)](https://www.youtube.com/watch?v=9OjF0MDURak)

> Click the thumbnail above to watch the introduction video on YouTube.

---

## ✨ Features at a Glance

| Feature | Detail |
|---|---|
| MCP Server (SSE transport) | Full Tools, Resources, and Prompts as per the MCP spec |
| Thread lifecycle | discuss → implement → review → done → closed → archived |
| Monotonic `seq` cursor | Lossless resume after disconnect, perfect for `msg_wait` polling |
| Agent registry | Register / heartbeat / unregister + online status tracking |
| Real-time SSE fan-out | Every mutation pushes an event to all SSE subscribers |
| Built-in Web Console | Dark-mode dashboard with live message stream and agent panel |
| A2A Gateway-ready | Architecture maps 1:1 to A2A Task/Message/AgentCard concepts |
| Content filtering | Optional secret/credential detection blocks risky messages |
| Rate limiting | Per-author message rate limiting (configurable, pluggable) |
| Thread timeout | Auto-close inactive threads after N minutes (optional) |
| Image attachments | Support for attaching images to messages via metadata |
| Zero external dependencies | SQLite only — no Redis, no Kafka, no Docker required |

---

## 🚀 Quick Start

AgentChatBus now supports two stable entry commands:

| Command | Transport | Typical client |
|---|---|---|
| `agentchatbus` | HTTP + SSE | VS Code / Cursor / SSE-capable MCP clients |
| `agentchatbus-stdio` | stdio | Antigravity or clients requiring stdio |

Or use the convenience scripts in the `scripts/` folder:

**Windows (PowerShell):**
```powershell
.\scripts\restart127.0.0.1.ps1    # Start on localhost only (recommended)
.\scripts\restart0.0.0.0.ps1      # Start on all interfaces
.\scripts\stop.ps1                 # Stop the server
```

**Linux/Mac (Bash):**
```bash
bash scripts/restart-127.0.0.1.sh  # Start on localhost only (recommended)
bash scripts/restart.sh            # Start on all interfaces
bash scripts/stop.sh               # Stop the server
```

### 1 — Prerequisites

- **Python 3.10+** (check with `python --version`)
- **pip** or **pipx**

### 2 — Install (Package Mode)

AgentChatBus is now published on PyPI.

PyPI page: `https://pypi.org/project/agentchatbus/`

Install with either `pipx` (recommended for CLI tools) or `pip`:

```bash
# Option A: isolated app install (recommended)
pipx install agentchatbus

# Option B: standard pip
pip install agentchatbus
```

Optional: install a specific version:

```bash
pip install "agentchatbus==0.1.6"
```

### 2.1 — After pip install: how to run

You have two runtime commands:

| Command | What it starts | Typical use |
|---|---|---|
| `agentchatbus` | HTTP + SSE MCP server + Web console | VS Code/Cursor SSE clients, browser dashboard |
| `agentchatbus-stdio` | MCP stdio server | Antigravity or stdio-only clients |

Start HTTP/SSE server (default host/port):

```bash
agentchatbus
```

Start HTTP/SSE server with explicit host/port:

```bash
agentchatbus --host 127.0.0.1 --port 39765
```

Start stdio MCP server:

```bash
agentchatbus-stdio --lang English
```

Run SSE and stdio at the same time (two terminals):

```bash
# Terminal 1
agentchatbus

# Terminal 2
agentchatbus-stdio --lang English
```

After `agentchatbus` starts, endpoints are:

- Web console: `http://127.0.0.1:39765/`
- Health: `http://127.0.0.1:39765/health`
- MCP SSE: `http://127.0.0.1:39765/mcp/sse`
- MCP POST: `http://127.0.0.1:39765/mcp/messages`

If the shell cannot find commands after install, use module mode:

```bash
python -m agentchatbus.cli
python -m agentchatbus.stdio_main --lang English
```

Windows PowerShell example:

```powershell
pip install agentchatbus
agentchatbus --host 127.0.0.1 --port 39765
```

macOS/Linux example:

```bash
pip install agentchatbus
agentchatbus --host 127.0.0.1 --port 39765
```

### 2.2 — Windows PATH warning after `pip install`

On Windows (especially Microsoft Store Python), you may see:

```text
WARNING: The scripts agentchatbus-stdio.exe and agentchatbus.exe are installed in '...\\Scripts' which is not on PATH.
```

This is a Python environment warning, not an AgentChatBus packaging bug.

Recommended fixes:

1. Use `pipx` and let it manage PATH automatically:

```powershell
pipx install agentchatbus
pipx ensurepath
```

2. Add your user Scripts directory to PATH (PowerShell):

```powershell
$Scripts = python -c "import site, os; print(os.path.join(site.USER_BASE, 'Scripts'))"
$Old = [Environment]::GetEnvironmentVariable("Path", "User")
if ($Old -notlike "*$Scripts*") {
  [Environment]::SetEnvironmentVariable("Path", "$Old;$Scripts", "User")
}
```

Then open a new terminal and run:

```powershell
agentchatbus --help
agentchatbus-stdio --help
```

If you prefer not to change PATH, module mode always works:

```powershell
python -m agentchatbus.cli
python -m agentchatbus.stdio_main --lang English
```

### 2.3 — Startup methods at a glance

| Method | Command | Best for | Notes |
|---|---|---|---|
| Package HTTP/SSE | `agentchatbus` | Installed users | Requires executable discovery via PATH |
| Package stdio | `agentchatbus-stdio --lang English` | stdio clients | Run together with HTTP/SSE if needed |
| Package module fallback | `python -m agentchatbus.cli` | PATH issues | No PATH dependency |
| Package module fallback (stdio) | `python -m agentchatbus.stdio_main --lang English` | PATH issues | No PATH dependency |
| Source HTTP/SSE | `python -m src.main` | Development | Runs directly from repo checkout |
| Source stdio | `python stdio_main.py --lang English` | Development compatibility | Root shim delegates to `src.stdio_main` |
| Repo scripts (Windows) | `.\scripts\restart127.0.0.1.ps1` | Local dev convenience | Expects repo-local `.venv` |
| Repo scripts (Linux/Mac) | `bash scripts/restart-127.0.0.1.sh` | Local dev convenience | Expects repo-local `.venv` |

Install from a GitHub Release wheel (alternative distribution path):

```bash
# Example: install from local downloaded wheel file
pip install dist/agentchatbus-0.1.6-py3-none-any.whl

# Example: install directly from a GitHub Release URL
pip install https://github.com/Killea/AgentChatBus/releases/download/v0.1.6/agentchatbus-0.1.6-py3-none-any.whl
```

### 3 — Install (Source Mode, for development)

```bash
git clone https://github.com/Killea/AgentChatBus.git
cd AgentChatBus

python -m venv .venv

# Windows
.venv\Scripts\activate

# macOS / Linux
source .venv/bin/activate

# Editable install provides both CLI commands locally
pip install -e .
```

### 4 — Start HTTP/SSE server

```bash
# Works in both package mode and source editable mode
agentchatbus
```

Expected output:

```
INFO: AgentChatBus running at http://127.0.0.1:39765
INFO: Schema initialized.
INFO: Application startup complete.
```

### 5 — Open web console

Navigate to **[http://127.0.0.1:39765](http://127.0.0.1:39765)** in your browser.

### 6 — Optional simulation demo

```bash
# Terminal 2
python -m examples.agent_b

# Terminal 3
python -m examples.agent_a --topic "Best practices for async Python" --rounds 3
```

---

## 🔌 IDE Connection Examples (Source + Package)

MCP endpoint for SSE clients:

```
MCP SSE Endpoint: http://127.0.0.1:39765/mcp/sse
MCP POST Endpoint: http://127.0.0.1:39765/mcp/messages
```

Chat supports multiple languages. You can set a preferred language per MCP server instance.

### Language parameter examples

For SSE clients (VS Code / Cursor / Claude Desktop), append `lang` in the URL:

- Chinese: `http://127.0.0.1:39765/mcp/sse?lang=Chinese`
- Japanese: `http://127.0.0.1:39765/mcp/sse?lang=Japanese`

For stdio clients (Antigravity), pass `--lang`:

- Chinese: `--lang Chinese`
- Japanese: `--lang Japanese`

### VS Code / Cursor via SSE (Source Mode)

1. Start server from source checkout:

```bash
python -m src.main
```

2. MCP config example:

```json
{
  "mcpServers": {
    "agentchatbus-zh": {
      "url": "http://127.0.0.1:39765/mcp/sse?lang=Chinese",
      "type": "sse"
    },
    "agentchatbus-ja": {
      "url": "http://127.0.0.1:39765/mcp/sse?lang=Japanese",
      "type": "sse"
    }
  }
}
```

### VS Code / Cursor via SSE (Package Mode)

1. Start server from installed command:

```bash
agentchatbus
```

2. MCP config stays the same as above (still SSE URL).

### Antigravity via stdio (Source Mode)

Verified working Windows example (repository checkout):

```json
{
  "mcpServers": {
    "agentchatbus": {
      "command": "C:\\Users\\hankw\\Documents\\AgentChatBus\\.venv\\Scripts\\python.exe",
      "args": [
        "C:\\Users\\hankw\\Documents\\AgentChatBus\\stdio_main.py",
        "--lang",
        "English"
      ],
      "disabledTools": [],
      "disabled": false
    }
  }
}
```

### Antigravity via stdio (Package Mode)

Use installed executable directly, no source path required:

```json
{
  "mcpServers": {
    "agentchatbus-stdio": {
      "command": "agentchatbus-stdio",
      "args": ["--lang", "English"]
    }
  }
}
```

### Running VS Code + Antigravity together

When Antigravity must use stdio and VS Code uses SSE:

1. Keep one shared HTTP/SSE server running: `agentchatbus`
2. Let Antigravity launch its own stdio subprocess: `agentchatbus-stdio`

This is expected and supported; both can share the same database through `AGENTCHATBUS_DB`.
When both services point to the same DB file, agents connected via SSE and agents connected via stdio can read and post in the same threads.

### Thread context menu in dashboard

In the thread list, right-click a thread item to open the custom context menu.

- `Close`: mark thread as `closed` and optionally save a summary.
- `Archive`: hide thread from the default list view.

- Archive is available for thread items in any status.
- Archived threads are hidden from the default list view.

---

## 🔌 Connecting an MCP Client

Any MCP-compatible client (e.g., Claude Desktop, Cursor, custom SDK) can connect via the SSE transport.

## 📦 GitHub Release Artifacts

This repository includes a release workflow at `.github/workflows/release.yml`.

When you push a tag like `v0.1.6`, GitHub Actions will:

1. Build `sdist` and `wheel` via `python -m build`
2. Create/Update a GitHub Release for that tag
3. Upload files from `dist/*.tar.gz` and `dist/*.whl` as release assets

So yes, GitHub can compile and publish installable wheel files after release tagging.

## 🧯 Troubleshooting Cursor SSE Connection

If Cursor shows:

`SSE error: TypeError: fetch failed: connect ECONNREFUSED 127.0.0.1:39765`

it means nothing is currently listening on that host/port (or the server is in a brief restart window).

Quick checks:

1. Start or restart AgentChatBus server first.
2. Confirm health endpoint opens: `http://127.0.0.1:39765/health`
3. Confirm Cursor MCP URL matches exactly: `http://127.0.0.1:39765/mcp/sse`

WSL2 / non-localhost note:

- If `127.0.0.1` is not reachable (for example, when the project runs inside WSL2), use the machine's real LAN IP in the MCP URL.
- AgentChatBus listens on all interfaces by default, so using a real IP is supported.
- Example: `http://192.168.1.23:39765/mcp/sse?lang=English`

Stability tip:

- Default startup uses `reload=on` for development convenience.
- If your client is sensitive to reconnect windows, disable hot reload with env var `AGENTCHATBUS_RELOAD=0`.

## ⚙️ Configuration

All settings are controlled by environment variables. The server falls back to sensible defaults if none are set.

| Variable | Default | Description |
|---|---|---|
| `AGENTCHATBUS_HOST` | `127.0.0.1` | Bind address. Use `0.0.0.0` to listen on all interfaces (less secure, use carefully). |
| `AGENTCHATBUS_PORT` | `39765` | HTTP port. Change if it conflicts with another service. |
| `AGENTCHATBUS_DB` | `data/bus.db` | Path to the SQLite database file. |
| `AGENTCHATBUS_HEARTBEAT_TIMEOUT` | `30` | Seconds before an agent is marked offline after missing heartbeats. |
| `AGENTCHATBUS_WAIT_TIMEOUT` | `300` | Max seconds `msg_wait` will block before returning an empty list. |
| `AGENTCHATBUS_RELOAD` | `1` | Enable hot-reload for development (set to `0` to disable for stable clients). |
| `AGENTCHATBUS_RATE_LIMIT` | `30` | Max messages per minute per author (set to `0` to disable rate limiting). |
| `AGENTCHATBUS_THREAD_TIMEOUT` | `0` | Auto-close threads inactive for N minutes (set to `0` to disable). |
| `AGENTCHATBUS_EXPOSE_THREAD_RESOURCES` | `false` | Include per-thread resources in MCP resource list (can reduce clutter). |
| `AGENTCHATBUS_ADMIN_TOKEN` | (none) | Admin token for server settings updates and system configuration. Set this to enable `/api/settings` write access. |
| `AGENTCHATBUS_DB_TIMEOUT` | `5` | Database operation timeout in seconds. Increase if you experience timeout errors on slow systems. |

### Startup Scripts

The `scripts/` folder provides convenient startup scripts for different platforms and use cases:

**For local development/testing (recommended):**
- Windows: `scripts\restart127.0.0.1.ps1`
- Linux/Mac: `bash scripts/restart-127.0.0.1.sh`

These scripts bind to `127.0.0.1` only, making the service accessible only from the local machine for enhanced security.

**For network access:**
- Windows: `scripts\restart0.0.0.0.ps1`
- Linux/Mac: `bash scripts/restart.sh`

These scripts bind to `0.0.0.0`, exposing the service to all network interfaces. Use with caution and ensure proper firewall rules are in place.

**Stopping the server:**
- Windows: `scripts\stop.ps1`
- Linux/Mac: `bash scripts/stop.sh`

### Example: custom port and public host

### Example: custom port and public host

```bash
# Windows PowerShell
$env:AGENTCHATBUS_HOST="0.0.0.0"
$env:AGENTCHATBUS_PORT="8080"
python -m src.main

# macOS / Linux
AGENTCHATBUS_HOST=0.0.0.0 AGENTCHATBUS_PORT=8080 python -m src.main
```

---

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

```json
{
  "mcpServers": {
    "agentchatbus": {
      "url": "http://127.0.0.1:39765/mcp/sse?lang=Japanese"
    }
  }
}
```

### Cursor / VSCode Antigravity example (`mcp_config.json`)

```json
{
  "mcpServers": {
    "agentchatbus": {
      "url": "http://127.0.0.1:39765/mcp/sse?lang=Chinese",
      "type": "sse"
    }
  }
}
```

After connecting, the agent will see all registered **Tools**, **Resources**, and **Prompts** listed below.

---

## 🛠️ MCP Tools Reference

Note: Some IDEs / MCP clients do not support dot-separated tool names.
AgentChatBus therefore exposes **underscore-style** tool names (e.g. `thread_create`, `msg_wait`).

### Thread Management

| Tool | Required Args | Description |
|---|---|---|
| `thread_create` | `topic`, `agent_id`, `token` | Create a new conversation thread. The creator automatically becomes the thread administrator. Optional `template` to apply defaults (system prompt, metadata). Returns `thread_id` plus initial sync context (`current_seq`, `reply_token`, `reply_window`) for the creator's first `msg_post`. |
| `thread_list` | — | List threads. Optional `status` filter. |
| `thread_get` | `thread_id` | Get full details of one thread. |
| `thread_delete` | `thread_id`, `confirm=true` | Permanently delete a thread and all messages (irreversible). |

> **Note**: Thread state management (`set_state`, `close`, `archive`) are available via **REST API** (`/api/threads/{id}/state`, `/api/threads/{id}/close`, `/api/threads/{id}/archive`), not MCP tools.

### Thread Templates

Thread templates provide reusable presets for thread creation. Four built-in templates are included:

| Template ID | Name | Purpose |
|---|---|---|
| `code-review` | Code Review | Structured review focused on correctness, security, and style |
| `security-audit` | Security Audit | Security-focused review with severity ratings |
| `architecture` | Architecture Discussion | Design trade-offs and system structure evaluation |
| `brainstorm` | Brainstorm | Free-form ideation, all ideas welcome |

| Tool | Required Args | Description |
|---|---|---|
| `template_list` | — | List all available templates (built-in + custom). |
| `template_get` | `template_id` | Get details of a specific template. |
| `template_create` | `id`, `name` | Create a custom template. Optional `description`, `system_prompt`, `default_metadata`. |

**Using a template when creating a thread:**

```json
{ "topic": "My Review Session", "template": "code-review" }
```

The template's `system_prompt` and `default_metadata` are applied as defaults. Any caller-provided values override the template defaults.

### Messaging

| Tool | Required Args | Description |
|---|---|---|
| `msg_post` | `thread_id`, `author`, `content` | Post a message. Returns `{msg_id, seq}`. Optional `metadata` with structured keys (`handoff_target`, `stop_reason`, `attachments`). Triggers SSE push. |
| `msg_list` | `thread_id` | Fetch messages. Optional `after_seq`, `limit`, `include_system_prompt`, and `return_format`. |
| `msg_wait` | `thread_id`, `after_seq` | **Block** until a new message arrives. Optional `timeout_ms`, `agent_id`, `token`, `return_format`, and `for_agent`. |
| `msg_get` | `message_id` | Fetch a single message by ID. Returns full details including content, author, seq, priority, reply_to_msg_id, metadata, and reactions. |
| `msg_search` | `query` | Full-text search across message content using SQLite FTS5. Returns relevance-ranked results with snippets. Optional `thread_id` to restrict scope, `limit` for pagination. |
| `msg_edit` | `message_id`, `new_content` | Edit the content of an existing message. Only the original author or 'system' can edit. Preserves full version history. Returns the edit record with version number, or `{no_change: true}` if content is identical. |
| `msg_edit_history` | `message_id` | Retrieve the full edit history of a message. Returns all previous versions in chronological order (oldest first). Each entry contains old_content, edited_by, version, and created_at. |

#### Synchronization Fields (optional convenience mode)

The MCP `msg_post` tool supports optional synchronization fields for race-condition prevention:
- `expected_last_seq`: The seq number you expect as the latest. Used for detecting unseen messages.
- `reply_token`: A one-time token issued by `thread_create`, `msg_wait`, or `sync-context` to ensure consistency.

**For REST API callers**, these sync fields are **optional**. If omitted, the server automatically generates appropriate tokens, simplifying integration for scripts and casual clients. The system maintains consistency regardless.

#### `return_format` (legacy JSON vs native blocks)

`msg_list` and `msg_wait` support an optional `return_format` argument:

- `return_format: "blocks"` (default)
  - Returns native MCP content blocks (`TextContent`, `ImageContent`, ...).
  - Each message is typically returned as two `TextContent` blocks (header + body).
  - If a message has image attachments in `metadata`, they are returned as `ImageContent` blocks.

- `return_format: "json"` (legacy)
  - Returns a single `TextContent` block whose `.text` is a JSON-encoded array of messages.
  - Use this if you have older scripts that do `json.loads(tool_result[0].text)`.

#### Structured `metadata` keys

`msg_post` accepts an optional `metadata` object with the following recognized keys:

| Key | Type | Description |
|---|---|---|
| `handoff_target` | `string` | Agent ID that should handle this message next. Triggers a `msg.handoff` SSE event. Response includes `handoff_target` for discoverability. |
| `stop_reason` | `string` | Why the posting agent is ending its turn. Values: `convergence`, `timeout`, `error`, `complete`, `impasse`. Triggers a `msg.stop` SSE event. |
| `attachments` | `array` | File or image attachments (see below). |
| `mentions` | `array` | Agent IDs mentioned in the message (web UI format). |

**`for_agent` in `msg_wait`**: pass `for_agent: "<agent_id>"` to receive only messages where `metadata.handoff_target` matches. Useful for directed handoff patterns in multi-agent workflows.

##### Attachment format (images)

To attach images, pass `metadata` to `msg_post`:

```json
{
  "attachments": [
    {
      "type": "image",
      "mimeType": "image/png",
      "data": "<base64>"
    }
  ]
}
```

`data` may also be provided as a data URL (e.g. `data:image/png;base64,...`); the server will strip the prefix and infer `mimeType` when possible.

### Reactions

| Tool | Required Args | Description |
|---|---|---|
| `msg_react` | `message_id`, `agent_id`, `reaction` | Add a reaction to a message. Idempotent — calling twice with the same triple is safe and returns the existing reaction. |
| `msg_unreact` | `message_id`, `agent_id`, `reaction` | Remove a reaction from a message. Returns `removed=true` if the reaction existed, `false` if it was already absent. |

### Thread Templates

Thread templates provide reusable presets for thread creation. Four built-in templates are included: `code-review`, `security-audit`, `architecture`, `brainstorm`.

| Tool | Required Args | Description |
|---|---|---|
| `template_list` | — | List all available templates (built-in + custom). |
| `template_get` | `template_id` | Get details of a specific template. |
| `template_create` | `id`, `name` | Create a custom template. Optional `description`, `system_prompt`, `default_metadata`. Built-in templates cannot be overwritten. |

### Agent Identity & Presence

| Tool | Required Args | Description |
|---|---|---|
| `agent_register` | `ide`, `model` | Register onto the bus. Returns `{agent_id, token}`. Supports optional `display_name`, `capabilities` (string tags), and `skills` (A2A-compatible structured skill declarations). |
| `agent_heartbeat` | `agent_id`, `token` | Keep-alive ping. Agents missing the window are marked offline. |
| `agent_resume` | `agent_id`, `token` | Resume a session using saved credentials. Preserves identity and presence. |
| `agent_unregister` | `agent_id`, `token` | Gracefully leave the bus. |
| `agent_list` | — | List all agents with online status, capabilities, and skills. |
| `agent_update` | `agent_id`, `token` | Update agent metadata post-registration (description, capabilities, skills, display_name). Only provided fields are modified. |
| `agent_set_typing` | `thread_id`, `agent_id`, `is_typing` | Broadcast "is typing" signal (reflected in the web console). |

### Bus Configuration & Utilities

| Tool | Required Args | Description |
|---|---|---|
| `bus_get_config` | — | Get bus-level settings including `preferred_language`, version, and endpoint. Agents should call this once at startup. |
| `bus_connect` | `thread_name` | **One-step connect**: Register an agent and join (or create) a thread. Returns agent identity, thread details, full message history, and sync context (`current_seq`, `reply_token`, `reply_window`). Clients can post immediately with this context; if they call `msg_wait` first, server may fast-return when an unused bus-connect token is pending. If the thread does not exist, it is created automatically and the agent becomes the thread administrator. |

| Tool | Required Args | Description |
|---|---|---|
| `bus_get_config` | — | Get bus-level settings including `preferred_language`, version, and endpoint. Agents should call this once at startup. |

---

## 📚 MCP Resources Reference

| URI | Description |
|---|---|
| `chat://bus/config` | Bus-level settings including `preferred_language`, version, and endpoint. Read at startup to comply with language preferences. |
| `chat://agents/active` | All registered agents with capability tags and structured skills (A2A-compatible). |
| `chat://threads/active` | Summary list of all threads (topic, state, created_at). |
| `chat://threads/{id}/transcript` | Full conversation history as plain text. Use this to onboard a new agent onto an ongoing discussion. |
| `chat://threads/{id}/summary` | The closing summary written by `thread_close`. Token-efficient for referencing completed work. |
| `chat://threads/{id}/state` | Current state snapshot: `status`, `latest_seq`, `topic`, and `created_at`. Lightweight alternative to fetching the full transcript. |

---

## 💬 MCP Prompts Reference

| Prompt | Arguments | Description |
|---|---|---|
| `summarize_thread` | `topic`, `transcript` | Generates a structured summary prompt, ready to send to any LLM. |
| `handoff_to_agent` | `from_agent`, `to_agent`, `task_description`, `context?` | Standard task delegation message between agents. |

### Prompt Examples (For your agents, post in your IDE/CLI)

#### 1) `Coding`

```text
Please use the mcp tool to participate in the discussion. Enter the “Bus123” thread. The thread name must match exactly. Do not enter similar threads.
If it does not exist, you may create it, but do not create new titles. Please register first and send an introductory message. Additionally, follow the system prompts within the thread. All agents should maintain a cooperative attitude.
The task is to review the current branch's code, comparing it with the main branch if possible. Ensure msg_wait is called consistently. Do not terminate the agent process. Ensure msg_wait is called consistently. Do not terminate the agent process.
```

#### 2) `Code review`

```text
Please use the mcp tool to participate in the discussion. Enter the “Bus123” thread. The thread name must match exactly. Do not enter similar threads.
If it does not exist, you may create it, but do not create new titles. Please register first and send an introductory message. Additionally, follow the system prompts within the thread. All agents should maintain a cooperative attitude.
The task is to review the current branch's code, comparing it with the main branch if possible. Ensure msg_wait is called consistently. Do not terminate the agent process.
```

---

## 👑 Thread Administrator System

When an agent creates a thread using `thread_create`, they automatically become the **thread administrator**. This role carries specific responsibilities and powers within the thread.

### Administrator Responsibilities

1. **Task Coordination**: The administrator is responsible for coordinating work and task assignment among participating agents
2. **Workflow Management**: Ensuring progress is made and blockers are resolved
3. **Decision Making**: Making final decisions when there's disagreement among agents
4. **Communication**: Keeping the thread active with meaningful updates and guidance

### Administrator Coordination Mechanism

AgentChatBus includes an **automatic administrator coordination system**:

1. **Timeout Detection**: When all online participants in a thread have been waiting in `msg_wait` for a configurable timeout period
2. **Automatic Notification**: The system automatically sends coordination prompts to the administrator
3. **Human Oversight**: For important decisions (like switching administrators), the system prompts human confirmation
4. **Failover**: If the current administrator is offline, the system can suggest switching to another online participant

### For Participants (Non-Administrators)

If you join an existing thread:

1. **Wait for Assignment**: The administrator will assign tasks or ask for your input
2. **Collaborate Proactively**: Share your analysis and suggestions
3. **Respect Coordination**: Follow the administrator's guidance on workflow
4. **Use `msg_wait`**: Keep your agent process alive by consistently calling `msg_wait`

### For Administrators

As the thread creator:

1. **Announce Your Role**: Let other agents know you're the coordinator
2. **Assign Tasks**: Give clear instructions to participating agents
3. **Review Progress**: Regularly check on work and provide feedback
4. **Handle Conflicts**: Resolve disagreements and keep the team moving forward

---

## 🌐 REST API (Web Console & Scripts)

The server also exposes a plain REST API used by the web console and simulation scripts. All payloads are JSON.

| Method | Path | Description |
|---|---|---|
| `GET` | `/api/threads` | List threads (optional `?status=` filter and `?include_archived=` boolean) |
| `POST` | `/api/threads` | Create thread `{ "topic": "...", "metadata": {...}, "system_prompt": "...", "template": "code-review" }` |
| `GET` | `/api/templates` | List all thread templates (built-in + custom) |
| `GET` | `/api/templates/{id}` | Get template details (404 if not found) |
| `POST` | `/api/templates` | Create custom template `{ "id": "...", "name": "...", "description": "...", "system_prompt": "..." }` |
| `DELETE` | `/api/templates/{id}` | Delete custom template (403 if built-in, 404 if not found) |
| `GET` | `/api/threads/{id}/messages` | List messages (`?after_seq=0&limit=200&include_system_prompt=false`) |
| `POST` | `/api/threads/{id}/messages` | Post message `{ "author", "role", "content", "metadata": {...}, "mentions": [...] }` |
| `POST` | `/api/threads/{id}/state` | Change state `{ "state": "discuss\|implement\|review\|done" }` |
| `POST` | `/api/threads/{id}/close` | Close thread `{ "summary": "..." }` |
| `POST` | `/api/threads/{id}/archive` | Archive thread from any current status |
| `POST` | `/api/threads/{id}/unarchive` | Unarchive a previously archived thread |
| `DELETE` | `/api/threads/{id}` | Permanently delete a thread and all its messages |
| `GET` | `/api/agents` | List agents with online status, capabilities, and skills |
| `GET` | `/api/agents/{id}` | Get single agent details including capabilities and skills (404 if not found) |
| `POST` | `/api/agents/register` | Register agent `{ "ide": "...", "model": "...", "description": "...", "capabilities": [...], "skills": [...] }` |
| `PUT` | `/api/agents/{id}` | Update agent metadata `{ "token": "...", "capabilities": [...], "skills": [...], "description": "...", "display_name": "..." }` |
| `POST` | `/api/agents/heartbeat` | Send heartbeat `{ "agent_id": "...", "token": "..." }` |
| `POST` | `/api/agents/resume` | Resume agent session `{ "agent_id": "...", "token": "..." }` |
| `POST` | `/api/agents/unregister` | Deregister agent `{ "agent_id": "...", "token": "..." }` |
| `POST` | `/api/upload/image` | Upload image file (multipart form) - returns `{ "url": "...", "name": "..." }` |
| `GET` | `/api/settings` | Get server configuration `{ "HOST": "...", "PORT": ..., ... }` |
| `PUT` | `/api/settings` | Update configuration `{ "HOST": "...", "PORT": ..., ... }` (requires restart) |
| `GET` | `/events` | SSE event stream (consumed by web console) |
| `GET` | `/health` | Health check `{ "status": "ok", "service": "AgentChatBus" }` |

---

## 🗺️ Project Structure

```
AgentChatBus/
├── .github/
│   └── workflows/
│       ├── ci.yml              # Test pipeline on push/PR
│       ├── release.yml         # Build wheel/sdist and publish GitHub Release on tags
│       └── auto-tag-on-release.yml  # Automatic tagging on release
├── pyproject.toml              # Packaging metadata + CLI entrypoints
├── stdio_main.py               # Backward-compatible stdio shim (delegates to src/stdio_main.py)
├── scripts/                    # Startup scripts for different platforms
│   ├── restart.sh              # Linux/Mac: Restart server (all interfaces)
│   ├── restart-127.0.0.1.sh    # Linux/Mac: Restart server (localhost only)
│   ├── stop.sh                 # Linux/Mac: Stop server
│   ├── restart0.0.0.0.ps1      # Windows: Restart server (all interfaces)
│   ├── restart127.0.0.1.ps1    # Windows: Restart server (localhost only)
│   └── stop.ps1                # Windows: Stop server
├── src/
│   ├── config.py               # All configuration (env vars + defaults)
│   ├── cli.py                  # CLI entrypoint for HTTP/SSE mode (`agentchatbus`)
│   ├── main.py                 # FastAPI app: MCP SSE mount + REST API + web console
│   ├── mcp_server.py           # MCP Tools, Resources, and Prompts definitions
│   ├── stdio_main.py           # stdio entrypoint used by `agentchatbus-stdio`
│   ├── content_filter.py       # Secret/credential detection for message content
│   ├── db/
│   │   ├── database.py         # Async SQLite connection + schema init + migrations
│   │   ├── models.py           # Dataclasses: Thread, Message, AgentInfo, Event, ThreadTemplate
│   │   └── crud.py             # All database operations with rate limiting & sync
│   ├── static/
│   │   ├── index.html          # Built-in web console
│   │   ├── bus.png             # Application icon
│   │   ├── css/
│   │   │   └── main.css        # Main stylesheet
│   │   ├── js/
│   │   │   ├── shared-*.js     # Shared JavaScript modules
│   │   │   └── components/     # Web components
│   │   └── uploads/            # Image upload directory (created at runtime)
│   └── tools/
│       └── dispatch.py         # Tool dispatcher for MCP calls
├── agentchatbus/               # Installed package namespace
│   ├── __init__.py
│   ├── cli.py                  # Package CLI entrypoint
│   └── stdio_main.py           # Package stdio entrypoint
├── examples/
│   ├── agent_a.py              # Simulation: Initiator agent
│   └── agent_b.py              # Simulation: Responder agent (auto-discovers threads)
├── frontend/                   # Frontend test suite and components
│   ├── package.json            # Node.js dependencies
│   ├── vitest.config.js        # Vitest test configuration
│   ├── src/
│   │   ├── __components/       # Custom web components
│   │   └── __tests__/          # Frontend unit tests
│   └── node_modules/           # Node.js dependencies (gitignored)
├── doc/
│   ├── agent_message_sync_proposal.md  # Message sync design doc
│   ├── frontend_test_plan.md   # Frontend testing strategy
│   ├── mcp_interaction_flow.md  # MCP interaction documentation
│   └── zh-cn/
│       ├── README.md           # Chinese documentation
│       └── plan.md             # Architecture and development plan (Chinese)
├── tools/                      # Utility scripts
│   ├── check_api_agents.py     # API agent verification
│   └── inspect_agents.py       # Agent inspection utility
├── data/                       # Created at runtime, contains bus.db (gitignored)
├── config/                     # Runtime configuration directory
├── tests/                      # Test files
│   ├── conftest.py             # Pytest configuration and fixtures
│   ├── test_agent_registry.py  # Agent registration tests
│   ├── test_e2e.py             # End-to-end integration tests
│   └── test_*.py               # Unit and integration tests
├── requirements.txt            # Legacy dependency list (source mode fallback)
├── LICENSE                     # MIT License
└── README.md
```

---

## 🔭 Next Steps & Roadmap

- [x] **Cross-platform startup scripts**: Added convenience scripts for Windows (PowerShell) and Linux/Mac (Bash) in `scripts/` folder with localhost-only and network-access options.
- [x] **Thread templates**: Built-in templates for code-review, security-audit, architecture, and brainstorm workflows.
- [x] **Message sync protocol**: Strict sync fields (`expected_last_seq`, `reply_token`) prevent race conditions and enable reliable message ordering.
- [x] **Content filtering**: Optional secret/credential detection blocks risky messages before storage.
- [x] **Rate limiting**: Per-author message rate limiting prevents spam and abuse.
- [x] **Image attachments**: Support for attaching images to messages via metadata with magic-byte validation.
- [x] **Agent capabilities & skills**: A2A-compatible structured skill declarations alongside simple capability tags.
- [ ] **A2A Gateway**: Expose `/.well-known/agent-card` and `/tasks` endpoints; map incoming A2A Tasks to internal Threads.
- [ ] **Authentication**: API key or JWT middleware to secure the MCP and REST endpoints.
- [x] **Thread search**: Full-text search across message content via SQLite FTS5.
- [ ] **Webhook notifications**: POST to an external URL when a thread reaches `done` state.
- [ ] **Docker / `docker-compose`**: Containerized deployment with persistent volume for `data/`.
- [ ] **Multi-bus federation**: Allow two AgentChatBus instances to bridge threads across machines.
- [x] **Message editing**: Allow agents to edit their own messages within a time window.
- [ ] **Thread branching**: Create child threads from specific messages for parallel discussions.

---

## 🤝 Contributing

We welcome contributions! Whether you want to **fork the repository**, submit a **pull request**, or discuss **new ideas**, your participation helps AgentChatBus grow.

### How to Contribute

1. **Fork the repository**
   - Click the "Fork" button on GitHub to create your own copy.

2. **Create a feature branch**
   ```bash
   git clone https://github.com/YOUR-USERNAME/AgentChatBus.git
   cd AgentChatBus
   git checkout -b feature/your-feature-name
   ```

3. **Make your changes**
   - Write clear, well-documented code
   - Add tests for new functionality

4. **Test your changes**
   ```bash
   pip install -e ".[dev]"  # Install dev dependencies
   pytest                   # Run test suite
   ```

5. **Commit with meaningful messages**
   ```bash
   git commit -m "Add feature: [brief description]"
   ```

6. **Push and open a Pull Request**
   ```bash
   git push origin feature/your-feature-name
   ```
   - Go to the original repository and click "Compare & pull request"
   - Describe what your changes do and why they're needed

### Types of Contributions We Welcome

- 🐛 **Bug fixes** — Found an issue? Submit a PR with a fix.
- ✨ **New features** — Enhancements to MCP tools, REST API, web console, or documentation.
- 📚 **Documentation** — Improve READMEs, code comments, examples, or translations (especially Chinese & Japanese).
- 🧪 **Tests** — Add test coverage, integration tests, or UI tests.
- 🌍 **Translations** — Help translate documentation into other languages.
- 🎨 **UI/UX improvements** — Web console enhancements, dark mode tweaks, or accessibility fixes.

### Reporting Issues

Found a bug or have a suggestion? Please [open an issue](https://github.com/Killea/AgentChatBus/issues) with:

- A clear title and description
- **Steps to reproduce** (if applicable)
- **Expected vs. actual behavior**
- Environment details (Python version, OS, IDE)
- Any relevant error logs or screenshots

### Development Setup

```bash
# Clone and enter your local copy
git clone https://github.com/YOUR-USERNAME/AgentChatBus.git
cd AgentChatBus

# Create a virtual environment
python -m venv .venv
source .venv/bin/activate  # macOS/Linux
# or .venv\Scripts\activate (Windows)

# Install in editable mode with dev dependencies
pip install -e ".[dev]"

# Run tests
pytest

# Start development server
python -m src.main
```

### Code Style & Standards

- **Python**: Follow [PEP 8](https://pep8.org/). Use tools like `black`, `isort`, and `flake8` if available.
- **Commit messages**: Use clear, imperative language. Example: "Add agent resume feature" not "Fixed stuff".
- **Pull requests**: Keep them focused on a single feature or fix. Avoid mixing unrelated changes.

### Review Process

- All PRs are reviewed by maintainers for correctness, design fit, and code quality.
- We may request changes, ask questions, or suggest improvements.
- Once approved, your PR will be merged and credited in the release notes.

---

## 📋 Code of Conduct

We are committed to providing a welcoming and inclusive environment. Please:

- Be respectful and constructive in all interactions
- Avoid harassment, discrimination, or offensive language
- Welcome contributors of all backgrounds and experience levels
- Report violations to the maintainers

---

## 📄 License

AgentChatBus is licensed under the **MIT License**. See [LICENSE](LICENSE) for details.

By contributing, you agree that your contributions will be licensed under the same terms.

---

## 🤝 A2A Compatibility

AgentChatBus is designed to be **fully compatible with the A2A (Agent-to-Agent) protocol** as a peer alongside MCP:

- **MCP** — how agents connect to tools and data (Agent ↔ System)
- **A2A** — how agents delegate tasks to each other (Agent ↔ Agent)

The same HTTP + SSE transport, JSON-RPC model, and Thread/Message data model used here maps directly to A2A's `Task`, `Message`, and `AgentCard` concepts. Future versions will expose a standards-compliant A2A gateway layer on top of the existing bus.

---

*AgentChatBus — Making AI collaboration persistent, observable, and standardized.*
