agent-switchboard 2.2.2__tar.gz → 2.4.0__tar.gz

{agent_switchboard-2.2.2 → agent_switchboard-2.4.0}/.github/workflows/ci.yml

@@ -143,13 +143,19 @@ jobs:
   # success is the failure being fixed.
   browser:
     runs-on: ubuntu-latest
-    # The only job here that installs system packages, and the only one that
-    # has hung. On #138 `playwright install --with-deps` sat in apt for 71
-    # minutes; GitHub's default job timeout is six HOURS, so nothing would have
-    # said so until the afternoon was gone, and the PR reads as `unstable` —
-    # not red, not green — the whole time. Ten minutes is roughly five times
-    # the step's normal cost, so it bounds the hang without failing a slow
-    # mirror.
+    # This job used to install system packages, and it was the only one that
+    # ever hung or failed on something outside the repo. On #138
+    # `playwright install --with-deps` sat in apt for 71 minutes; on #251 the
+    # same step failed twice with a Hash Sum mismatch fetching Google's Chrome
+    # index, because `--with-deps` adds apt — and therefore dl.google.com — to
+    # the critical path of a job that only needs a browser binary.
+    #
+    # ubuntu-latest already ships the shared libraries Chromium links against,
+    # so the deps step is gone. If that ever stops being true, Chromium fails
+    # to launch and the tests below go red — loudly, and without a skip, which
+    # the last step enforces.
+    #
+    # The timeout stays: it bounded the hang before and costs nothing.
     timeout-minutes: 10
     steps:
       - uses: actions/checkout@v4
@@ -157,7 +163,7 @@ jobs:
         with:
           python-version: "3.12"
       - run: pip install -e '.[dev]' playwright
-      - run: playwright install --with-deps chromium
+      - run: playwright install chromium
       - name: the page, in a browser — and nothing may skip
         # `-p no:randomly` keeps the summary line stable to grep. The skip
         # check is the whole point of the job: if the browser fixture ever
@@ -170,6 +176,27 @@ jobs:
             exit 1
           fi
 
+  # The landing page quotes real terminal output. Until #277 the largest of
+  # those blocks was generated from site/demo.cast, so it could not drift;
+  # that generator is gone and the quotes are now placed by hand, which means
+  # a change to the CLI's output can leave the page showing a line no run
+  # prints any more. site/PRINCIPLES.md principle 4 is the whole reason this
+  # page is worth anything, so it is checked rather than trusted.
+  #
+  # Offline on purpose: it reads only files in this repository. The island
+  # boards are quoted from another host and are checked by hand with
+  # `python3 site/check-quotes.py --online`, because a CI run should not go
+  # red over somebody else's uptime. Stdlib only, so there is nothing to
+  # install.
+  site-quotes:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+      - run: python3 site/check-quotes.py
+
   docker:
     runs-on: ubuntu-latest
     steps:
@@ -184,48 +211,86 @@ jobs:
           curl -sf http://127.0.0.1:8787/health | grep -q '"ok":true'
           docker rm -f swb
 
-  # Dogfooding: this CI run announces itself on the same hub the rest of
-  # this project coordinates over, same as local/cloud agents do via the
-  # SessionStart hook `init` installs (see cli.py's _SESSION_START_CMD).
-  # It announces into its own workspace rather than the interactive one, so a
-  # CI run never shows up in the middle of a human session's peers.
+  # A smoke test against the real hub, not a notice board.
+  #
+  # This used to announce into a fixed room so a CI run appeared beside the
+  # human sessions. That room's identifier sat in this file in plain text, and
+  # since #73 the hub does no authorization — reaching a room IS knowing its
+  # identifier — so it was the one published room in a repository whose own
+  # .gitignore refuses to commit .mcp.json for the same reason.
   #
-  # The token is read from MANAGED_HUB_TOKEN in the checkout, the same way
-  # deploy.yml reads the value it starts the hub with. That is the whole point:
-  # a private second copy in `secrets.SWITCHBOARD_TOKEN` drifted from the hub's
-  # own token and locked this job out for a day without failing a build (#96).
-  # Since #76 a token admits a caller to the hub and scopes nothing, so there
-  # is nothing for a secret copy to protect that the published one does not.
+  # The fix is not a secret. Nobody was reading what CI announced, so the room
+  # does not need to persist: the job mints its own, uses it, and drops it. No
+  # identifier to leak, no key to rotate, no secret withheld from a fork's pull
+  # request — and the job now behaves identically for a contributor as it does
+  # on main.
   #
-  # Never gates the rest of CI, and never fails silently either: the announce
-  # cannot break a build, but a failure is reported as a warning on the run
-  # instead of one line of stderr in a green job.
+  # What it buys beyond safety: the old job could not fail. It warned and
+  # exited green, so a client that could not reach the hub at all still showed
+  # a passing check. This one mints, announces, and reads the roster back,
+  # asserting the agent it just created is there. That is the whole client
+  # path — keygen, seal, POST, GET, decrypt — against the live hub on every
+  # run, and it goes red when any of it breaks.
+  #
+  # The token still comes from MANAGED_HUB_TOKEN in the checkout rather than a
+  # secret: a private copy drifted from the hub's own token and locked this job
+  # out for a day without failing a build (#96). Since #76 a token admits a
+  # caller and scopes nothing, so a secret copy protects nothing the published
+  # one does not.
   register-switchboard:
+    # Never on a pull request. This is the one job that talks to a server
+    # somebody has to keep up, and a hub reboot must not turn a contributor's
+    # PR red for a reason that has nothing to do with their change — red for
+    # no reason is how people learn to ignore red.
+    #
+    # On main it gates, which is the point: a check that cannot fail is not a
+    # check, and the old one warned and exited green even when the client
+    # could not reach the hub at all.
+    if: github.event_name != 'pull_request'
     runs-on: ubuntu-latest
+    timeout-minutes: 5
     steps:
       - uses: actions/checkout@v4
       - uses: actions/setup-python@v5
         with:
           python-version: "3.12"
       - run: pip install -e .
-      - name: Announce this CI run to the hub
+      - name: Mint a room, announce into it, and read it back
         env:
           SWITCHBOARD_URL: https://switchboard.lucille-ai.com
-          SWITCHBOARD_WORKSPACE: w_gAbpTxVh-Jl0pjx0Hnqupw
+          SWITCHBOARD_AGENT_ID: ci-${{ github.run_id }}-${{ github.run_attempt }}
         run: |
+          set -euo pipefail
+
           SWITCHBOARD_TOKEN="$(sed -n 's/^MANAGED_HUB_TOKEN = "\([^"]*\)".*/\1/p' \
             src/switchboard/config.py | head -1)"
-          export SWITCHBOARD_TOKEN
           if [ -z "$SWITCHBOARD_TOKEN" ]; then
-            echo "::warning title=switchboard::MANAGED_HUB_TOKEN not found in" \
-              "src/switchboard/config.py — this CI run was not announced"
-            exit 0
+            echo "::error title=switchboard::MANAGED_HUB_TOKEN not found in" \
+              "src/switchboard/config.py"
+            exit 1
           fi
-          if ! out="$(switchboard -q register --kind ci -c build \
-              --task "${{ github.event_name }} ${{ github.ref_name }}@${{ github.sha }}" 2>&1)"; then
-            # Last line only: an auth failure is one line, but a connection
-            # failure is a whole httpx traceback (#88), and a warning is a
-            # one-line surface. The last line is the diagnosis in both cases.
-            echo "::warning title=switchboard::announce failed:" \
-              "$(printf '%s' "${out:-no output}" | tail -n 1)"
+          export SWITCHBOARD_TOKEN
+
+          # A room of its own, thrown away when the job ends. Everything in it
+          # expires on its own anyway — presence in two minutes.
+          eval "$(switchboard keygen --no-input | sed 's/^/export /')"
+
+          MARK="${{ github.event_name }} ${{ github.ref_name }}@${{ github.sha }}"
+          switchboard -q announce --kind ci -c build --task "$MARK"
+
+          # The assertion, and it is deliberately on the task rather than on
+          # the agent id. Ids are scrambled before they reach the hub, so the
+          # one in SWITCHBOARD_AGENT_ID never appears in a roster — an
+          # assertion against it fails every time, which is how this was
+          # written the first time and caught by rehearsing it.
+          #
+          # The task is sealed on the way out and opened on the way back, so
+          # finding it here proves the whole path: mint, seal, POST, GET,
+          # decrypt. Announcing alone would only prove a write was accepted.
+          if ! switchboard --json agents | grep -qF "$MARK"; then
+            echo "::error title=switchboard::announced \"$MARK\" but it did" \
+              "not come back from the roster"
+            switchboard --json agents
+            exit 1
           fi
+          echo "hub round trip ok — announced and read back: $MARK"

{agent_switchboard-2.2.2 → agent_switchboard-2.4.0}/.gitignore

@@ -30,3 +30,9 @@ uv.lock
 
 # repoctx: generated index + feedback state, per-machine.
 .repoctx/
+
+# Seeded design canvas — regenerated from site/design/*.dc.html by the design skill
+site/design/agentswitchboard-landing.html
+
+# macOS Finder metadata
+.DS_Store

{agent_switchboard-2.2.2 → agent_switchboard-2.4.0}/ARCS.md

@@ -41,7 +41,7 @@ issue — read off a line in the README rather than reported by anyone.
 
 ### 🟠 What protects a room once the hub stops authorizing anyone
 
-`hub-boundary` · 9 item(s), 6 startable
+`hub-boundary` · 10 item(s), 6 startable
 
 `https://github.com/gald33/switchboard/issues/61` · `https://github.com/gald33/switchboard/issues/73` · `docs/model.md` · `docs/encryption.md`
 
@@ -67,7 +67,8 @@ under pressure.
 
 | item | status | priority |
 |---|---|---|
-| `ci-workspace-is-public` | ready | now |
+| `a-drain-that-retries-forever-never-escalates` | ready | now |
+| `ci-workspace-is-public` | done | now |
 | `stale-resolver-references` | ready | now |
 | `seal-agent-meta` | ready | next |
 | `abuse-control-after-authorization` | deferred | — |
@@ -79,7 +80,7 @@ under pressure.
 
 ### 🟠 The first ten minutes, for somebody who has not read the docs
 
-`setup-and-first-run` · 19 item(s), 13 startable
+`setup-and-first-run` · 23 item(s), 14 startable
 
 `https://github.com/gald33/switchboard/issues/86` · `https://github.com/gald33/switchboard/issues/88` · `https://github.com/gald33/switchboard/issues/89` · `docs/environments.md`
 
@@ -101,9 +102,12 @@ wrong says so.
 
 | item | status | priority |
 |---|---|---|
+| `first-contact-needs-a-key-it-cannot-have` | done | now |
+| `inbox-consumes-what-it-cannot-open` | done | now |
 | `automatic-session-checkpoints` | ready | next |
 | `connect-failure-message` | done | next |
 | `cross-key-rendezvous` | ready | next |
+| `discovery-is-uneven-and-delivery-is-unknowable` | ready | next |
 | `init-writes-rooms-file` | ready | next |
 | `known-rooms-address-book` | done | next |
 | `a-lobby-derived-from-the-key` | ready | — |
@@ -120,6 +124,7 @@ wrong says so.
 | `unread-dms-not-shown-outside-mcp` | ready | — |
 | `write-parity-across-surfaces` | ready | — |
 | `hooks-warning-false-positive` | done | later |
+| `rootless-warning-false-positive` | done | later |
 
 ### 🟠 Ceilings that are honest about themselves
 

{agent_switchboard-2.2.2 → agent_switchboard-2.4.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: agent-switchboard
-Version: 2.2.2
+Version: 2.4.0
 Summary: An ephemeral orchestration hub for AI coding agents: presence, leases, messaging and a shared blackboard, all with TTLs.
 Project-URL: Homepage, https://github.com/gald33/switchboard
 Project-URL: Issues, https://github.com/gald33/switchboard/issues
@@ -40,7 +40,7 @@ Description-Content-Type: text/markdown
 
 **An ephemeral orchestration hub for AI coding agents.**
 
-*Early release — pre-1.0, the shape is still settling. Two minutes in:
+*Early release — the shape is still settling. Two minutes in:
 [watch two agents coordinate](demo/README.md) before installing anything.*
 
 When several coding agents work the same repo — one on your laptop, one in a
@@ -81,6 +81,29 @@ live exactly as long as the work does.
 That's the whole model. Direct messages aren't a fifth concept — a DM to agent
 `bob` is just a message on channel `@bob`.
 
+### A message is half an exchange
+
+Agents are turn-based. They run, they end, and something else starts them
+later. So an agent that sends a message is almost never launching a one-off —
+it sends because it needs something back, and the answer is due after its turn
+is over, into an inbox nothing is watching.
+
+`switchboard listen` is the other half — not a fifth primitive, but the way an
+agent stays reachable across the gap it is not awake for. It parks on the
+inbox and **exits the moment something arrives**, which is the one event a
+runner already reacts to: Claude Code re-invokes a session when a background
+process exits, so the reply *is* the wake — seconds after it lands, rather than
+at whatever check somebody scheduled.
+
+```bash
+switchboard dm reviewer-agent "0142 is mine — does that clash with yours?"
+switchboard listen --until forecast:p50    # as a background process, before the turn ends
+```
+
+`say`, `dm` and `whisper` report where each end stands — whether a listener is
+parked for you, and for the agent you sent to — so "sent" is never mistaken for
+"will be answered into something that is listening".
+
 ### Why leases expire
 
 This is the part worth dwelling on. A conventional "claim" — a row in a table,
@@ -100,22 +123,21 @@ heartbeat — 15 minutes by default — with nobody having to remember anything.
 ## Install
 
 ```bash
-# Agent side: client + CLI only (one dependency, httpx)
+# Agents, the CLI and the MCP bridge — everything except running a hub
 pip install agent-switchboard
 
-# Hub side: also the server
+# Also the hub, if you are running one yourself
 pip install "agent-switchboard[server]"
-
-# With end-to-end encryption
-pip install "agent-switchboard[crypto]"
-
-# With the MCP bridge for Claude Code / any MCP client
-pip install "agent-switchboard[all]"
 ```
 
+Encryption is not an extra: `cryptography` is a base dependency, because a
+build that cannot encrypt is not a working install. `[crypto]` still resolves
+— released docs and images ask for it — but it is now a no-op, and `[all]` is
+`[server]` plus that no-op. Nothing but `switchboard serve` needs either.
+
 To track `main` instead of a release — for unreleased fixes, or to
 contribute — install from GitHub instead:
-`pip install "agent-switchboard[all] @ git+https://github.com/gald33/switchboard.git"`,
+`pip install "agent-switchboard[server] @ git+https://github.com/gald33/switchboard.git"`,
 or pin a commit or tag by appending it to the URL:
 `git+https://github.com/gald33/switchboard.git@v0.7.2`.
 
@@ -305,13 +327,40 @@ Agents then get these as native tools:
 | `claim` / `release` / `claims` | take, drop and inspect leases |
 | `say` / `dm` / `inbox` / `history` | channel and direct messaging |
 | `board_set` / `board_get` / `board_list` | shared scratch space |
+| `rendezvous` | meet an agent you have never exchanged a message with |
 | `checkin` | heartbeat + renew leases + drain inbox, in one call |
+| *(CLI only)* `switchboard listen` | park until a reply arrives, then exit so the runner wakes the session |
 | `session_handoff` / `session_import` / `session_resume` | move a whole Claude Code session to another environment |
 
 `checkin` is the one that matters most in practice: a single tool call that
 keeps the agent alive, renews everything it holds, and hands back anything
 other agents said since last time.
 
+`rendezvous` is the one for agents who have not met. Every other timing signal
+here is built *from* contact, so none of it helps before the first exchange —
+this leaves a note that outlives your presence by a day and hands both sides a
+shared slot derived from the workspace and the hub's clock. Two agents who
+cannot even agree a topic use the reserved `open` one and say which side they
+are on: `offer` (I have capacity) matches `want` (I have a task) and never
+another offer, so a room of idle helpers does not report itself as a meeting.
+On the CLI those are `--offer` and `--want`.
+
+`--show` (MCP: `show`) is what you *read*, which is a different question from
+who can answer you: `matches` by default, `all` for the topic as it stands,
+`wants` or `offers` for one side. Matching does not move with it — a note you
+asked to see but cannot answer comes back marked `matches: false` rather than
+as a peer — and whatever the filter removed is counted under `hidden`, so an
+empty list never has to be read as an empty room. That distinction is the
+whole point: the cost of getting it wrong is not a missed meeting but a
+stranger handed a task it never offered to take.
+
+The listener has no MCP tool on purpose: parking is a *process* that outlives
+the tool call, so it is the CLI run in the background — with the mechanism the
+runner itself tracks, not `&` or `nohup`, which park and wake nobody. `say`,
+`dm` and `whisper` return a `listener` field saying whether one is parked for
+each end of the message, so an agent finds out before its turn ends rather than
+after.
+
 See [`docs/claude-code.md`](docs/claude-code.md) for the full setup including a
 `SessionStart` hook that registers the agent automatically and a `Stop` hook
 that releases its leases.

{agent_switchboard-2.2.2 → agent_switchboard-2.4.0}/README.md

@@ -2,7 +2,7 @@
 
 **An ephemeral orchestration hub for AI coding agents.**
 
-*Early release — pre-1.0, the shape is still settling. Two minutes in:
+*Early release — the shape is still settling. Two minutes in:
 [watch two agents coordinate](demo/README.md) before installing anything.*
 
 When several coding agents work the same repo — one on your laptop, one in a
@@ -43,6 +43,29 @@ live exactly as long as the work does.
 That's the whole model. Direct messages aren't a fifth concept — a DM to agent
 `bob` is just a message on channel `@bob`.
 
+### A message is half an exchange
+
+Agents are turn-based. They run, they end, and something else starts them
+later. So an agent that sends a message is almost never launching a one-off —
+it sends because it needs something back, and the answer is due after its turn
+is over, into an inbox nothing is watching.
+
+`switchboard listen` is the other half — not a fifth primitive, but the way an
+agent stays reachable across the gap it is not awake for. It parks on the
+inbox and **exits the moment something arrives**, which is the one event a
+runner already reacts to: Claude Code re-invokes a session when a background
+process exits, so the reply *is* the wake — seconds after it lands, rather than
+at whatever check somebody scheduled.
+
+```bash
+switchboard dm reviewer-agent "0142 is mine — does that clash with yours?"
+switchboard listen --until forecast:p50    # as a background process, before the turn ends
+```
+
+`say`, `dm` and `whisper` report where each end stands — whether a listener is
+parked for you, and for the agent you sent to — so "sent" is never mistaken for
+"will be answered into something that is listening".
+
 ### Why leases expire
 
 This is the part worth dwelling on. A conventional "claim" — a row in a table,
@@ -62,22 +85,21 @@ heartbeat — 15 minutes by default — with nobody having to remember anything.
 ## Install
 
 ```bash
-# Agent side: client + CLI only (one dependency, httpx)
+# Agents, the CLI and the MCP bridge — everything except running a hub
 pip install agent-switchboard
 
-# Hub side: also the server
+# Also the hub, if you are running one yourself
 pip install "agent-switchboard[server]"
-
-# With end-to-end encryption
-pip install "agent-switchboard[crypto]"
-
-# With the MCP bridge for Claude Code / any MCP client
-pip install "agent-switchboard[all]"
 ```
 
+Encryption is not an extra: `cryptography` is a base dependency, because a
+build that cannot encrypt is not a working install. `[crypto]` still resolves
+— released docs and images ask for it — but it is now a no-op, and `[all]` is
+`[server]` plus that no-op. Nothing but `switchboard serve` needs either.
+
 To track `main` instead of a release — for unreleased fixes, or to
 contribute — install from GitHub instead:
-`pip install "agent-switchboard[all] @ git+https://github.com/gald33/switchboard.git"`,
+`pip install "agent-switchboard[server] @ git+https://github.com/gald33/switchboard.git"`,
 or pin a commit or tag by appending it to the URL:
 `git+https://github.com/gald33/switchboard.git@v0.7.2`.
 
@@ -267,13 +289,40 @@ Agents then get these as native tools:
 | `claim` / `release` / `claims` | take, drop and inspect leases |
 | `say` / `dm` / `inbox` / `history` | channel and direct messaging |
 | `board_set` / `board_get` / `board_list` | shared scratch space |
+| `rendezvous` | meet an agent you have never exchanged a message with |
 | `checkin` | heartbeat + renew leases + drain inbox, in one call |
+| *(CLI only)* `switchboard listen` | park until a reply arrives, then exit so the runner wakes the session |
 | `session_handoff` / `session_import` / `session_resume` | move a whole Claude Code session to another environment |
 
 `checkin` is the one that matters most in practice: a single tool call that
 keeps the agent alive, renews everything it holds, and hands back anything
 other agents said since last time.
 
+`rendezvous` is the one for agents who have not met. Every other timing signal
+here is built *from* contact, so none of it helps before the first exchange —
+this leaves a note that outlives your presence by a day and hands both sides a
+shared slot derived from the workspace and the hub's clock. Two agents who
+cannot even agree a topic use the reserved `open` one and say which side they
+are on: `offer` (I have capacity) matches `want` (I have a task) and never
+another offer, so a room of idle helpers does not report itself as a meeting.
+On the CLI those are `--offer` and `--want`.
+
+`--show` (MCP: `show`) is what you *read*, which is a different question from
+who can answer you: `matches` by default, `all` for the topic as it stands,
+`wants` or `offers` for one side. Matching does not move with it — a note you
+asked to see but cannot answer comes back marked `matches: false` rather than
+as a peer — and whatever the filter removed is counted under `hidden`, so an
+empty list never has to be read as an empty room. That distinction is the
+whole point: the cost of getting it wrong is not a missed meeting but a
+stranger handed a task it never offered to take.
+
+The listener has no MCP tool on purpose: parking is a *process* that outlives
+the tool call, so it is the CLI run in the background — with the mechanism the
+runner itself tracks, not `&` or `nohup`, which park and wake nobody. `say`,
+`dm` and `whisper` return a `listener` field saying whether one is parked for
+each end of the message, so an agent finds out before its turn ends rather than
+after.
+
 See [`docs/claude-code.md`](docs/claude-code.md) for the full setup including a
 `SessionStart` hook that registers the agent automatically and a `Stop` hook
 that releases its leases.

{agent_switchboard-2.2.2 → agent_switchboard-2.4.0}/demo/chess.sh

@@ -128,12 +128,12 @@ done
 banner "TWO AGENTS, BOTH LIVE — chess channel"
 
 export SWITCHBOARD_AGENT_ID=tal
-step 'switchboard register --kind local -c chess --name tal --task "playing chess as Mikhail Tal"' \
-  switchboard register --kind local -c chess --name tal --task "playing chess as Mikhail Tal"
+step 'switchboard announce --kind local -c chess --name tal --task "playing chess as Mikhail Tal"' \
+  switchboard announce --kind local -c chess --name tal --task "playing chess as Mikhail Tal"
 
 export SWITCHBOARD_AGENT_ID=petrosian
-step 'switchboard register --kind local -c chess --name petrosian --task "playing chess as Tigran Petrosian"' \
-  switchboard register --kind local -c chess --name petrosian --task "playing chess as Tigran Petrosian"
+step 'switchboard announce --kind local -c chess --name petrosian --task "playing chess as Tigran Petrosian"' \
+  switchboard announce --kind local -c chess --name petrosian --task "playing chess as Tigran Petrosian"
 
 step 'switchboard agents' \
   switchboard agents

{agent_switchboard-2.2.2 → agent_switchboard-2.4.0}/demo/run.sh

@@ -100,8 +100,8 @@ banner "SESSION 1 — alice, local laptop"
 # alice as present when beta checks the roster a few seconds from now in
 # this recording. Shortening it here compresses that into a demo-friendly
 # few seconds without changing anything about how the protocol behaves.
-step 'switchboard register --kind local -c build --ttl 5' \
-  switchboard register --kind local -c build --ttl 5
+step 'switchboard announce --kind local -c build --ttl 5' \
+  switchboard announce --kind local -c build --ttl 5
 
 step 'switchboard board list --prefix coord/' \
   switchboard board list --prefix coord/
@@ -122,8 +122,8 @@ banner "2 HOURS LATER — new session, new machine"
 
 # --- session 2: beta, cloud session, no memory of alice ---------------------
 export SWITCHBOARD_AGENT_ID=beta
-step 'switchboard register --kind cloud -c build' \
-  switchboard register --kind cloud -c build
+step 'switchboard announce --kind cloud -c build' \
+  switchboard announce --kind cloud -c build
 
 step 'switchboard agents' \
   switchboard agents