agent-bus-mcp 0.1.0__tar.gz

agent_bus_mcp-0.1.0/.github/workflows/build-wheels.yml

@@ -0,0 +1,112 @@
+name: build-wheels
+
+on:
+  workflow_call:
+    inputs:
+      upload_artifacts:
+        type: boolean
+        default: true
+  workflow_dispatch:
+    inputs:
+      upload_artifacts:
+        type: boolean
+        default: true
+
+env:
+  ORT_VERSION: "1.23.2"
+
+jobs:
+  sdist:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Validate version sync
+        run: |
+          python - <<'PY'
+          import tomllib
+
+          with open("pyproject.toml", "rb") as fh:
+            pyproject = tomllib.load(fh)
+          with open("Cargo.toml", "rb") as fh:
+            cargo = tomllib.load(fh)
+
+          py_version = pyproject["project"]["version"]
+          cargo_version = cargo["package"]["version"]
+
+          if py_version != cargo_version:
+            raise SystemExit(
+              f"Version mismatch: pyproject.toml={py_version} Cargo.toml={cargo_version}"
+            )
+          print(f"Version OK: {py_version}")
+          PY
+
+      - name: Build sdist
+        uses: PyO3/maturin-action@v1
+        with:
+          command: sdist
+          args: --out dist
+
+      - name: Upload sdist
+        if: inputs.upload_artifacts
+        uses: actions/upload-artifact@v4
+        with:
+          name: sdist
+          path: dist/*.tar.gz
+          if-no-files-found: error
+
+  wheels:
+    runs-on: ${{ matrix.os }}
+    strategy:
+      fail-fast: false
+      matrix:
+        os:
+          - ubuntu-latest
+          - macos-14
+          - windows-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Download ONNX Runtime (Windows)
+        if: runner.os == 'Windows'
+        shell: pwsh
+        run: |
+          $zip = "$env:RUNNER_TEMP/onnxruntime-win-x64-$env:ORT_VERSION.zip"
+          $dir = "$env:RUNNER_TEMP/onnxruntime-win-x64-$env:ORT_VERSION"
+          Invoke-WebRequest -Uri "https://github.com/microsoft/onnxruntime/releases/download/v$env:ORT_VERSION/onnxruntime-win-x64-$env:ORT_VERSION.zip" -OutFile $zip
+          Expand-Archive -Path $zip -DestinationPath $env:RUNNER_TEMP
+          "ORT_LIB_LOCATION=$dir\\lib" | Out-File -FilePath $env:GITHUB_ENV -Append
+          "ORT_PREFER_DYNAMIC_LINK=1" | Out-File -FilePath $env:GITHUB_ENV -Append
+          "PATH=$dir\\lib;$env:PATH" | Out-File -FilePath $env:GITHUB_ENV -Append
+
+      - name: Build wheels (Linux, manylinux_2_28)
+        if: runner.os == 'Linux'
+        uses: PyO3/maturin-action@v1
+        with:
+          command: build
+          args: --release --out dist
+          manylinux: 2_28
+
+      - name: Build wheels (Linux, manylinux_2_28 aarch64)
+        if: runner.os == 'Linux'
+        uses: PyO3/maturin-action@v1
+        with:
+          command: build
+          args: --release --out dist
+          manylinux: 2_28
+          target: aarch64-unknown-linux-gnu
+
+      - name: Build wheels (macOS/Windows)
+        if: runner.os != 'Linux'
+        uses: PyO3/maturin-action@v1
+        with:
+          command: build
+          args: --release --out dist
+
+      - name: Upload wheels
+        if: inputs.upload_artifacts
+        uses: actions/upload-artifact@v4
+        with:
+          name: wheels-${{ runner.os }}
+          path: dist/*.whl
+          if-no-files-found: error

agent_bus_mcp-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,84 @@
+name: ci
+
+on:
+  push:
+    branches:
+      - main
+  pull_request:
+
+env:
+  ORT_VERSION: "1.23.2"
+
+jobs:
+  build:
+    runs-on: ${{ matrix.os }}
+    strategy:
+      fail-fast: false
+      matrix:
+        os:
+          - ubuntu-latest
+          - macos-14
+          - windows-latest
+        python-version:
+          - "3.12"
+          - "3.13"
+          - "3.14"
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: dtolnay/rust-toolchain@stable
+        with:
+          components: rustfmt, clippy
+
+      - uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+
+      - uses: astral-sh/setup-uv@v3
+        with:
+          enable-cache: true
+
+      - name: Download ONNX Runtime (Windows)
+        if: runner.os == 'Windows'
+        shell: pwsh
+        run: |
+          $zip = "$env:RUNNER_TEMP/onnxruntime-win-x64-$env:ORT_VERSION.zip"
+          $dir = "$env:RUNNER_TEMP/onnxruntime-win-x64-$env:ORT_VERSION"
+          Invoke-WebRequest -Uri "https://github.com/microsoft/onnxruntime/releases/download/v$env:ORT_VERSION/onnxruntime-win-x64-$env:ORT_VERSION.zip" -OutFile $zip
+          Expand-Archive -Path $zip -DestinationPath $env:RUNNER_TEMP
+          "ORT_LIB_LOCATION=$dir\\lib" | Out-File -FilePath $env:GITHUB_ENV -Append
+          "ORT_PREFER_DYNAMIC_LINK=1" | Out-File -FilePath $env:GITHUB_ENV -Append
+          "PATH=$dir\\lib;$env:PATH" | Out-File -FilePath $env:GITHUB_ENV -Append
+
+      - name: Sync deps
+        run: uv sync --dev
+
+      - name: Build wheel
+        run: uv run maturin build --release -o dist
+
+      - name: Install wheel
+        shell: bash
+        run: uv pip install --force-reinstall dist/*.whl
+
+      - name: Run tests
+        run: uv run pytest
+
+      - name: Cargo fmt
+        run: cargo fmt --check
+
+      - name: Cargo clippy
+        run: cargo clippy --all-targets -- -D warnings
+
+      - name: Ruff format
+        run: uv run ruff format --check
+
+      - name: Ruff lint
+        run: uv run ruff check
+
+      - name: Ty type check
+        run: uv run ty check
+
+  wheels:
+    uses: ./.github/workflows/build-wheels.yml
+    with:
+      upload_artifacts: false

agent_bus_mcp-0.1.0/.github/workflows/publish-testpypi.yml

@@ -0,0 +1,134 @@
+name: publish-testpypi
+
+on:
+  workflow_dispatch:
+    inputs:
+      publish_target:
+        description: "Publish destination"
+        required: true
+        type: choice
+        default: testpypi
+        options:
+          - testpypi
+          - pypi
+
+permissions:
+  contents: write
+
+jobs:
+  build:
+    uses: ./.github/workflows/build-wheels.yml
+    with:
+      upload_artifacts: true
+
+  upload:
+    needs: build
+    runs-on: ubuntu-latest
+    outputs:
+      version: ${{ steps.version.outputs.version }}
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Download artifacts
+        uses: actions/download-artifact@v4
+        with:
+          path: dist
+          merge-multiple: true
+
+      - uses: astral-sh/setup-uv@v3
+        with:
+          enable-cache: false
+
+      - name: Upload to TestPyPI
+        shell: bash
+        run: |
+          set -euo pipefail
+          repo_url="https://test.pypi.org/legacy/"
+          token="${{ secrets.TEST_PYPI_API_TOKEN }}"
+          if [ "${{ inputs.publish_target }}" = "pypi" ]; then
+            repo_url="https://upload.pypi.org/legacy/"
+            token="${{ secrets.PYPI_API_TOKEN }}"
+          fi
+          MATURIN_PYPI_TOKEN="$token" MATURIN_REPOSITORY_URL="$repo_url" \
+            uvx --from "maturin>=1.11.5,<2.0" maturin upload --non-interactive --skip-existing dist/*
+
+      - name: Determine version
+        id: version
+        run: |
+          python - <<'PY'
+          import os
+          import tomllib
+
+          with open("pyproject.toml", "rb") as fh:
+            data = tomllib.load(fh)
+          version = data["project"]["version"]
+          with open(os.environ["GITHUB_OUTPUT"], "a", encoding="utf-8") as fh:
+            fh.write(f"version={version}\n")
+          print(f"Detected version: {version}")
+          PY
+
+  qa-install:
+    needs: upload
+    if: ${{ inputs.publish_target == 'testpypi' }}
+    runs-on: ${{ matrix.os }}
+    strategy:
+      fail-fast: false
+      matrix:
+        os:
+          - ubuntu-latest
+          - macos-14
+          - windows-latest
+    steps:
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+
+      - uses: astral-sh/setup-uv@v3
+        with:
+          enable-cache: true
+
+      - name: Install from TestPyPI (no build)
+        shell: bash
+        env:
+          VERSION: ${{ needs.upload.outputs.version }}
+        run: |
+          set -euo pipefail
+          echo "Testing install for agent-bus-mcp==$VERSION on $RUNNER_OS"
+          for attempt in {1..10}; do
+            if uvx --no-build \
+                --default-index https://test.pypi.org/simple \
+                --index https://pypi.org/simple \
+                --from "agent-bus-mcp==${VERSION}" \
+                agent-bus --help; then
+              exit 0
+            fi
+            echo "Install failed (attempt $attempt). Waiting for TestPyPI propagation..."
+            sleep 20
+          done
+          echo "Install failed after retries."
+          exit 1
+
+  tag-release:
+    needs: upload
+    if: ${{ inputs.publish_target == 'pypi' }}
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+          fetch-tags: true
+
+      - name: Create annotated tag
+        env:
+          VERSION: ${{ needs.upload.outputs.version }}
+        run: |
+          set -euo pipefail
+          tag="v${VERSION}"
+          if git rev-parse "$tag" >/dev/null 2>&1; then
+            echo "Tag $tag already exists, skipping."
+            exit 0
+          fi
+          git config user.name "github-actions[bot]"
+          git config user.email "41898282+github-actions[bot]@users.noreply.github.com"
+          git tag -a "$tag" "$GITHUB_SHA" -m "Release $tag"
+          git push origin "$tag"

agent_bus_mcp-0.1.0/.gitignore

@@ -0,0 +1,29 @@
+.venv/
+__pycache__/
+*.py[cod]
+.pytest_cache/
+.ruff_cache/
+.mypy_cache/
+dist/
+dist-*/
+build/
+target/
+*.egg-info/
+agent_bus/_core*.so
+agent_bus/_core*.pyd
+agent_bus/_core*.dylib
+.DS_Store
+.claude
+.claude/
+.gemini/
+.vscode/
+specs*.md
+
+# Waylog transcripts (may contain sensitive info)
+.waylog/
+.waylog-journal/
+
+# Local DB artifacts (if created under repo by tests/dev)
+*.sqlite
+*.sqlite-wal
+*.sqlite-shm

agent_bus_mcp-0.1.0/AGENTS.md

@@ -0,0 +1,50 @@
+# Repository Guidelines
+
+## Project Structure & Module Organization
+
+- `agent_bus/`: main Python package
+  - `peer_server.py`: MCP server (FastMCP) tools: `topic_*`, `cursor_reset`, `sync`
+  - `db.py`: SQLite (WAL) storage, schema/versioning, sync/cursor logic
+  - `cli.py`: admin CLI (`agent-bus cli ...`)
+  - `web/`: optional FastAPI web UI + Jinja templates in `agent_bus/web/templates/`
+- `tests/`: pytest suite (`test_*.py`)
+- `spec.md`: protocol + schema spec (treat as the source of truth when changing behavior)
+
+## Build, Test, and Development Commands
+
+This repo targets Python 3.12+ and uses `uv` for local development:
+
+```bash
+uv sync                 # install runtime deps
+uv sync --dev           # install dev deps (pytest, ruff, web extra)
+uv run agent-bus        # run MCP server over stdio
+uv sync --extra web     # install Web UI deps
+uv run agent-bus serve  # run Web UI (default http://127.0.0.1:8080)
+uv run ruff format      # format
+uv run ruff check       # lint
+uv run pytest           # tests
+```
+
+## Coding Style & Naming Conventions
+
+- Format/lint with Ruff (`ruff format`, `ruff check`). Line length is 100.
+- Prefer type hints and small, focused modules.
+- Naming: `snake_case` (functions/vars), `PascalCase` (types), `SCREAMING_SNAKE_CASE` (constants).
+
+## Testing Guidelines
+
+- Framework: pytest (some tests use `anyio` to exercise the stdio MCP server).
+- Keep tests hermetic: use `tmp_path` and point `AGENT_BUS_DB` at a temp SQLite file.
+- Name tests `tests/test_*.py` and prefer unit tests for `AgentBusDB` plus a small number of end-to-end smoke tests.
+
+## Commit & Pull Request Guidelines
+
+Commit history uses lightweight Conventional-ish prefixes (e.g. `feat(web): ...`, `fix(web): ...`, `docs: ...`, `chore: ...`) and component prefixes like `web: ...` / `peer: ...` / `cli: ...`. Follow one of those patterns.
+
+PRs should include: a short description, how to test, and screenshots for Web UI changes. Run `uv run ruff check` and `uv run pytest` before requesting review.
+
+## Security & Configuration Tips
+
+- Web UI has no auth; keep it bound to localhost unless you add protections.
+- DB schema is versioned; a mismatch requires wiping the DB (see `agent-bus cli db wipe --yes`).
+- Key env vars: `AGENT_BUS_DB`, `AGENT_BUS_MAX_*`, `AGENT_BUS_POLL_*`.

agent_bus_mcp-0.1.0/CLAUDE.md

@@ -0,0 +1,82 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## Project Overview
+
+Agent Bus is a local SQLite-backed MCP (Model Context Protocol) server for peer-to-peer agent communication. It enables multiple AI agents to communicate through a shared message bus with delta-based sync via server-side cursors.
+
+## Common Commands
+
+```bash
+# Install dependencies
+uv sync              # Core dependencies only
+uv sync --dev        # With dev dependencies (pytest, ruff)
+uv sync --extra web  # With web UI dependencies
+
+# Run the MCP server (stdio transport)
+uv run agent-bus
+
+# Run the web UI
+uv run agent-bus serve
+
+# Linting and formatting
+uv run ruff format
+uv run ruff check
+
+# Run all tests
+uv run pytest
+
+# Run a single test file
+uv run pytest tests/test_db.py
+
+# Run a specific test
+uv run pytest tests/test_db.py::test_topic_create_reuse_newest_open
+
+# CLI administrative commands
+uv run agent-bus cli topics list --status all
+uv run agent-bus cli topics watch <topic_id> --follow
+uv run agent-bus cli db wipe --yes
+```
+
+## Architecture
+
+### Core Components
+
+- **`agent_bus/peer_server.py`**: MCP server implementation using FastMCP. Defines all MCP tools (`ping`, `topic_create`, `topic_join`, `sync`, etc.). The `sync()` tool is the primary read/write interface with delta-based polling and server-side cursors.
+
+- **`agent_bus/db.py`**: SQLite database layer (`AgentBusDB` class). Handles all persistence: topics, messages, cursors, and sequences. Uses WAL mode for concurrent access. Key method is `sync_once()` which handles message sending and receiving in a single transaction.
+
+- **`agent_bus/models.py`**: Frozen dataclasses for `Topic`, `Message`, and `Cursor`.
+
+- **`agent_bus/common.py`**: Shared utilities including `tool_ok()`/`tool_error()` for MCP response formatting, error codes, and environment variable helpers.
+
+- **`agent_bus/cli.py`**: Click-based CLI for administrative operations (list topics, watch messages, export, delete).
+
+- **`agent_bus/entrypoint.py`**: Main entry point. Runs MCP server by default; `serve` subcommand starts web UI; `cli` subcommand runs admin commands.
+
+- **`agent_bus/web/server.py`**: Optional FastAPI web server with HTMX-powered UI for browsing topics and messages.
+
+### Key Patterns
+
+- **Server-side cursors**: Each agent has a cursor per topic tracking `last_seq`. The `sync()` tool advances this cursor, enabling delta-based message retrieval without re-fetching history.
+
+- **Idempotent sends**: Use `client_message_id` to make message sends idempotent for retry safety.
+
+- **Per-session join**: Agents must call `topic_join()` before `sync()`. Join state is in-memory (`_joined_agent_names` dict in peer_server.py).
+
+- **Presence tracking**: Derived from cursor `updated_at` timestamps - calling `sync()` updates presence.
+
+### Database Schema (v6)
+
+Tables: `meta`, `topics`, `topic_seq`, `messages`, `cursors`
+
+- Topics can be "open" or "closed"
+- Messages have sequential `seq` numbers per topic
+- Cursors track `(topic_id, agent_name, last_seq)`
+
+### Environment Variables
+
+- `AGENT_BUS_DB`: SQLite path (default: `~/.agent_bus/agent_bus.sqlite`)
+- `AGENT_BUS_MAX_SYNC_ITEMS`: Max messages per sync (default: 20)
+- `AGENT_BUS_MAX_MESSAGE_CHARS`: Max message length (default: 65536)