cc-peer 1.3.5 → 1.5.0

package/dist/cc-peer.d.mts

@@ -1,309 +1,2 @@
-import { EventEmitter } from "node:events";
-import { z } from "zod";
-//#region src/adapters/node/paths.d.ts
-interface PathConfig {
-  homeDir?: string;
-  socketDir?: string;
-}
-//#endregion
-//#region src/ports/transport.d.ts
-/** Transport port: per-exchange connections and the listening inbox. */
-interface Transport {
-  /**
-   * One connection, one write of the given lines (each newline-terminated), then close after a short linger. Mirrors the reference client's `Pe`.
-   */
-  connectWrite: (socketPath: string, lines: readonly string[], lingerMs?: number) => Promise<void>;
-  /** Probe whether a socket accepts connections (roster admission uses this). */
-  probe: (socketPath: string) => Promise<boolean>;
-  listen: (socketPath: string, onConnection: (conn: Readonly<InboundConnection>) => void) => Promise<ListeningSocket>;
-}
-interface InboundConnection {
-  /** Resolves once the kernel reports the connecting process's pid (macOS). */
-  peerPid: () => number | undefined;
-  readLines: () => AsyncIterable<string>;
-  close: () => void;
-}
-interface ListeningSocket {
-  socketPath: string;
-  close: () => Promise<void>;
-}
-//#endregion
-//#region src/schemas/registry.d.ts
-/** One entry of the ~/.claude/sessions/<pid>.json registry. */
-declare const RegistryEntrySchema: z.ZodObject<{
-  pid: z.ZodNumber;
-  sessionId: z.ZodString;
-  cwd: z.ZodString;
-  startedAt: z.ZodNumber;
-  procStart: z.ZodString;
-  version: z.ZodString;
-  peerProtocol: z.ZodNumber;
-  peerFeatures: z.ZodArray<z.ZodEnum<{
-    notify_idle: "notify_idle";
-    reply_across_default_dirs: "reply_across_default_dirs";
-    artifact_yield: "artifact_yield";
-  }> & {
-    is(value: unknown): value is "notify_idle" | "reply_across_default_dirs" | "artifact_yield";
-  }>;
-  kind: z.ZodEnum<{
-    interactive: "interactive";
-    bg: "bg";
-    daemon: "daemon";
-    "daemon-worker": "daemon-worker";
-  }> & {
-    is(value: unknown): value is "interactive" | "bg" | "daemon" | "daemon-worker";
-  };
-  entrypoint: z.ZodString;
-  pidDomain: z.ZodString;
-  messagingSocketPath: z.ZodString;
-  name: z.ZodOptional<z.ZodString>;
-  nameSource: z.ZodOptional<z.ZodEnum<{
-    user: "user";
-    peer: "peer";
-    derived: "derived";
-    collision: "collision";
-    auto: "auto";
-    hook: "hook";
-  }> & {
-    is(value: unknown): value is "user" | "peer" | "derived" | "collision" | "auto" | "hook";
-  }>;
-  nameSince: z.ZodOptional<z.ZodNumber>;
-  updatedAt: z.ZodNumber;
-  status: z.ZodOptional<z.ZodEnum<{
-    idle: "idle";
-    busy: "busy";
-    shell: "shell";
-    waiting: "waiting";
-  }> & {
-    is(value: unknown): value is "idle" | "busy" | "shell" | "waiting";
-  }>;
-  statusUpdatedAt: z.ZodOptional<z.ZodNumber>;
-  bridgeSessionId: z.ZodOptional<z.ZodString>;
-}, z.core.$strip> & {
-  is(value: unknown): value is {
-    pid: number;
-    sessionId: string;
-    cwd: string;
-    startedAt: number;
-    procStart: string;
-    version: string;
-    peerProtocol: number;
-    peerFeatures: ("notify_idle" | "reply_across_default_dirs" | "artifact_yield")[];
-    kind: "interactive" | "bg" | "daemon" | "daemon-worker";
-    entrypoint: string;
-    pidDomain: string;
-    messagingSocketPath: string;
-    updatedAt: number;
-    name?: string | undefined;
-    nameSource?: "user" | "peer" | "derived" | "collision" | "auto" | "hook" | undefined;
-    nameSince?: number | undefined;
-    status?: "idle" | "busy" | "shell" | "waiting" | undefined;
-    statusUpdatedAt?: number | undefined;
-    bridgeSessionId?: string | undefined;
-  };
-};
-type RegistryEntry = z.infer<typeof RegistryEntrySchema>;
-//#endregion
-//#region src/ports/registry-store.d.ts
-/** Registry port: the ~/.claude/sessions/<pid>.json store. */
-interface RegistryStore {
-  list: () => Promise<RegistryEntry[]>;
-  read: (pid: number) => Promise<RegistryEntry | undefined>;
-  write: (entry: RegistryEntry) => Promise<void>;
-  /** Heartbeat: bump updatedAt/statusUpdatedAt without rewriting the rest. */
-  touch: (pid: number) => Promise<void>;
-  remove: (pid: number) => Promise<void>;
-}
-//#endregion
-//#region src/schemas/keyfile.d.ts
-/** The auth key a session publishes next to its socket. */
-declare const PeerKeyFileSchema: z.ZodObject<{
-  peerToken: z.ZodString;
-  procStart: z.ZodString;
-  pidDomain: z.ZodString;
-}, z.core.$strip> & {
-  is(value: unknown): value is {
-    peerToken: string;
-    procStart: string;
-    pidDomain: string;
-  };
-};
-type PeerKeyFile = z.infer<typeof PeerKeyFileSchema>;
-//#endregion
-//#region src/ports/key-store.d.ts
-/** Key-store port: auth keys published next to each session socket. */
-interface KeyStore {
-  readForSocket: (socketPath: string) => Promise<PeerKeyFile | undefined>;
-  /** Write our own key file for the socket we own. */
-  writeForSocket: (socketPath: string, keyFile: Readonly<PeerKeyFile>) => Promise<void>;
-  removeForSocket: (socketPath: string) => Promise<void>;
-}
-//#endregion
-//#region src/ports/proc-info.d.ts
-/** Process-info port: the liveness and proc-start facts the roster needs. */
-interface ProcInfo {
-  alive: (pid: number) => Promise<boolean>;
-  /**
-   * The process start string, byte-equal to `LC_ALL=C TZ=UTC ps -o lstart=` output — the exact value the receiver's registry byte-compares against.
-   */
-  lstart: (pid: number) => Promise<string | undefined>;
-}
-//#endregion
-//#region src/ports/clock.d.ts
-/** Clock port: injectable time for pacer/refill and freshness windows. */
-interface Clock {
-  nowMs: () => number;
-}
-//#endregion
-//#region src/schemas/wire.d.ts
-declare const PeerMessageStatusSchema: z.ZodObject<{
-  type: z.ZodLiteral<"control">;
-  action: z.ZodLiteral<"peer_message_status">;
-  status: z.ZodEnum<{
-    held: "held";
-    delivered: "delivered";
-    denied: "denied";
-    expired: "expired";
-    dropped: "dropped";
-  }>;
-  reason: z.ZodString;
-  from: z.ZodString;
-  orig_msg_id: z.ZodString;
-  status_detail: z.ZodOptional<z.ZodString>;
-  drop_reason: z.ZodOptional<z.ZodEnum<{
-    "rate-limited": "rate-limited";
-    duplicate: "duplicate";
-    "hop-loop": "hop-loop";
-    "hop-runaway": "hop-runaway";
-    "queue-full": "queue-full";
-  }> & {
-    is(value: unknown): value is "rate-limited" | "duplicate" | "hop-loop" | "hop-runaway" | "queue-full";
-  }>;
-  dropped_msg_ids: z.ZodOptional<z.ZodArray<z.ZodString>>;
-  msgV: z.ZodNumber;
-  msg_id: z.ZodString;
-}, z.core.$strip> & {
-  is(value: unknown): value is {
-    type: "control";
-    action: "peer_message_status";
-    status: "held" | "delivered" | "denied" | "expired" | "dropped";
-    reason: string;
-    from: string;
-    orig_msg_id: string;
-    msgV: number;
-    msg_id: string;
-    status_detail?: string | undefined;
-    drop_reason?: "rate-limited" | "duplicate" | "hop-loop" | "hop-runaway" | "queue-full" | undefined;
-    dropped_msg_ids?: string[] | undefined;
-  };
-};
-type PeerMessageStatus = z.infer<typeof PeerMessageStatusSchema>;
-declare const PeerIdleNoticeSchema: z.ZodObject<{
-  type: z.ZodLiteral<"control">;
-  action: z.ZodLiteral<"peer_idle_notice">;
-  orig_msg_id: z.ZodString;
-  state: z.ZodEnum<{
-    idle: "idle";
-    exited: "exited";
-  }>;
-  finished_at: z.ZodNumber;
-  detail: z.ZodOptional<z.ZodString>;
-  from: z.ZodString;
-  from_mode: z.ZodOptional<z.ZodEnum<{
-    bypass: "bypass";
-    prompting: "prompting";
-  }>>;
-  msgV: z.ZodNumber;
-  msg_id: z.ZodString;
-}, z.core.$strip> & {
-  is(value: unknown): value is {
-    type: "control";
-    action: "peer_idle_notice";
-    orig_msg_id: string;
-    state: "idle" | "exited";
-    finished_at: number;
-    from: string;
-    msgV: number;
-    msg_id: string;
-    detail?: string | undefined;
-    from_mode?: "bypass" | "prompting" | undefined;
-  };
-};
-type PeerIdleNotice = z.infer<typeof PeerIdleNoticeSchema>;
-//#endregion
-//#region src/cc-peer.d.ts
-/** Package version placeholder until semantic-release owns it. */
-export declare const CC_PEER_VERSION = "0.0.0";
-/** How a target can be addressed. */
-export type PeerRef = {
-  pid: number;
-} | {
-  name: string;
-} | {
-  address: string;
-};
-export interface CcPeerOptions extends PathConfig {
-  name?: string;
-  sessionId?: string;
-  heartbeatMs?: number;
-  logger?: (message: string) => void;
-}
-export interface SendOptions {
-  priority?: "next" | "later";
-  /** Attaches from-mode attestation; false deliberately sends unattested (recipient holds it). */
-  fromMode?: "bypass" | "prompting" | false;
-  /** When set, must match the receiver's sessionId or the frame is silently dropped. */
-  sessionId?: string;
-}
-export interface InboundMessage {
-  from?: string;
-  fromSession?: string;
-  fromName?: string;
-  fromMode?: "bypass" | "prompting";
-  hopChain?: string[];
-  body: string;
-  msgId: string;
-}
-export type Receipt = PeerMessageStatus;
-export type IdleNotice = PeerIdleNotice;
-interface Deps {
-  transport: Transport;
-  registry: RegistryStore;
-  keys: KeyStore;
-  procInfo: ProcInfo;
-  clock: Clock;
-}
-/**
- * A registered peer on Claude Code's cross-session mesh. Receipts and idle notices only reach the process that owns the listening socket (the protocol verifies return addresses via kernel peer pids), so do not split sending and listening across differently-owned processes.
- */
-export declare class CcPeer extends EventEmitter {
-  private readonly options;
-  private readonly deps;
-  private listening;
-  private heartbeatTimer;
-  private ownKey;
-  private readonly pacer;
-  private readonly log;
-  private stopped;
-  constructor(options: Readonly<CcPeerOptions>, deps: Deps);
-  static create(options?: Readonly<CcPeerOptions>): Promise<CcPeer>;
-  /**
-   * Bind, publish key and registry, and begin listening. Public rather than private because dependency-injected construction (this constructor takes the full Deps) needs to trigger it explicitly; everyday callers use the static create(), which wires the real node adapters.
-   */
-  start(): Promise<void>;
-  /** procStart is a required parameter, not read from this.ownKey: start() already guarantees a non-empty value before this is called, so the type checker enforces it rather than a runtime fallback that can never actually fire. */
-  private buildRegistryEntry;
-  roster(): Promise<RegistryEntry[]>;
-  send(target: PeerRef, body: string, options?: Readonly<SendOptions>): Promise<{
-    msgId: string;
-  }>;
-  private pacedSend;
-  subscribeIdle(target: PeerRef): Promise<{
-    msgId: string;
-  }>;
-  private resolveTarget;
-  /** ownToken is passed explicitly rather than read from this.ownKey: the listener callback that invokes this is only ever registered after start() has set ownKey, so the parameter records that guarantee at the type level instead of a runtime guard that can never actually be false. */
-  private handleConnection;
-  stop(): Promise<void>;
-}
-//#endregion
+import { a as InboundMessage, c as SendOptions, i as IdleNotice, n as CcPeer, o as PeerRef, r as CcPeerOptions, s as Receipt, t as CC_PEER_VERSION } from "./cc-peer-B3i4ZlKV.mjs";
+export { CC_PEER_VERSION, CcPeer, CcPeerOptions, IdleNotice, InboundMessage, PeerRef, Receipt, SendOptions };

package/dist/cc-peer.mjs

@@ -1,2 +1,2 @@
-import { n as CcPeer, t as CC_PEER_VERSION } from "./cc-peer-CJqStHIL.mjs";
+import { n as CcPeer, t as CC_PEER_VERSION } from "./cc-peer-BduoSupO.mjs";
 export { CC_PEER_VERSION, CcPeer };

package/dist/errors-Dcqq2MIW.mjs

@@ -0,0 +1,53 @@
+//#region src/schemas/define-schema.ts
+/**
+* Attach an `.is()` type guard to a Zod schema so schema, inferred type, and runtime guard derive from one definition (single source of truth). `Schema.parse()` at JSON boundaries; `Schema.is()` for narrowing.
+*/
+function defineSchema(schema) {
+	return Object.assign(schema, { is(value) {
+		return schema.safeParse(value).success;
+	} });
+}
+//#endregion
+//#region src/errors.ts
+/** Base error for every cc-peer failure; `code` is machine-readable. */
+var CcPeerError = class extends Error {
+	code;
+	constructor(code, message) {
+		super(message);
+		this.code = code;
+		this.name = "CcPeerError";
+	}
+};
+var NoLiveInboxError = class extends CcPeerError {
+	constructor(message) {
+		super("NO_LIVE_INBOX", message);
+		this.name = "NoLiveInboxError";
+	}
+};
+var UnknownPeerError = class extends CcPeerError {
+	constructor(message) {
+		super("UNKNOWN_PEER", message);
+		this.name = "UnknownPeerError";
+	}
+};
+var MessageTooLargeError = class extends CcPeerError {
+	constructor(message) {
+		super("MESSAGE_TOO_LARGE", message);
+		this.name = "MessageTooLargeError";
+	}
+};
+var NotStartedError = class extends CcPeerError {
+	constructor(message) {
+		super("NOT_STARTED", message);
+		this.name = "NotStartedError";
+	}
+};
+/** A reply-alias worker process exited (or failed to reach the "started" acknowledgement) before it finished registering as a discoverable peer. */
+var AliasStartError = class extends CcPeerError {
+	constructor(message) {
+		super("ALIAS_START_FAILED", message);
+		this.name = "AliasStartError";
+	}
+};
+//#endregion
+export { UnknownPeerError as a, NotStartedError as i, MessageTooLargeError as n, defineSchema as o, NoLiveInboxError as r, AliasStartError as t };

package/dist/errors-Dl_lSq1N.cjs

@@ -0,0 +1,88 @@
+//#region src/schemas/define-schema.ts
+/**
+* Attach an `.is()` type guard to a Zod schema so schema, inferred type, and runtime guard derive from one definition (single source of truth). `Schema.parse()` at JSON boundaries; `Schema.is()` for narrowing.
+*/
+function defineSchema(schema) {
+	return Object.assign(schema, { is(value) {
+		return schema.safeParse(value).success;
+	} });
+}
+//#endregion
+//#region src/errors.ts
+/** Base error for every cc-peer failure; `code` is machine-readable. */
+var CcPeerError = class extends Error {
+	code;
+	constructor(code, message) {
+		super(message);
+		this.code = code;
+		this.name = "CcPeerError";
+	}
+};
+var NoLiveInboxError = class extends CcPeerError {
+	constructor(message) {
+		super("NO_LIVE_INBOX", message);
+		this.name = "NoLiveInboxError";
+	}
+};
+var UnknownPeerError = class extends CcPeerError {
+	constructor(message) {
+		super("UNKNOWN_PEER", message);
+		this.name = "UnknownPeerError";
+	}
+};
+var MessageTooLargeError = class extends CcPeerError {
+	constructor(message) {
+		super("MESSAGE_TOO_LARGE", message);
+		this.name = "MessageTooLargeError";
+	}
+};
+var NotStartedError = class extends CcPeerError {
+	constructor(message) {
+		super("NOT_STARTED", message);
+		this.name = "NotStartedError";
+	}
+};
+/** A reply-alias worker process exited (or failed to reach the "started" acknowledgement) before it finished registering as a discoverable peer. */
+var AliasStartError = class extends CcPeerError {
+	constructor(message) {
+		super("ALIAS_START_FAILED", message);
+		this.name = "AliasStartError";
+	}
+};
+//#endregion
+Object.defineProperty(exports, "AliasStartError", {
+	enumerable: true,
+	get: function() {
+		return AliasStartError;
+	}
+});
+Object.defineProperty(exports, "MessageTooLargeError", {
+	enumerable: true,
+	get: function() {
+		return MessageTooLargeError;
+	}
+});
+Object.defineProperty(exports, "NoLiveInboxError", {
+	enumerable: true,
+	get: function() {
+		return NoLiveInboxError;
+	}
+});
+Object.defineProperty(exports, "NotStartedError", {
+	enumerable: true,
+	get: function() {
+		return NotStartedError;
+	}
+});
+Object.defineProperty(exports, "UnknownPeerError", {
+	enumerable: true,
+	get: function() {
+		return UnknownPeerError;
+	}
+});
+Object.defineProperty(exports, "defineSchema", {
+	enumerable: true,
+	get: function() {
+		return defineSchema;
+	}
+});

package/dist/rolldown-runtime-VH7oDXx4.cjs

@@ -0,0 +1,28 @@
+//#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
+Object.defineProperty(exports, "__toESM", {
+	enumerable: true,
+	get: function() {
+		return __toESM;
+	}
+});

package/docs/PROTOCOL.md

@@ -76,6 +76,15 @@ The roster builder (`listLivePeerSessions`) reads all `~/.claude/sessions/<pid>.
 
 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).
 
+### Session enumeration and reply aliases (for a relay/front building on this SDK)
+
+Two capabilities a message relay ("front") needs from this protocol, gated on what it actually supports rather than assumed:
+
+- **Session enumeration** — listing every live local Claude Code session, not just ones the relay itself registered — is already fully native. The roster builder above reads every `~/.claude/sessions/<pid>.json` file on disk, regardless of who wrote it; `cc-peer`'s own `CcPeer.roster()` (and the REST facade's `GET /sessions`) is exactly this roster builder, so a relay gets full session discovery for free, with no separate mechanism needed.
+- **Reply aliases** — giving each correspondent that messages a relayed session its own natively-`SendMessage`-reachable name, so the session can reply to it directly by name — is **not** natively supported for more than one name per process. The registry is one file per real OS pid (`registryFilePath`: `<pid>.json`) and each entry carries a single optional `name` field; a process publishing a second name overwrites, rather than adds to, its own entry. This is directly observable in this SDK's own test suite: two `CcPeer` instances sharing one pid (unavoidable — both are the same OS process) leave only the last-registered name visible in the roster, because both wrote to the identical `<pid>.json` file. Native name resolution (`ListAgents`/`SendMessage(name=X)`) walks the registry directory exactly as it is on disk — it has no concept of "this one process answers to several names."
+
+The practical consequence: a relay that wants N correspondents to each get their own reply-able name needs N distinct, genuinely live OS processes — one real pid, one registry file, one name, per correspondent — not a lighter-weight in-process mapping. `cc-peer`'s own `AliasPool` (see the root README) implements exactly this: it lazily forks one lightweight child process per correspondent name, each running an ordinary `CcPeer` instance under that name, and relays whatever the relayed session replies with back to the parent process for translation into whatever channel the correspondent actually lives on.
+
 ## 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:

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "cc-peer",
-  "version": "1.3.5",
+  "version": "1.5.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",
@@ -32,6 +32,16 @@
         "default": "./dist/cc-peer.cjs"
       }
     },
+    "./alias-pool": {
+      "import": {
+        "types": "./dist/alias-pool.d.mts",
+        "default": "./dist/alias-pool.mjs"
+      },
+      "require": {
+        "types": "./dist/alias-pool.d.cts",
+        "default": "./dist/alias-pool.cjs"
+      }
+    },
     "./schemas/*.schema.json": "./schemas/*.schema.json",
     "./package.json": "./package.json"
   },
@@ -59,7 +69,7 @@
     "test:integration": "vitest run --project integration",
     "test:e2e": "vitest run --config vitest.e2e.config.ts",
     "test:mutation": "stryker run stryker.config.ts",
-    "prepublishOnly": "pnpm lint && pnpm typecheck && pnpm test:coverage && pnpm build && publint && attw --pack",
+    "prepublishOnly": "pnpm lint && pnpm typecheck && pnpm test:coverage && pnpm build && publint && attw --pack --profile node16",
     "prepare": "husky",
     "test:coverage": "vitest run --coverage"
   },

package/schemas/registry-entry.schema.json

@@ -27,6 +27,10 @@
       "type": "string",
       "minLength": 1
     },
+    "ccPeerVersion": {
+      "type": "string",
+      "minLength": 1
+    },
     "peerProtocol": {
       "type": "integer",
       "minimum": -9007199254740991,