bus-mcp 0.1.0__tar.gz

bus_mcp-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Jaimen Bell
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

bus_mcp-0.1.0/PKG-INFO

@@ -0,0 +1,160 @@
+Metadata-Version: 2.4
+Name: bus-mcp
+Version: 0.1.0
+Summary: Ergonomic MCP server fronting the self-hosted AlphaHive coordination-bus HTTP API (backend/coordination_bus.py) -- post/read/claim/release/heartbeat/status as MCP tools instead of hand-rolled curl. Fast-follow to the coordination-bus arc, github-mcp-shaped (MCP over an HTTP API).
+Requires-Python: >=3.12
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: fastmcp==3.4.2
+Requires-Dist: httpx==0.28.1
+Provides-Extra: test
+Requires-Dist: pytest==9.0.3; extra == "test"
+Requires-Dist: respx==0.23.1; extra == "test"
+Dynamic: license-file
+
+# bus-mcp
+
+An ergonomic MCP server fronting the self-hosted **AlphaHive coordination
+bus** (`backend/coordination_bus.py` in the `alphahive` repo) -- so a Claude
+agent calls `claim_lane("feeds-refactor", owner="session-A")` instead of
+hand-rolling `curl -X POST .../lanes/feeds-refactor/claim -d '{...}'`. Built
+to the [desktop-mcp](https://github.com)/[github-mcp](https://github.com)
+standard (own pyproject, fastmcp server, honest README, real test suite) --
+this is that exact "MCP over an HTTP API" pattern turned on our own
+self-hosted API.
+
+## What this is / is not
+
+This fronts a **private, localhost-only, no-auth v1 coordination substrate**
+-- not a public service. The bus itself is a blackboard (append-only
+messages) + a lane-claim registry (task-queue leases with steal-on-expiry) +
+a status rollup for a command-center panel. It **executes nothing
+outward-facing**: `action_flag` on a message is recorded and displayed only,
+never acted on by the bus. bus-mcp adds zero new capability over what the
+bus already does via `curl` -- it only makes the six routes ergonomic MCP
+tools with typed inputs and typed errors instead of raw HTTP.
+
+## Tools
+
+| Tool | Bus route | Purpose |
+|---|---|---|
+| `post_message` | `POST /api/bus/message` | Append one message to the blackboard (topic, sender, body, action_flag) |
+| `read_messages` | `GET /api/bus/messages` | Recent messages, newest first, optional topic filter |
+| `claim_lane` | `POST /api/bus/lanes/{lane}/claim` | Claim-if-free / steal-if-lease-expired / renew-if-own; 409 if held live by another |
+| `release_lane` | `POST /api/bus/lanes/{lane}/release` | Free a held lane; 409 if held live by another |
+| `heartbeat_lane` | `POST /api/bus/lanes/{lane}/heartbeat` | Renew the lease; 409 if you don't hold it live |
+| `get_bus_status` | `GET /api/bus/status` | Rollup: active lanes, orphaned claims, recent messages, pending action flags |
+
+No write-safety *knob* here the way github-mcp has one for real external
+writes -- every bus route is coordination-only (store/display/claim). As of
+coordination-bus **v1.1**, the bus MAY optionally require a shared secret on
+its 4 write routes (default off); this client mirrors that with zero new
+config surface of its own -- see "Write-secret auth (v1.1)" below.
+
+## Typed errors, never a raw crash
+
+Every tool returns `{"ok": true, ...}` on success or `{"ok": false, "error":
+{...}}` on failure -- never an unhandled exception or stack trace.
+
+- **`bus_unreachable`** -- connection refused, timeout, or DNS failure. Means
+  the AlphaHive backend isn't running, or is running without the bus routes
+  loaded (`backend/coordination_bus.py` mounted on `:8100`).
+- **`bus_api_error`** -- the bus responded with a 4xx/5xx. Carries
+  `status_code` + the bus's own `detail` text -- e.g. a `409` lane-conflict
+  message telling you who holds the lane and for how long.
+
+Internally, `bus_mcp/client.py` raises typed `BusUnreachable` / `BusApiError`
+exceptions; `bus_mcp/routes.py` catches both and normalizes to the dict
+shape above before a tool ever returns. Tests exercise both layers.
+
+## Env vars
+
+| Var | Default | Purpose |
+|---|---|---|
+| `BUS_MCP_BASE_URL` | `http://127.0.0.1:8100/api/bus` | Base URL of the coordination bus |
+| `BUS_MCP_TIMEOUT_S` | `10.0` | Per-request timeout (seconds) |
+| `BUS_MCP_LIVE` | unset | Set to `1` to run the real-network smoke test (see Testing) |
+| `BUS_WRITE_SECRET` | unset | Same var the bus itself reads to arm write-auth (v1.1). When set here, every write tool call sends `X-Bus-Secret: <value>` automatically. Unset = no header sent, matching an unarmed bus byte-for-byte. |
+
+## Write-secret auth (v1.1)
+
+The coordination bus can optionally gate its 4 write routes (`post_message`,
+`claim_lane`, `release_lane`, `heartbeat_lane`) behind a shared secret header
+(`X-Bus-Secret`), read from `BUS_WRITE_SECRET` on the bus side. This client
+reads the **same env var name** from its own process and, when set,
+`bus_mcp/client.py`'s `post()` attaches the header to every write call --
+`bus_mcp/routes.py` and every tool caller stay unaware of arming state
+entirely. `client.get()` never attaches the header (GET routes are never
+gated bus-side).
+
+**To use with an armed bus:** set `BUS_WRITE_SECRET` to the same value in
+both the AlphaHive backend's environment and this MCP server's environment
+(e.g. in the config that launches `run_server.py`), then restart both
+processes. If the value is missing or wrong, a write tool call returns the
+normal `{"ok": false, "error": {"type": "bus_api_error", "status_code": 401,
+...}}` shape -- no special-casing needed, it flows through the same typed
+`BusApiError` path as any other 4xx.
+
+**Unset (default):** no header is sent, identical to talking to a bus that
+has never been armed -- zero behavior change from pre-v1.1.
+
+## Usage examples
+
+Once connected in a Claude session, an agent can:
+
+```
+claim_lane(lane="feeds-refactor", owner="session-A", lease_s=300)
+heartbeat_lane(lane="feeds-refactor", owner="session-A")
+post_message(topic="converge", sender="session-A", body="lane merged to master")
+release_lane(lane="feeds-refactor", owner="session-A")
+get_bus_status()
+```
+
+## Testing
+
+```bash
+.venv/Scripts/python.exe -m pytest -q
+```
+
+All HTTP is mocked via [respx](https://lundberg.github.io/respx/) -- the
+full suite never depends on a live bus. One additional test,
+`tests/test_live_smoke.py::test_live_get_bus_status_returns_rollup`, is
+gated behind `BUS_MCP_LIVE=1` and calls a real running bus's `get_bus_status`
+route. **As of this writing the bus routes are dormant/404 on the live
+`:8100` AlphaHive backend** until the operator restarts it with
+`coordination_bus.py`'s router mounted -- so that one gated test is expected
+to skip (or fail if forced) until that restart happens. That is correct
+behavior, not a bug in this repo.
+
+## Install / connect
+
+```bash
+python -m venv .venv
+.venv/Scripts/python.exe -m pip install -e ".[test]"
+```
+
+Registered in `~/.claude.json` under `mcpServers.bus-mcp` as a stdio server
+invoking `run_server.py` by absolute path (no `cwd` needed -- the entrypoint
+adds its own directory to `sys.path`).
+
+## Handshake check
+
+```bash
+.venv/Scripts/python.exe scripts/list_tools.py
+```
+
+Prints the six registered tool names with no transport started -- pure
+introspection, useful for verifying the server wires up cleanly after any
+change.
+
+## Out of scope
+
+- Authenticating *who* `owner`/`sender` claims to be -- the shared secret
+  (v1.1) proves possession of a value, not identity; that stays client-
+  asserted the same as before. See the bus's own README for that boundary.
+- Restarting the AlphaHive backend to bring the live bus routes up
+  (operator, elevated -- not something this MCP does)
+- Bus v2 execution/approval features (a separate, not-yet-built arc)
+
+<!-- MCP registry ownership marker -->
+mcp-name: io.github.jaimenbell/bus-mcp

bus_mcp-0.1.0/README.md

@@ -0,0 +1,146 @@
+# bus-mcp
+
+An ergonomic MCP server fronting the self-hosted **AlphaHive coordination
+bus** (`backend/coordination_bus.py` in the `alphahive` repo) -- so a Claude
+agent calls `claim_lane("feeds-refactor", owner="session-A")` instead of
+hand-rolling `curl -X POST .../lanes/feeds-refactor/claim -d '{...}'`. Built
+to the [desktop-mcp](https://github.com)/[github-mcp](https://github.com)
+standard (own pyproject, fastmcp server, honest README, real test suite) --
+this is that exact "MCP over an HTTP API" pattern turned on our own
+self-hosted API.
+
+## What this is / is not
+
+This fronts a **private, localhost-only, no-auth v1 coordination substrate**
+-- not a public service. The bus itself is a blackboard (append-only
+messages) + a lane-claim registry (task-queue leases with steal-on-expiry) +
+a status rollup for a command-center panel. It **executes nothing
+outward-facing**: `action_flag` on a message is recorded and displayed only,
+never acted on by the bus. bus-mcp adds zero new capability over what the
+bus already does via `curl` -- it only makes the six routes ergonomic MCP
+tools with typed inputs and typed errors instead of raw HTTP.
+
+## Tools
+
+| Tool | Bus route | Purpose |
+|---|---|---|
+| `post_message` | `POST /api/bus/message` | Append one message to the blackboard (topic, sender, body, action_flag) |
+| `read_messages` | `GET /api/bus/messages` | Recent messages, newest first, optional topic filter |
+| `claim_lane` | `POST /api/bus/lanes/{lane}/claim` | Claim-if-free / steal-if-lease-expired / renew-if-own; 409 if held live by another |
+| `release_lane` | `POST /api/bus/lanes/{lane}/release` | Free a held lane; 409 if held live by another |
+| `heartbeat_lane` | `POST /api/bus/lanes/{lane}/heartbeat` | Renew the lease; 409 if you don't hold it live |
+| `get_bus_status` | `GET /api/bus/status` | Rollup: active lanes, orphaned claims, recent messages, pending action flags |
+
+No write-safety *knob* here the way github-mcp has one for real external
+writes -- every bus route is coordination-only (store/display/claim). As of
+coordination-bus **v1.1**, the bus MAY optionally require a shared secret on
+its 4 write routes (default off); this client mirrors that with zero new
+config surface of its own -- see "Write-secret auth (v1.1)" below.
+
+## Typed errors, never a raw crash
+
+Every tool returns `{"ok": true, ...}` on success or `{"ok": false, "error":
+{...}}` on failure -- never an unhandled exception or stack trace.
+
+- **`bus_unreachable`** -- connection refused, timeout, or DNS failure. Means
+  the AlphaHive backend isn't running, or is running without the bus routes
+  loaded (`backend/coordination_bus.py` mounted on `:8100`).
+- **`bus_api_error`** -- the bus responded with a 4xx/5xx. Carries
+  `status_code` + the bus's own `detail` text -- e.g. a `409` lane-conflict
+  message telling you who holds the lane and for how long.
+
+Internally, `bus_mcp/client.py` raises typed `BusUnreachable` / `BusApiError`
+exceptions; `bus_mcp/routes.py` catches both and normalizes to the dict
+shape above before a tool ever returns. Tests exercise both layers.
+
+## Env vars
+
+| Var | Default | Purpose |
+|---|---|---|
+| `BUS_MCP_BASE_URL` | `http://127.0.0.1:8100/api/bus` | Base URL of the coordination bus |
+| `BUS_MCP_TIMEOUT_S` | `10.0` | Per-request timeout (seconds) |
+| `BUS_MCP_LIVE` | unset | Set to `1` to run the real-network smoke test (see Testing) |
+| `BUS_WRITE_SECRET` | unset | Same var the bus itself reads to arm write-auth (v1.1). When set here, every write tool call sends `X-Bus-Secret: <value>` automatically. Unset = no header sent, matching an unarmed bus byte-for-byte. |
+
+## Write-secret auth (v1.1)
+
+The coordination bus can optionally gate its 4 write routes (`post_message`,
+`claim_lane`, `release_lane`, `heartbeat_lane`) behind a shared secret header
+(`X-Bus-Secret`), read from `BUS_WRITE_SECRET` on the bus side. This client
+reads the **same env var name** from its own process and, when set,
+`bus_mcp/client.py`'s `post()` attaches the header to every write call --
+`bus_mcp/routes.py` and every tool caller stay unaware of arming state
+entirely. `client.get()` never attaches the header (GET routes are never
+gated bus-side).
+
+**To use with an armed bus:** set `BUS_WRITE_SECRET` to the same value in
+both the AlphaHive backend's environment and this MCP server's environment
+(e.g. in the config that launches `run_server.py`), then restart both
+processes. If the value is missing or wrong, a write tool call returns the
+normal `{"ok": false, "error": {"type": "bus_api_error", "status_code": 401,
+...}}` shape -- no special-casing needed, it flows through the same typed
+`BusApiError` path as any other 4xx.
+
+**Unset (default):** no header is sent, identical to talking to a bus that
+has never been armed -- zero behavior change from pre-v1.1.
+
+## Usage examples
+
+Once connected in a Claude session, an agent can:
+
+```
+claim_lane(lane="feeds-refactor", owner="session-A", lease_s=300)
+heartbeat_lane(lane="feeds-refactor", owner="session-A")
+post_message(topic="converge", sender="session-A", body="lane merged to master")
+release_lane(lane="feeds-refactor", owner="session-A")
+get_bus_status()
+```
+
+## Testing
+
+```bash
+.venv/Scripts/python.exe -m pytest -q
+```
+
+All HTTP is mocked via [respx](https://lundberg.github.io/respx/) -- the
+full suite never depends on a live bus. One additional test,
+`tests/test_live_smoke.py::test_live_get_bus_status_returns_rollup`, is
+gated behind `BUS_MCP_LIVE=1` and calls a real running bus's `get_bus_status`
+route. **As of this writing the bus routes are dormant/404 on the live
+`:8100` AlphaHive backend** until the operator restarts it with
+`coordination_bus.py`'s router mounted -- so that one gated test is expected
+to skip (or fail if forced) until that restart happens. That is correct
+behavior, not a bug in this repo.
+
+## Install / connect
+
+```bash
+python -m venv .venv
+.venv/Scripts/python.exe -m pip install -e ".[test]"
+```
+
+Registered in `~/.claude.json` under `mcpServers.bus-mcp` as a stdio server
+invoking `run_server.py` by absolute path (no `cwd` needed -- the entrypoint
+adds its own directory to `sys.path`).
+
+## Handshake check
+
+```bash
+.venv/Scripts/python.exe scripts/list_tools.py
+```
+
+Prints the six registered tool names with no transport started -- pure
+introspection, useful for verifying the server wires up cleanly after any
+change.
+
+## Out of scope
+
+- Authenticating *who* `owner`/`sender` claims to be -- the shared secret
+  (v1.1) proves possession of a value, not identity; that stays client-
+  asserted the same as before. See the bus's own README for that boundary.
+- Restarting the AlphaHive backend to bring the live bus routes up
+  (operator, elevated -- not something this MCP does)
+- Bus v2 execution/approval features (a separate, not-yet-built arc)
+
+<!-- MCP registry ownership marker -->
+mcp-name: io.github.jaimenbell/bus-mcp

bus_mcp-0.1.0/bus_mcp/client.py

@@ -0,0 +1,120 @@
+"""bus_mcp.client -- thin, typed httpx wrapper over the coordination-bus HTTP
+API (backend/coordination_bus.py in the alphahive repo).
+
+Every bus route is a plain function here returning a parsed JSON dict on
+success. Failure NEVER raises a raw httpx/requests exception up to a tool
+caller and never lets a stack trace reach the MCP transport -- it raises one
+of the two typed exceptions below, which server.py tool wrappers catch and
+turn into a clean `{"ok": False, "error": {...}}` payload.
+
+Typed error taxonomy:
+  BusUnreachable -- connect failed / timed out / DNS failure / bad URL. The
+    bus process (AlphaHive backend on :8100) is not up or not routable.
+  BusApiError    -- the bus responded but with a 4xx/5xx (e.g. 409 lane
+    conflict, 422 validation). Carries status_code + the bus's detail text.
+"""
+from __future__ import annotations
+
+from typing import Any
+
+import httpx
+
+from . import config
+
+
+class BusUnreachable(Exception):
+    """The coordination bus is not reachable (connection refused, timeout,
+    DNS failure, or a malformed base URL). Typically means the AlphaHive
+    backend isn't running, or isn't running with the bus routes loaded."""
+
+    def __init__(self, message: str, *, tool: str) -> None:
+        super().__init__(message)
+        self.tool = tool
+
+
+class BusApiError(Exception):
+    """The bus responded with an HTTP error status (4xx/5xx). Carries the
+    status code and the bus's own detail message (e.g. a 409 lane-conflict
+    detail string from coordination_bus.py)."""
+
+    def __init__(self, message: str, *, tool: str, status_code: int) -> None:
+        super().__init__(message)
+        self.tool = tool
+        self.status_code = status_code
+
+
+def _url(path: str) -> str:
+    return f"{config.get_base_url()}{path}"
+
+
+def _unreachable_message(tool: str) -> str:
+    return (
+        f"[{tool}] the coordination bus isn't reachable at {config.get_base_url()} "
+        "-- is the AlphaHive backend running with the bus routes loaded "
+        "(backend/coordination_bus.py mounted on :8100)?"
+    )
+
+
+def _handle_response(tool: str, response: httpx.Response) -> dict[str, Any]:
+    if response.status_code >= 400:
+        try:
+            body = response.json()
+            detail = body.get("detail", response.text)
+        except (ValueError, AttributeError):
+            detail = response.text or f"HTTP {response.status_code}"
+        raise BusApiError(
+            f"[{tool}] bus returned {response.status_code}: {detail}",
+            tool=tool,
+            status_code=response.status_code,
+        )
+    if not response.content:
+        return {}
+    try:
+        return response.json()
+    except ValueError as exc:
+        raise BusApiError(
+            f"[{tool}] bus returned non-JSON content: {exc}",
+            tool=tool,
+            status_code=response.status_code,
+        ) from exc
+
+
+def request(
+    tool: str,
+    method: str,
+    path: str,
+    *,
+    params: dict[str, Any] | None = None,
+    json: dict[str, Any] | None = None,
+    headers: dict[str, str] | None = None,
+) -> dict[str, Any]:
+    """Make one request against the bus. Raises BusUnreachable on a network
+    failure, BusApiError on a 4xx/5xx, else returns the parsed JSON body."""
+    try:
+        with httpx.Client(timeout=config.get_timeout_s()) as http_client:
+            response = http_client.request(
+                method, _url(path), params=params, json=json, headers=headers
+            )
+    except httpx.HTTPError as exc:
+        raise BusUnreachable(_unreachable_message(tool), tool=tool) from exc
+    except httpx.InvalidURL as exc:
+        # httpx.InvalidURL does NOT subclass httpx.HTTPError -- must be
+        # listed explicitly or a malformed BUS_MCP_BASE_URL crashes instead
+        # of surfacing a clean typed error.
+        raise BusUnreachable(_unreachable_message(tool), tool=tool) from exc
+    return _handle_response(tool, response)
+
+
+def get(tool: str, path: str, *, params: dict[str, Any] | None = None) -> dict[str, Any]:
+    return request(tool, "GET", path, params=params)
+
+
+def post(tool: str, path: str, *, json: dict[str, Any] | None = None) -> dict[str, Any]:
+    """POST to a write route. When BUS_WRITE_SECRET is set in this process's
+    env, automatically attaches the X-Bus-Secret header the coordination-bus
+    v1.1 write-auth dependency expects -- callers (routes.py) never need to
+    know or care whether the bus is armed. Unset (default) sends no header,
+    identical to pre-v1.1 behavior."""
+    secret = config.get_write_secret()
+    headers = {"X-Bus-Secret": secret} if secret is not None else None
+    return request(tool, "POST", path, json=json, headers=headers)

bus_mcp-0.1.0/bus_mcp/config.py

@@ -0,0 +1,50 @@
+"""bus_mcp.config -- environment configuration for the bus-mcp server.
+
+The coordination bus is a self-hosted, localhost-only v1 service
+(backend/coordination_bus.py in the alphahive repo). v1 "executes nothing
+outward-facing" (action_flag is store+display only) -- every route is safe to
+call. As of coordination-bus v1.1, the 4 write routes MAY be gated behind an
+optional shared secret (BUS_WRITE_SECRET, header X-Bus-Secret); this client
+mirrors that same env var so arming the bus and arming this MCP is one env
+var set in both processes, not a bus-mcp-specific config surface. Unset (the
+default) means the bus is unarmed -- this client sends no header, matching
+the bus's own default-open behavior byte-for-byte.
+"""
+from __future__ import annotations
+
+import os
+
+DEFAULT_BASE_URL = "http://127.0.0.1:8100/api/bus"
+DEFAULT_TIMEOUT_S = 10.0
+DEFAULT_LEASE_S = 300
+
+
+def get_base_url() -> str:
+    """Base URL for the coordination bus API, e.g. http://127.0.0.1:8100/api/bus.
+    Overridable via BUS_MCP_BASE_URL for a non-default host/port."""
+    return os.environ.get("BUS_MCP_BASE_URL", DEFAULT_BASE_URL).rstrip("/")
+
+
+def get_timeout_s() -> float:
+    """Per-request timeout in seconds. Overridable via BUS_MCP_TIMEOUT_S."""
+    raw = os.environ.get("BUS_MCP_TIMEOUT_S")
+    if not raw:
+        return DEFAULT_TIMEOUT_S
+    try:
+        return float(raw)
+    except ValueError:
+        return DEFAULT_TIMEOUT_S
+
+
+def is_live_smoke_enabled() -> bool:
+    """True when BUS_MCP_LIVE=1 -- gates the real-network smoke test."""
+    return os.environ.get("BUS_MCP_LIVE") == "1"
+
+
+def get_write_secret() -> str | None:
+    """Reads BUS_WRITE_SECRET from the environment on every call (not cached),
+    mirroring the bus server's own per-request read -- so tests can
+    monkeypatch it and an operator can arm/disarm without a code change.
+    Empty string counts as unset. None means: send no X-Bus-Secret header,
+    matching the bus's own default-open behavior."""
+    return os.environ.get("BUS_WRITE_SECRET") or None

bus_mcp-0.1.0/bus_mcp/routes.py

@@ -0,0 +1,106 @@
+"""bus_mcp.routes -- one function per coordination-bus route (backend/
+coordination_bus.py), 1:1. Each function calls bus_mcp.client, which raises
+BusUnreachable / BusApiError on failure; every function here catches both and
+normalizes to `{"ok": False, "error": {...}}` so a tool caller never sees a
+raw exception or stack trace -- only server.py's @mcp.tool wrappers call
+these, and they return whatever these functions return, unmodified.
+"""
+from __future__ import annotations
+
+from typing import Any
+
+from . import client, config
+
+
+def _error_payload(exc: client.BusUnreachable | client.BusApiError) -> dict[str, Any]:
+    if isinstance(exc, client.BusUnreachable):
+        return {
+            "ok": False,
+            "error": {
+                "type": "bus_unreachable",
+                "message": str(exc),
+                "tool": exc.tool,
+            },
+        }
+    return {
+        "ok": False,
+        "error": {
+            "type": "bus_api_error",
+            "message": str(exc),
+            "tool": exc.tool,
+            "status_code": exc.status_code,
+        },
+    }
+
+
+def post_message(topic: str, sender: str, body: str, action_flag: bool = False) -> dict[str, Any]:
+    """Append one message to the bus blackboard (append-only). v1 stores
+    action_flag but performs no action -- it is display-only, seen by a human
+    watching the command-center panel."""
+    try:
+        result = client.post(
+            "post_message",
+            "/message",
+            json={"topic": topic, "sender": sender, "body": body, "action_flag": action_flag},
+        )
+    except (client.BusUnreachable, client.BusApiError) as exc:
+        return _error_payload(exc)
+    return {"ok": True, **result}
+
+
+def read_messages(topic: str | None = None, limit: int = 50) -> dict[str, Any]:
+    """Recent bus messages, newest first, optionally filtered by topic."""
+    params: dict[str, Any] = {"limit": limit}
+    if topic is not None:
+        params["topic"] = topic
+    try:
+        result = client.get("read_messages", "/messages", params=params)
+    except (client.BusUnreachable, client.BusApiError) as exc:
+        return _error_payload(exc)
+    return {"ok": True, **result}
+
+
+def claim_lane(lane: str, owner: str, lease_s: int = config.DEFAULT_LEASE_S) -> dict[str, Any]:
+    """Claim a coordination lane before starting work in it: claim-if-free,
+    steal-if-lease-expired, renew-if-you-already-own-it. A 409 (lane held
+    live by another owner) surfaces as a clean ok=False conflict, not a
+    crash -- check `error.type == "bus_api_error"` and `status_code == 409`."""
+    try:
+        result = client.post(
+            "claim_lane", f"/lanes/{lane}/claim", json={"owner": owner, "lease_s": lease_s}
+        )
+    except (client.BusUnreachable, client.BusApiError) as exc:
+        return _error_payload(exc)
+    return {"ok": True, **result}
+
+
+def release_lane(lane: str, owner: str) -> dict[str, Any]:
+    """Release a lane you hold. A 409 (held live by another owner) surfaces
+    as a clean ok=False conflict, not a crash."""
+    try:
+        result = client.post("release_lane", f"/lanes/{lane}/release", json={"owner": owner})
+    except (client.BusUnreachable, client.BusApiError) as exc:
+        return _error_payload(exc)
+    return {"ok": True, **result}
+
+
+def heartbeat_lane(lane: str, owner: str, lease_s: int = config.DEFAULT_LEASE_S) -> dict[str, Any]:
+    """Renew the lease on a lane you hold live. A 409 (not held live by you)
+    surfaces as a clean ok=False conflict telling you to (re)claim instead."""
+    try:
+        result = client.post(
+            "heartbeat_lane", f"/lanes/{lane}/heartbeat", json={"owner": owner, "lease_s": lease_s}
+        )
+    except (client.BusUnreachable, client.BusApiError) as exc:
+        return _error_payload(exc)
+    return {"ok": True, **result}
+
+
+def get_bus_status() -> dict[str, Any]:
+    """Roll-up for the command-center panel: active lanes, orphaned/stale
+    claims, recent messages, pending display-only action flags."""
+    try:
+        result = client.get("get_bus_status", "/status")
+    except (client.BusUnreachable, client.BusApiError) as exc:
+        return _error_payload(exc)
+    return {"ok": True, **result}