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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: agent-switchboard
-Version: 2.2.0
+Version: 2.2.1
 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

{agent_switchboard-2.2.0 → agent_switchboard-2.2.1}/docs/adaptive-timing.md

@@ -48,7 +48,7 @@ is never a commitment, and no agent is required to obey another's forecast.
   machines. It is shared by every repo on that machine, but every read and
   write is keyed by `(agent_id, workspace)` — and `workspace` defaults to
   the git remote's org/repo — so history never bleeds from one repo into
-  another's forecasts. `agent_id` derives from kind/branch/hostname, so the
+  another's forecasts. `agent_id` derives from kind/hostname/session, so the
   same person on two laptops builds two independent histories that converge
   separately. All of that is deliberate: the premise is that timing is
   local and personal, and a shared or committed history would be neither.

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

@@ -466,6 +466,65 @@ 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.
 
+### If you work in the desktop app
+
+Installing the transcript is the whole job for a CLI user and half of one for
+everybody else. The desktop app keeps its own list of sessions beside the
+transcripts, so a conversation whose transcript is installed but whose record
+is not exists on disk and is invisible in the app — which is exactly what
+happened the first time a session was handed from a cloud agent to a laptop:
+it resumed perfectly on the command line and could not be found in the app the
+recipient actually used.
+
+So `switchboard init` asks, once, on a machine that runs the app: should a
+session handed to you also appear in its sidebar? Say yes and `receive` writes
+the record too. The question is asked at setup rather than per handoff for two
+reasons — it writes into another program's store, which is a thing to agree to
+deliberately, and the account and project the row is filed under are ids that
+app assigns, discoverable only where it runs. A cloud runner has neither, so
+the step is silently skipped there.
+
+`switchboard session register <id>` does it for a session already installed,
+and `session unregister <id>` is the undo. Prefer that over deleting the row
+inside the app: in-app delete and archive both write a release marker next to
+the transcript which the CLI acts on, while unregister removes only the record.
+
+Two things worth knowing. The app reads its store at launch, so a registered
+session appears after the next restart rather than immediately. And this is an
+undocumented format belonging to another program: `switchboard.desktop` says
+which app version it was verified against, keeps every detail in that one
+module, and answers "not here" rather than guessing when the shape is not what
+it expects.
+
+### What travels, and what a reader can take out
+
+The subagent transcripts in the `<id>/` sidecar travel by default, and that
+is the trade worth naming because it is not the obvious one. They are most
+of a capsule's bytes — three quarters of it is normal — and none of its
+resume: `claude --resume` reads the main transcript alone, so the sidecar
+costs the receiver no context at cold start. What it buys is retrievability.
+A subagent's transcript is finished work, often millions of tokens of it,
+that the receiving session can go and read *if it needs to* rather than
+re-derive at model prices. Bytes on a board with a ten-minute TTL are the
+cheap side of that trade, so the default is on.
+
+`--no-subagents` (`no_subagents` on `session_handoff`) drops them, for a slow
+link or a receiver that only needs the conversation continued. The capsule
+records that it did, as `omitted_subagent_files`, because a session that
+never spawned a subagent and one whose subagents were left behind both
+arrive as a single file, and a receiver deciding whether to ask again needs
+to tell those apart.
+
+A capsule can also be collected with no Switchboard on the machine at all.
+The [viewer](../extras/viewer/) already holds the plaintext — it fetched the
+board entry and opened it with the room key, which is why a sealed value is
+legible there — so a board entry it could open offers a **save** button that
+writes the value out as a file. Feed that file to `switchboard session
+import FILE` wherever the tooling *is* installed. It asks the hub for
+nothing extra, and it is the one path to a handoff for a human with a
+browser and no checkout. Where the page could not open a value it offers
+nothing: a file of envelope bytes would look like the value and is not.
+
 ### What is trusted, and what is not
 
 A transcript is instructions. Whoever resumes it runs a conversation

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

@@ -43,20 +43,23 @@ An agent registers itself (id, name, kind, branch, current task) and then
 heartbeats. If it stops heartbeating, it disappears from the roster within its
 TTL — two minutes by default.
 
-The agent id is inferred from `kind`, git branch and hostname, so a session
-that restarts on the same branch reclaims its own identity rather than
-appearing as a stranger. Override it with `SWITCHBOARD_AGENT_ID` when you want
-something specific.
+The agent id is inferred from `kind`, hostname and a hash of the session id,
+so a session that resumes reclaims its own identity — its leases, its read
+cursor — rather than appearing as a stranger. Two sessions on one machine get
+different ids, because the session is part of the derivation. Override it with
+`SWITCHBOARD_AGENT_ID` when you want something specific.
 
 `kind` is auto-detected as `ci` (in GitHub Actions), `cloud` (in a remote
 Claude Code session or a Codespace) or `local`.
 
-Because the inferred id has no process or session component, two sessions
-that share `kind`, branch and hostname — two terminals on the same checkout,
-say — collide on the same agent id. They are indistinguishable to the hub:
-same presence row, same lease ownership, same message cursor. If you run
-more than one session against the same branch and host, set
-`SWITCHBOARD_AGENT_ID` explicitly for at least one of them.
+**The branch is deliberately not part of the id.** It is registered as its own
+field, which is what `dm` resolves a typed branch name against — so it says
+where an agent is *now* and follows it across a checkout, while the id stays
+put. An id has to outlive the session's whole life: it is what the signer
+socket is keyed on, what the roster stores a public key against, what holds a
+lease and what owns a read cursor. Folding the branch in meant that checking
+one out — the most ordinary thing an agent does — minted a second identity and
+orphaned all four.
 
 ## Leases
 

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

@@ -19,7 +19,7 @@ switchboard serve --port 8787
 You should see:
 
 ```
-switchboard 2.2.0 → http://127.0.0.1:8787  db=switchboard.db
+switchboard 2.2.1 → http://127.0.0.1:8787  db=switchboard.db
 ```
 
 Leave it running.
@@ -35,7 +35,7 @@ export SWITCHBOARD_WORKSPACE=demo
 ```
 
 In the second terminal, give the agent a distinct identity so you can tell them
-apart (normally this is inferred from branch and hostname):
+apart (normally this is inferred from your host and session):
 
 ```bash
 export SWITCHBOARD_AGENT_ID=beta
@@ -47,7 +47,7 @@ export SWITCHBOARD_AGENT_ID=beta
 
 ```bash
 $ switchboard health
-{ "ok": true, "version": "2.2.0", "auth": true }
+{ "ok": true, "version": "2.2.1", "auth": true }
 
 $ switchboard register -c build
 registered local-main-yourhost (local) in demo

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

@@ -3,6 +3,50 @@
 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.2.0 → 2.2.1
+
+**Your agent ids change once.** An id was `kind-branch-host-session`; the
+branch is gone from it, so it is now `kind-host-session`. The branch was in
+there from when it was the only thing telling two sessions apart — the
+session suffix took that job and left the branch behind as decoration, and
+decoration with teeth: an id is what the signer socket is keyed on, what the
+roster stores a public key against, what holds a lease and what owns a read
+cursor. Checking out a branch, the most ordinary thing an agent does, minted
+a second identity and orphaned all four.
+
+Nothing to do about it. On first announce after upgrading, an agent appears
+under its new id; the row under the old one stops being refreshed and lapses
+on the presence TTL like any other. **Leases and read cursors held by the old
+id are not transferred** — a lease expires on its own TTL (15 minutes by
+default) and a cursor's cost is one repeated read. If you cannot wait for a
+lease to lapse, release it before upgrading, or pin `SWITCHBOARD_AGENT_ID`
+across the upgrade to keep the id you had.
+
+Branch-based lookup is unaffected: `dm` and the other recipient resolvers
+match the roster's own `branch` field, registered on every announce, which
+follows an agent across a checkout in a way an id baked at startup never
+did. A name still says the branch if you registered it that way.
+
+`client.identity_drift_warning` is now `client.rootless_warning`, and warns
+about a different thing. It existed for this bug's directory half — outside a
+checkout the branch read as `detached` and the id moved — which no longer
+happens. What still drifts outside a checkout is the *workspace*, derived
+from the directory when there is no remote to read, which puts the agent in a
+different room entirely; that is what the renamed function now says.
+
+Also fixed: an option value beginning with `-` no longer has to be escaped
+by hand. `switchboard session receive --from <agent-id>` and `board list
+--prefix <key>` died on "expected one argument" for about one id in
+sixty-six, because ids and board keys are base64url and argparse will not
+read a dash-leading token as an option's value. Both now work as typed —
+the same repair `dm -yLAoQ63…` already had for positionals, extended to the
+other half of the problem.
+
+Additive in the same release: `--no-subagents` on `session export`,
+`handoff` and `publish` (`no_subagents` on `session_handoff`) leaves the
+subagent transcripts out of a capsule, and the viewer can save an opened
+board value to a file. Neither changes an existing default.
+
 ## 2.1.0 → 2.2.0
 
 Additive. A whole Claude Code session can be moved between environments

{agent_switchboard-2.2.0 → agent_switchboard-2.2.1}/docs/viewer.md

@@ -104,6 +104,16 @@ the rest: the whole key, who wrote it and when, and a value that keeps its own
 line breaks instead of being folded to fit. The sidebar itself now widens with
 the screen rather than staying 340px on every one.
 
+An opened entry also offers **save**, which writes the value out as a file
+named after its key. The page is already holding the plaintext — it fetched
+the entry and opened it with the room key, which is the whole reason a sealed
+value is legible here — so this asks the hub for nothing and needs no CLI. It
+is how a person with a browser and no checkout collects a
+[session capsule](claude-code.md#7-hand-a-whole-session-to-another-environment)
+and feeds it to `switchboard session import` somewhere else. A value this page
+could not open offers no button: a file of envelope bytes would look like the
+value and is not.
+
 Each of the three side panels says how much is inside it and folds away, and
 what you fold stays folded. On a window too narrow for two columns they stop
 being a stack under the conversation — where, the talking being long and never

{agent_switchboard-2.2.0 → agent_switchboard-2.2.1}/extras/viewer/switchboard_viewer/web/index.html

@@ -139,6 +139,13 @@
   .detail .meta { color: var(--dim); font-size: 12px; margin: 4px 0 14px;
                   display: flex; flex-wrap: wrap; gap: 4px 12px; }
   .detail .body, .detail pre { font-size: 13px; }
+  /* Quiet until wanted: a board value is usually read, not taken, and a
+     download button competing with the value would say otherwise. */
+  .detail .meta .save { border: 1px solid var(--line); border-radius: 6px;
+                        background: transparent; color: var(--dim); font: inherit;
+                        font-size: 12px; padding: 0 8px; cursor: pointer; }
+  .detail .meta .save:hover, .detail .meta .save:focus-visible {
+                        color: var(--accent); border-color: var(--accent); }
   .detail .nothing { color: var(--dim); font-size: 13px; }
   /* A key is the row's own text, so it reads as text — and as something that
      does something only where it does something. */

{agent_switchboard-2.2.0 → agent_switchboard-2.2.1}/extras/viewer/switchboard_viewer/web/render.js

@@ -513,6 +513,8 @@ function drawDetail(s) {
       <span>${who(entry.updated_by)}</span>
       <span>${stamp(entry.updated_at)}</span>
       <span>expires in ${countdown(entry.expires_in, s.generated_at)}</span>
+      ${readable(entry) ? `<button class="save" type="button"
+        data-save="${esc(entry.key)}">save</button>` : ""}
     </div>
     ${bodyHtml(entry.value)}`;
   if (pane.dataset.html !== html) {
@@ -521,6 +523,49 @@ function drawDetail(s) {
   }
 }
 
+/** Whether this page holds the entry's plaintext at all.
+ *
+ *  A value that could not be opened arrives as `null` — the builder drops the
+ *  envelope rather than let ciphertext render as content — and that is the
+ *  condition to check, not `sealed`, which only says whether the *key* stayed
+ *  a blinded token. Without a room key nothing is unblinded, so `sealed` is
+ *  false for every entry in a room this page cannot read: exactly the rooms
+ *  where offering to save one would write out a file that is not the value.
+ */
+function readable(entry) {
+  return Boolean(entry) && entry.value !== null && entry.value !== undefined;
+}
+
+/** Hand the reader the value they are already looking at, as a file.
+ *
+ *  The page has the plaintext: it fetched the entry and opened it with the
+ *  room key, which is the whole reason a sealed value is legible here at all.
+ *  Writing it out asks the hub for nothing and needs no checkout, no CLI and
+ *  no agent — which is the point. A session capsule saved from here goes
+ *  straight into `switchboard session import`, so a human with a browser can
+ *  collect a handoff that no tooling on their machine could.
+ *
+ *  Named after the key so the file says what it is, and `.json` when the
+ *  value is structured, because everything worth saving from a board is.
+ */
+function saveEntry(key) {
+  const entry = (last?.board || []).find((e) => e.key === key);
+  if (!readable(entry)) return;
+  const structured = typeof entry.value !== "string";
+  const text = structured ? JSON.stringify(entry.value, null, 2) : entry.value;
+  const name = `${key.replace(/[^A-Za-z0-9._-]+/g, "-").replace(/^-+|-+$/g, "")
+                 || "board-entry"}${structured ? ".json" : ".txt"}`;
+  const url = URL.createObjectURL(
+    new Blob([text], { type: structured ? "application/json" : "text/plain" }));
+  const a = document.createElement("a");
+  a.href = url;
+  a.download = name;
+  a.click();
+  // Same turn would race the click on some browsers; the next one is safe and
+  // still prompt enough that nothing accumulates.
+  setTimeout(() => URL.revokeObjectURL(url), 0);
+}
+
 export function render(s, { onRoom, onClose } = {}) {
   last = s;
   if (onRoom || onClose) handlers = { onRoom, onClose };
@@ -784,6 +829,11 @@ export function render(s, { onRoom, onClose } = {}) {
         scopeChanged();
         return;
       }
+      const save = e.target.closest("[data-save]");
+      if (save) {
+        saveEntry(save.dataset.save);
+        return;
+      }
       const entry = e.target.closest("[data-board]");
       if (entry) {
         opened = entry.dataset.board;

{agent_switchboard-2.2.0 → agent_switchboard-2.2.1}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "agent-switchboard"
-version = "2.2.0"
+version = "2.2.1"
 description = "An ephemeral orchestration hub for AI coding agents: presence, leases, messaging and a shared blackboard, all with TTLs."
 readme = "README.md"
 requires-python = ">=3.10"

{agent_switchboard-2.2.0 → agent_switchboard-2.2.1}/src/switchboard/__init__.py

@@ -47,7 +47,7 @@ from .store import (
 from .timing import unwrap_forecast, wrap_forecast
 from .writekey import RoomWriteKey, generate_write_key
 
-__version__ = "2.2.0"
+__version__ = "2.2.1"
 
 __all__ = [
     "Invite",

{agent_switchboard-2.2.0 → agent_switchboard-2.2.1}/src/switchboard/claude_session.py

@@ -268,6 +268,7 @@ def package(
     *,
     config_dir: str | os.PathLike[str] | None = None,
     cwd: str | os.PathLike[str] | None = None,
+    subagents: bool = True,
 ) -> dict[str, Any]:
     """Build a capsule for a session found under this machine's config dir.
 
@@ -275,6 +276,19 @@ def package(
     (rare: it means the session was already imported here from elsewhere).
     Nothing is modified; the transcript is read as it is, which inside a live
     session means up to the tool call that asked for the export.
+
+    ``subagents`` carries the sidecar directory — every subagent's own
+    transcript — and defaults to on, which looks expensive and is not. Those
+    files are most of the bytes (three quarters, on a session that ran a
+    couple of workflows) and none of them are needed to resume: ``--resume``
+    reads the main transcript alone, so they cost the receiving model no
+    context at all. What they are is the work already done, at rest: one
+    session here carried 153 subagent transcripts holding some five million
+    tokens of finished analysis for six megabytes on the wire. Dropping them
+    saves a transfer nobody notices and throws away the answer to "why did we
+    reject that finding?", which otherwise has to be bought again. Turn it
+    off for a slow link or a receiver that only needs the conversation; the
+    capsule then says so, rather than arriving quietly short.
     """
     session_id = valid_session_id(session_id)
     cfg = _resolve_config_dir(config_dir)
@@ -307,10 +321,14 @@ def package(
         })
 
     add(transcript, f"{session_id}.jsonl")
+    omitted = 0
     if sidecar.is_dir():
         for path in sorted(sidecar.rglob("*")):
             if path.is_file() and not path.is_symlink():
-                add(path, f"{session_id}/{path.relative_to(sidecar).as_posix()}")
+                if subagents:
+                    add(path, f"{session_id}/{path.relative_to(sidecar).as_posix()}")
+                else:
+                    omitted += 1
 
     meta = transcript_metadata(transcript)
     return {
@@ -323,6 +341,11 @@ def package(
         "exported_at": time.strftime("%Y-%m-%dT%H:%M:%SZ", time.gmtime()),
         "stats": {k: meta[k] for k in ("records", "user_messages", "assistant_messages")},
         "files": files,
+        # Recorded rather than inferred from the file list: a session that
+        # never spawned a subagent and one whose subagents were dropped both
+        # arrive with a single file, and a receiver deciding whether to ask
+        # for them again needs to tell those apart.
+        **({"omitted_subagent_files": omitted} if omitted else {}),
     }