agent-switchboard 2.0.1__tar.gz → 2.2.0__tar.gz

{agent_switchboard-2.0.1 → agent_switchboard-2.2.0}/ARCS.md

@@ -79,7 +79,7 @@ under pressure.
 
 ### 🟠 The first ten minutes, for somebody who has not read the docs
 
-`setup-and-first-run` · 15 item(s), 10 startable
+`setup-and-first-run` · 18 item(s), 12 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`
 
@@ -102,7 +102,9 @@ wrong says so.
 | item | status | priority |
 |---|---|---|
 | `connect-failure-message` | done | next |
+| `cross-key-rendezvous` | ready | next |
 | `init-writes-rooms-file` | ready | next |
+| `known-rooms-address-book` | done | next |
 | `a-lobby-derived-from-the-key` | ready | — |
 | `clients-that-cannot-post` | ready | — |
 | `every-silent-failure-looks-like-a-quiet-room` | ready | — |
@@ -112,6 +114,7 @@ wrong says so.
 | `presence-ttl-is-not-one-size` | ready | — |
 | `robots-policy-for-public-hosts` | deferred | — |
 | `selective-wake-for-the-listener` | ready | — |
+| `stale-token-in-session-env` | ready | — |
 | `timing-cold-start-in-ephemeral-environments` | deferred | — |
 | `unread-dms-not-shown-outside-mcp` | ready | — |
 | `write-parity-across-surfaces` | ready | — |

{agent_switchboard-2.0.1 → agent_switchboard-2.2.0}/CONTRIBUTING.md

@@ -22,6 +22,8 @@ no service to run for the tests — they spin the app up in-process.
 | `cli.py` | The `switchboard` command. |
 | `mcp_server.py` | MCP stdio bridge — speaks JSON-RPC directly, no SDK. |
 | `config.py` | Env-driven settings and the TTL defaults/ceilings. |
+| `claude_session.py` | Claude Code harness adapter: locate, package, install, resume a session's transcript; stdlib only. |
+| `handoff.py` | Session capsules over the hub: board value + signed pointer; hub-neutral. |
 
 The dependency direction is one-way: `store` knows nothing about HTTP,
 `server` knows nothing about the CLI, and `cli`/`mcp_server` both go through

{agent_switchboard-2.0.1 → agent_switchboard-2.2.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: agent-switchboard
-Version: 2.0.1
+Version: 2.2.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
@@ -306,6 +306,7 @@ Agents then get these as native tools:
 | `say` / `dm` / `inbox` / `history` | channel and direct messaging |
 | `board_set` / `board_get` / `board_list` | shared scratch space |
 | `checkin` | heartbeat + renew leases + drain inbox, in one call |
+| `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

{agent_switchboard-2.0.1 → agent_switchboard-2.2.0}/README.md

@@ -268,6 +268,7 @@ Agents then get these as native tools:
 | `say` / `dm` / `inbox` / `history` | channel and direct messaging |
 | `board_set` / `board_get` / `board_list` | shared scratch space |
 | `checkin` | heartbeat + renew leases + drain inbox, in one call |
+| `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

{agent_switchboard-2.0.1 → agent_switchboard-2.2.0}/docs/claude-code.md

@@ -104,7 +104,7 @@ claude mcp add switchboard \
 ```
 
 Verify with `/mcp` inside Claude Code — you should see `switchboard` connected
-with 14 tools.
+with 26 tools.
 
 ## 4. Tell the agent to use it
 
@@ -286,6 +286,53 @@ switchboard listen --until forecast:p50 --effort medium
 switchboard listen --until +900
 ```
 
+One process parks in the rooms that matter: the one named, the lobby every
+holder of this key shares, and every room this machine was put in lately. That is the default because a parked agent is the most
+reachable it ever is, and a peer on another repo holding the same key has
+nowhere else to look for it. The exit line names both, the wake payload says
+which room the message came from (`room` and `role`, beside `messages`), and a
+message in either is the wake. `--no-lobby` parks in the named room only, for a
+session that specifically does not want to be found while it works; without a
+key there is no lobby to derive, and the listener says so. When both rooms
+have a message in the same instant, the process — not the agent — decides
+which is the wake: the named room today, and a rule that lives in one place
+(`_choose_wake`) if that ever needs to change.
+
+### The rooms this machine knows
+
+A session accumulates rooms — the repo's, one per invite it was handed, a side
+room per `keygen`, another repo's — and the failure that follows is not
+"no listener" but "a listener in the wrong two rooms". So the tool keeps a
+book of them, per machine, at `~/.switchboard/known-rooms.json`
+(`SWITCHBOARD_KNOWN_ROOMS` moves it; empty disables it), written by the
+commands that already hold the coordinates: `init`, `join`, `keygen
+--as-invite`, and any `--invite <command>`. Nothing is asked of the agent.
+
+Two things use it, and they are different questions:
+
+- **Looking for someone.** `switchboard rendezvous <topic>` sweeps every
+  known room as well as this one — read-only, no note left anywhere but here
+  — and reports per room who is there and who has a listener parked.
+  `switchboard find <name or branch>` is the same sweep with a peer in mind.
+  `--here` keeps `rendezvous` to this room. `switchboard --room <label>
+  <command>` then runs one command in the room the sweep pointed at.
+- **Expecting someone.** `listen` parks in this room, the lobby, and every
+  room this machine joined, was invited into or minted in the last hour —
+  without being told. `--in <label>` adds a known room; `--only <label>`
+  parks there and nowhere else.
+
+`switchboard rooms --known` shows the book; `--forget <label>` drops an entry;
+`--label <workspace>=<name>` names one.
+
+**What the book holds is references, never keys.** An entry records how a
+room's key was acquired — the environment variable that holds it, the
+checkout `init` wrote it to, or the invite it arrived as — and the tool
+resolves it the same way at use time. An invite was already in the session's
+context, so keeping it exposes nothing new; a key that never appeared in the
+conversation is never copied into the file, printed, or retyped. A room whose
+key can no longer be found that way is reported as such, not opened in the
+clear.
+
 `forecast:p50` takes the time from the agent's own
 [adaptive-timing](adaptive-timing.md) model — the moment it predicts it would
 next have looked anyway — which turns a forecast from something advisory into
@@ -336,6 +383,156 @@ filled in. One implementation, reachable two ways. The command is the one to
 reach for otherwise: the shim bakes in a single room and cannot leave it, which
 is right for a repo's own agents and wrong for anything crossing repos.
 
+## 7. Hand a whole session to another environment
+
+Everything above moves *facts* between sessions — a claim, a message, a
+payload on the board. Sometimes what should move is the session itself: the
+conversation a laptop started is the one a cloud runner should continue,
+tool results and all, rather than a summary of it the next agent re-derives
+at cold-start prices. A Claude Code session turns out to be portable as one
+file, and Switchboard carries that file the way it carries any other handoff
+— payload on the blackboard, pointer in a message — with nothing added to
+the hub: no endpoint, no schema, no fifth primitive.
+
+The facts this rests on were established empirically and are logged in
+[`extras/session-capsule/README.md`](../extras/session-capsule/README.md);
+the short version is what the code relies on. Claude Code writes every turn,
+tool call and tool result of a session to
+`<config-dir>/projects/<project-key>/<id>.jsonl` — `<config-dir>` is
+`$CLAUDE_CONFIG_DIR`, else `~/.claude`; `<project-key>` is the working
+directory with every character outside `[A-Za-z0-9]` replaced by `-` — plus
+an optional `<id>/` sidecar directory when the session spawned subagents.
+Copy that file under any project key on another machine and `claude --resume
+<id>` continues the conversation there, from a different directory, with no
+path rewriting and no other state. `claude --bg --resume <id>` does the same
+as a background session that `claude attach <short-id>` opens later. The
+transcript is carried byte for byte and never interpreted.
+
+### The flow
+
+On the side handing off — inside the session, where Claude Code exports
+`CLAUDE_CODE_SESSION_ID` and the MCP bridge and hook commands inherit it:
+
+```
+session_handoff  to="<agent id from roster>"
+```
+
+or from a shell, `switchboard session handoff <agent>`, with `<agent>`
+resolved the way `dm` resolves it: a roster id, or a unique name or branch.
+One call exports the session, publishes it on the board under
+`sessions/<session-id>` with a ten-minute TTL (`--ttl` / `ttl` changes it,
+never past the hub's board ceiling), and sends the recipient a signed
+pointer as a direct message. The result says how many bytes went, when the
+capsule expires, and which leases you still hold. Those are listed in the
+pointer and *kept* unless you pass `--release-leases` / `release_leases`:
+the sender is still running when it hands off, the receiver may never
+appear, and a lease nobody holds is exactly the window a third agent walks
+into.
+
+On the side receiving:
+
+```
+session_import                        → installed: [{session_id, resume, …}]
+session_resume  session_id="<id>"     → attach: "claude attach <short-id>"
+```
+
+or `switchboard session receive`, then `switchboard session resume <id>`
+(`--bg` for a background session, `--command` to print the line instead of
+running it). `receive` reads this agent's own inbox — a committed read, so
+the pointer is consumed rather than collected again on every read for ten
+minutes — verifies the pointer's signature against the roster and the
+capsule's sha256 against what the pointer announced, deletes the board
+entry, and only then installs the files. The delete is the claim: the hub
+answers it inside one transaction, so of two receivers exactly one installs
+and the other is told the capsule was taken. Then it sends the sender a
+receipt. On the CLI the files land where the session already lives on this
+machine if it does (the return leg of a round trip), else under the capsule's
+original project key, unless `--cwd` names the directory you will resume
+from; the MCP tool defaults to this session's project directory. Either way
+the id ends up
+under exactly one key, because `claude --resume` refuses to choose between
+duplicates. Other direct messages the read consumed come back as `other`
+rather than being lost.
+
+Local → cloud → local is then three commands and no hub change: `session
+handoff` on the laptop, `session receive` in the cloud session followed by
+`claude --resume`, and the same pair back when the cloud side is done. The
+hub saw two sealed values it cannot name — the pointer's discriminator
+travels inside the sealed body and the message type stays `note`, so not
+even the row type says what moved.
+
+`switchboard session export -o FILE` and `switchboard session import FILE`
+are the two halves with no hub between them: a capsule file, created `0600`
+because it is as private as the transcript it carries, that you move however
+you like.
+
+### What is trusted, and what is not
+
+A transcript is instructions. Whoever resumes it runs a conversation
+somebody else wrote, with their own credentials and their own repo, so the
+rules here are stricter than for any other payload, and each is a refusal
+rather than a warning:
+
+- **Nothing installs from a pointer nobody vouches for.** The sender must be
+  on the roster and the pointer's signature must verify, and the capsule
+  must be the bytes that pointer announced. A pointer that fails either
+  comes back as not installed, with the reason; `--unverified` /
+  `unverified` overrides that, on your own say-so.
+- **Nothing resumes on its own.** `session_import` installs; `session_resume`
+  is a separate call. On the CLI, `session receive --resume` runs `claude
+  --resume` afterwards only for senders named with `--from <agent-id>` (or
+  `--any-sender`), and `--bg` makes that a background session.
+- **A plaintext room is refused.** The hub would hold everything the session
+  read — every file and secret in a tool result — in the clear. Hand off
+  inside a keyed room, or pass `--allow-plaintext` / `allow_plaintext` when
+  the hub is yours and local.
+- **A checkpoint has no sender.** `switchboard session publish` (or
+  `session_handoff` with no `to`) puts the capsule on the board with nobody
+  pointed at it; anyone holding the key can collect it by id — `switchboard
+  session receive <id>`, `session_import(session_id=…)` — while it lasts.
+  That is trusting the room, and the result says so: `verified: null`.
+
+What the design does not protect against, stated plainly. Any holder of the
+room key can delete or replace a board entry — the hub has no owners — so a
+handoff can be made to vanish in transit, though the signature check means
+it cannot be *substituted* without the receiver noticing. In a keyed room
+every `board_list` fetches every value, because keys are blinded and a
+prefix cannot hide one; the ten-minute TTL and the delete-on-claim are what
+bound that cost, and a handoff nobody collected is re-sent, not recovered.
+Version skew between Claude Code releases, and the interactive trust prompt
+on a first resume, are untested. And a session resumed on another host
+derives a different Switchboard agent id unless `SWITCHBOARD_AGENT_ID` is
+pinned: the same conversation, but not, to the roster, the same agent.
+
+### Without a model in the loop
+
+Every step is a plain function, so none of this needs an LLM to drive it. A
+Claude Code `Stop` hook can run `switchboard session handoff <agent>` or
+`switchboard session publish` so a session checkpoints itself — opt-in, and
+deliberately not among the hooks `init` installs, which stay runner-agnostic.
+Know what `Stop` means here: it fires at the end of every response, not once
+when the session ends (the installed Stop hook releases leases on the same
+cadence), so a checkpoint hook publishes a capsule per turn. Give it a short
+`--ttl`; in a keyed room every board listing pays for the capsule until it
+expires. And a parked receiver can loop:
+
+```bash
+export SWITCHBOARD_AGENT_ID=cloud-receiver
+while true; do
+  switchboard session receive --wait 25 --resume --bg --from <sender-id>
+done
+```
+
+`receive` prints `listening as <agent id>` so the sender knows whom to hand
+off to. Pin `SWITCHBOARD_AGENT_ID` for that loop: an unpinned id is derived
+per process, so each iteration would listen somewhere new and a pointer sent
+to the last one is read by nobody. The exit code is what the loop branches
+on — `0` when something was installed (or nothing was pending, without
+`--wait`), `2` when `--wait` elapsed with nothing, and `1` when a pointer or
+an id named a capsule that could not be installed: expired, claimed by
+another receiver, unverified, or not what was announced. That last one is
+the case to log.
+
 ## Tool reference
 
 | Tool | Use it when |
@@ -354,6 +551,9 @@ is right for a repo's own agents and wrong for anything crossing repos.
 | `board_set` / `board_get` / `board_list` | Hand off structured context |
 | `keygen` | Starting a private side-conversation with specific peers — see below |
 | `join_room` | Enter a room somebody sent an invite for — see below |
+| `session_handoff` | Move this whole session to another agent, or with no `to` checkpoint it on the board for anyone holding the key — see section 7 |
+| `session_import` | Collect a session handed to you (or one capsule by id) into this machine's Claude config dir; installs, never resumes |
+| `session_resume` | Start `claude --bg --resume` for an installed session and get the `claude attach` line back. Local; never touches the hub |
 
 ### A room somebody sent you
 

{agent_switchboard-2.0.1 → agent_switchboard-2.2.0}/docs/concepts.md

@@ -134,6 +134,12 @@ which is how you do leader election without a lease.
 Default TTL is 24 hours, the longest in the system, because a handoff has to
 survive the gap between one session ending and the next starting.
 
+A whole Claude Code session can travel the same way, as an opaque capsule
+under `sessions/<session-id>` with a TTL of minutes rather than a day, since
+a transcript is everything the session read; the receiver's tool collects and
+deletes it rather than reading it as text — see
+[claude-code.md](claude-code.md#7-hand-a-whole-session-to-another-environment).
+
 ## Putting it together
 
 The intended shape of an agent's life on a hub:

{agent_switchboard-2.0.1 → agent_switchboard-2.2.0}/docs/encryption.md

@@ -700,8 +700,13 @@ already published.
 > **Named `ask` in 0.11.0.** The name said "question" when the primitive is
 > "sealed to one peer" — you may equally want to *tell* someone something the
 > room should not read. 1.0.0 renamed the tool, CLI command and client method
-> to `whisper`. `Client.ask` still works as a deprecated alias; the CLI takes
-> `whisper` only. The wire format is unchanged, so 0.11.0 peers stay readable.
+> to `whisper` and left the wire alone: the envelope marker, the HKDF label
+> and the AEAD context all still said `ask`, on the reasoning that a name only
+> humans read was not worth a break. **2.1.0 renamed the wire too**, after a
+> second implementation written to the human name opened whispers under the
+> wrong context for four days without an error. A 2.1.0 reader still opens
+> what any earlier release sealed; an earlier reader cannot open a 2.1.0
+> whisper. `Client.ask` is gone. See [upgrading.md](upgrading.md#201--210).
 
 What it costs, stated as plainly as everything above:
 

{agent_switchboard-2.0.1 → agent_switchboard-2.2.0}/docs/quickstart.md

@@ -19,7 +19,7 @@ switchboard serve --port 8787
 You should see:
 
 ```
-switchboard 2.0.1 → http://127.0.0.1:8787  db=switchboard.db
+switchboard 2.2.0 → http://127.0.0.1:8787  db=switchboard.db
 ```
 
 Leave it running.
@@ -47,7 +47,7 @@ export SWITCHBOARD_AGENT_ID=beta
 
 ```bash
 $ switchboard health
-{ "ok": true, "version": "2.0.1", "auth": true }
+{ "ok": true, "version": "2.2.0", "auth": true }
 
 $ switchboard register -c build
 registered local-main-yourhost (local) in demo

{agent_switchboard-2.0.1 → agent_switchboard-2.2.0}/docs/upgrading.md

@@ -3,6 +3,71 @@
 What changes for you between releases that are not backwards compatible, in
 the order you will hit them. Everything not listed here kept its behaviour.
 
+## 2.1.0 → 2.2.0
+
+Additive. A whole Claude Code session can be moved between environments
+through the hub: `switchboard session handoff <agent>` publishes the
+conversation as a capsule sealed to the room, and `switchboard session
+receive` collects it and installs it for `claude --resume`. `export` and
+`import` do the two halves against a file instead. The capsule is a
+blackboard entry that expires on its own and is deleted the moment it is
+collected; the hub never opens it. Nothing that worked in 2.1.0 changed.
+
+The commands are new, so a peer running 2.1.0 or earlier cannot collect a
+capsule you publish and will not recognise the pointer. Both ends need 2.2.0.
+
+## 2.0.1 → 2.1.0
+
+**The whisper envelope says `whisper` on the wire.** From 0.11.0 to 2.0.1 it
+said `ask` in three places a reader never sees — the envelope marker
+`m`, the HKDF label the pair key is derived under, and the AEAD context the
+body is sealed under (`ask.body`) — while the tool, CLI and method had said
+`whisper` since 1.0.0. The split was kept on purpose, to spare a break for a
+name only humans read; it cost more than it saved when a page written to
+the human name opened whispers under `message.body` and every one came back
+unreadable, with no error to say why. Now the wire says what the tool says:
+`m: "whisper"`, `switchboard/v1/whisper`, `whisper.body`.
+
+### Upgrade readers before senders
+
+A 2.1.0 client **opens** everything an earlier one sealed — the marker says
+which names an envelope was sealed under, and the old names are still
+accepted on the way in. The other direction does not hold: **a 2.0.1 client
+cannot open a 2.1.0 whisper**, and reports it `unreadable` exactly as it
+would a sender whose exchange key it has not seen. So upgrade the agents
+that *receive* whispers first, and the ones that send them last. In a room
+where one process does both, upgrade it with everybody it whispers to. The
+hub is not involved — it never opens an envelope — and needs no change.
+
+### `Client.ask` is removed
+
+The deprecated alias for `whisper`, kept since 1.0.0, is gone from the sync
+and async clients. Nothing else answered to the old name any longer. The
+wire `type` `"ask"` a 0.11.0 sender puts on a message still opens.
+
+### Also new, none of it breaking
+
+- **A book of known rooms**, per machine, at `~/.switchboard/known-rooms.json`.
+  Written by `init`, `join`, `keygen --as-invite`, any `--invite` command and
+  any command run inside an `init`-ed checkout. It holds *references* — the
+  variable, the checkout, or the invite a key arrived as — never a key's
+  value. `SWITCHBOARD_KNOWN_ROOMS` moves it; set it empty to disable it.
+  `switchboard rooms --known`, `--forget`, `--label` manage it.
+- **`rendezvous` sweeps every known room** by default, read-only, and reports
+  per room who is there and who has a listener parked; `--here` keeps it to
+  this room. New `switchboard find <name or branch>` is the same sweep with a
+  peer in mind. `--room <label>` runs any command in a known room.
+- **`listen` parks in more than one room**, in one process: this room, the
+  lobby every holder of your key shares, and every room this machine joined,
+  was invited into or minted in the last hour. `--no-lobby`, `--in <label>`
+  and `--only <label>` adjust that. The wake payload keeps `messages` first
+  and adds `room`, `role` and `agent_id`.
+- **Minted keys never start with a hyphen**, so `--key <key>` cannot be read
+  as a flag. Existing keys are unaffected.
+- **The coordination skill is a third the length**, with one table naming
+  every primitive on both surfaces; `init` upgrades an installed copy in
+  place, as it does for every recorded revision.
+
 ## 2.0.0 → 2.0.1
 
 Server only. The hub's CORS allow-list now includes the two write-key