agent-comms 8.15.9 → 8.15.11

package/src/bridges/cc-peer/front-runtime.ts

@@ -0,0 +1,167 @@
+/**
+ * Real cc-peer/MeshStore construction for the default coordinator-run front (agent-comms#157) -- the counterpart to bridges/cc-peer/run.ts's own real CcPeer.create()/createBridgeMesh construction for the one-shot `bridge cc-peer` command. Wires front-controller.ts's CcPeerFront (attach/detach diffing across ticks) to front-relay.ts's buildFrontedSessionRecord/detachFrontedSession (one session's own relay) against one shared, front-wide CcPeer instance and a fresh per-session MeshStore built from loadIdentityForFront's lock-free identity.
+ *
+ * Untested directly, exactly like run.ts's own real construction (see cc-peer-bridge.test.ts's header comment): front.ts, front-controller.ts, and front-relay.ts already carry the front's entire decision/diffing/relay logic under direct DI-based unit tests, so this file's only remaining job -- calling the real cc-peer/core APIs in the right order -- is exercised by actually running a bridge as this machine's coordinator.
+ */
+
+import { parseDisplayName } from "../../core/display-name.js";
+import { CcPeer, CC_PEER_VERSION } from "cc-peer";
+import { AliasPool } from "cc-peer/alias-pool";
+import type { AliasMessage } from "cc-peer/alias-pool";
+import {
+  createBridgeMeshFromIdentity,
+  ensureRegistered,
+  ensureProjectRoom,
+} from "../../core/index.js";
+import {
+  loadIdentityForFront,
+  probeSlotOwner,
+} from "../../core/identity-store.js";
+import { CcPeerFront } from "./front-controller.js";
+import { computeFrontSlot } from "./front.js";
+import type { CcPeerRosterEntryLike } from "./front.js";
+import type { CcPeerInboundMessage } from "./bridge.js";
+import {
+  buildFrontedSessionRecord,
+  detachFrontedSession,
+  type FrontedRelayRecord,
+  type FrontRelayPeer,
+} from "./front-relay.js";
+import { ReplyAliasDirectory } from "./reply-aliases.js";
+import { SharedPeer } from "./shared-peer.js";
+
+/** cc-peer's own registered display name for the front's shared peer -- distinct from any individual fronted session's own agent-comms display name (front-relay.ts's ensureRegistered call uses the session's own cc-peer name/pid for that). */
+const FRONT_PEER_NAME = "agent-comms-front";
+
+/** The slice of a cc-peer peer the front uses: reading the local roster, receiving messages, and sending to a fronted session. The real CcPeer satisfies it. */
+export interface FrontCcPeer extends FrontRelayPeer {
+  roster: () => Promise<readonly CcPeerRosterEntryLike[]>;
+  on: (
+    event: "message",
+    listener: (message: Readonly<CcPeerInboundMessage>) => void,
+  ) => unknown;
+  stop: () => Promise<void>;
+}
+
+export interface CreateDefaultCcPeerFrontOptions {
+  coordinatorPort?: number | undefined;
+  hubUrl?: string | undefined;
+  pollIntervalMs?: number | undefined;
+  onError?: ((error: Error) => void) | undefined;
+  /** The cc-peer peer this process already owns, when it has one. cc-peer allows one peer per process, so a process that runs its own (the one-shot `bridge cc-peer` command) must lend it here rather than let the front try to create a second. The front only borrows it: it never stops it, and registers its inbound listener on it once. Without this the front creates and owns its own peer. */
+  peer?: FrontCcPeer | undefined;
+  /** The name the shared peer is registered under, which fronted sessions are told to message to answer a join request. Defaults to the front's own peer name; a host process that lends its own peer names it here. */
+  peerName?: string | undefined;
+  /** Sessions this process already relays by other means, which the front must therefore leave alone. */
+  excludeSession?:
+    ((entry: Readonly<CcPeerRosterEntryLike>) => boolean) | undefined;
+}
+
+/** The session's own cc-peer display name when it is usable as an agent name (parseDisplayName, which registration enforces), otherwise "claude-code-<pid>": ensureRegistered requires a defaultName, and a session that never picked a name, or picked one registration would refuse, is still worth fronting under something stable and identifiable. */
+function defaultSessionName(entry: Readonly<CcPeerRosterEntryLike>): string {
+  const name =
+    entry.name === undefined ? undefined : parseDisplayName(entry.name);
+  return name ?? `claude-code-${String(entry.pid)}`;
+}
+
+/**
+ * Builds the default cc-peer front. start()/stop() are safe to call from bridge-mesh.ts's onCoordinatorRoleChanged hook regardless of whether cc-peer itself is usable on this machine: the shared CcPeer instance is created lazily, on the first poll tick that actually needs it (listRoster), not at start() itself, and any construction or attach failure is reported via onError rather than thrown -- "absent sockets" (no local Claude Code sessions at all) is then a clean no-op front rather than a crash of the coordinator that owns it.
+ */
+export function createDefaultCcPeerFront(
+  options: Readonly<CreateDefaultCcPeerFrontOptions> = {},
+): Pick<CcPeerFront<FrontedRelayRecord>, "start" | "stop"> {
+  const borrowedPeer = options.peer;
+  const peerName = options.peerName ?? FRONT_PEER_NAME;
+  let aliasPool: AliasPool | undefined;
+  const aliasDirectory = new ReplyAliasDirectory();
+
+  const front = new CcPeerFront<FrontedRelayRecord>({
+    listRoster: async () => {
+      const peer = await ensureSharedPeer();
+      return peer.roster();
+    },
+    probeSlotOwner,
+    attach: async (entry) => attachSession(entry, await ensureSharedPeer()),
+    detach: detachFrontedSession,
+    aliasDirectory,
+    excludeSession: options.excludeSession,
+    pollIntervalMs: options.pollIntervalMs,
+    onError: options.onError,
+  });
+
+  const sharedPeer = new SharedPeer<FrontCcPeer>(async () => {
+    if (borrowedPeer !== undefined) return borrowedPeer;
+    const peer = await CcPeer.create({ name: FRONT_PEER_NAME });
+    peer.on("message", (message: Readonly<CcPeerInboundMessage>) => {
+      front.handleInboundMessage(message);
+    });
+    return peer;
+  });
+  // A borrowed peer outlives the front's own start/stop cycles, so its listener is attached once here rather than on every (re)creation, which would relay each inbound message once per restart.
+  borrowedPeer?.on("message", (message: Readonly<CcPeerInboundMessage>) => {
+    front.handleInboundMessage(message);
+  });
+
+  return {
+    start: () => {
+      front.start();
+    },
+    stop: async () => {
+      await front.stop();
+      const peer = await sharedPeer.release();
+      if (borrowedPeer === undefined) await peer?.stop();
+      await aliasPool?.stopAll();
+      aliasPool = undefined;
+    },
+  };
+
+  /** Materialises the front's own shared AliasPool on first use (mirroring ensureSharedPeer's own lazy-construction convention) and wires its "message" event, every reply arriving on any fronted session's own correspondent aliases, straight into the controller's handleAliasMessage, which resolves the sending session and the alias's own correspondent before routing it on. The pool is also what delivers a correspondent's own messages into a fronted session, from that correspondent's alias, so the session's reply comes back on this same "message" event. */
+  function ensureAliasPool(): AliasPool {
+    if (aliasPool) return aliasPool;
+    const pool = AliasPool.create();
+    pool.on("message", (message: Readonly<AliasMessage>) => {
+      front.handleAliasMessage(message);
+    });
+    aliasPool = pool;
+    return pool;
+  }
+
+  async function ensureSharedPeer(): Promise<FrontCcPeer> {
+    return sharedPeer.get();
+  }
+
+  async function attachSession(
+    entry: Readonly<CcPeerRosterEntryLike>,
+    peer: Readonly<FrontCcPeer>,
+  ): Promise<FrontedRelayRecord> {
+    const slot = computeFrontSlot(entry.cwd);
+    const identity = loadIdentityForFront(slot);
+    const { store, tool } = await createBridgeMeshFromIdentity(identity, slot, {
+      coordinatorPort: options.coordinatorPort,
+      hubUrl: options.hubUrl,
+    });
+    store.getCcPeerVersion = () => CC_PEER_VERSION;
+
+    const reg = await ensureRegistered({
+      store,
+      harness: "claude-code",
+      cwd: entry.cwd,
+      defaultName: defaultSessionName(entry),
+      visibility: "visible",
+    });
+    const roomId = await ensureProjectRoom(store, reg.agentId, entry.cwd);
+
+    return buildFrontedSessionRecord({
+      entry,
+      peerName,
+      agentId: reg.agentId,
+      roomId,
+      store,
+      tool,
+      peer,
+      aliasPool: ensureAliasPool(),
+      aliasDirectory,
+      onError: options.onError,
+    });
+  }
+}

package/src/bridges/cc-peer/front.ts

@@ -0,0 +1,59 @@
+/**
+ * Pure decision logic for the default cc-peer front (agent-comms#157): a machine's coordinator bridge relays every local Claude Code session that doesn't already front itself, using the same (harness, cwd) identity slot that session's own agent-comms bridge would use, so addressing carries over unchanged the moment that session's own bridge appears.
+ *
+ * Kept free of any real cc-peer/MeshStore construction so it's testable without a real local Claude Code session, a real filesystem, or real sockets -- see front-runtime.ts for the stateful controller and the real wiring built on top of these functions.
+ */
+
+import type { IdentitySlot } from "../../core/identity-store.js";
+
+/** The slice of cc-peer's own RegistryEntry this module needs. Narrowed rather than importing cc-peer's type directly so this file has no compile-time dependency on the cc-peer package (only front-runtime.ts, which does the real construction, needs that). */
+export interface CcPeerRosterEntryLike {
+  pid: number;
+  cwd: string;
+  name?: string | undefined;
+  /** cc-peer's own registry entries for library-backed peers (this front itself, the one-shot `bridge cc-peer` command, an alias-pool worker) always carry the literal string "cc-peer" here -- see buildRegistryEntry in cc-peer's own source. A real interactive Claude Code session, which registers itself natively rather than through the cc-peer library, reports its own Claude Code version instead. */
+  version: string;
+  messagingSocketPath: string;
+}
+
+/** True for a roster entry that is itself a cc-peer-library-backed peer (this front's own shared identity, the one-shot bridge command, an alias-pool worker) rather than a real interactive Claude Code session -- see CcPeerRosterEntryLike.version's own doc comment for the mechanism. The front must never try to front one of these: it would compute a spurious claude-code identity slot for a process that isn't a Claude Code session at all, and relay cc-peer traffic into it that nothing there ever reads. */
+export function isCcPeerLibraryPeer(
+  entry: Readonly<CcPeerRosterEntryLike>,
+): boolean {
+  return entry.version === "cc-peer";
+}
+
+/** The identity slot a session's own agent-comms bridge would hold if it started right now -- the same (harness, cwd) pair every real claude-code bridge entry point (bridges/claude-code/channel.ts) already constructs. */
+export function computeFrontSlot(cwd: string): IdentitySlot {
+  return { harness: "claude-code", cwd };
+}
+
+/**
+ * Filters a cc-peer roster down to the real Claude Code sessions this front should attach to right now: excludes other cc-peer-library peers, and excludes any session whose own slot is already held by a live PID (that session already fronts itself, via its own agent-comms bridge). probeSlotOwner is injected rather than imported directly so this stays a pure function over its inputs -- the real probe (identity-store.ts's probeSlotOwner) reads the filesystem, which has no place in a decision function tested purely over data.
+ */
+export function selectSessionsToFront(
+  roster: readonly CcPeerRosterEntryLike[],
+  probeSlotOwner: (slot: Readonly<IdentitySlot>) => number | undefined,
+): CcPeerRosterEntryLike[] {
+  return roster.filter((entry) => {
+    if (isCcPeerLibraryPeer(entry)) return false;
+    const slot = computeFrontSlot(entry.cwd);
+    return probeSlotOwner(slot) === undefined;
+  });
+}
+
+/**
+ * Finds which currently-fronted session an inbound cc-peer message came from, by matching the envelope's own `from` field (always the literal string "uds:" followed by the sender's own listening socket path, per cc-peer's own send() -- see CcPeer.send in cc-peer's source) against each fronted session's messagingSocketPath. Generic over the fronted-session record type so front-runtime.ts's real records (which carry a live MeshStore/CommsTool alongside the roster entry) can be matched directly without this module needing to know their shape.
+ */
+export function matchInboundMessageSession<
+  T extends { readonly messagingSocketPath: string },
+>(
+  fronted: Readonly<Iterable<T>>,
+  message: Readonly<{ from?: string }>,
+): T | undefined {
+  if (message.from === undefined) return undefined;
+  for (const record of fronted) {
+    if (message.from === `uds:${record.messagingSocketPath}`) return record;
+  }
+  return undefined;
+}

package/src/bridges/cc-peer/reply-aliases.ts

@@ -0,0 +1,90 @@
+/**
+ * Lazy per-correspondent reply aliases for the default cc-peer front (agent-comms#158) — pure alias-name derivation and the in-memory correspondent↔alias directory the front consults on both the mesh-to-session direction (materialise an alias so the session can address a reply to it) and the session-to-mesh direction (translate a reply arriving on an alias back into the correspondent it stands for and where that reply should go).
+ *
+ * Deliberately not persisted: aliases are ephemeral by design, lost on restart and re-materialised by the next inbound message from that correspondent (see the issue body's "Rejected alternatives" for why a directory of every mesh agent is not minted upfront). Kept free of any real cc-peer/AliasPool construction, exactly like front.ts's pure decision logic — front-relay.ts and front-controller.ts consult this directory, and front-runtime.ts supplies the real AliasPool the alias names get materialised against.
+ */
+
+import type { DeliveryEvent } from "../../core/types.js";
+
+/** How many leading hex characters of a correspondent's device-id go into its alias name -- 48 bits of a SHA-256 hash, chosen purely for a short, readable cc-peer peer name; cc-peer's own registry name field has no length or format restriction beyond non-empty (see AliasStartCommandSchema in cc-peer's alias-ipc schema), so this is a readability choice, not a protocol requirement. */
+const ALIAS_ID_LENGTH = 12;
+
+/** cc-peer peer names materialised for reply aliases are prefixed so they read unambiguously as a mesh correspondent, not a real local Claude Code session, in `roster()`/UI listings that show every locally known peer name side by side. */
+const ALIAS_NAME_PREFIX = "mesh-";
+
+/** Derives the cc-peer peer name a correspondent's reply alias registers under. Deterministic and side-effect-free: the same correspondent id always derives the same name, so ReplyAliasDirectory only needs to remember the mapping, not invent a fresh name per call. */
+export function deriveAliasName(correspondentId: string): string {
+  return `${ALIAS_NAME_PREFIX}${correspondentId.slice(0, ALIAS_ID_LENGTH)}`;
+}
+
+/** Where a reply arriving on a correspondent's alias should go back to: a DM straight to that correspondent, or a post back into the room the message that produced the alias was itself sent in. A room's own reply-aliased message always names the room it came from, so a reply lands in the same room rather than always falling back to a DM (agent-comms#289). */
+export type ReplyContext =
+  { readonly kind: "dm" } | { readonly kind: "room"; readonly room: string };
+
+/** The mesh correspondent and reply context a DeliveryEvent carries, for the event types with a single, repliable-to sender — undefined for every other event type (room membership/status/capability events describe something happening, not a message from one correspondent worth aliasing). */
+export interface ReplyTarget {
+  readonly correspondentId: string;
+  readonly context: ReplyContext;
+}
+
+/** Resolves a DeliveryEvent's own reply target, or undefined when the event has no single originating correspondent. A dm event's reply target is always another dm; a room_message event's reply target is the room the message was posted in, since that is what a reply to it should return to, not the sender's own dm channel (agent-comms#289). */
+export function replyTargetForEvent(
+  event: Readonly<DeliveryEvent>,
+): ReplyTarget | undefined {
+  switch (event.type) {
+    case "dm":
+      return { correspondentId: event.message.from, context: { kind: "dm" } };
+    case "room_message":
+      return {
+        correspondentId: event.message.from,
+        context: { kind: "room", room: event.message.room },
+      };
+    case "room_invite":
+    case "member_joined":
+    case "member_left":
+    case "room_members":
+    case "member_status":
+    case "delivery_status":
+    case "invite_declined":
+    case "name_changed":
+    case "connection_request":
+    case "capability_request":
+    case "room_join_request":
+      return undefined;
+    default:
+      return event satisfies never;
+  }
+}
+
+/**
+ * Bounded, in-memory, bijective map between the cc-peer peer names materialised for a front's reply aliases and the mesh correspondent id each one stands for, plus the reply context (dm vs. room) each alias currently carries. Bounded by real correspondents, per the issue's own "Rejected alternatives": a name is only ever minted by ensure(), which the front calls solely on genuine inbound contact from that correspondent — nothing pre-populates this directory with the wider mesh roster.
+ *
+ * A single correspondent id can reach a fronted session two different ways — a direct dm, and a message posted in a room they share with the session — and both share the same alias, since the alias scheme is keyed on the correspondent alone (agent-comms#158). ensure() therefore always records the context of the *most recent* event sent from that alias: a session's reply always continues whatever conversation it was last shown on that alias, so the context that matters is the one behind the last message it actually saw, not whichever context first minted the name.
+ */
+export class ReplyAliasDirectory {
+  private readonly nameToCorrespondent = new Map<string, string>();
+  private readonly correspondentToName = new Map<string, string>();
+  private readonly nameToContext = new Map<string, ReplyContext>();
+
+  /** Returns the alias name for a correspondent, deriving and recording it the first time this correspondent is seen, and records `context` as that alias's current reply target regardless of whether the alias was just minted or already existed. Idempotent on the name itself: a correspondent already known always gets back its existing name, so a session's reply target stays stable across repeated inbound contact within the same front lifetime; the context, however, is refreshed on every call. */
+  ensure(correspondentId: string, context: ReplyContext): string {
+    const existing = this.correspondentToName.get(correspondentId);
+    const name = existing ?? deriveAliasName(correspondentId);
+    if (existing === undefined) {
+      this.correspondentToName.set(correspondentId, name);
+      this.nameToCorrespondent.set(name, correspondentId);
+    }
+    this.nameToContext.set(name, context);
+    return name;
+  }
+
+  /** The correspondent a previously-minted alias name stands for, or undefined for a name this directory never minted (or no longer remembers, e.g. after a front restart cleared it) -- the front's own signal to treat an inbound reply as addressed to a stale alias rather than a known correspondent. */
+  correspondentFor(aliasName: string): string | undefined {
+    return this.nameToCorrespondent.get(aliasName);
+  }
+
+  /** The reply context a previously-minted alias name currently carries (dm or a named room), or undefined for a name this directory never minted. Always defined whenever correspondentFor(aliasName) is, since both are set together by ensure(). */
+  contextFor(aliasName: string): ReplyContext | undefined {
+    return this.nameToContext.get(aliasName);
+  }
+}

package/src/bridges/cc-peer/run.ts

@@ -0,0 +1,100 @@
+/**
+ * cc-peer bridge — CLI entry point.
+ *
+ * Run via: npx agent-comms bridge cc-peer <target-name> npx agent-comms bridge cc-peer --pid=<pid>
+ *
+ * Constructs the real CcPeer and MeshStore, then hands both to wireCcPeerBridge for the actual relay wiring (see bridge.ts).
+ */
+
+import { CcPeer, CC_PEER_VERSION } from "cc-peer";
+import {
+  createBridgeMesh,
+  createMeshErrorReporter,
+  ensureRegistered,
+  ensureProjectRoom,
+  installShutdownSignalHandlers,
+} from "../../core/index.js";
+import type { IdentitySlot } from "../../core/identity-store.js";
+import { releaseIdentityLock } from "../../core/identity-store.js";
+import {
+  createTargetSenderMatcher,
+  targetMatchesEntry,
+  wireCcPeerBridge,
+  type CcPeerRef,
+} from "./bridge.js";
+import { wireDefaultCcPeerFront } from "./default-front.js";
+
+const PID_FLAG_PREFIX = "--pid=";
+/** argv layout for `node cli.js bridge cc-peer <target-arg>`: index 0/1 are the node binary and script path, 2 is "bridge", 3 is the bridge id ("cc-peer") itself -- this bridge's own args start one past that. */
+const BRIDGE_ARGS_START_INDEX = 4;
+/** The name this command registers its one cc-peer peer under, which the target session is told to message to answer a join request. */
+const BRIDGE_PEER_NAME = "agent-comms-bridge";
+
+function parseTarget(argv: readonly string[]): CcPeerRef {
+  const arg = argv[0];
+  if (arg === undefined || arg === "") {
+    console.error(
+      "Usage: agent-comms bridge cc-peer <target-name> | --pid=<pid>",
+    );
+    process.exit(1);
+  }
+  if (arg.startsWith(PID_FLAG_PREFIX)) {
+    const pid = Number(arg.slice(PID_FLAG_PREFIX.length));
+    if (!Number.isInteger(pid) || pid <= 0) {
+      console.error(`Invalid --pid value: ${arg}`);
+      process.exit(1);
+    }
+    return { pid };
+  }
+  return { name: arg };
+}
+
+export async function run(): Promise<void> {
+  const target = parseTarget(process.argv.slice(BRIDGE_ARGS_START_INDEX));
+
+  const identitySlot: IdentitySlot = { harness: "cc-peer", cwd: process.cwd() };
+  // cc-peer allows one peer per process, so this is the only one: the default front borrows it below rather than creating its own, and the front leaves this bridge's own target alone since the relay below already covers it.
+  const peer = await CcPeer.create({ name: BRIDGE_PEER_NAME });
+  const { store, tool } = await createBridgeMesh(identitySlot);
+  store.onError = createMeshErrorReporter();
+  store.getCcPeerVersion = () => CC_PEER_VERSION;
+  store.onCoordinatorRoleChanged = wireDefaultCcPeerFront(store, {
+    peer,
+    peerName: BRIDGE_PEER_NAME,
+    excludeSession: (entry) => targetMatchesEntry(target, entry),
+  });
+
+  const reg = await ensureRegistered({
+    store,
+    cwd: process.cwd(),
+    harness: "cc-peer",
+    defaultName: "cc-peer-bridge",
+  });
+  const roomId = await ensureProjectRoom(store, reg.agentId, process.cwd());
+
+  wireCcPeerBridge({
+    store,
+    tool,
+    peer,
+    agentId: reg.agentId,
+    roomId,
+    target,
+    cwd: process.cwd(),
+    peerName: BRIDGE_PEER_NAME,
+    isFromTarget: createTargetSenderMatcher(target, async () => peer.roster()),
+  });
+
+  await store.init();
+
+  installShutdownSignalHandlers({
+    shutdown: async () => {
+      await peer.stop();
+      await store.setAgentOffline(reg.agentId);
+      // After store.shutdown(), not before: the mesh handover this bridge owes its peers rides the sessions shutdown() closes, and the lock is what stops a replacement claiming this slot's identity while that is still in flight.
+      await store.shutdown();
+      releaseIdentityLock(identitySlot);
+    },
+    disposition: "exit",
+    onError: createMeshErrorReporter(),
+  });
+}

package/src/bridges/cc-peer/shared-peer.ts

@@ -0,0 +1,28 @@
+/**
+ * SharedPeer -- a lazily-created, process-wide holder of one cc-peer peer.
+ *
+ * cc-peer binds one socket per process (`<socket dir>/<pid>.sock`) and registers one session entry per pid, so a second CcPeer.create in the same process fails with EADDRINUSE. Every role in a process that talks through cc-peer (the default front, the one-shot `bridge cc-peer` command) therefore has to go through a single instance.
+ */
+
+/** Holds at most one peer of type P, created by the injected factory on first use. */
+export class SharedPeer<P> {
+  private promise: Promise<P> | undefined;
+
+  constructor(private readonly create: () => Promise<P>) {}
+
+  /** The shared peer, creating it on the first call. Concurrent callers share one creation. A failed creation is forgotten, so the next call retries rather than replaying the same rejection forever. */
+  async get(): Promise<P> {
+    this.promise ??= this.create().catch((error: unknown) => {
+      this.promise = undefined;
+      throw error;
+    });
+    return this.promise;
+  }
+
+  /** Forgets the shared peer and returns it so the caller can stop it, or undefined if none was ever successfully created. The next get() creates a fresh one. */
+  async release(): Promise<P | undefined> {
+    const pending = this.promise;
+    this.promise = undefined;
+    return pending?.catch(() => undefined);
+  }
+}