cc-peer 0.0.0 → 1.1.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,351 @@
+#!/usr/bin/env node
+//#region \0rolldown/runtime.js
+var __create = Object.create;
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __getProtoOf = Object.getPrototypeOf;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __copyProps = (to, from, except, desc) => {
+	if (from && typeof from === "object" || typeof from === "function") for (var keys = __getOwnPropNames(from), i = 0, n = keys.length, key; i < n; i++) {
+		key = keys[i];
+		if (!__hasOwnProp.call(to, key) && key !== except) __defProp(to, key, {
+			get: ((k) => from[k]).bind(null, key),
+			enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable
+		});
+	}
+	return to;
+};
+var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__getProtoOf(mod)) : {}, __copyProps(isNodeMode || !mod || !mod.__esModule || !__hasOwnProp.call(mod, "default") ? __defProp(target, "default", {
+	value: mod,
+	enumerable: true
+}) : target, mod));
+//#endregion
+const require_cc_peer = require("../cc-peer-CH38-mD2.cjs");
+let node_crypto = require("node:crypto");
+let zod = require("zod");
+let node_process = require("node:process");
+node_process = __toESM(node_process, 1);
+let node_http = require("node:http");
+//#region src/api/schemas.ts
+/** Address a REST target by session pid, roster name, or raw address. */
+const PeerTargetSchema = require_cc_peer.defineSchema(zod.z.object({
+	pid: zod.z.number().int().positive().optional(),
+	name: zod.z.string().min(1).optional(),
+	address: zod.z.string().min(1).optional()
+}).refine((t) => t.pid !== void 0 || t.name !== void 0 || t.address !== void 0, { message: "target must specify pid, name, or address" }).meta({
+	id: "PeerTarget",
+	title: "Peer target"
+}));
+const SendMessageRequestSchema = require_cc_peer.defineSchema(zod.z.object({
+	to: PeerTargetSchema,
+	body: zod.z.string().min(1),
+	priority: require_cc_peer.PrioritySchema.optional(),
+	/** false deliberately sends unattested (the recipient holds it). */
+	fromMode: zod.z.union([zod.z.enum(["bypass", "prompting"]), zod.z.literal(false)]).optional()
+}).meta({
+	id: "SendMessageRequest",
+	title: "Send message request"
+}));
+const IdleSubscriptionRequestSchema = require_cc_peer.defineSchema(zod.z.object({ to: PeerTargetSchema }).meta({
+	id: "IdleSubscriptionRequest",
+	title: "Idle subscription request"
+}));
+/**
+* The schemas that become OpenAPI 3.1 components. OpenAPI 3.1 component schemas are JSON Schema 2020-12, so z.toJSONSchema with that target converts each definition losslessly; ids come from .meta() so components are named and reusable rather than inlined per-operation.
+*/
+const API_COMPONENT_SCHEMAS = {
+	PeerTarget: PeerTargetSchema,
+	SendMessageRequest: SendMessageRequestSchema,
+	IdleSubscriptionRequest: IdleSubscriptionRequestSchema,
+	SendAccepted: require_cc_peer.defineSchema(zod.z.object({ msgId: zod.z.string() }).meta({
+		id: "SendAccepted",
+		title: "Send accepted"
+	})),
+	RosterResponse: require_cc_peer.defineSchema(zod.z.object({ sessions: zod.z.array(require_cc_peer.RegistryEntrySchema) }).meta({
+		id: "RosterResponse",
+		title: "Roster response"
+	})),
+	ErrorResponse: require_cc_peer.defineSchema(zod.z.object({ error: zod.z.string() }).meta({
+		id: "ErrorResponse",
+		title: "Error response"
+	}))
+};
+//#endregion
+//#region src/api/server.ts
+/** Loopback only; this bridges onto a same-user IPC trust boundary. */
+const BIND_HOST = "127.0.0.1";
+const ALLOWED_HOSTS = /* @__PURE__ */ new Set([
+	"localhost",
+	"127.0.0.1",
+	`[${BIND_HOST}]`
+]);
+/** API tokens are 24 random bytes in hex. */
+const API_TOKEN_BYTES = 24;
+const HTTP_OK = 200;
+const HTTP_ACCEPTED = 202;
+const HTTP_UNAUTHORIZED = 401;
+const HTTP_FORBIDDEN = 403;
+const HTTP_NOT_FOUND = 404;
+const HTTP_INTERNAL = 500;
+async function createApiServer(peer, options = {}) {
+	const token = options.noToken === true ? void 0 : options.token ?? (0, node_crypto.randomBytes)(API_TOKEN_BYTES).toString("hex");
+	const server = (0, node_http.createServer)((req, res) => {
+		handle(peer, req, res, token);
+	});
+	return new Promise((resolve) => {
+		server.listen(options.port ?? 0, BIND_HOST, () => {
+			const address = server.address();
+			resolve({
+				port: typeof address === "object" && address !== null ? address.port : 0,
+				token,
+				close: async () => {
+					await new Promise((resolveClose) => {
+						server.close(() => {
+							resolveClose();
+						});
+					});
+				}
+			});
+		});
+	});
+}
+async function handle(peer, req, res, token) {
+	const finish = (status, body) => {
+		res.writeHead(status, {
+			"content-type": "application/json",
+			"cache-control": "no-store"
+		});
+		res.end(body);
+	};
+	const host = (req.headers.host ?? "").split(":")[0] ?? "";
+	if (!ALLOWED_HOSTS.has(host)) {
+		finish(HTTP_FORBIDDEN, errorBody("host not allowed"));
+		return;
+	}
+	if (token !== void 0) {
+		if ((req.headers.authorization ?? "") !== `Bearer ${token}`) {
+			finish(HTTP_UNAUTHORIZED, errorBody("unauthorized"));
+			return;
+		}
+	}
+	const url = new URL(req.url ?? "/", `http://${req.headers.host ?? "localhost"}`);
+	try {
+		if (req.method === "GET" && url.pathname === "/healthz") {
+			finish(HTTP_OK, JSON.stringify({ ok: true }));
+			return;
+		}
+		if (req.method === "GET" && url.pathname === "/openapi.json") {
+			finish(HTTP_OK, JSON.stringify(openApiDocument()));
+			return;
+		}
+		if (req.method === "GET" && url.pathname === "/sessions") {
+			const roster = await peer.roster();
+			finish(HTTP_OK, JSON.stringify({ sessions: roster }));
+			return;
+		}
+		if (req.method === "POST" && url.pathname === "/messages") {
+			const request = SendMessageRequestSchema.parse(JSON.parse(await readBody(req)));
+			const sent = await peer.send(toPeerRef(request.to), request.body, {
+				...request.priority !== void 0 ? { priority: request.priority } : {},
+				...request.fromMode !== void 0 ? { fromMode: request.fromMode } : {}
+			});
+			finish(HTTP_ACCEPTED, JSON.stringify(sent));
+			return;
+		}
+		if (req.method === "POST" && url.pathname === "/idle-subscriptions") {
+			const request = IdleSubscriptionRequestSchema.parse(JSON.parse(await readBody(req)));
+			const sent = await peer.subscribeIdle(toPeerRef(request.to));
+			finish(HTTP_ACCEPTED, JSON.stringify(sent));
+			return;
+		}
+		if (req.method === "GET" && url.pathname === "/events") {
+			streamEvents(peer, req, res);
+			return;
+		}
+		finish(HTTP_NOT_FOUND, errorBody("not found"));
+	} catch (error) {
+		finish(HTTP_INTERNAL, errorBody(error instanceof Error ? error.message : "internal"));
+	}
+}
+function toPeerRef(to) {
+	if (to.pid !== void 0) return { pid: to.pid };
+	if (to.name !== void 0) return { name: to.name };
+	if (to.address !== void 0) return { address: to.address };
+	throw new Error("target must specify pid, name, or address");
+}
+function errorBody(message) {
+	return JSON.stringify(API_COMPONENT_SCHEMAS.ErrorResponse.parse({ error: message }));
+}
+function streamEvents(peer, req, res) {
+	res.writeHead(HTTP_OK, {
+		"content-type": "text/event-stream",
+		"cache-control": "no-store",
+		connection: "keep-alive"
+	});
+	const forward = (event, data) => {
+		res.write(`event: ${event}\ndata: ${JSON.stringify(data)}\n\n`);
+	};
+	const onMessage = (m) => {
+		forward("message", m);
+	};
+	const onReceipt = (r) => {
+		forward("receipt", r);
+	};
+	const onIdle = (n) => {
+		forward("idle", n);
+	};
+	peer.on("message", onMessage);
+	peer.on("receipt", onReceipt);
+	peer.on("idle", onIdle);
+	req.on("close", () => {
+		peer.off("message", onMessage);
+		peer.off("receipt", onReceipt);
+		peer.off("idle", onIdle);
+	});
+	res.write(": connected\n\n");
+}
+async function readBody(req) {
+	return new Promise((resolve) => {
+		let data = "";
+		req.on("data", (chunk) => {
+			data += chunk.toString("utf8");
+		});
+		req.on("end", () => {
+			resolve(data);
+		});
+	});
+}
+function ref(name) {
+	return { $ref: `#/components/schemas/${name}` };
+}
+/**
+* OpenAPI 3.1 document: hand-authored paths/operations (which Zod cannot express) with every component schema converted losslessly from the same Zod definitions the server parses request bodies with — 3.1 components are JSON Schema 2020-12, so z.toJSONSchema output embeds directly.
+*/
+function openApiDocument() {
+	const components = {};
+	for (const [name, schema] of Object.entries(API_COMPONENT_SCHEMAS)) components[name] = zod.z.toJSONSchema(schema, { target: "draft-2020-12" });
+	const jsonBody = (name) => ({
+		required: true,
+		content: { "application/json": { schema: ref(name) } }
+	});
+	return {
+		openapi: "3.1.0",
+		info: {
+			title: "cc-peer",
+			version: "1.0.0",
+			description: "REST facade over Claude Code's local cross-session peer messaging. Loopback only; bearer-token auth by default."
+		},
+		servers: [{ url: `http://${BIND_HOST}` }],
+		paths: {
+			"/healthz": { get: {
+				summary: "Liveness probe",
+				responses: { "200": { description: "OK" } }
+			} },
+			"/openapi.json": { get: {
+				summary: "This document",
+				responses: { "200": { description: "OpenAPI document" } }
+			} },
+			"/sessions": { get: {
+				summary: "Live peer roster with admission checks applied",
+				responses: { "200": {
+					description: "Roster entries",
+					content: { "application/json": { schema: ref("RosterResponse") } }
+				} }
+			} },
+			"/messages": { post: {
+				summary: "Send a message to a peer by pid, name, or address",
+				requestBody: jsonBody("SendMessageRequest"),
+				responses: {
+					"202": {
+						description: "Queued; delivery receipts arrive on /events",
+						content: { "application/json": { schema: ref("SendAccepted") } }
+					},
+					"400": {
+						description: "Invalid request body",
+						content: { "application/json": { schema: ref("ErrorResponse") } }
+					}
+				}
+			} },
+			"/idle-subscriptions": { post: {
+				summary: "Subscribe for a peer's next idle (or exit) notice",
+				requestBody: jsonBody("IdleSubscriptionRequest"),
+				responses: { "202": {
+					description: "Subscribed; notices arrive on /events",
+					content: { "application/json": { schema: ref("SendAccepted") } }
+				} }
+			} },
+			"/events": { get: {
+				summary: "SSE stream of inbound messages, receipts, and idle notices",
+				responses: { "200": { description: "text/event-stream" } }
+			} }
+		},
+		components: {
+			schemas: components,
+			securitySchemes: { bearer: {
+				type: "http",
+				scheme: "bearer"
+			} }
+		},
+		security: [{ bearer: [] }]
+	};
+}
+//#endregion
+//#region src/bin/cc-peer.ts
+function parseArgs(argv) {
+	const args = { noToken: false };
+	for (let i = 0; i < argv.length; i += 1) {
+		const arg = argv[i];
+		const next = argv[i + 1];
+		if (arg === "--port" && next !== void 0) {
+			args.port = Number.parseInt(next, 10);
+			i += 1;
+		} else if (arg === "--token" && next !== void 0) {
+			args.token = next;
+			i += 1;
+		} else if (arg === "--name" && next !== void 0) {
+			args.name = next;
+			i += 1;
+		} else if (arg === "--home" && next !== void 0) {
+			args.home = next;
+			i += 1;
+		} else if (arg === "--no-token") args.noToken = true;
+	}
+	return args;
+}
+async function main() {
+	const args = parseArgs(node_process.default.argv.slice(2));
+	const peer = await require_cc_peer.CcPeer.create({
+		...args.name !== void 0 ? { name: args.name } : {},
+		...args.home !== void 0 ? { homeDir: args.home } : {},
+		logger: (message) => {
+			node_process.default.stderr.write(`[cc-peer] ${message}\n`);
+		}
+	});
+	const server = await createApiServer(peer, {
+		...args.port !== void 0 ? { port: args.port } : {},
+		...args.token !== void 0 ? { token: args.token } : {},
+		noToken: args.noToken
+	});
+	node_process.default.stderr.write(`[cc-peer] REST facade listening on http://127.0.0.1:${server.port.toString()}\n`);
+	if (server.token !== void 0) {
+		node_process.default.stderr.write(`[cc-peer] bearer token: ${server.token}\n`);
+		node_process.default.stderr.write("[cc-peer] example: curl -H 'Authorization: Bearer <token>' http://127.0.0.1:" + server.port.toString() + "/sessions\n");
+	}
+	const shutdown = async () => {
+		await server.close();
+		await peer.stop();
+		node_process.default.exit(0);
+	};
+	node_process.default.on("SIGINT", () => {
+		shutdown();
+	});
+	node_process.default.on("SIGTERM", () => {
+		shutdown();
+	});
+}
+main().catch((error) => {
+	node_process.default.stderr.write(`[cc-peer] fatal: ${error instanceof Error ? error.message : String(error)}\n`);
+	node_process.default.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 {}