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

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

@@ -79,7 +79,7 @@ under pressure.
 
 ### 🟠 The first ten minutes, for somebody who has not read the docs
 
-`setup-and-first-run` · 18 item(s), 12 startable
+`setup-and-first-run` · 19 item(s), 13 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,6 +101,7 @@ wrong says so.
 
 | item | status | priority |
 |---|---|---|
+| `automatic-session-checkpoints` | ready | next |
 | `connect-failure-message` | done | next |
 | `cross-key-rendezvous` | ready | next |
 | `init-writes-rooms-file` | ready | next |

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: agent-switchboard
-Version: 2.2.1
+Version: 2.2.2
 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.1 → agent_switchboard-2.2.2}/docs/claude-code.md

@@ -466,6 +466,44 @@ 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 a handoff cannot reach, and what to send instead
+
+A handoff lands a transcript on a filesystem. That covers every environment
+where a session can run a shell — your laptop, another machine, a cloud
+container — because the receiving side collects the capsule and
+`claude --resume` finds it. The first real handoff went cloud-container to
+laptop that way.
+
+It does not reach a session running in Claude's own cloud, and it is worth
+saying why rather than leaving somebody to discover it. Checked against CLI
+2.1.259 on 2026-09-05: `--cloud <session_id>` **attaches** to a cloud session
+that already exists, `--environment ccpool_…` creates a **new** one on a
+self-hosted pool, and neither takes a transcript. The `/move-to-cloud` and
+`/teleport` commands exist in the binary but are registered only for an
+interactive terminal, and the teleport path seeds a fresh session with a
+written summary rather than the conversation. There is no endpoint anywhere
+that accepts a transcript, so a conversation cannot be uploaded to become a
+cloud session, and nothing in this repo pretends otherwise.
+
+Two things do work in that direction, and between them they cover most of
+what people want from it.
+
+**Consult it.** A cloud container can run `session receive` like anything
+else. The transcript lands on its disk and the session *reads* it — greps for
+the decision it needs, opens the twenty records that matter — instead of
+resuming it. This is not a workaround for the missing upload: a 4.5 MB
+transcript could not be injected into a context window even if an endpoint
+existed, and consulting on demand is the only shape that scales.
+
+**Send the shape of it.** `switchboard session brief <id>` prints what a
+session was for, read off the record rather than retold by a model: what the
+human asked, which files were touched, how it worked. On the first real
+handoff that is 960 bytes out of 4.5 MB, and it fits in a message you can
+paste anywhere — including a cloud session in a browser that no capsule can
+reach. The filtering is the substance: Claude Code writes tool results, hook
+output and notifications as `user` records too, so 285 user turns there
+contain 14 things a human actually typed.
+
 ### If you work in the desktop app
 
 Installing the transcript is the whole job for a CLI user and half of one for

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

@@ -19,7 +19,7 @@ switchboard serve --port 8787
 You should see:
 
 ```
-switchboard 2.2.1 → http://127.0.0.1:8787  db=switchboard.db
+switchboard 2.2.2 → 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.2.1", "auth": true }
+{ "ok": true, "version": "2.2.2", "auth": true }
 
 $ switchboard register -c build
 registered local-main-yourhost (local) in demo

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

@@ -47,6 +47,18 @@ Additive in the same release: `--no-subagents` on `session export`,
 subagent transcripts out of a capsule, and the viewer can save an opened
 board value to a file. Neither changes an existing default.
 
+## 2.2.1 → 2.2.2
+
+Additive. `switchboard session brief <id>` prints what a session was for —
+the human's instructions, the files touched, the tools used — read off the
+transcript rather than retold by a model. It exists for the place a capsule
+cannot reach: a session running in Claude's own cloud, which accepts no
+transcript through any endpoint. On a 4.5 MB transcript the brief is under a
+kilobyte, so it fits in a message you can paste anywhere.
+
+`docs/claude-code.md` now states plainly what a handoff can and cannot reach,
+checked against Claude Code 2.1.259. Nothing that worked in 2.2.1 changed.
+
 ## 2.1.0 → 2.2.0
 
 Additive. A whole Claude Code session can be moved between environments

{agent_switchboard-2.2.1 → agent_switchboard-2.2.2}/extras/viewer/pyproject.toml

@@ -19,7 +19,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "switchboard-viewer"
-version = "0.10.0"
+version = "0.11.0"
 description = "A read-only page showing your Switchboard rooms to a human: who is awake, what is claimed, and the conversation as it happens."
 readme = "README.md"
 requires-python = ">=3.10"

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

@@ -1,6 +1,6 @@
 [project]
 name = "agent-switchboard"
-version = "2.2.1"
+version = "2.2.2"
 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.1 → agent_switchboard-2.2.2}/roadmap/ROADMAP.md

@@ -17,8 +17,12 @@ Claim before starting: `roadmap claim <key>`
   - ↔ related: **`init-writes-rooms-file`** — Both decide where a room identifier is allowed to live. This one is about an identifier that should not have been committed; that one proposes that `init` start committing a rooms record carrying a workspace token by default. Settle the rule here first, or `init` ships the same mistake as the default for every adopter.
   - ↔ related: **`read-only-rooms`** — Half of that item — anyone who can read the repo can post as CI — is closed by minting the CI room write-protected: the identifier can stay committed, since knowing it no longer lets anyone write into it. The other half, sealing what CI announces, is unchanged.
 - `now` **`stale-resolver-references`** — Delete the comments describing auth machinery that no longer exists
+- `next` **`automatic-session-checkpoints`** — A session that ends anywhere is collectable everywhere, without anyone running a command
+  - ↔ related: **`cross-key-rendezvous`** — Shares the addressing problem from the other end. That one asks how a stranger finds you; this one asks which of several checkpoints is the one you meant. Both resolve to "the tool decides, the agent does not choose", so settle the rule in one place rather than twice.
+  - ↔ related: **`selective-wake-for-the-listener`** — Both are about a session being reachable across a gap the agent is not awake for. That one wakes a parked session when a message lands; this one makes sure the session's own context survives the gap at all. Read that one first for the hook and background-process conventions this must follow.
 - `next` **`cross-key-rendezvous`** — Two agents that share no key have no room to meet in, and a human had to carry the coordinates
   - ↔ related: **`a-lobby-derived-from-the-key`** — That one made the lobby unguessable by deriving it from the key, deliberately rejecting a well-known room. This is the cost of that decision, observed: holders of different keys have no lobby in common. Read it first; the fix here keeps its rejection and works around it, rather than reopening it.
+  - ↔ related: **`automatic-session-checkpoints`** — Shares the addressing problem from the other end. That one asks how a stranger finds you; this one asks which of several checkpoints is the one you meant. Both resolve to "the tool decides, the agent does not choose", so settle the rule in one place rather than twice.
   - ↔ related: **`known-rooms-address-book`** — That one gives a project a room strangers can find. This is what an agent does with rooms once it knows them: a published meeting room, an invite it was handed, a side room it minted, its repo rooms — one list, swept when searching, chosen from when parking. Do that one first; this consumes what it publishes.
   - ↔ related: **`selective-wake-for-the-listener`** — The other half of the same evening: a turn-based session that cannot park a listener returns on shared slots instead, which worked. Meeting failed one layer up — there was no shared room for the slots to be in.
 - `next` **`init-writes-rooms-file`** — Make init produce the rooms record the model says is authoritative
@@ -60,6 +64,7 @@ Claim before starting: `roadmap claim <key>`
   - ↔ related: **`every-silent-failure-looks-like-a-quiet-room`** — The symptom when this fires is a 401 on the published credential, which two agents spent a day mis-attributing — first to a stale client, then to a perimeter that had moved. Read that item for why a wrong credential is hard to tell from a quiet room.
 - **`selective-wake-for-the-listener`** — Wake the listener on what matters, and on the time it promised, not on every message
   - ↔ related: **`a-lobby-derived-from-the-key`** — What makes a lobby worth having rather than merely tidy: an agent parked with `listen` is visible on a roster, so a lobby is a place peers can actually be found waiting rather than a room that is empty whenever nobody is mid-turn.
+  - ↔ related: **`automatic-session-checkpoints`** — Both are about a session being reachable across a gap the agent is not awake for. That one wakes a parked session when a message lands; this one makes sure the session's own context survives the gap at all. Read that one first for the hook and background-process conventions this must follow.
   - ↔ related: **`cross-key-rendezvous`** — The other half of the same evening: a turn-based session that cannot park a listener returns on shared slots instead, which worked. Meeting failed one layer up — there was no shared room for the slots to be in.
   - ↔ related: **`every-silent-failure-looks-like-a-quiet-room`** — Cause 8 below is a defect in what that item builds on — a parked listener watches the inbox of the id it started under, and a `git checkout` re-derives that id without telling either side. The fix belongs in `listen`, not here.
   - ↔ related: **`known-rooms-address-book`** — Same primitive, other axis. That one is about which *messages* wake a parked listener; this is about which *rooms* it is parked in, and why it need not be all of them.
@@ -110,6 +115,7 @@ _Nothing blocked._
 graph TD
   a_lobby_derived_from_the_key["Give every key a lobby, so agents that share one can find each other without naming a room"]
   abuse_control_after_authorization["Replace the abuse control that per-token authorization used to provide"]
+  automatic_session_checkpoints["A session that ends anywhere is collectable everywhere, without anyone running a command"]
   board_ttl_ceiling["Decide whether a board value has earned seven times a lease's lifetime"]
   ci_workspace_is_public["Stop publishing the one room identifier that was never meant to be guessable"]
   clients_that_cannot_post["Decide what a client that cannot hold a secret or issue arbitrary HTTP gets"]
@@ -144,6 +150,8 @@ graph TD
   a_lobby_derived_from_the_key -.- one_resolved_context_across_surfaces
   a_lobby_derived_from_the_key -.- selective_wake_for_the_listener
   abuse_control_after_authorization -.- ci_workspace_is_public
+  automatic_session_checkpoints -.- cross_key_rendezvous
+  automatic_session_checkpoints -.- selective_wake_for_the_listener
   board_ttl_ceiling -.- ttl_clamped_silently
   ci_workspace_is_public -.- init_writes_rooms_file
   ci_workspace_is_public -.- read_only_rooms
@@ -282,6 +290,95 @@ graph TD
 
 </details>
 
+### `automatic-session-checkpoints`
+
+- **title:** A session that ends anywhere is collectable everywhere, without anyone running a command
+- **status:** ready
+- **arc:** setup-and-first-run
+- **priority:** next
+- **related to** (not a dependency — both are startable):
+  - `cross-key-rendezvous` — Shares the addressing problem from the other end. That one asks how a stranger finds you; this one asks which of several checkpoints is the one you meant. Both resolve to "the tool decides, the agent does not choose", so settle the rule in one place rather than twice.
+  - `selective-wake-for-the-listener` — Both are about a session being reachable across a gap the agent is not awake for. That one wakes a parked session when a message lands; this one makes sure the session's own context survives the gap at all. Read that one first for the hook and background-process conventions this must follow.
+- **refs:**
+  - `src/switchboard/handoff.py`
+  - `src/switchboard/claude_session.py`
+  - `docs/claude-code.md`
+  - `https://github.com/gald33/switchboard/pull/229`
+
+<details><summary>evidence</summary>
+
+> **Inferred from a design conversation on 2026-09-05, after the first real
+> handoff the night before.** Nothing is broken; the mechanism works. What this
+> item records is what the working mechanism still asks of a human, and one
+> fragility that only shows up when something goes wrong.
+>
+> **The question that started it: how does Cursor move sessions between cloud
+> and local so smoothly, and can we?** Reading Cursor's own store on a machine
+> that runs it answers the first half. Its `conversations` table tags each row
+> with a `source` — 496 `local` against 47 `cloud-cache` on the machine
+> inspected — the cloud ones carry a server-side `scope` hash the local ones
+> lack, the table has `root_fingerprint` and `cache_fingerprint` columns, and a
+> `conversation_search_reconciliation` table holds a sync `cursor`. That is a
+> client cache over a server-authoritative store. Cursor does not move a
+> session between cloud and local; both ends are clients of one record its
+> servers hold, so there is nothing to move.
+>
+> **That is exactly the trade Switchboard must not make.** Copying it means the
+> hub storing transcripts it currently cannot read, which is the single
+> property the whole design exists to protect (`docs/model.md`). The local-first
+> choice is what let a session cross from a cloud container to a laptop on
+> 2026-09-04 between two agents sharing no account, sealed with a key the hub
+> never saw. A cache-and-sync design cannot do that, because the server has to
+> hold the conversation in order to synchronise it.
+>
+> **So the achievable version of "seamless" is not shared storage — it is that
+> nobody types a command.** A Cursor user does not experience syncing; they
+> experience "it was there". That experience needs the handoff to happen at the
+> boundaries automatically, and every part is already built:
+>
+> - `session publish` with no recipient is already a **checkpoint** — the
+>   capsule goes up sealed, addressed to nobody, collectable by anyone holding
+>   the room's key, which in practice is your own other machines
+>   (`handoff.py`).
+> - `init` already installs `SessionStart` and `Stop` hooks
+>   (`cli.py`, `_session_start_cmd` / `_stop_cmd`).
+> - `session receive` already takes `--wait`.
+>
+> Wiring them is the work: checkpoint on `Stop` and on going idle, collect on
+> `SessionStart`.
+>
+> **And it closes a fragility, which is the stronger half of the case.** A
+> handoff is explicit today, so a session that dies unexpectedly leaves nothing
+> behind — the 2026-09-04 transfer survived only because the cloud agent chose
+> to publish before it finished. Cursor survives that case because the server
+> already holds the conversation. Periodic self-checkpointing is how a
+> local-first design gets the same durability without giving anything away: the
+> last checkpoint is always collectable and expires on its own, so nothing
+> accumulates on the hub.
+>
+> **The open question, and the reason this is an item rather than a patch.**
+> Addressing. When several sessions have checkpointed, a starting session must
+> not collect all of them, and "the newest" is not obviously right either.
+> `--from` and sender verification are the raw material; the rule is not
+> decided. Most likely: the most recent checkpoint for **this repo** from **this
+> account**, with everything else needing to be asked for by id. Settle it
+> together with `cross-key-rendezvous`, which has the same shape of question.
+>
+> **What this must not promise, and the docs should say so rather than let
+> somebody find out.** Two live sessions cannot edit one conversation: without
+> an authority to reconcile against, a handoff is a baton and not a mirror.
+> Continuity is only as good as the checkpoint interval. And a transcript is
+> large — the first real one was 19.8 MB across 175 files — so checkpointing
+> every turn is not free, which argues for idle and end-of-session rather than
+> continuous.
+>
+> **Done when** a session that ends on one machine is collectable on another
+> with nobody running `handoff` or `receive`, when a session killed without
+> warning still leaves a collectable checkpoint, and when the addressing rule is
+> written down and tested rather than left to whoever calls `receive` first.
+
+</details>
+
 ### `board-ttl-ceiling`
 
 - **title:** Decide whether a board value has earned seven times a lease's lifetime
@@ -484,6 +581,7 @@ graph TD
 - **priority:** next
 - **related to** (not a dependency — both are startable):
   - `a-lobby-derived-from-the-key` — That one made the lobby unguessable by deriving it from the key, deliberately rejecting a well-known room. This is the cost of that decision, observed: holders of different keys have no lobby in common. Read it first; the fix here keeps its rejection and works around it, rather than reopening it.
+  - `automatic-session-checkpoints` — Shares the addressing problem from the other end. That one asks how a stranger finds you; this one asks which of several checkpoints is the one you meant. Both resolve to "the tool decides, the agent does not choose", so settle the rule in one place rather than twice.
   - `known-rooms-address-book` — That one gives a project a room strangers can find. This is what an agent does with rooms once it knows them: a published meeting room, an invite it was handed, a side room it minted, its repo rooms — one list, swept when searching, chosen from when parking. Do that one first; this consumes what it publishes.
   - `selective-wake-for-the-listener` — The other half of the same evening: a turn-based session that cannot park a listener returns on shared slots instead, which worked. Meeting failed one layer up — there was no shared room for the slots to be in.
 - **refs:**
@@ -1744,6 +1842,7 @@ graph TD
 - **arc:** setup-and-first-run
 - **related to** (not a dependency — both are startable):
   - `a-lobby-derived-from-the-key` — What makes a lobby worth having rather than merely tidy: an agent parked with `listen` is visible on a roster, so a lobby is a place peers can actually be found waiting rather than a room that is empty whenever nobody is mid-turn.
+  - `automatic-session-checkpoints` — Both are about a session being reachable across a gap the agent is not awake for. That one wakes a parked session when a message lands; this one makes sure the session's own context survives the gap at all. Read that one first for the hook and background-process conventions this must follow.
   - `cross-key-rendezvous` — The other half of the same evening: a turn-based session that cannot park a listener returns on shared slots instead, which worked. Meeting failed one layer up — there was no shared room for the slots to be in.
   - `every-silent-failure-looks-like-a-quiet-room` — Cause 8 below is a defect in what that item builds on — a parked listener watches the inbox of the id it started under, and a `git checkout` re-derives that id without telling either side. The fix belongs in `listen`, not here.
   - `known-rooms-address-book` — Same primitive, other axis. That one is about which *messages* wake a parked listener; this is about which *rooms* it is parked in, and why it need not be all of them.

agent_switchboard-2.2.2/roadmap/items/automatic-session-checkpoints.yaml

@@ -0,0 +1,92 @@
+id: automatic-session-checkpoints
+title: A session that ends anywhere is collectable everywhere, without anyone running a command
+status: ready
+arc: setup-and-first-run
+priority: next
+blocked_on: []
+related_to:
+- key: selective-wake-for-the-listener
+  note: 'Both are about a session being reachable across a gap the agent is not awake
+    for. That one wakes a parked session when a message lands; this one makes sure the
+    session''s own context survives the gap at all. Read that one first for the hook
+    and background-process conventions this must follow.'
+- key: cross-key-rendezvous
+  note: 'Shares the addressing problem from the other end. That one asks how a stranger
+    finds you; this one asks which of several checkpoints is the one you meant. Both
+    resolve to "the tool decides, the agent does not choose", so settle the rule in
+    one place rather than twice.'
+refs:
+- 'src/switchboard/handoff.py'
+- 'src/switchboard/claude_session.py'
+- 'docs/claude-code.md'
+- 'https://github.com/gald33/switchboard/pull/229'
+evidence: |
+  **Inferred from a design conversation on 2026-09-05, after the first real
+  handoff the night before.** Nothing is broken; the mechanism works. What this
+  item records is what the working mechanism still asks of a human, and one
+  fragility that only shows up when something goes wrong.
+
+  **The question that started it: how does Cursor move sessions between cloud
+  and local so smoothly, and can we?** Reading Cursor's own store on a machine
+  that runs it answers the first half. Its `conversations` table tags each row
+  with a `source` — 496 `local` against 47 `cloud-cache` on the machine
+  inspected — the cloud ones carry a server-side `scope` hash the local ones
+  lack, the table has `root_fingerprint` and `cache_fingerprint` columns, and a
+  `conversation_search_reconciliation` table holds a sync `cursor`. That is a
+  client cache over a server-authoritative store. Cursor does not move a
+  session between cloud and local; both ends are clients of one record its
+  servers hold, so there is nothing to move.
+
+  **That is exactly the trade Switchboard must not make.** Copying it means the
+  hub storing transcripts it currently cannot read, which is the single
+  property the whole design exists to protect (`docs/model.md`). The local-first
+  choice is what let a session cross from a cloud container to a laptop on
+  2026-09-04 between two agents sharing no account, sealed with a key the hub
+  never saw. A cache-and-sync design cannot do that, because the server has to
+  hold the conversation in order to synchronise it.
+
+  **So the achievable version of "seamless" is not shared storage — it is that
+  nobody types a command.** A Cursor user does not experience syncing; they
+  experience "it was there". That experience needs the handoff to happen at the
+  boundaries automatically, and every part is already built:
+
+  - `session publish` with no recipient is already a **checkpoint** — the
+    capsule goes up sealed, addressed to nobody, collectable by anyone holding
+    the room's key, which in practice is your own other machines
+    (`handoff.py`).
+  - `init` already installs `SessionStart` and `Stop` hooks
+    (`cli.py`, `_session_start_cmd` / `_stop_cmd`).
+  - `session receive` already takes `--wait`.
+
+  Wiring them is the work: checkpoint on `Stop` and on going idle, collect on
+  `SessionStart`.
+
+  **And it closes a fragility, which is the stronger half of the case.** A
+  handoff is explicit today, so a session that dies unexpectedly leaves nothing
+  behind — the 2026-09-04 transfer survived only because the cloud agent chose
+  to publish before it finished. Cursor survives that case because the server
+  already holds the conversation. Periodic self-checkpointing is how a
+  local-first design gets the same durability without giving anything away: the
+  last checkpoint is always collectable and expires on its own, so nothing
+  accumulates on the hub.
+
+  **The open question, and the reason this is an item rather than a patch.**
+  Addressing. When several sessions have checkpointed, a starting session must
+  not collect all of them, and "the newest" is not obviously right either.
+  `--from` and sender verification are the raw material; the rule is not
+  decided. Most likely: the most recent checkpoint for **this repo** from **this
+  account**, with everything else needing to be asked for by id. Settle it
+  together with `cross-key-rendezvous`, which has the same shape of question.
+
+  **What this must not promise, and the docs should say so rather than let
+  somebody find out.** Two live sessions cannot edit one conversation: without
+  an authority to reconcile against, a handoff is a baton and not a mirror.
+  Continuity is only as good as the checkpoint interval. And a transcript is
+  large — the first real one was 19.8 MB across 175 files — so checkpointing
+  every turn is not free, which argues for idle and end-of-session rather than
+  continuous.
+
+  **Done when** a session that ends on one machine is collectable on another
+  with nobody running `handoff` or `receive`, when a session killed without
+  warning still leaves a collectable checkpoint, and when the addressing rule is
+  written down and tested rather than left to whoever calls `receive` first.

{agent_switchboard-2.2.1 → agent_switchboard-2.2.2}/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.1"
+__version__ = "2.2.2"
 
 __all__ = [
     "Invite",

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

@@ -224,6 +224,109 @@ def transcript_metadata(path: Path) -> dict[str, Any]:
     return meta
 
 
+#: Wrappers the harness puts in `user` records that no human typed: tool
+#: results, hook output, notifications, slash-command echoes. A brief that
+#: counted these as instructions would report hundreds of turns for a session
+#: whose human said twenty things.
+_NOT_TYPED = (
+    "<task-notification", "<system-reminder", "<local-command", "<command-name",
+    "<command-message", "<command-args", "<user-prompt-submit-hook",
+    # Not a wrapper but not an instruction either: the harness writes this
+    # where a human pressed escape, and it says nothing about the work.
+    "[Request interrupted",
+)
+#: How much of one instruction a brief keeps. Long enough to recognise what was
+#: asked, short enough that the whole brief stays pasteable.
+BRIEF_CHARS = 240
+
+
+def _record_text(record: dict[str, Any]) -> str:
+    """The prose of a record, ignoring tool calls and results."""
+    content = (record.get("message") or {}).get("content")
+    if isinstance(content, str):
+        return content
+    if not isinstance(content, list):
+        return ""
+    return "\n".join(
+        part.get("text", "") for part in content
+        if isinstance(part, dict) and part.get("type") == "text"
+    )
+
+
+def brief(path: Path, *, limit: int = 0) -> dict[str, Any]:
+    """What a session was *about*, small enough to paste into another one.
+
+    A transcript is the wrong thing to hand a fresh session even where the
+    machinery allows it: this one is 4.5 MB, which no context window holds, and
+    replaying it would cost more than the work it describes. What actually
+    carries is much smaller — what the human asked for, which files were
+    touched, how the session worked. Read off the record rather than
+    summarised by a model, so it states what happened instead of what a
+    retelling remembers.
+
+    The filtering is the substance. Claude Code writes tool results, hook
+    output and notifications as ``user`` records too, so a naive count reports
+    hundreds of "instructions" for a session whose human typed twenty. Only
+    prose that no wrapper claims is kept.
+
+    ``limit`` caps the instructions returned, newest first after the opening
+    one — a long session's shape is its first ask and its last few, not its
+    middle.
+    """
+    records = 0
+    instructions: list[str] = []
+    files: dict[str, int] = {}
+    tools: dict[str, int] = {}
+    with path.open("rb") as fh:
+        for raw in fh:
+            records += 1
+            try:
+                record = json.loads(raw)
+            except ValueError:
+                continue
+            if not isinstance(record, dict):
+                continue
+            kind = record.get("type")
+            if kind == "user":
+                text = " ".join(_record_text(record).split())
+                if text and not text.startswith(_NOT_TYPED):
+                    text = text[:BRIEF_CHARS]
+                    # A repeated instruction is usually the same ask re-sent
+                    # after an interruption, not a second thing wanted.
+                    if not instructions or instructions[-1] != text:
+                        instructions.append(text)
+            elif kind == "assistant":
+                content = (record.get("message") or {}).get("content")
+                if not isinstance(content, list):
+                    continue
+                for part in content:
+                    if not isinstance(part, dict) or part.get("type") != "tool_use":
+                        continue
+                    name = str(part.get("name") or "?")
+                    tools[name] = tools.get(name, 0) + 1
+                    target = (part.get("input") or {}).get("file_path")
+                    if isinstance(target, str) and target:
+                        files[target] = files.get(target, 0) + 1
+    kept = instructions
+    if limit and len(instructions) > limit:
+        # The opening ask plus the most recent ones: a session's shape is what
+        # it was for and where it got to, not the middle.
+        kept = instructions[:1] + instructions[-(limit - 1):]
+    meta = transcript_metadata(path)
+    return {
+        "records": records,
+        "cwd": meta["cwd"],
+        "git_branch": meta["git_branch"],
+        "version": meta["version"],
+        "user_messages": meta["user_messages"],
+        "assistant_messages": meta["assistant_messages"],
+        "instructions": kept,
+        "instructions_total": len(instructions),
+        "files": sorted(files, key=lambda f: -files[f]),
+        "tools": dict(sorted(tools.items(), key=lambda kv: -kv[1])),
+    }
+
+
 # -------------------------------------------------------------- package ---
 
 def _sha256(data: bytes) -> str:

{agent_switchboard-2.2.1 → agent_switchboard-2.2.2}/src/switchboard/cli.py

@@ -3150,6 +3150,8 @@ def cmd_session(args: argparse.Namespace) -> int:
             return _session_resume(args)
         if action in ("register", "unregister"):
             return _session_register(args)
+        if action == "brief":
+            return _session_brief(args)
         if action in ("handoff", "publish"):
             return _session_publish(args, fmt)
         return _session_receive(args, fmt)
@@ -3260,6 +3262,64 @@ def _session_register(args: argparse.Namespace) -> int:
     return EXIT_OK if report.get("registered") else EXIT_ERROR
 
 
+def _session_brief(args: argparse.Namespace) -> int:
+    """What a session was about, small enough to paste into another one.
+
+    The answer to a question `receive` cannot address: a cloud session in
+    somebody's browser cannot be handed a transcript — no endpoint accepts one
+    — and could not hold this one if it could, since 4.5 MB does not fit in a
+    context window. What travels is the shape: what was asked, what was
+    touched, how it worked. Read off the record rather than retold by a model.
+    """
+    session_id = claude_session.valid_session_id(args.session_id)
+    cfg = claude_session.config_dir(getattr(args, "config_dir", None))
+    found = claude_session.find_transcripts(cfg, session_id)
+    if not found:
+        print(f"error: no transcript for {session_id} under {cfg / 'projects'}",
+              file=sys.stderr)
+        return EXIT_ERROR
+    if len(found) > 1 and not args.cwd:
+        where = ", ".join(str(p.parent.name) for p in found)
+        print(f"error: {session_id} is under more than one project key ({where}); "
+              f"name the directory with --cwd", file=sys.stderr)
+        return EXIT_ERROR
+    path = found[0]
+    if args.cwd:
+        key = claude_session.project_key(args.cwd)
+        path = next((p for p in found if p.parent.name == key), found[0])
+    report = claude_session.brief(path, limit=args.limit)
+    if args.json:
+        _print_json({"session_id": session_id, **report})
+        return EXIT_OK
+    fmt = Fmt(_use_color(sys.stdout))
+    print(fmt.bold(f"session {session_id}"))
+    print(f"  {report['records']} records · {report['user_messages']} user / "
+          f"{report['assistant_messages']} assistant turns · "
+          f"claude {report['version'] or '?'}")
+    if report["cwd"]:
+        branch = f" on {report['git_branch']}" if report["git_branch"] else ""
+        print(f"  worked in {report['cwd']}{branch}")
+    if report["tools"]:
+        top = ", ".join(f"{name} {count}" for name, count in
+                        list(report["tools"].items())[:5])
+        print(f"  tools: {top}")
+    if report["files"]:
+        shown = ", ".join(Path(f).name for f in report["files"][:8])
+        more = f" (+{len(report['files']) - 8})" if len(report["files"]) > 8 else ""
+        print(f"  files: {shown}{more}")
+    total = report["instructions_total"]
+    kept = len(report["instructions"])
+    heading = "what was asked" + (f" ({kept} of {total})" if kept < total else
+                                  f" ({total})")
+    print(f"\n{fmt.bold(heading)}")
+    for line in report["instructions"]:
+        print(f"  - {line}")
+    if not report["instructions"]:
+        print(fmt.dim("  (nothing a human typed — every user record is tool "
+                      "output or a notification)"))
+    return EXIT_OK
+
+
 def _session_import(args: argparse.Namespace) -> int:
     capsule = claude_session.read_capsule(args.capsule_file)
     result = claude_session.install(capsule, cwd=args.cwd, force=args.force)
@@ -6624,6 +6684,26 @@ def build_parser() -> argparse.ArgumentParser:
     s.add_argument("--any-sender", action="store_true",
                    help="with --resume: start sessions from any roster-verified sender "
                         "(never one nobody vouched for)")
+    s = ssub.add_parser(
+        "brief",
+        help="what a session was about, small enough to paste into another one",
+        description="A transcript is the wrong thing to hand a fresh session even "
+                    "where the machinery allows it: a large one does not fit in a "
+                    "context window, and replaying it costs more than the work it "
+                    "describes. This prints what actually carries — what the human "
+                    "asked for, which files were touched, how the session worked — "
+                    "read off the record rather than retold by a model. Use it to "
+                    "start a session somewhere a capsule cannot reach, a cloud "
+                    "session in a browser being the case that prompted it.",
+    )
+    s.add_argument("session_id", metavar="session-id")
+    s.add_argument("--limit", type=int, default=0,
+                   help="keep at most this many instructions: the first, then the "
+                        "most recent (default: all)")
+    s.add_argument("--cwd", help="which project key, when the id is under more than one")
+    s.add_argument("--config-dir", help=argparse.SUPPRESS)
+    s.set_defaults(func=cmd_session, session_action="brief")
+
     s = ssub.add_parser(
         "register",
         help="give the desktop app a row for a session installed here",