agent-comms 8.15.9 → 8.15.10

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);
+  }
+}

package/src/bridges/claude-code/channel.ts

@@ -0,0 +1,318 @@
+/**
+ * Agent Comms — Claude Code channel bridge.
+ *
+ * MCP channel server that provides the "agent_comms" tool and pushes
+ * incoming messages into Claude's context via <channel> events and hooks.
+ * Uses TCP mesh for real-time delivery — no filesystem polling.
+ *
+ * Run via: npx agent-comms bridge claude-code
+ *
+ * Pending events are persisted to ~/.agents/bus/pending/claude-code--<slug>.jsonl
+ * so the asyncRewake hook scripts (hooks/drain.sh) can drain them out-of-process
+ * and wake idle Claude via exit code 2.
+ */
+
+import { execFileSync } from "node:child_process";
+import * as fs from "node:fs";
+import * as os from "node:os";
+import * as path from "node:path";
+
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+
+import {
+  createBridgeMesh,
+  createMeshErrorReporter,
+  buildAction,
+  ensureRegistered,
+  extractStreamingBehavior,
+  formatDeliveryEvent,
+  installShutdownSignalHandlers,
+  isActionableEvent,
+  MCP_TOOL_PARAMS,
+  type BridgeRunOptions,
+} from "../../core/index.js";
+import {
+  releaseIdentityLock,
+  type IdentitySlot,
+} from "../../core/identity-store.js";
+import { wireDefaultCcPeerFront } from "../cc-peer/default-front.js";
+import {
+  tryStartBridgeWebServer,
+  getWebUrlStatus,
+} from "../user/web/server.js";
+import { nanoid } from "../../core/nanoid.js";
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+function isErrnoException(err: unknown): err is NodeJS.ErrnoException {
+  return typeof err === "object" && err !== null && "code" in err;
+}
+
+function cwdSlug(cwd: string): string {
+  return cwd.replace(/[^a-zA-Z0-9]/g, "_");
+}
+
+/** Maximum number of process-tree ancestors to walk when hunting for the Claude Code CLI PID. */
+const MAX_PID_WALK_HOPS = 10;
+
+/** Length of the random suffix appended to an auto-generated agent display name. */
+const AUTO_NAME_SUFFIX_LENGTH = 4;
+
+function pendingDir(): string {
+  return path.join(os.homedir(), ".agents", "bus", "pending");
+}
+
+/**
+ * Walk up the process tree to find the Claude Code CLI PID.
+ *
+ * The bridge runs ~3 hops below claude (tsx wrapper → tsx loader → bridge),
+ * so process.ppid alone isn't enough. We walk until we find an ancestor
+ * whose command basename is "claude".
+ *
+ * Two Claude Code instances in the same cwd would otherwise share one
+ * pending file and consume each other's messages. Keying by Claude PID
+ * isolates them. Returns undefined if no claude ancestor can be located
+ * within 10 hops — caller falls back to cwd-only path.
+ */
+function findClaudeCodePid(): number | undefined {
+  let pid = process.ppid;
+  for (let i = 0; i < MAX_PID_WALK_HOPS && pid > 1; i++) {
+    let out: string;
+    try {
+      out = execFileSync("ps", ["-o", "ppid=,comm=", "-p", String(pid)], {
+        encoding: "utf-8",
+      });
+    } catch {
+      return undefined;
+    }
+    const trimmed = out.trim();
+    const match = /^(\d+)\s+(.+)$/.exec(trimmed);
+    if (!match) return undefined;
+    const parentPid = Number.parseInt(match[1] ?? "", 10);
+    const comm = (match[2] ?? "").trim();
+    if (/(^|\/)claude$/.test(comm)) return pid;
+    if (!Number.isFinite(parentPid)) return undefined;
+    pid = parentPid;
+  }
+  return undefined;
+}
+
+function pendingFilePath(cwd: string, claudePid: number | undefined): string {
+  const slug = cwdSlug(cwd);
+  const name =
+    claudePid !== undefined
+      ? `claude-code--${slug}--${String(claudePid)}.jsonl`
+      : `claude-code--${slug}.jsonl`;
+  return path.join(pendingDir(), name);
+}
+
+/**
+ * Drop pending files in this cwd whose owning Claude Code PID is no longer
+ * alive. Prevents accumulation when sessions exit without graceful shutdown.
+ */
+function cleanupStalePendingFiles(cwd: string): void {
+  const dir = pendingDir();
+  const slug = cwdSlug(cwd);
+  const prefix = `claude-code--${slug}--`;
+  let entries: string[];
+  try {
+    entries = fs.readdirSync(dir);
+  } catch (err) {
+    if (isErrnoException(err) && err.code === "ENOENT") return;
+    return;
+  }
+  for (const entry of entries) {
+    if (!entry.startsWith(prefix) || !entry.endsWith(".jsonl")) continue;
+    const pidStr = entry.slice(prefix.length, -".jsonl".length);
+    const pid = Number.parseInt(pidStr, 10);
+    if (!Number.isFinite(pid) || pid <= 1) continue;
+    try {
+      process.kill(pid, 0);
+    } catch (err) {
+      if (isErrnoException(err) && err.code === "ESRCH") {
+        try {
+          fs.unlinkSync(path.join(dir, entry));
+        } catch {
+          // best-effort cleanup, ignore failures
+        }
+      }
+    }
+  }
+}
+
+function appendPending(filePath: string, line: string): void {
+  fs.mkdirSync(path.dirname(filePath), { recursive: true });
+  fs.appendFileSync(filePath, line + "\n");
+}
+
+function drainPending(filePath: string): string[] {
+  const drainPath = `${filePath}.draining-${String(process.pid)}-${String(Date.now())}`;
+  try {
+    fs.renameSync(filePath, drainPath);
+  } catch (err) {
+    if (isErrnoException(err) && err.code === "ENOENT") return [];
+    throw err;
+  }
+  const content = fs.readFileSync(drainPath, "utf-8");
+  fs.unlinkSync(drainPath);
+  return content
+    .split("\n")
+    .map((l) => l.trim())
+    .filter((l) => l.length > 0);
+}
+
+export async function run(options?: Readonly<BridgeRunOptions>): Promise<void> {
+  // Persistent identity for this slot: a stable device-id means the agent ID survives restarts, so peers can keep targeting us
+  const identitySlot: IdentitySlot = options?.slot ?? {
+    harness: "claude-code",
+    cwd: process.cwd(),
+  };
+  const { store, tool } = await createBridgeMesh(identitySlot, options?.mesh);
+  store.onError = createMeshErrorReporter();
+  store.onCoordinatorRoleChanged = wireDefaultCcPeerFront(store);
+  let agentId: string | undefined;
+
+  const claudeCodePid = findClaudeCodePid();
+  if (claudeCodePid === undefined) {
+    process.stderr.write(
+      "agent-comms bridge: could not locate Claude Code PID; using shared cwd pending file (concurrent sessions in the same cwd will share messages)\n",
+    );
+  }
+  cleanupStalePendingFiles(process.cwd());
+  const pendingFile = pendingFilePath(process.cwd(), claudeCodePid);
+
+  const mcp = new McpServer(
+    { name: "agent-comms", version: "0.2.0" },
+    {
+      capabilities: {
+        experimental: { "claude/channel": {} },
+      },
+    },
+  );
+
+  // All events are written to the pending file so the out-of-process hook
+  // drain script can surface them to idle Claude via asyncRewake exit 2.
+  // Actionable events also get an eager channel push for mid-turn delivery
+  // when channels are enabled (--dangerously-load-development-channels).
+  store.onDelivery = async (_targetId: string, event) => {
+    const line = formatDeliveryEvent(event);
+    const hint = extractStreamingBehavior(event);
+    const shouldPush = isActionableEvent(event) && hint !== "info";
+
+    appendPending(pendingFile, line);
+
+    if (shouldPush) {
+      await mcp.server.notification({
+        method: "notifications/claude/channel",
+        params: {
+          content: line,
+          meta: { streamingBehavior: hint ?? "steer" },
+        },
+      });
+    }
+  };
+
+  // -----------------------------------------------------------------------
+  // Tool registration
+  // -----------------------------------------------------------------------
+
+  mcp.registerTool(
+    "agent_comms",
+    {
+      description: [
+        "Cross-harness agent communication mesh. Actions:",
+        "register, update, whoami, web_url, create_room, list_rooms, join_room, leave_room,",
+        "send, dm, list_agents, read_room, invite, decline_invite, kick, destroy_room.",
+        'Incoming messages appear as <channel source="agent-comms"> events or [comms] Pending prefix.',
+        "Use streamingBehavior on send/dm: steer (act now), followUp (act when idle), info (whenever, default).",
+      ].join(" "),
+      inputSchema: MCP_TOOL_PARAMS,
+    },
+    async (rawParams: unknown) => {
+      const params = isRecord(rawParams) ? rawParams : {};
+      const actionParam = params.action;
+      if (agentId === undefined) {
+        const name =
+          actionParam === "register" && typeof params.name === "string"
+            ? params.name
+            : `claude-code-${nanoid(AUTO_NAME_SUFFIX_LENGTH)}`;
+        const reg = await ensureRegistered({
+          cwd: process.cwd(),
+          store,
+          harness: "claude-code",
+          defaultName: name,
+        });
+        agentId = reg.agentId;
+      }
+
+      const action = buildAction(params);
+      const result = await tool.handle(
+        {
+          agentId,
+          harness: "claude-code",
+          cwd: process.cwd(),
+          pid: process.pid,
+        },
+        action,
+      );
+
+      const pending = drainPending(pendingFile);
+      const prefix =
+        pending.length > 0
+          ? `[comms] Pending:\n${pending.map((l) => `  📬 ${l}`).join("\n")}\n\n`
+          : "";
+
+      return {
+        content: [{ type: "text", text: `${prefix}${result.content}` }],
+        isError: result.isError,
+      };
+    },
+  );
+
+  // -----------------------------------------------------------------------
+  // Startup
+  // -----------------------------------------------------------------------
+
+  await store.init();
+  const webHandle = await tryStartBridgeWebServer(store, "claude-code");
+  tool.getWebUrlStatus = () => getWebUrlStatus(webHandle);
+  await mcp.connect(new StdioServerTransport());
+
+  const reg = await ensureRegistered({
+    cwd: process.cwd(),
+    store,
+    harness: "claude-code",
+    defaultName: `claude-code-${nanoid(AUTO_NAME_SUFFIX_LENGTH)}`,
+  });
+  agentId = reg.agentId;
+
+  // -----------------------------------------------------------------------
+  // Shutdown — clean up mesh state when Claude Code exits
+  // -----------------------------------------------------------------------
+
+  async function shutdown(): Promise<void> {
+    try {
+      if (agentId !== undefined) {
+        await store.setAgentOffline(agentId);
+      }
+      await store.shutdown();
+    } catch {
+      // best-effort — the process is exiting anyway
+    } finally {
+      releaseIdentityLock(identitySlot);
+    }
+  }
+
+  installShutdownSignalHandlers({ shutdown, disposition: "exit" });
+
+  process.on("exit", () => {
+    // Synchronous fallback if async shutdown didn't complete in time.
+    // store.shutdown() is async but the coordinator socket unref() in
+    // MeshStore.init() means the process won't hang on the way out.
+    // Lock release is synchronous and pid-guarded, so it is safe to repeat.
+    releaseIdentityLock(identitySlot);
+  });
+}

package/src/bridges/codex/tool.ts

@@ -0,0 +1,132 @@
+/**
+ * Agent Comms — Codex MCP tool server.
+ *
+ * Provides the "agent_comms" tool for Codex to call.
+ * Uses TCP mesh for state sync. Pending messages are drained and
+ * appended to every tool response so Codex sees them mid-turn.
+ *
+ * Run via: npx agent-comms bridge codex
+ */
+
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+
+import {
+  createBridgeMesh,
+  createMeshErrorReporter,
+  buildAction,
+  ensureRegistered,
+  drainAndFormat,
+  installShutdownSignalHandlers,
+  MCP_TOOL_PARAMS,
+} from "../../core/index.js";
+import type { IdentitySlot } from "../../core/identity-store.js";
+import { releaseIdentityLock } from "../../core/identity-store.js";
+import { wireDefaultCcPeerFront } from "../cc-peer/default-front.js";
+import {
+  tryStartBridgeWebServer,
+  getWebUrlStatus,
+} from "../user/web/server.js";
+import { nanoid } from "../../core/nanoid.js";
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+/** Length of the random suffix appended to an auto-generated `codex-<suffix>` agent name. */
+const CODEX_AGENT_NAME_SUFFIX_LENGTH = 4;
+
+export async function run(): Promise<void> {
+  // Persistent identity for this slot: a stable device-id means the agent ID survives restarts, so peers can keep targeting us.
+  const identitySlot: IdentitySlot = { harness: "codex", cwd: process.cwd() };
+  const { store, tool } = await createBridgeMesh(identitySlot);
+  store.onError = createMeshErrorReporter();
+  store.onCoordinatorRoleChanged = wireDefaultCcPeerFront(store);
+  let agentId: string | undefined;
+
+  const mcp = new McpServer(
+    { name: "agent-comms", version: "0.2.0" },
+    { capabilities: {} },
+  );
+
+  // -----------------------------------------------------------------------
+  // Tool registration
+  // -----------------------------------------------------------------------
+
+  mcp.registerTool(
+    "agent_comms",
+    {
+      description: [
+        "Cross-harness agent communication mesh. Actions:",
+        "register, update, whoami, web_url, create_room, list_rooms, join_room, leave_room,",
+        "send, dm, list_agents, read_room, invite, decline_invite, kick, destroy_room.",
+        "Pending incoming messages are included in every response.",
+      ].join(" "),
+      inputSchema: MCP_TOOL_PARAMS,
+    },
+    async (rawParams: unknown) => {
+      const params = isRecord(rawParams) ? rawParams : {};
+      const actionParam = params.action;
+      if (agentId === undefined) {
+        const name =
+          actionParam === "register" && typeof params.name === "string"
+            ? params.name
+            : `codex-${nanoid(CODEX_AGENT_NAME_SUFFIX_LENGTH)}`;
+        const reg = await ensureRegistered({
+          cwd: process.cwd(),
+          store,
+          harness: "codex",
+          defaultName: name,
+        });
+        agentId = reg.agentId;
+      }
+
+      const action = buildAction(params);
+      const result = await tool.handle(
+        { agentId, harness: "codex", cwd: process.cwd(), pid: process.pid },
+        action,
+      );
+
+      // Drain pending delivery messages and append to response
+      const deliveryLines = await drainAndFormat(store, agentId);
+      const content: { type: "text"; text: string }[] = [
+        { type: "text", text: result.content },
+      ];
+
+      if (deliveryLines.length > 0) {
+        content.push({
+          type: "text",
+          text: "📬 Incoming messages:\n" + deliveryLines.join("\n"),
+        });
+      }
+
+      return { content, isError: result.isError };
+    },
+  );
+
+  // -----------------------------------------------------------------------
+  // Startup
+  // -----------------------------------------------------------------------
+
+  await store.init();
+  const webHandle = await tryStartBridgeWebServer(store, "codex");
+  tool.getWebUrlStatus = () => getWebUrlStatus(webHandle);
+  await mcp.connect(new StdioServerTransport());
+
+  const reg = await ensureRegistered({
+    cwd: process.cwd(),
+    store,
+    harness: "codex",
+    defaultName: `codex-${nanoid(CODEX_AGENT_NAME_SUFFIX_LENGTH)}`,
+  });
+  agentId = reg.agentId;
+
+  installShutdownSignalHandlers({
+    shutdown: async () => {
+      if (agentId !== undefined) await store.setAgentOffline(agentId);
+      await store.shutdown();
+      releaseIdentityLock(identitySlot);
+    },
+    disposition: "exit",
+  });
+}