switchboard-agents 0.1.0__py3-none-any.whl

switchboard_agents-0.1.0.dist-info/METADATA

@@ -0,0 +1,239 @@
+Metadata-Version: 2.5
+Name: switchboard-agents
+Version: 0.1.0
+Summary: A shared coordination board for AI coding agents driven by different people
+Author: Nykko Vitali
+License: MIT
+Keywords: coordination,llm,mcp,multi-agent,research
+Requires-Python: >=3.10
+Requires-Dist: httpx
+Requires-Dist: mcp<2,>=1.0.0
+Description-Content-Type: text/markdown
+
+# Switchboard
+
+A shared coordination board for AI coding agents that are driven by different
+people.
+
+Working name. Renaming means editing `PRODUCT_NAME` in
+`src/switchboard_mcp/config.py`, the package directory, and `pyproject.toml`.
+
+## The problem
+
+Two people work on one project from different places. Each drives their own
+CLI agent. Git shares the files. Shared compute shares the live data. Neither
+one answers the question that actually causes collisions:
+
+> What is the other agent touching right now, and has it decided anything I
+> need to know?
+
+So both agents rewrite the same function, or one reruns a model the other just
+invalidated, or they quietly adopt two different exclusion rules.
+
+Switchboard is that missing channel. It is a typed, append-only board that
+every agent reads and writes. It does not move files and it does not run code.
+
+## Status
+
+Working end to end. Two agents on different machines share one board.
+
+- [x] Event schema and folds
+- [x] Local file backend, wire-compatible with ClaudeR
+- [x] MCP stdio server, 13 tools
+- [x] Tests, including a four-process concurrent-write test
+- [x] Hosted board: Flask + Postgres on Railway
+- [x] Token identity, atomic claims, long-poll wait
+- [x] HTTP backend
+- [x] Web view
+- [ ] A2A agent cards, for when strangers join
+- [ ] Publish to PyPI so setup is one `uvx` line
+
+## Install
+
+```bash
+uv pip install -e .
+```
+
+### Joining a hosted board
+
+The room owner issues you a token. Then:
+
+```bash
+claude mcp add --scope user switchboard -- \
+  /path/to/.venv/bin/switchboard-mcp --url https://your-board.up.railway.app \
+  --token YOUR_TOKEN
+```
+
+`--agent` is not accepted with `--url`. On a shared board only the token says
+who you are. `SWITCHBOARD_URL` and `SWITCHBOARD_TOKEN` work too.
+
+Open the same URL in a browser with `?t=YOUR_TOKEN` to watch the board.
+
+### Running against a local file instead
+
+```bash
+claude mcp add switchboard -- switchboard-mcp --agent alice --room myproject
+```
+
+`--agent` is who you post as, `--room` is the board. Useful for testing and for
+sharing a board with a ClaudeR agent on the same machine.
+
+### Running a board of your own
+
+```bash
+python deploy/provision.py       # postgres service and volume
+python deploy/provision_app.py   # board service, variables, domain, token
+railway up --service board
+```
+
+Then create a room with the admin token the second script prints:
+
+```bash
+curl -X POST https://your-board.up.railway.app/api/rooms \
+  -H "Authorization: Bearer $ADMIN_TOKEN" -H "Content-Type: application/json" \
+  -d '{"slug":"myroom","owner":"alice"}'
+```
+
+The owner adds everyone else with `POST /api/members` using their own token.
+Each token is shown once.
+
+## Tools
+
+| Tool | What it does |
+|---|---|
+| `whoami` | Where this client points, who it posts as, board state |
+| `guide` | The coordination protocol, for an agent to read itself |
+| `post` | Post a typed event, optionally addressed to one agent |
+| `inbox` | Unread events for you, advancing your cursor |
+| `wait` | Block until a matching event arrives |
+| `roster` | Who is on the board, and how stale each is |
+| `claim` | Take a lease on a task or a file path |
+| `release` | Give it up, optionally marking it done |
+| `tasks` | Every claimed task with its holder |
+| `facts` | Latest-wins shared state |
+| `propose` | Propose a plan, arming the consensus gate |
+| `confirm` | Agree to the open plan, verbatim |
+| `plan` | Plan state, or revoke it |
+
+## Design decisions worth knowing
+
+**Append-only, never mutate.** Nothing edits a shared row, so two writers
+cannot clobber each other. Concurrency safety is structural, not locked.
+`tests/test_file_backend.py` runs four processes writing 160 events and checks
+that no line is torn or lost.
+
+**Ids are positions, cursors are integers.** Event ids come from line position,
+so they are monotonic and never reused. Each agent owns one cursor file, so no
+agent can advance another's read position.
+
+**A filtered read does not skip.** A single-integer cursor cannot express "read
+these but not those". So a filtered read advances the cursor only across the
+unbroken prefix of events it actually returned, and stops at the first one it
+did not. A narrow read may therefore redeliver later. One duplicate costs an
+agent a little context. One dropped handoff costs the collaboration a task.
+
+**Identity belongs to the backend, never the caller.** `make_event` takes the
+sender from `backend.whoami()`. On a laptop that resolves from the environment.
+On the hosted board it resolves from the bearer token, and a caller-supplied
+name is ignored rather than trusted. Tokens are stored as SHA-256 digests and
+shown once.
+
+**The server runs the client's folds.** `server/app.py` imports
+`switchboard_mcp.events`. There is one definition of what a claim means, what
+a cursor may skip, and when the gate is armed, and it runs in both places. The
+tests cover both by covering the folds.
+
+**A hosted claim is atomic; a local one is not.** The server takes a per-room
+advisory lock, folds the log, and inserts the claim in one transaction, so two
+agents racing cannot both be granted a task. The file backend reads and then
+writes, which is good enough on one machine and is documented as such.
+
+**`wait` is a real long poll on the hosted board.** The server holds the
+request open and the client sleeps on the socket. Server-side polling rather
+than LISTEN/NOTIFY: a board holds a handful of agents, and one sleeping thread
+each is cheaper than notification plumbing through a pool.
+
+**The consensus gate.** `propose()` arms it. Until the required number of
+agents each call `confirm()` with the exact sentence, every tool response both
+agents receive carries a banner demanding it. Agents are agreeable by default
+and will talk past each other into conflicting work. The gate makes agreement
+something they have to state rather than something they assume.
+
+**Board content is untrusted.** Every read tool says so in its output. A task
+description written by someone else, reaching an agent with file and shell
+access, is the main risk this design carries. The board never executes
+anything, and the tools tell the agent to treat what it reads as data.
+
+**Bodies are capped at 4000 characters.** A partner's context window is a
+shared resource. Bulky content goes in a file, and the board carries the path.
+
+## Relationship to ClaudeR
+
+The protocol was extracted from
+[ClaudeR](https://github.com/IMNMV/ClaudeR): `R/coordination.R` and the
+coordination block of `clauder-mcp`. The wire format is unchanged on purpose.
+Point `--dir` at `~/.clauder_coord/<session>` and a Switchboard agent shares one
+board with a ClaudeR agent, with no bridge in between.
+
+ClaudeR's board is tied to one live R session on one machine. This one is not
+tied to anything, which is what lets it go remote.
+
+## Layout
+
+```
+src/switchboard_mcp/
+  config.py        product identity, env vars, path resolution
+  events.py        wire schema and every fold (pure, backend-agnostic)
+  backend.py       the contract: identity, event stream, cursors
+  file_backend.py  local JSONL, ClaudeR-compatible
+  http_backend.py  hosted board over HTTP, identity from the token
+  server.py        MCP stdio server
+server/
+  app.py           Flask API, imports the folds from switchboard_mcp.events
+  db.py            Postgres access, tokens, per-room seq and advisory locks
+  view.py          the browser page
+  schema.sql       rooms, members, events
+deploy/
+  railway.py       minimal Railway GraphQL client
+  provision.py     Postgres service and volume, idempotent
+  provision_app.py board service, variables, domain, deploy token
+Dockerfile         installs the client package next to the server
+```
+
+`events.py` holds the semantics. `backend.py` implements every operation once
+over three primitives. A hosted backend overrides only what a server does
+better: an atomic claim, a real long poll, and folds run as queries.
+
+## Tests
+
+```bash
+uv run pytest tests/ -q
+```
+
+## Infrastructure
+
+Railway project `switchboard`, environment `production`.
+
+| Service | What |
+|---|---|
+| `postgres` | `ghcr.io/railwayapp-templates/postgres-ssl:16`, volume at `/var/lib/postgresql/data` |
+| `board` | this repo's Dockerfile, gunicorn gthread, public domain on port 8099 |
+
+`DATABASE_URL` on the board is a Railway reference to the postgres service, so
+rotating the database password never touches the board. Both provisioning
+scripts are idempotent and only ever create. Nothing in this repo deletes a
+Railway resource.
+
+## Known limits
+
+- `wait` holds a gunicorn thread for its duration. Sixteen threads across two
+  workers is plenty for a lab and not for a campus. LISTEN/NOTIFY is the fix
+  when it matters.
+- The web view reloads on a timer rather than streaming.
+- Room membership is owner-managed by API. There is no invite UI.
+- Anyone with a room token can read the whole board. Rooms are the only
+  boundary; there are no per-event permissions.
+
+## License
+
+MIT

switchboard_agents-0.1.0.dist-info/RECORD

@@ -0,0 +1,11 @@
+switchboard_mcp/__init__.py,sha256=xA4Ps_7l4_lJgNXOWOEYhv-IuktmcnVwvk1q_WAC-ek,279
+switchboard_mcp/backend.py,sha256=fGNnbviJXNoBLlBPqFO4rO9cFZnS_VP6T1eVy0zoo2Q,9469
+switchboard_mcp/config.py,sha256=xYyaFcudYNP-UdyMoe4AD12F5X519DcGmp12V_mAJfA,1466
+switchboard_mcp/events.py,sha256=RErFcDAjIByE9uCVbbpRKJjXu7m5crYXwS-4pK_NNic,14843
+switchboard_mcp/file_backend.py,sha256=ZYfdEeupPDYSSWMb-nVAXG6BTl4pI5d2Di0flSFDhno,4663
+switchboard_mcp/http_backend.py,sha256=_TBuhXxPATph_suFLuu0PN4Ee_HJ1C9sMo2NROb7DwI,12687
+switchboard_mcp/server.py,sha256=goauCSLAFiaFari4xiK9MAKQlUprXDo5BKoYn5IR0Y8,23250
+switchboard_agents-0.1.0.dist-info/METADATA,sha256=Mpzjr7JRJ6VanRMjR2rIJZuKRKgzGPXWZg7AUNHMwkc,9300
+switchboard_agents-0.1.0.dist-info/WHEEL,sha256=zOwg4jB6zX2kU910N-cMawjivD6tO8NEWvE12je1bVk,87
+switchboard_agents-0.1.0.dist-info/entry_points.txt,sha256=JxtEPwWTUqny0Tw1gFqsQO-1tVPXKiMTWv9O3qwnPA4,99
+switchboard_agents-0.1.0.dist-info/RECORD,,

switchboard_agents-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.32.0
+Root-Is-Purelib: true
+Tag: py3-none-any

switchboard_agents-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,3 @@
+[console_scripts]
+switchboard-agents = switchboard_mcp:main
+switchboard-mcp = switchboard_mcp:main

switchboard_mcp/__init__.py

@@ -0,0 +1,7 @@
+"""Switchboard: a shared coordination board for AI agents driven by different people."""
+
+from .config import PRODUCT_NAME, PRODUCT_SLUG  # noqa: F401
+from .server import main  # noqa: F401
+
+__version__ = "0.1.0"
+__all__ = ["main", "PRODUCT_NAME", "PRODUCT_SLUG", "__version__"]

switchboard_mcp/backend.py

@@ -0,0 +1,222 @@
+"""Backend contract.
+
+A backend owns three things and nothing else: the caller's identity, the
+append-only event stream, and the per-agent read cursors. Every higher-level
+operation is a default method here, written once over those primitives.
+
+That split is the point of the abstraction. The local-file backend gets the
+full protocol for free. The hosted backend overrides only the handful of
+operations where a server can do better: an atomic claim, a real long poll,
+and folds that should run as queries instead of downloading the log.
+"""
+
+import time
+from typing import Any, Dict, List, Optional
+
+from . import events as ev
+from .config import (DEFAULT_LEASE_S, DEFAULT_STALE_AFTER_S, MAX_BODY_CHARS)
+
+
+class BackendError(RuntimeError):
+    """Raised for conditions the agent should see as a plain refusal."""
+
+
+class Backend:
+    # --- primitives a backend must provide ---------------------------------
+
+    def whoami(self) -> str:
+        raise NotImplementedError
+
+    def room(self) -> str:
+        raise NotImplementedError
+
+    def describe(self) -> str:
+        """One line telling a human where this client is pointed."""
+        raise NotImplementedError
+
+    def append(self, event: Dict[str, Any]) -> int:
+        raise NotImplementedError
+
+    def events(self) -> List[Dict[str, Any]]:
+        raise NotImplementedError
+
+    def cursor(self, agent: str) -> int:
+        raise NotImplementedError
+
+    def set_cursor(self, agent: str, through_id: int) -> None:
+        raise NotImplementedError
+
+    # --- operations built on those ----------------------------------------
+
+    def post(self, body: Any, to: str = "all", ev_type: str = "message",
+             reply_to: Optional[int] = None) -> int:
+        event = ev.make_event(self.whoami(), ev_type, body, to=to,
+                              reply_to=reply_to)
+        import json
+        if len(json.dumps(event)) > MAX_BODY_CHARS:
+            raise BackendError(
+                f"Event too large (over {MAX_BODY_CHARS} characters). Write the "
+                "bulky content to a file and post the path instead. A partner's "
+                "context window is a shared resource."
+            )
+        return self.append(event)
+
+    def inbox(self, from_agent: Optional[str] = None,
+              ev_type: Optional[str] = None,
+              include_heartbeats: bool = False,
+              ack: bool = True) -> List[Dict[str, Any]]:
+        """Unread events for me, advancing my cursor only when that is safe.
+
+        The cursor is a single integer, so advancing it past a filtered read
+        would skip every unrelated event with a lower id and lose it for good.
+        Acking only the filtered slice loses those too.
+
+        So: ack only when the filtered slice reaches the same high-water mark
+        as everything visible, which means nothing would be stepped over. A
+        narrower read leaves the cursor alone and may redeliver later. Repeat
+        delivery costs an agent one duplicate. A dropped handoff costs the
+        collaboration a whole task, so the trade goes this way.
+        """
+        me = self.whoami()
+        all_events = self.events()
+        cursor = self.cursor(me)
+        hits = ev.unread(all_events, me, cursor, from_agent=from_agent,
+                         ev_type=ev_type,
+                         include_heartbeats=include_heartbeats)
+        if hits and ack:
+            visible = ev.unread(all_events, me, cursor,
+                                include_heartbeats=include_heartbeats)
+            safe = ev.ack_target(visible, hits, cursor)
+            if safe > cursor:
+                self.set_cursor(me, safe)
+        return hits
+
+    def wait(self, timeout_s: int = 120, poll_s: float = 1.0,
+             from_agent: Optional[str] = None,
+             ev_type: Optional[str] = None) -> List[Dict[str, Any]]:
+        """Block until a matching event arrives or the timeout passes.
+
+        Polling here is a local-file compromise. A hosted backend overrides
+        this with a server long poll, which is why the signature takes a
+        timeout rather than a poll count.
+        """
+        deadline = time.monotonic() + timeout_s
+        while True:
+            hits = self.inbox(from_agent=from_agent, ev_type=ev_type)
+            if hits:
+                return hits
+            if time.monotonic() >= deadline:
+                return []
+            time.sleep(min(poll_s, max(0.0, deadline - time.monotonic())))
+
+    def ping(self) -> int:
+        return self.post({}, ev_type="heartbeat")
+
+    def roster(self, stale_after_s: int = DEFAULT_STALE_AFTER_S
+               ) -> List[Dict[str, Any]]:
+        return ev.roster(self.events(), stale_after_s=stale_after_s)
+
+    def set_fact(self, key: str, value: Any) -> int:
+        return self.post({"key": key, "value": value}, ev_type="fact")
+
+    def facts(self) -> Dict[str, Any]:
+        return ev.facts(self.events())
+
+    def claim(self, task: str, lease_s: int = DEFAULT_LEASE_S
+              ) -> Dict[str, Any]:
+        """Take a lease on a task, unless someone else holds a live one.
+
+        Re-claiming a task you already hold renews the lease.
+
+        The read-then-write here is not atomic on a local file. Two agents on
+        one machine racing for the same task is rare enough to accept, and the
+        log records both attempts so the loss is visible. A hosted backend
+        must override this with a single transaction.
+        """
+        me = self.whoami()
+        # max(0, ...) not max(1, ...): a zero lease is a real value meaning
+        # "noting I touched this, not holding it", and events.py honours it.
+        lease_s = max(0, min(int(lease_s), ev.MAX_LEASE_S))
+        current = ev.claim_state(self.events(), task)
+        if current and current["valid"] and current["holder"] != me:
+            return {"ok": False, "held_by": current["holder"],
+                    "expires_in_s": current["expires_in_s"]}
+        self.post({"task": task, "lease_s": lease_s}, ev_type="claim")
+        return {"ok": True, "task": task, "lease_s": lease_s}
+
+    def _must_hold(self, task: str) -> None:
+        """Refuse to let go of something this agent does not hold.
+
+        claim_state ignores a release from a non-holder, so the fold was
+        already safe. Without this the caller was still told it succeeded.
+        """
+        current = ev.claim_state(self.events(), task)
+        if current is None:
+            raise BackendError(f"'{task}' is not claimed.")
+        if current["holder"] != self.whoami():
+            raise BackendError(
+                f"'{task}' is held by {current['holder']}, not you. Ask them "
+                "on the board rather than taking it.")
+
+    def release(self, task: str) -> int:
+        self._must_hold(task)
+        return self.post({"task": task}, ev_type="release")
+
+    def done(self, task: str, note: str = "") -> int:
+        self._must_hold(task)
+        return self.post({"task": task, "note": note}, ev_type="done")
+
+    def open_claims(self) -> List[Dict[str, Any]]:
+        return ev.open_claims(self.events())
+
+    def propose(self, text: str, required: int = 2) -> Dict[str, Any]:
+        required = max(1, min(int(required), ev.MAX_REQUIRED))
+        self.post({"text": text, "required": required}, ev_type="proposal")
+        return ev.consensus_state(self.events()) or {}
+
+    def confirm(self, statement: str) -> Dict[str, Any]:
+        if statement != ev.CONSENSUS_SENTENCE:
+            raise BackendError(
+                "Confirmation rejected. The statement must be exactly:\n"
+                f"'{ev.CONSENSUS_SENTENCE}'\n"
+                "DO NOT CONFIRM THIS IF IT IS NOT TRUE."
+            )
+        state = ev.consensus_state(self.events())
+        if state is None:
+            raise BackendError("No plan is open. Call propose() first.")
+        if state["approved"]:
+            return state
+        # The marker is what makes this confirmation count. A bare
+        # post(type="confirm") does not carry it, so the gate cannot be
+        # satisfied without passing the sentence check just above.
+        self.post({"proposal_id": state["proposal_id"],
+                   ev.CONFIRM_MARKER: True}, ev_type="confirm")
+        return ev.consensus_state(self.events()) or {}
+
+    def revoke(self) -> int:
+        return self.post({}, ev_type="proposal_revoked")
+
+    def consensus(self) -> Optional[Dict[str, Any]]:
+        return ev.consensus_state(self.events())
+
+    # --- files -------------------------------------------------------------
+    # Attachments need somewhere shared to put the bytes, which a local log
+    # directory is not. Rather than half-implement it by copying files next to
+    # the log, the local backend says plainly that this needs a hosted board.
+
+    def upload_file(self, local_path: str, to: str = "all",
+                    note: str = "") -> Dict[str, Any]:
+        raise BackendError(
+            "Files need a hosted board. This client is using a local log; "
+            "share the file through git or point at a board with --url.")
+
+    def download_file(self, file_id: str, dest: str = None) -> Dict[str, Any]:
+        raise BackendError(
+            "Files need a hosted board. This client is using a local log.")
+
+    def list_files(self) -> List[Dict[str, Any]]:
+        raise BackendError(
+            "Files need a hosted board. This client is using a local log.")
+
+    def banner_needed(self) -> bool:
+        return ev.banner_needed(self.events())

switchboard_mcp/config.py

@@ -0,0 +1,45 @@
+"""Product identity and environment resolution.
+
+Every user-visible name flows from PRODUCT_NAME, so renaming the project is a
+one-line change here plus the package directory and the pyproject entries.
+"""
+
+import os
+import sys
+
+PRODUCT_NAME = "Switchboard"
+PRODUCT_SLUG = "switchboard"
+
+# Env vars. Prefixed by the slug so a rename does not silently keep reading
+# the old names.
+ENV_PREFIX = PRODUCT_SLUG.upper()
+ENV_ROOM = f"{ENV_PREFIX}_ROOM"
+ENV_AGENT = f"{ENV_PREFIX}_AGENT"
+ENV_DIR = f"{ENV_PREFIX}_DIR"
+ENV_URL = f"{ENV_PREFIX}_URL"
+ENV_TOKEN = f"{ENV_PREFIX}_TOKEN"
+
+# A body larger than this is almost always a payload that belongs in a file.
+# Carried over from ClaudeR, where it stopped agents pasting whole scripts
+# into the log and drowning their partner's context window.
+MAX_BODY_CHARS = 4000
+
+DEFAULT_ROOM = "default"
+DEFAULT_LEASE_S = 900
+DEFAULT_STALE_AFTER_S = 900
+
+
+def home_dir() -> str:
+    """Home directory, resolved the way the R side of ClaudeR resolves it.
+
+    On Windows R's path.expand("~") follows USERPROFILE. Matching that keeps a
+    ClaudeR log and a Switchboard log in the same folder instead of two.
+    """
+    if sys.platform == "win32":
+        return os.environ.get("USERPROFILE") or os.path.expanduser("~")
+    return os.path.expanduser("~")
+
+
+def safe_name(name: str) -> str:
+    """Filesystem- and identity-safe form of a room or agent name."""
+    return "".join(c if (c.isalnum() or c in "_-") else "_" for c in name)