cc-peer 0.0.0 → 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Joseph Mearman
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,61 @@
+# cc-peer
+
+[![GitHub](https://img.shields.io/badge/GitHub-181717?logo=github&logoColor=white)](https://github.com/ExaDev/cc-peer) [![npm](https://img.shields.io/npm/v/cc-peer)](https://www.npmjs.com/package/cc-peer) [![CI](https://img.shields.io/github/actions/workflow/status/ExaDev/cc-peer/ci.yml?branch=main)](https://github.com/ExaDev/cc-peer/actions)
+
+Talk to the Claude Code instances running on your machine, from any Node application: send messages, register as a named peer other sessions can discover and message, receive replies and delivery receipts, and subscribe to idle notifications. Ships a REST facade you can run with `npx cc-peer`.
+
+> **Unofficial.** This SDK speaks Claude Code's local cross-session peer protocol, which was reverse-engineered and verified against Claude Code 2.1.269. It is not affiliated with or endorsed by Anthropic, and the protocol may change without notice between Claude Code releases.
+
+## Why
+
+Claude Code sessions are isolated: each interactive session binds a private Unix socket, and the only first-party way in is another Claude Code session's `SendMessage`. `cc-peer` opens that door to everything else — build tooling, agents in other harnesses, dashboards, shell scripts — with the protocol's own consent model intact (permission-mode attestation, hold-for-review, delivery receipts).
+
+## How it works
+
+- **Discovery**: live sessions publish a registry at `~/.claude/sessions/<pid>.json`; `cc-peer` reads it, verifies each entry's socket and process, and can register itself there so real Claude sessions see it by name in `ListAgents`.
+- **Transport**: per-exchange Unix-socket connections carrying two newline-delimited JSON lines (a bearer-token auth line, then the frame), authenticated with per-session key files.
+- **Consent**: unattested messages land in the recipient's hold-for-review dialog; attested ones deliver directly. Delivery status comes back as receipts (`held`, `delivered`, `denied`, `expired`, `dropped` with reasons).
+- **Idle subscriptions**: ask any session to notify you when it next goes idle (or exits).
+
+The full wire reference for implementing the protocol yourself lives in [docs/PROTOCOL.md](docs/PROTOCOL.md), with machine-readable JSON Schemas published alongside the package (`cc-peer/schemas/*.schema.json`).
+
+## Install
+
+```bash
+npm install cc-peer
+```
+
+Or run the REST facade with no install:
+
+```bash
+npx cc-peer
+```
+
+## Usage
+
+```ts
+import { CcPeer } from "cc-peer";
+
+const peer = await CcPeer.create({ name: "my-app" });
+
+peer.on("message", (m) => console.log(`${m.fromName ?? m.from}: ${m.body}`));
+peer.on("receipt", (r) => console.log(`status: ${r.status}`));
+
+const sessions = await peer.roster();
+const { msgId } = await peer.send(sessions[0]!.pid, "hello from my app");
+
+await peer.subscribeIdle(sessions[0]!.pid);
+peer.on("idle", (n) => console.log(`session ${n.state}`));
+
+// …later
+await peer.stop();
+```
+
+The REST facade (`npx cc-peer`) serves `GET /sessions`, `POST /messages`, `POST /idle-subscriptions`, `GET /events` (SSE), and a self-describing `GET /openapi.json` on loopback with a bearer token.
+
+## Limitations
+
+- **Same-process constraint**: receipts and idle notices only reach the process that owns the peer's listening socket (the protocol verifies return addresses via kernel peer-pids). Do not split `CcPeer` listening and sending across processes or differently-owned workers.
+- **Single machine**: the local protocol is Unix-socket only. Writing to cloud sessions directly is blocked by design (device-attestation-signed events); bridged sessions reachable locally still work via their local mirror.
+- **File transfers to Claude sessions** wait on an upstream feature flag (`tengu_send_file`) before Claude-side materialisation activates; peer-to-peer transfers work today.
+- Verified against Claude Code 2.1.269; treat every Claude Code upgrade as a potential protocol change.

package/dist/bin/cc-peer.cjs

@@ -0,0 +1,5 @@
+#!/usr/bin/env node
+//#region src/bin/cc-peer.ts
+console.error("cc-peer: the REST facade lands in milestone 7 — nothing to serve yet");
+process.exit(1);
+//#endregion

package/dist/bin/cc-peer.d.cts

@@ -0,0 +1 @@
+export {}

package/dist/bin/cc-peer.d.mts

@@ -0,0 +1 @@
+export {}

package/dist/bin/cc-peer.mjs

@@ -0,0 +1,6 @@
+#!/usr/bin/env node
+//#region src/bin/cc-peer.ts
+console.error("cc-peer: the REST facade lands in milestone 7 — nothing to serve yet");
+process.exit(1);
+//#endregion
+export {};

package/dist/cc-peer.cjs

@@ -0,0 +1,5 @@
+Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
+//#region src/cc-peer.ts
+const CC_PEER_VERSION = "0.0.0";
+//#endregion
+exports.CC_PEER_VERSION = CC_PEER_VERSION;

package/dist/cc-peer.d.cts

@@ -0,0 +1,3 @@
+//#region src/cc-peer.d.ts
+export declare const CC_PEER_VERSION = "0.0.0";
+//#endregion

package/dist/cc-peer.d.mts

@@ -0,0 +1,3 @@
+//#region src/cc-peer.d.ts
+export declare const CC_PEER_VERSION = "0.0.0";
+//#endregion

package/dist/cc-peer.mjs

@@ -0,0 +1,4 @@
+//#region src/cc-peer.ts
+const CC_PEER_VERSION = "0.0.0";
+//#endregion
+export { CC_PEER_VERSION };

package/docs/PROTOCOL.md

@@ -0,0 +1,193 @@
+# cc-peer protocol reference
+
+This document is the implement-it-yourself reference for Claude Code's local cross-session peer messaging, reverse-engineered and live-verified against Claude Code 2.1.269 by the cc-peer project. Machine-readable companions ship with the package (`cc-peer/schemas/*.schema.json`, JSON Schema draft 2020-12, generated from the same Zod definitions the SDK uses).
+
+Unofficial and unaffiliated with Anthropic; the protocol may change without notice between Claude Code releases.
+
+# Claude Code — Cross-Session Messaging UDS Protocol
+
+How `SendMessage` / `ListAgents` peer messaging actually travels between Claude Code processes: a per-session Unix domain socket with a file-backed bearer token, newline-delimited JSON framing, a permission-attestation consent model, and a receipted reverse channel — plus a cloud bridge leg for off-machine delivery. Reverse-engineered from the 2.1.269 binary and verified end to end with hand-rolled raw-socket clients (no harness tools): fresh Claude sessions received, held, and replied to injected messages; a standalone Python process registered as a named peer and exchanged messages, receipts, and subscriptions with real sessions.
+
+The consent design parallels agent-comms (ExaDev's cross-harness mesh; its consent design parallels this protocol)' six-obligation room-token work: credential-gated transport, kernel peer-pid verification, permission-mode attestation, hold-for-review, and return-address verification.
+
+## Transport and identity
+
+- Each interactive session binds `/tmp/cc-socks/<pid>.sock` (Unix socket, same-uid peers only). The registry entry `~/.claude/sessions/<pid>.json` records `messagingSocketPath`, `sessionId`, `bridgeSessionId`, `peerProtocol`, `peerFeatures` (`notify_idle`, `reply_across_default_dirs`, `artifact_yield`), name, status, and `procStart`.
+- On startup the session writes a key file `~/.claude/sessions/<pid>.<hash>.key` (mode 0600) where `<hash>` is `sha256` of the canonical socket path. Content: `{"peerToken":"<32 hex>","procStart":"...","pidDomain":"darwin"}`. A second in-process token, the `childToken`, is exported to subprocesses via `CLAUDE_CODE_MESSAGING_TOKEN` (with `CLAUDE_CODE_MESSAGING_SOCKET` and `CLAUDE_CODE_CHILD_SESSION=1`) — the inbox's startup banner documents the official injection recipe: `echo '{"type":"auth","token":"'$CLAUDE_CODE_MESSAGING_TOKEN'"}'; echo '{"type":"user",...}' | socat - UNIX-CONNECT:$CLAUDE_CODE_MESSAGING_SOCKET`.
+- Sender-side vetting (`Pe` in the uds-client chunk): the target's key file is read, its owning pid checked alive with a matching proc-start token (recycled-pid defence), and optionally the connected peer's pid/uid read from the kernel. A live socket with no vouching key is refused on platforms where auth is mandatory; on macOS auth is optional, and an unrecognised token degrades to the unauthenticated path rather than being rejected.
+- Address schemes (`Jf`): `uds:<path>`, `bridge:<id>`, `did:<x>` (reserved — parsed as raw passthrough, no local resolution in 2.1.269), bare `*.sock` paths, and Windows named pipes.
+
+## Wire protocol
+
+One connection, one write, then close (~150 ms linger on macOS). Two newline-terminated JSON lines: auth, then the frame. Nothing is ever acknowledged on the same connection — delivery surfaces in the receiver's conversation, and status travels back as separate receipt connections.
+
+**Line 1, auth** — the target's own `peerToken` (peer-class) or `childToken` (child-class):
+
+```json
+{"type":"auth","token":"<peerToken or childToken>"}
+```
+
+**Line 2, user message** (`hnt`):
+
+```json
+{
+  "msgV": 1,
+  "msg_id": "<uuid v4>",
+  "type": "user",
+  "message": {"role": "user", "content": "<cross-session-message envelope, below>"},
+  "priority": "next",
+  "from": "uds:/tmp/cc-socks/<sender pid>.sock",
+  "file_attachments": [{"path": "...", "file_name": "...", "file_size": 0, "sha256": "...", "media_type": "..."}]
+}
+```
+
+- `"type":"user"` is load-bearing: any other type value is silently dropped after auth, with the connection left open and no error — a wrong type is indistinguishable from a delivery that never happened.
+- `msgV` is exactly `1` in genuine traffic and not strictly validated (`2` and absent both deliver). `msg_id` is a `randomUUID()`. `priority` is `"next"` on the SendMessage path; `"later"` is accepted identically. A `session_id` field, when present, must match the receiver's session id or the frame is silently dropped (no hold, no receipt, no trace).
+- Control frames share the connection shape with `"type":"control"` plus an `action` field — see Receipts and Idle subscriptions.
+
+## The envelope
+
+`message.content` must be the tag-wrapped envelope built by `uGe`/`zfe` and round-trip-checked by `HB`:
+
+```
+<cross-session-message from="uds:..." from-session="..." hop-chain="..." from-name="..." from-mode="...">BODY</cross-session-message>
+```
+
+- Attribute **order is canonical and load-bearing**: `from, from-session, hop-chain, from-name, from-mode`. The parser regex matches that sequence only; a wrong order or an invalid attribute value fails the parse, the round-trip rebuild fails, and the entire envelope is treated as an opaque unattested body (held, raw tags shown in the preview).
+- Grammar: `from` charset `[A-Za-z0-9%:_/.\-]`, max 300; `from-session` `[A-Za-z0-9_-]{1,80}`; `hop-chain` comma-joined 24-hex ids, max 32 entries at the grammar level; `from-name` free-ish text with `"` `<` `>` stripped and lookalikes normalised, max 80; `from-mode` one of the permission-mode enum (`bypass`, `prompting`, ...). Body: literal text, one newline inside each tag; occurrences of the closing tag are escaped to `<\`.
+
+## Consent: holds, attestation, and the self-sent verdict
+
+An unattested envelope arriving at a session that bypasses permission prompts is **held for human approval** ("The sender did not attest its permission mode and this session bypasses prompts"), with a Deny/Deliver dialog; `crossSessionInbound: accept` bypasses the hold. The setting's default (unset) is mode-parity: auto-deliver only on bypass↔bypass or prompting↔prompting; unattested senders are held only while the receiver bypasses.
+
+The self-sent verdict (`ye`) short-circuits the hold entirely. A message is self-sent when the connecting process's **ancestry includes the target pid**, or it presents the target's **childToken** with no contrary evidence (macOS walks `ps` ancestry; the childToken sits in every subprocess env, which is precisely the supported injection path). Verified live: an unattested frame with the session's own childToken delivered straight into the sending session's conversation mid-turn; a *foreign* childToken grants nothing — it falls to the ordinary hold. So child parity is strictly per-parent.
+
+## Registering a standalone peer and name discovery
+
+A standalone process becomes a first-class peer with three artifacts, all self-writable:
+
+1. Bind `/tmp/cc-socks/<pid>.sock`.
+2. Write the key file with a self-generated `peerToken`.
+3. Write the registry entry `<pid>.json` with `messagingSocketPath`, `name`, `status`, `peerFeatures`, and a correct `procStart`.
+
+**`procStart` must byte-match `LC_ALL=C TZ=UTC ps -o lstart= -p <pid>` output** — the exact command Claude's own generators use, compared as a plain string. Two traps: macOS `ps` formats `lstart` per the locale (bare `ps` under en_GB emits day-before-month; `LC_ALL=C` emits ctime order), and the value is UTC, not local. A mismatch classifies the pid as `recycled` and the roster silently skips the entry. Store the forced-locale/UTC command's output verbatim.
+
+The roster builder (`listLivePeerSessions`) reads all `~/.claude/sessions/<pid>.json` files — no daemon involvement; the filesystem is authoritative — and includes an entry when it has a `sock`, is not the caller's own, is not spare/parked, its socket accepts a live connect probe, and its pid is `present` (alive with matching `procStart`; `gone` entries are swept, `recycled` skipped). `nameSource` and `status` are whitelisted on read; out-of-list values parse harmlessly to undefined.
+
+Verified chain: a Python peer registered this way appears in `ListAgents` within seconds and receives native `SendMessage` by bare name (`from-name` resolves from the sender's own registry entry).
+
+## Receipts and status
+
+`peer_message_status` is pushed from receiver to sender over a fresh connection to the sender's socket, authenticated with the sender's own peerToken:
+
+```json
+{"type":"control","action":"peer_message_status","status":"held","reason":"<human-readable>","from":"uds:/tmp/cc-socks/<receiver>.sock","orig_msg_id":"<the send's msg_id>","msgV":1,"msg_id":"<receipt's own id>"}
+```
+
+All statuses verified on the wire:
+
+| Status | When | Extra fields |
+|---|---|---|
+| `held` | unattested message entered the approval dialog | — |
+| `delivered` | hold approved and released | — |
+| `denied` | hold denied | — |
+| `expired` | hold unapproved past TTL (~25 min; pending holds expire together) | `status_detail:"refused"` when the receiver refuses inbound |
+| `dropped` | rejected at inbox admission | `drop_reason`, `dropped_msg_ids` |
+
+Clean fire-and-forget delivery pushes no receipt — receipts exist for holds and failures.
+
+Drop reasons (drop taxonomy): `duplicate` (same sender + same body hash within `dedupWindowMs` 30 s — **not** msg_id; identical msg_id with different bodies both deliver), `rate-limited` (token bucket below), `hop-loop` and `hop-runaway` (hop-chain guards below), `queue-full` (undelivered-queue cap). Verified live: `duplicate`, `rate-limited` (35-message burst against the 30-token bucket), `hop-runaway` (29-entry chain), `hop-loop` (12× target-own token). `queue-full` was attempted with 55 admitted messages queued behind a hold modal and did not fire — the effective cap is dynamically raised above the 50 code default (`tengu_harbor_kite_limits`, zod range 10-5000); it is the one code-verified variant, with a receipt frame identical to its captured siblings.
+
+## Idle subscriptions
+
+Subscribe: `{"type":"control","action":"notify_when_idle","from":"uds:...","from_mode":"bypass","msgV":1,"msg_id":"<uuid>"}`. The notice returns correlated by `orig_msg_id` = the subscription's `msg_id`:
+
+```json
+{"type":"control","action":"peer_idle_notice","orig_msg_id":"...","state":"idle","finished_at":1789216922033,"detail":"<preview of the target's last reply>","from":"uds:...","from_mode":"bypass","msgV":1,"msg_id":"..."}
+```
+
+`state` is `idle` (verified: fires immediately if the target is already idle) or `exited` (verified: fires on session shutdown, including a kill). `finished_at` is epoch-ms of the target's last turn end.
+
+## Guard rails and admission semantics
+
+Peer-guard defaults (`tengu_harbor_kite_limits`-overridable): `bucketCapacity:30, refillPerSecond:0.5, dedupWindowMs:30000, maxSelfHops:10, maxChainLength:28, maxTrackedSenders:256`.
+
+**Return-address verification** — the load-bearing reverse-channel rule: the receiver records the kernel-reported peer pid of each inbound connection and pushes receipts/notices only if the claimed `from` socket is owned by that same live process. Messages from a throwaway client claiming another peer's address deliver fine but receive nothing back ("unvettable reply target"). A standalone peer must send from the process that binds its socket. (Trap: macOS Python launchers — Homebrew and Xcode `Python.app` shims — fork before exec; the surviving process owns the socket and must be the sender.)
+
+**Hop tokens** — `ownUdsHopToken = HMAC-SHA256(key = randomBytes(32) at process init, msg = "uds:<canonical socket path>").hex().slice(0,24)`: per-boot ephemeral, not externally computable. The loop-detection self-token set also covers the bridge address and a bridge-identity id. The loop guard fires at ≥ `maxSelfHops` (10) occurrences of a self-token — a single occurrence is harmless and delivers. Outbound replies to peer-origin messages stamp `i_e(own address)` into the chain, so a target's token is **mintable** by asking it to reply once and reading the chain it emits; a 12×-token chain then triggers `hop-loop`. Chains over 32 entries fail envelope parsing (hold as unattested); 29-32-entry chains parse but trip `hop-runaway` at the > 28 guard.
+
+Also enforced: a max line cap (`message_too_large`), symlink refusal on reply targets, and stale-socket refusal keyed to pid liveness plus proc-start tokens.
+
+## artifact_yield (`yield_artifact_replies` family)
+
+Same-conversation primitive: one live process of a conversation asks another to hand over in-flight artifact-reply generation.
+
+- Request: `{action:"yield_artifact_replies", from, msg_id, session_id, slugs[<=16], reason:"resume"|"claim" (default), sent_at (epoch ms, ~4 s freshness window), claimed_at?, requester:{cwd?,tmux?}}`
+- Answer: `{action:"artifact_replies_yielded", orig_msg_id, yielded?, not_held?, refused?}`
+- Hand-back: `{action:"unyield_artifact_replies", orig_msg_id, slugs, stopped?}`
+
+Admission (verified live, both directions): the target looks up the requester's registry record by socket and requires its `sessionId` to equal the target's own conversation id, plus pid match. With a random registry `sessionId` the request is refused silently; with the target's `sessionId` written into the registry, the target admitted the request and answered `artifact_replies_yielded {yielded:[], not_held:["probe-artifact"]}`. Trust boundary: the conversation gate reads the same-user-writable registry — it gates capability between processes, not identity against the local user.
+
+## File transfer (`file_attachments`)
+
+Sender stages each file into `~/.claude/file-transfers/<sha8>-<uuid8>-<name>` (0600) and attaches the descriptor array to the frame. Caps: 30 MiB per file, 16 per message, 1-day spool GC. Receiver validates each descriptor (absolute path, parent must be the spool, regular file, size, sha256 integrity), copies into `~/.claude/uploads/<receiving-session-id>/`, deletes the staged copy when spools are shared, and prepends `@"<uploads path>"` mentions plus `[SendFile: ... was not delivered — <reason>]` failure notes to the delivered body.
+
+Staging and the descriptor-carrying frame replicate exactly, but receive-side materialisation never executes on this account: the `tengu_send_file` flag is absent from the served Statsig evaluations (never served on, not merely cached-off), proven by a deliberately sha-mismatched descriptor producing no inline failure note and no uploads directory. The gate is a server rollout decision; everything up to it is documented and the send-side gate (`A6e()`) is explicit in code.
+
+## Cloud and bridge routing
+
+Local UDS is one leg. Every signed-in session carries a `bridgeSessionId` in its registry (universally present), mirrored at `https://claude.ai/code/<bridgeSessionId>`. Roster candidates without a `sock` (cloud-session / bridge-session kinds) route over the first-party Sessions API at `https://api.anthropic.com`:
+
+- `GET /v1/code/sessions`, `GET /v1/code/sessions/<id>` — roster and detail
+- `POST /v1/code/sessions/<id>/events` — signed, batched turn events (`anthropic/ccr-turn-event-uuid`, `anthropic/ccr-turn-linked-event-uuids`, `traceparent` headers)
+- `GET .../events` and `.../events/stream` — sequenced, redialling stream with liveness timeouts and service-clock drift checks
+- `mark_read`, `archive`, title, `bridge`, `device` (attestation binding), `teleport-events`, `move-to-cloud`, `client/presence`, `synced_file/*`, self-hosted runner/worker endpoints
+- Auth: OAuth bearer plus trusted-device headers; `isolatePeerMachines` gates cross-machine sends
+
+Event signing: the payload is canonicalised with JCS (`claude-code-jcs@1`), signed with an external device key into an `anthropic.ccr.client_event.v1` attestation, and bound via `anthropic.ccr.create_session_bind.v1` / `session_bind.v1` messages carrying a `boundDeviceUuid`. Unattested events classify `bound_unattested` server-side. The device key is not extractable by design — the replication boundary for standalone cloud writes.
+
+Delivery to cloud targets is best-effort: sessions report `acceptsPeerMessages`, and senders surface "accepted by the server ... but delivery is not confirmed" when unreported. Verified live: a `SendMessage` to a `bridge:<bridgeSessionId>` address was server-accepted with exactly that caveat and arrived in the target's local transcript (the bridge id maps back to the conversation via cloud ingest or local-sock mirroring; the code supports both legs).
+
+## Adjacent: the daemon
+
+`~/.claude/daemon` supervises background/scheduled agents, not interactive sessions: `roster.json` (v5) tracks workers (pid, procStart, sessionId, rendezvous socket under `/tmp/cc-daemon-501/<hash>/rv/`, pty socket), gated by `control.key` with uid-checked control connections.
+
+## Reproduction
+
+Minimal sender (auth + one user frame, single write):
+
+```python
+import socket, json, uuid, time
+TOKEN = "<target peerToken from ~/.claude/sessions/<pid>.<hash>.key>"
+SOCK, FROM = "/tmp/cc-socks/<target>.sock", "uds:/tmp/cc-socks/<sender>.sock"
+wrapper = f'<cross-session-message from="{FROM}" from-name="<name>" from-mode="bypass">\n<body>\n</cross-session-message>'
+frame = {"msgV": 1, "msg_id": str(uuid.uuid4()), "type": "user",
+         "message": {"role": "user", "content": wrapper},
+         "priority": "next", "from": FROM}
+s = socket.socket(socket.AF_UNIX, socket.SOCK_STREAM); s.settimeout(5)
+s.connect(SOCK)
+s.sendall((json.dumps({"type": "auth", "token": TOKEN}) + "\n" + json.dumps(frame) + "\n").encode())
+time.sleep(0.2); s.close()
+```
+
+A receiving peer is the mirror: bind the socket, write key file and registry (procStart from `LC_ALL=C TZ=UTC ps -o lstart=` verbatim), accept connections, verify the auth line against the peerToken, parse frames, and — for receipts and notices to arrive — send only from the socket-owning process.
+
+## Verification status
+
+| Feature | Status |
+|---|---|
+| Transport, auth (peer/child/unauthenticated), user frames, envelope grammar | verified live, both directions |
+| Holds, attestation, self-sent verdict, `crossSessionInbound` parity | verified live |
+| Peer registration, roster admission, name discovery | verified live (standalone peer in `ListAgents`, named `SendMessage`) |
+| Receipts: held / delivered / denied / expired / dropped{duplicate, rate-limited, hop-loop, hop-runaway} | verified live |
+| `queue-full` | code-verified; trigger attempted (55 queued), effective cap dynamically raised |
+| Idle subscriptions (`idle`, `exited`) | verified live |
+| artifact_yield admission + answer | verified live (refused and admitted paths); populated handover not exercised |
+| File transfer | staging + wire replicated; receive path behind a never-served server flag (evidenced) |
+| Cloud/bridge routing | `bridge:` addressing verified live; sessions-API surface and event-signer envelope extracted; device key not extractable by design |
+
+## Provenance
+
+Recovered by live reverse-engineering of the 2.1.269 binary and verified with hand-rolled raw-socket clients against fresh Claude Code sessions and a registered standalone peer: injected messages delivered and answered, receipts captured for every status, drop reasons triggered on demand, idle notices observed in both states, and the same-conversation yield admission demonstrated in both directions. Boundaries (device-attestation signing, the upstream file-transfer flag, the dynamically raised queue cap) are stated where they apply.
+
+The accompanying JSON Schemas are generated from the Zod definitions in `src/schemas/` — the same single source of truth the SDK runtime uses.

package/package.json

@@ -1,5 +1,110 @@
 {
   "name": "cc-peer",
-  "version": "0.0.0",
-  "private": false
+  "version": "1.0.0",
+  "description": "Communicate with local Claude Code instances over their native cross-session peer messaging: send and receive messages, register as a named discoverable peer, receipts, idle subscriptions, and a REST facade via `npx cc-peer`.",
+  "type": "module",
+  "license": "MIT",
+  "author": "Joseph Mearman <joseph@mearman.co.uk>",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/ExaDev/cc-peer.git"
+  },
+  "homepage": "https://github.com/ExaDev/cc-peer#readme",
+  "bugs": {
+    "url": "https://github.com/ExaDev/cc-peer/issues"
+  },
+  "sideEffects": false,
+  "engines": {
+    "node": ">=20"
+  },
+  "packageManager": "pnpm@10.33.0",
+  "bin": {
+    "cc-peer": "./dist/bin/cc-peer.mjs"
+  },
+  "exports": {
+    ".": {
+      "import": {
+        "types": "./dist/cc-peer.d.mts",
+        "default": "./dist/cc-peer.mjs"
+      },
+      "require": {
+        "types": "./dist/cc-peer.d.cts",
+        "default": "./dist/cc-peer.cjs"
+      }
+    },
+    "./schemas/*.schema.json": "./schemas/*.schema.json",
+    "./package.json": "./package.json"
+  },
+  "main": "./dist/cc-peer.cjs",
+  "types": "./dist/cc-peer.d.mts",
+  "files": [
+    "dist",
+    "schemas",
+    "docs"
+  ],
+  "publishConfig": {
+    "provenance": true,
+    "access": "public"
+  },
+  "scripts": {
+    "build": "turbo run _build",
+    "_build": "tsdown && tsx scripts/generate-json-schema.ts",
+    "lint": "turbo run _lint",
+    "_lint": "eslint . --cache",
+    "typecheck": "turbo run _typecheck",
+    "_typecheck": "tsc --noEmit",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "test:mutation": "stryker run",
+    "prepublishOnly": "pnpm lint && pnpm typecheck && pnpm test && pnpm build && publint && attw --pack",
+    "prepare": "husky"
+  },
+  "dependencies": {
+    "zod": "4.5.4"
+  },
+  "pnpm": {
+    "onlyBuiltDependencies": [
+      "@anthropic-ai/claude-code",
+      "esbuild",
+      "protobufjs",
+      "koffi"
+    ],
+    "overrides": {
+      "eslint-plugin-jsdoc": "64.3.6",
+      "conventional-changelog-writer": "9.2.1"
+    }
+  },
+  "devDependencies": {
+    "@anthropic-ai/claude-code": "2.1.261",
+    "@arethetypeswrong/cli": "0.18.5",
+    "@commitlint/config-conventional": "21.2.2",
+    "@commitlint/types": "21.2.0",
+    "@exadev/eslint-config": "2.11.0",
+    "@semantic-release/changelog": "7.0.0",
+    "@semantic-release/commit-analyzer": "13.0.1",
+    "@semantic-release/exec": "7.1.0",
+    "@semantic-release/git": "11.0.1",
+    "@semantic-release/github": "12.0.9",
+    "@semantic-release/npm": "13.1.5",
+    "@semantic-release/release-notes-generator": "14.1.1",
+    "@stryker-mutator/core": "10.0.0",
+    "@stryker-mutator/vitest-runner": "10.0.0",
+    "@types/node": "26.4.1",
+    "commitlint": "21.2.2",
+    "eslint": "10.10.0",
+    "eslint-config-prettier": "10.1.8",
+    "eslint-plugin-prettier": "5.5.6",
+    "globals": "17.12.0",
+    "husky": "9.1.7",
+    "jiti": "2.7.0",
+    "lint-staged": "17.5.0",
+    "prettier": "3.9.6",
+    "publint": "0.3.24",
+    "semantic-release": "25.0.9",
+    "tsdown": "0.23.0",
+    "tsx": "4.23.13",
+    "turbo": "2.10.12",
+    "typescript": "6.0.3",
+    "vitest": "5.0.0"
+  }
 }

package/schemas/artifact-replies-yielded.schema.json

@@ -0,0 +1,47 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "type": "object",
+  "properties": {
+    "type": {
+      "type": "string",
+      "const": "control"
+    },
+    "action": {
+      "type": "string",
+      "const": "artifact_replies_yielded"
+    },
+    "orig_msg_id": {
+      "type": "string",
+      "maxLength": 128
+    },
+    "yielded": {
+      "type": "string"
+    },
+    "not_held": {
+      "type": "string"
+    },
+    "refused": {
+      "type": "string"
+    },
+    "msgV": {
+      "type": "integer",
+      "minimum": -9007199254740991,
+      "maximum": 9007199254740991
+    },
+    "msg_id": {
+      "type": "string",
+      "minLength": 1
+    },
+    "from": {
+      "type": "string"
+    }
+  },
+  "required": [
+    "type",
+    "action",
+    "orig_msg_id",
+    "msgV",
+    "msg_id"
+  ],
+  "additionalProperties": false
+}

package/schemas/auth-line.schema.json

@@ -0,0 +1,19 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "type": "object",
+  "properties": {
+    "type": {
+      "type": "string",
+      "const": "auth"
+    },
+    "token": {
+      "type": "string",
+      "pattern": "^[0-9a-f]{32}$"
+    }
+  },
+  "required": [
+    "type",
+    "token"
+  ],
+  "additionalProperties": false
+}

package/schemas/envelope-attributes.schema.json

@@ -0,0 +1,38 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "type": "object",
+  "properties": {
+    "from": {
+      "type": "string",
+      "pattern": "^[A-Za-z0-9%:_/.\\\\-]{1,300}$"
+    },
+    "fromSession": {
+      "type": "string",
+      "pattern": "^[A-Za-z0-9_-]{1,80}$"
+    },
+    "hopChain": {
+      "maxItems": 32,
+      "type": "array",
+      "items": {
+        "type": "string",
+        "pattern": "^[0-9a-f]{24}$"
+      }
+    },
+    "fromName": {
+      "type": "string",
+      "minLength": 1,
+      "maxLength": 80
+    },
+    "fromMode": {
+      "type": "string",
+      "enum": [
+        "bypass",
+        "prompting"
+      ]
+    }
+  },
+  "required": [
+    "from"
+  ],
+  "additionalProperties": false
+}

package/schemas/notify-when-idle.schema.json

@@ -0,0 +1,42 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "type": "object",
+  "properties": {
+    "type": {
+      "type": "string",
+      "const": "control"
+    },
+    "action": {
+      "type": "string",
+      "const": "notify_when_idle"
+    },
+    "from": {
+      "type": "string",
+      "pattern": "^[A-Za-z0-9%:_/.\\\\-]{1,300}$"
+    },
+    "from_mode": {
+      "type": "string",
+      "enum": [
+        "bypass",
+        "prompting"
+      ]
+    },
+    "msgV": {
+      "type": "integer",
+      "minimum": -9007199254740991,
+      "maximum": 9007199254740991
+    },
+    "msg_id": {
+      "type": "string",
+      "minLength": 1
+    }
+  },
+  "required": [
+    "type",
+    "action",
+    "from",
+    "msgV",
+    "msg_id"
+  ],
+  "additionalProperties": false
+}

package/schemas/peer-idle-notice.schema.json

@@ -0,0 +1,62 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "type": "object",
+  "properties": {
+    "type": {
+      "type": "string",
+      "const": "control"
+    },
+    "action": {
+      "type": "string",
+      "const": "peer_idle_notice"
+    },
+    "orig_msg_id": {
+      "type": "string",
+      "minLength": 1
+    },
+    "state": {
+      "type": "string",
+      "enum": [
+        "idle",
+        "exited"
+      ]
+    },
+    "finished_at": {
+      "type": "number"
+    },
+    "detail": {
+      "type": "string"
+    },
+    "from": {
+      "type": "string",
+      "pattern": "^[A-Za-z0-9%:_/.\\\\-]{1,300}$"
+    },
+    "from_mode": {
+      "type": "string",
+      "enum": [
+        "bypass",
+        "prompting"
+      ]
+    },
+    "msgV": {
+      "type": "integer",
+      "minimum": -9007199254740991,
+      "maximum": 9007199254740991
+    },
+    "msg_id": {
+      "type": "string",
+      "minLength": 1
+    }
+  },
+  "required": [
+    "type",
+    "action",
+    "orig_msg_id",
+    "state",
+    "finished_at",
+    "from",
+    "msgV",
+    "msg_id"
+  ],
+  "additionalProperties": false
+}

package/schemas/peer-key-file.schema.json

@@ -0,0 +1,24 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "type": "object",
+  "properties": {
+    "peerToken": {
+      "type": "string",
+      "pattern": "^[0-9a-f]{32}$"
+    },
+    "procStart": {
+      "type": "string",
+      "minLength": 1
+    },
+    "pidDomain": {
+      "type": "string",
+      "minLength": 1
+    }
+  },
+  "required": [
+    "peerToken",
+    "procStart",
+    "pidDomain"
+  ],
+  "additionalProperties": false
+}

package/schemas/peer-message-status.schema.json

@@ -0,0 +1,74 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "type": "object",
+  "properties": {
+    "type": {
+      "type": "string",
+      "const": "control"
+    },
+    "action": {
+      "type": "string",
+      "const": "peer_message_status"
+    },
+    "status": {
+      "type": "string",
+      "enum": [
+        "held",
+        "delivered",
+        "denied",
+        "expired",
+        "dropped"
+      ]
+    },
+    "reason": {
+      "type": "string"
+    },
+    "from": {
+      "type": "string",
+      "pattern": "^[A-Za-z0-9%:_/.\\\\-]{1,300}$"
+    },
+    "orig_msg_id": {
+      "type": "string",
+      "minLength": 1
+    },
+    "status_detail": {
+      "type": "string"
+    },
+    "drop_reason": {
+      "type": "string",
+      "enum": [
+        "rate-limited",
+        "duplicate",
+        "hop-loop",
+        "hop-runaway",
+        "queue-full"
+      ]
+    },
+    "dropped_msg_ids": {
+      "type": "array",
+      "items": {
+        "type": "string"
+      }
+    },
+    "msgV": {
+      "type": "integer",
+      "minimum": -9007199254740991,
+      "maximum": 9007199254740991
+    },
+    "msg_id": {
+      "type": "string",
+      "minLength": 1
+    }
+  },
+  "required": [
+    "type",
+    "action",
+    "status",
+    "reason",
+    "from",
+    "orig_msg_id",
+    "msgV",
+    "msg_id"
+  ],
+  "additionalProperties": false
+}

package/schemas/registry-entry.schema.json

@@ -0,0 +1,124 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "type": "object",
+  "properties": {
+    "pid": {
+      "type": "integer",
+      "exclusiveMinimum": 0,
+      "maximum": 9007199254740991
+    },
+    "sessionId": {
+      "type": "string",
+      "minLength": 1
+    },
+    "cwd": {
+      "type": "string"
+    },
+    "startedAt": {
+      "type": "integer",
+      "minimum": 0,
+      "maximum": 9007199254740991
+    },
+    "procStart": {
+      "type": "string",
+      "minLength": 1
+    },
+    "version": {
+      "type": "string",
+      "minLength": 1
+    },
+    "peerProtocol": {
+      "type": "integer",
+      "minimum": -9007199254740991,
+      "maximum": 9007199254740991
+    },
+    "peerFeatures": {
+      "type": "array",
+      "items": {
+        "type": "string",
+        "enum": [
+          "notify_idle",
+          "reply_across_default_dirs",
+          "artifact_yield"
+        ]
+      }
+    },
+    "kind": {
+      "type": "string",
+      "enum": [
+        "interactive",
+        "bg",
+        "daemon",
+        "daemon-worker"
+      ]
+    },
+    "entrypoint": {
+      "type": "string"
+    },
+    "pidDomain": {
+      "type": "string",
+      "minLength": 1
+    },
+    "messagingSocketPath": {
+      "type": "string",
+      "minLength": 1
+    },
+    "name": {
+      "type": "string"
+    },
+    "nameSource": {
+      "type": "string",
+      "enum": [
+        "user",
+        "peer",
+        "derived",
+        "collision",
+        "auto",
+        "hook"
+      ]
+    },
+    "nameSince": {
+      "type": "integer",
+      "minimum": 0,
+      "maximum": 9007199254740991
+    },
+    "updatedAt": {
+      "type": "integer",
+      "minimum": 0,
+      "maximum": 9007199254740991
+    },
+    "status": {
+      "type": "string",
+      "enum": [
+        "busy",
+        "shell",
+        "idle",
+        "waiting"
+      ]
+    },
+    "statusUpdatedAt": {
+      "type": "integer",
+      "minimum": 0,
+      "maximum": 9007199254740991
+    },
+    "bridgeSessionId": {
+      "type": "string"
+    }
+  },
+  "required": [
+    "pid",
+    "sessionId",
+    "cwd",
+    "startedAt",
+    "procStart",
+    "version",
+    "peerProtocol",
+    "peerFeatures",
+    "kind",
+    "entrypoint",
+    "pidDomain",
+    "messagingSocketPath",
+    "updatedAt"
+  ],
+  "additionalProperties": false
+}

package/schemas/unyield-artifact-replies.schema.json

@@ -0,0 +1,50 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "type": "object",
+  "properties": {
+    "type": {
+      "type": "string",
+      "const": "control"
+    },
+    "action": {
+      "type": "string",
+      "const": "unyield_artifact_replies"
+    },
+    "orig_msg_id": {
+      "type": "string",
+      "maxLength": 128
+    },
+    "slugs": {
+      "maxItems": 16,
+      "type": "array",
+      "items": {
+        "type": "string",
+        "maxLength": 128
+      }
+    },
+    "stopped": {
+      "type": "boolean"
+    },
+    "msgV": {
+      "type": "integer",
+      "minimum": -9007199254740991,
+      "maximum": 9007199254740991
+    },
+    "msg_id": {
+      "type": "string",
+      "minLength": 1
+    },
+    "from": {
+      "type": "string"
+    }
+  },
+  "required": [
+    "type",
+    "action",
+    "orig_msg_id",
+    "slugs",
+    "msgV",
+    "msg_id"
+  ],
+  "additionalProperties": false
+}

package/schemas/user-frame.schema.json

@@ -0,0 +1,95 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "type": "object",
+  "properties": {
+    "msgV": {
+      "type": "integer",
+      "minimum": -9007199254740991,
+      "maximum": 9007199254740991
+    },
+    "msg_id": {
+      "type": "string",
+      "minLength": 1
+    },
+    "type": {
+      "type": "string",
+      "const": "user"
+    },
+    "message": {
+      "type": "object",
+      "properties": {
+        "role": {
+          "type": "string",
+          "const": "user"
+        },
+        "content": {
+          "type": "string"
+        }
+      },
+      "required": [
+        "role",
+        "content"
+      ],
+      "additionalProperties": false
+    },
+    "priority": {
+      "type": "string",
+      "enum": [
+        "next",
+        "later"
+      ]
+    },
+    "from": {
+      "type": "string",
+      "pattern": "^[A-Za-z0-9%:_/.\\\\-]{1,300}$"
+    },
+    "session_id": {
+      "type": "string"
+    },
+    "file_attachments": {
+      "maxItems": 16,
+      "type": "array",
+      "items": {
+        "type": "object",
+        "properties": {
+          "path": {
+            "type": "string",
+            "minLength": 1
+          },
+          "file_name": {
+            "type": "string",
+            "minLength": 1
+          },
+          "file_size": {
+            "type": "integer",
+            "minimum": 0,
+            "maximum": 9007199254740991
+          },
+          "sha256": {
+            "type": "string",
+            "pattern": "^[0-9a-f]{64}$"
+          },
+          "media_type": {
+            "type": "string"
+          }
+        },
+        "required": [
+          "path",
+          "file_name",
+          "file_size",
+          "sha256"
+        ],
+        "additionalProperties": false
+      }
+    }
+  },
+  "required": [
+    "msgV",
+    "msg_id",
+    "type",
+    "message",
+    "priority",
+    "from"
+  ],
+  "additionalProperties": false
+}

package/schemas/yield-artifact-replies.schema.json

@@ -0,0 +1,78 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "type": "object",
+  "properties": {
+    "type": {
+      "type": "string",
+      "const": "control"
+    },
+    "action": {
+      "type": "string",
+      "const": "yield_artifact_replies"
+    },
+    "from": {
+      "type": "string",
+      "maxLength": 512
+    },
+    "msg_id": {
+      "type": "string",
+      "minLength": 1,
+      "maxLength": 128
+    },
+    "session_id": {
+      "type": "string",
+      "maxLength": 512
+    },
+    "slugs": {
+      "maxItems": 16,
+      "type": "array",
+      "items": {
+        "type": "string",
+        "maxLength": 128
+      }
+    },
+    "reason": {
+      "default": "claim",
+      "type": "string",
+      "enum": [
+        "resume",
+        "claim"
+      ]
+    },
+    "sent_at": {
+      "type": "number"
+    },
+    "claimed_at": {
+      "type": "number"
+    },
+    "requester": {
+      "type": "object",
+      "properties": {
+        "cwd": {
+          "type": "string"
+        },
+        "tmux": {
+          "type": "string"
+        }
+      },
+      "additionalProperties": false
+    },
+    "msgV": {
+      "type": "integer",
+      "minimum": -9007199254740991,
+      "maximum": 9007199254740991
+    }
+  },
+  "required": [
+    "type",
+    "action",
+    "from",
+    "msg_id",
+    "session_id",
+    "slugs",
+    "reason",
+    "sent_at",
+    "msgV"
+  ],
+  "additionalProperties": false
+}