agent-comms 8.15.9 → 8.15.10

package/src/core/bridge.ts

@@ -0,0 +1,718 @@
+/**
+ * Agent Comms — shared bridge helpers.
+ *
+ * Every bridge needs the same three things:
+ *   1. Parse tool parameters into a CommsAction (via Zod schema)
+ *   2. Format a DeliveryEvent as human-readable text
+ *   3. Register (or recover) an agent identity
+ *
+ * Extracted here so each bridge only wires up its harness-specific
+ * push mechanism and tool registration.
+ */
+
+import * as path from "node:path";
+import type { CommsStore } from "./comms-store.js";
+import type {
+  CommsAction,
+  DeliveryEvent,
+  StreamingBehavior,
+  Visibility,
+} from "./types.js";
+import { ownerNamedRoomPath, slugRoomName } from "./room-path.js";
+import { describeDeliveryFor } from "./send-outcome.js";
+import { z } from "zod";
+
+// ---------------------------------------------------------------------------
+// Tool parameter schema — single source of truth for MCP input
+// ---------------------------------------------------------------------------
+
+const VisibilityEnum = z.enum(["visible", "hidden", "ghost"]);
+const StatusEnum = z.enum(["active", "idle", "busy"]);
+const RoomTypeEnum = z.enum(["public", "private", "secret"]);
+
+const MeshVisibilityEnum = z.enum(["discoverable", "quiet", "dark"]);
+
+export const MCP_TOOL_PARAMS = z.object({
+  action: z.enum([
+    "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",
+    "mesh_connect",
+    "mesh_accept",
+    "mesh_reject",
+    "mesh_pending",
+    "room_accept",
+    "room_reject",
+    "room_pending",
+    "capability_accept",
+    "capability_reject",
+    "capability_pending",
+    "mesh_discover",
+    "mesh_advertise",
+    "mesh_unadvertise",
+    "mesh_interfaces",
+    "mesh_listen",
+    "mesh_unlisten",
+    "mesh_listeners",
+    "mesh_set_visibility",
+    "mesh_get_visibility",
+    "gateway_trust",
+    "gateway_untrust",
+    "gateway_list_trusted",
+    "petname_set",
+    "petname_clear",
+    "petname_list",
+    "machine_name",
+    "principal_name",
+    "dm_admit",
+    "dm_use_grant",
+    "dm_revoke",
+    "gateway_generate_connection_code",
+    "gateway_redeem_connection_code",
+    "query_version",
+    "mesh_graph",
+    "mesh_trace",
+  ]),
+  name: z.string().optional(),
+  visibility: VisibilityEnum.optional(),
+  tags: z.array(z.string()).optional(),
+  status: StatusEnum.optional(),
+  room: z.string().optional(),
+  type: RoomTypeEnum.optional(),
+  description: z.string().optional(),
+  target: z.string().optional(),
+  content: z.string().optional(),
+  agent: z.string().optional(),
+  since: z.string().optional(),
+  replyTo: z.string().optional(),
+  reason: z.string().optional(),
+  method: z.string().optional(),
+  host: z.string().optional(),
+  port: z.number().optional(),
+  policy: z.string().optional(),
+  adapter: z.string().optional(),
+  id: z.string().optional(),
+  meshVisibility: MeshVisibilityEnum.optional(),
+  connectionId: z.string().optional(),
+  requesterId: z.string().optional(),
+  streamingBehavior: z.enum(["steer", "followUp", "info"]).optional(),
+  requestId: z.string().optional(),
+  capability: z.string().optional(),
+  expires: z.number().optional(),
+  delegationsRemaining: z.number().optional(),
+  /** A remote gateway's own device-id (hex), for gateway_trust/gateway_untrust, for gateway_redeem_connection_code (the code's own embedded deviceId field), and the device-id petname_set/petname_clear label. */
+  device: z.string().optional(),
+  /** The connection code's own nonce (gateway_redeem_connection_code). */
+  code: z.string().optional(),
+  /** ISO-8601 expiry for gateway_generate_connection_code's ttlMs override, or the redeemed code's own expiresAt field for gateway_redeem_connection_code. */
+  expiresAt: z.string().optional(),
+  /** ttlMs override for gateway_generate_connection_code; defaults to DEFAULT_CONNECTION_CODE_TTL_MS when omitted. */
+  ttlMs: z.number().optional(),
+  /** Armored PGP private key to sign a generated code with (gateway_generate_connection_code), or armored PGP public key to verify a redeemed code's signature against (gateway_redeem_connection_code). Both are supplied per call -- agent-comms never generates, stores, or manages PGP key material itself. */
+  privateKey: z.string().optional(),
+  publicKey: z.string().optional(),
+  /** Passphrase for privateKey, if it is passphrase-protected (gateway_generate_connection_code). */
+  passphrase: z.string().optional(),
+  /** The redeemed code's own signature field (gateway_redeem_connection_code), or a PGP fingerprint the caller already independently trusts, used either to pin a supplied publicKey or to fetch one from a keyserver when publicKey is omitted. */
+  signature: z.string().optional(),
+  fingerprint: z.string().optional(),
+  /** For gateway_trust/gateway_untrust (and dm_admit, where `target` names it): when true, the id names a user principal (agent-comms#187) rather than a bare remote device-id (agent-comms#193). */
+  principal: z.boolean().optional(),
+  /** For gateway_trust/gateway_untrust: when true, the id names a machine (agent-comms#343), whose devices (every bridge one OS account runs on that host) are trusted or revoked at once. */
+  machine: z.boolean().optional(),
+  /** The dm:send grant text dm_admit returned, presented by dm_use_grant. */
+  grant: z.string().optional(),
+  /** How long mesh_trace waits for a path.trace response before giving up (agent-comms#199). */
+  timeoutMs: z.number().optional(),
+});
+
+export type ToolParams = z.infer<typeof MCP_TOOL_PARAMS>;
+
+/**
+ * Zod schema for the MCP tool inputSchema field.
+ * This is the same schema exposed directly for the MCP SDK.
+ */
+// Removed MCP_TOOL_SCHEMA alias — use MCP_TOOL_PARAMS directly
+
+// ---------------------------------------------------------------------------
+// buildAction — parsed params → typed CommsAction
+// ---------------------------------------------------------------------------
+
+class BuildActionError extends Error {
+  constructor(
+    public readonly action: string,
+    field: string,
+  ) {
+    super(`Missing required field "${field}" for action "${action}"`);
+    this.name = "BuildActionError";
+  }
+}
+
+export function buildAction(params: Record<string, unknown>): CommsAction {
+  const parsed = MCP_TOOL_PARAMS.safeParse(params);
+  if (!parsed.success) return { action: "whoami" };
+  const p = parsed.data;
+
+  switch (p.action) {
+    case "register":
+      if (p.name === undefined) throw new BuildActionError("register", "name");
+      return {
+        action: "register",
+        name: p.name,
+        visibility: p.visibility ?? "visible",
+        tags: p.tags ?? [],
+      };
+    case "update": {
+      const update: CommsAction & { action: "update" } = { action: "update" };
+      if (p.visibility !== undefined) update.visibility = p.visibility;
+      if (p.status !== undefined) update.status = p.status;
+      if (p.name !== undefined) update.name = p.name;
+      if (p.tags !== undefined) update.tags = p.tags;
+      return update;
+    }
+    case "whoami":
+      return { action: "whoami" };
+    case "web_url":
+      return { action: "web_url" };
+    case "create_room":
+      if (p.room === undefined)
+        throw new BuildActionError("create_room", "room");
+      return {
+        action: "create_room",
+        name: p.room,
+        type: p.type ?? "public",
+        description: p.description ?? "",
+      };
+    case "list_rooms":
+      return { action: "list_rooms" };
+    case "join_room":
+      if (p.room === undefined) throw new BuildActionError("join_room", "room");
+      return { action: "join_room", room: p.room };
+    case "leave_room":
+      if (p.room === undefined)
+        throw new BuildActionError("leave_room", "room");
+      return { action: "leave_room", room: p.room };
+    case "send": {
+      if (p.content === undefined)
+        throw new BuildActionError("send", "content");
+      if (p.target !== undefined) {
+        const send: CommsAction & { action: "send" } = {
+          action: "send",
+          target: p.target,
+          content: p.content,
+        };
+        if (p.replyTo !== undefined) send.replyTo = p.replyTo;
+        if (p.streamingBehavior !== undefined)
+          send.streamingBehavior = p.streamingBehavior;
+        return send;
+      }
+      if (p.room !== undefined) {
+        const send: CommsAction & { action: "send" } = {
+          action: "send",
+          target: p.room,
+          content: p.content,
+        };
+        if (p.replyTo !== undefined) send.replyTo = p.replyTo;
+        if (p.streamingBehavior !== undefined)
+          send.streamingBehavior = p.streamingBehavior;
+        return send;
+      }
+      throw new BuildActionError("send", "target");
+    }
+    case "dm": {
+      if (p.content === undefined) throw new BuildActionError("dm", "content");
+      if (p.target !== undefined) {
+        const dm: CommsAction & { action: "dm" } = {
+          action: "dm",
+          target: p.target,
+          content: p.content,
+        };
+        if (p.streamingBehavior !== undefined)
+          dm.streamingBehavior = p.streamingBehavior;
+        return dm;
+      }
+      if (p.agent !== undefined) {
+        const dm: CommsAction & { action: "dm" } = {
+          action: "dm",
+          target: p.agent,
+          content: p.content,
+        };
+        if (p.streamingBehavior !== undefined)
+          dm.streamingBehavior = p.streamingBehavior;
+        return dm;
+      }
+      throw new BuildActionError("dm", "target");
+    }
+    case "list_agents":
+      return { action: "list_agents" };
+    case "read_room":
+      if (p.room === undefined) throw new BuildActionError("read_room", "room");
+      return {
+        action: "read_room",
+        room: p.room,
+        ...(p.since !== undefined && { since: p.since }),
+      };
+    case "invite":
+      if (p.room === undefined) throw new BuildActionError("invite", "room");
+      if (p.agent === undefined) throw new BuildActionError("invite", "agent");
+      return { action: "invite", room: p.room, agent: p.agent };
+    case "decline_invite":
+      if (p.room === undefined)
+        throw new BuildActionError("decline_invite", "room");
+      if (p.reason === undefined)
+        throw new BuildActionError("decline_invite", "reason");
+      return { action: "decline_invite", room: p.room, reason: p.reason };
+    case "kick":
+      if (p.room === undefined) throw new BuildActionError("kick", "room");
+      if (p.agent === undefined) throw new BuildActionError("kick", "agent");
+      return { action: "kick", room: p.room, agent: p.agent };
+    case "destroy_room":
+      if (p.room === undefined)
+        throw new BuildActionError("destroy_room", "room");
+      return { action: "destroy_room", room: p.room };
+    case "mesh_connect": {
+      if (p.host === undefined)
+        throw new BuildActionError("mesh_connect", "host");
+      if (p.port === undefined)
+        throw new BuildActionError("mesh_connect", "port");
+      return {
+        action: "mesh_connect",
+        host: p.host,
+        port: p.port,
+        ...(p.policy !== undefined && { policy: p.policy }),
+      };
+    }
+    case "mesh_accept": {
+      if (p.connectionId === undefined)
+        throw new BuildActionError("mesh_accept", "connectionId");
+      return { action: "mesh_accept", connectionId: p.connectionId };
+    }
+    case "mesh_reject": {
+      if (p.connectionId === undefined)
+        throw new BuildActionError("mesh_reject", "connectionId");
+      if (p.reason === undefined)
+        throw new BuildActionError("mesh_reject", "reason");
+      return {
+        action: "mesh_reject",
+        connectionId: p.connectionId,
+        reason: p.reason,
+      };
+    }
+    case "mesh_pending":
+      return { action: "mesh_pending" };
+    case "room_accept": {
+      if (p.room === undefined)
+        throw new BuildActionError("room_accept", "room");
+      if (p.requesterId === undefined)
+        throw new BuildActionError("room_accept", "requesterId");
+      return {
+        action: "room_accept",
+        room: p.room,
+        requesterId: p.requesterId,
+      };
+    }
+    case "room_reject": {
+      if (p.room === undefined)
+        throw new BuildActionError("room_reject", "room");
+      if (p.requesterId === undefined)
+        throw new BuildActionError("room_reject", "requesterId");
+      return {
+        action: "room_reject",
+        room: p.room,
+        requesterId: p.requesterId,
+        ...(p.reason !== undefined && { reason: p.reason }),
+      };
+    }
+    case "room_pending":
+      return { action: "room_pending" };
+    case "capability_accept": {
+      if (p.requestId === undefined)
+        throw new BuildActionError("capability_accept", "requestId");
+      if (p.expires === undefined)
+        throw new BuildActionError("capability_accept", "expires");
+      return {
+        action: "capability_accept",
+        requestId: p.requestId,
+        expires: p.expires,
+        ...(p.delegationsRemaining !== undefined && {
+          delegationsRemaining: p.delegationsRemaining,
+        }),
+        ...(p.capability !== undefined && { capability: p.capability }),
+      };
+    }
+    case "capability_reject": {
+      if (p.requestId === undefined)
+        throw new BuildActionError("capability_reject", "requestId");
+      return {
+        action: "capability_reject",
+        requestId: p.requestId,
+        ...(p.reason !== undefined && { reason: p.reason }),
+      };
+    }
+    case "capability_pending":
+      return { action: "capability_pending" };
+    case "mesh_discover": {
+      const discover: CommsAction & { action: "mesh_discover" } = {
+        action: "mesh_discover",
+      };
+      if (p.method !== undefined) discover.method = p.method;
+      return discover;
+    }
+    case "mesh_advertise":
+      if (p.name === undefined)
+        throw new BuildActionError("mesh_advertise", "name");
+      if (p.method === undefined)
+        throw new BuildActionError("mesh_advertise", "method");
+      return {
+        action: "mesh_advertise",
+        method: p.method,
+        name: p.name,
+        ...(p.port !== undefined && { port: p.port }),
+        ...(p.adapter !== undefined && { adapter: p.adapter }),
+      };
+    case "mesh_unadvertise":
+      if (p.id === undefined)
+        throw new BuildActionError("mesh_unadvertise", "id");
+      return { action: "mesh_unadvertise", id: p.id };
+    case "mesh_interfaces":
+      return { action: "mesh_interfaces" };
+    case "mesh_listen":
+      if (p.host === undefined)
+        throw new BuildActionError("mesh_listen", "host");
+      return {
+        action: "mesh_listen",
+        host: p.host,
+        ...(p.port !== undefined && { port: p.port }),
+        ...(p.policy !== undefined && { policy: p.policy }),
+      };
+    case "mesh_unlisten":
+      if (p.id === undefined) throw new BuildActionError("mesh_unlisten", "id");
+      return { action: "mesh_unlisten", id: p.id };
+    case "mesh_listeners":
+      return { action: "mesh_listeners" };
+    case "mesh_set_visibility": {
+      if (p.meshVisibility === undefined) {
+        throw new BuildActionError("mesh_set_visibility", "meshVisibility");
+      }
+      const result: CommsAction & { action: "mesh_set_visibility" } = {
+        action: "mesh_set_visibility",
+        visibility: p.meshVisibility,
+      };
+      if (p.adapter !== undefined) result.adapter = p.adapter;
+      return result;
+    }
+    case "mesh_get_visibility": {
+      const result: CommsAction & { action: "mesh_get_visibility" } = {
+        action: "mesh_get_visibility",
+      };
+      return result;
+    }
+    case "gateway_trust":
+      if (p.device === undefined)
+        throw new BuildActionError("gateway_trust", "device");
+      return {
+        action: "gateway_trust",
+        device: p.device,
+        ...(p.principal !== undefined && { principal: p.principal }),
+        ...(p.machine !== undefined && { machine: p.machine }),
+      };
+    case "gateway_untrust":
+      if (p.device === undefined)
+        throw new BuildActionError("gateway_untrust", "device");
+      return {
+        action: "gateway_untrust",
+        device: p.device,
+        ...(p.principal !== undefined && { principal: p.principal }),
+        ...(p.machine !== undefined && { machine: p.machine }),
+      };
+    case "gateway_list_trusted":
+      return { action: "gateway_list_trusted" };
+    case "petname_set":
+      if (p.device === undefined)
+        throw new BuildActionError("petname_set", "device");
+      if (p.name === undefined)
+        throw new BuildActionError("petname_set", "name");
+      return { action: "petname_set", device: p.device, name: p.name };
+    case "petname_clear":
+      if (p.device === undefined)
+        throw new BuildActionError("petname_clear", "device");
+      return { action: "petname_clear", device: p.device };
+    case "petname_list":
+      return { action: "petname_list" };
+    case "machine_name":
+      return {
+        action: "machine_name",
+        ...(p.name !== undefined && { name: p.name }),
+      };
+    case "principal_name":
+      return {
+        action: "principal_name",
+        ...(p.name !== undefined && { name: p.name }),
+      };
+    case "dm_admit":
+      if (p.target === undefined)
+        throw new BuildActionError("dm_admit", "target");
+      return {
+        action: "dm_admit",
+        target: p.target,
+        ...(p.principal !== undefined && { principal: p.principal }),
+      };
+    case "dm_use_grant":
+      if (p.target === undefined)
+        throw new BuildActionError("dm_use_grant", "target");
+      if (p.grant === undefined)
+        throw new BuildActionError("dm_use_grant", "grant");
+      return { action: "dm_use_grant", target: p.target, grant: p.grant };
+    case "dm_revoke":
+      if (p.target === undefined)
+        throw new BuildActionError("dm_revoke", "target");
+      return { action: "dm_revoke", target: p.target };
+    case "gateway_generate_connection_code":
+      return {
+        action: "gateway_generate_connection_code",
+        ...(p.ttlMs !== undefined && { ttlMs: p.ttlMs }),
+        ...(p.privateKey !== undefined && { privateKey: p.privateKey }),
+        ...(p.passphrase !== undefined && { passphrase: p.passphrase }),
+      };
+    case "gateway_redeem_connection_code":
+      if (p.code === undefined)
+        throw new BuildActionError("gateway_redeem_connection_code", "code");
+      if (p.expiresAt === undefined)
+        throw new BuildActionError(
+          "gateway_redeem_connection_code",
+          "expiresAt",
+        );
+      if (p.device === undefined)
+        throw new BuildActionError("gateway_redeem_connection_code", "device");
+      return {
+        action: "gateway_redeem_connection_code",
+        code: p.code,
+        expiresAt: p.expiresAt,
+        device: p.device,
+        ...(p.signature !== undefined && { signature: p.signature }),
+        ...(p.publicKey !== undefined && { publicKey: p.publicKey }),
+        ...(p.fingerprint !== undefined && { fingerprint: p.fingerprint }),
+      };
+    case "query_version":
+      if (p.device === undefined)
+        throw new BuildActionError("query_version", "device");
+      return { action: "query_version", device: p.device };
+    case "mesh_graph":
+      return { action: "mesh_graph" };
+    case "mesh_trace":
+      if (p.target === undefined)
+        throw new BuildActionError("mesh_trace", "target");
+      return {
+        action: "mesh_trace",
+        target: p.target,
+        ...(p.timeoutMs !== undefined && { timeoutMs: p.timeoutMs }),
+      };
+    default:
+      return p.action satisfies never;
+  }
+}
+
+// ---------------------------------------------------------------------------
+// extractStreamingBehavior — pull hint from message envelope if present
+// ---------------------------------------------------------------------------
+
+export function extractStreamingBehavior(
+  event: DeliveryEvent,
+): StreamingBehavior | undefined {
+  if (event.type === "dm" || event.type === "room_message") {
+    return event.message.streamingBehavior;
+  }
+  return undefined;
+}
+
+// ---------------------------------------------------------------------------
+// formatDeliveryEvent — DeliveryEvent → human-readable string
+// ---------------------------------------------------------------------------
+
+export function formatDeliveryEvent(event: DeliveryEvent): string {
+  const hint = extractStreamingBehavior(event);
+  const pfx =
+    hint === "steer" ? "[STEER] " : hint === "followUp" ? "[FOLLOWUP] " : "";
+  switch (event.type) {
+    case "room_message":
+      return `${pfx}[${event.message.room}] ${event.message.from}: ${event.message.content}`;
+    case "dm":
+      return `${pfx}DM from ${event.message.from}: ${event.message.content}`;
+    case "room_invite": {
+      const desc = event.roomDescription ? ` — ${event.roomDescription}` : "";
+      const who = event.fromCwd
+        ? `${event.fromName} (${event.fromCwd})`
+        : event.fromName;
+      return `${who} invited you to room "${event.room}"${desc}`;
+    }
+    case "member_joined":
+      return `${event.agent} joined ${event.room}`;
+    case "member_left":
+      return `${event.agent} left ${event.room}`;
+    case "room_members": {
+      const names = event.members
+        .map((m) => `${m.name} (${m.status})`)
+        .join(", ");
+      return `Room ${event.room} members: ${names}`;
+    }
+    case "member_status":
+      return `${event.agent} is now ${event.status} in ${event.room}`;
+    case "delivery_status":
+      return `Message ${event.messageId} ${describeDeliveryFor(event.delivery, event.agent)}${event.room !== undefined ? ` in ${event.room}` : ""}`;
+    case "invite_declined":
+      return `${event.agentName} declined invite to ${event.room}: "${event.reason}"`;
+    case "name_changed":
+      return `${event.oldName} is now known as ${event.newName}`;
+    case "connection_request":
+      return `Connection request from ${event.peerId} (${event.name}) fingerprint ${event.fingerprint}`;
+    case "capability_request":
+      return `${event.requesterDevice} is asking for "${event.capability}" (${event.requestId})`;
+    case "room_join_request":
+      return `${event.requesterId} is asking to join ${event.room}: room_accept or room_reject to answer`;
+    default:
+      return event satisfies never;
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Event classification — actionable vs informational
+// ---------------------------------------------------------------------------
+
+/**
+ * Classify a delivery event as actionable (requires model attention)
+ * or informational (can be buffered and returned with next tool call).
+ *
+ * Actionable: DMs, room messages, room invites, and room join requests awaiting its decision — the model may need to respond, and a requester may be blocked until it does.
+ * Informational: status changes, joins/leaves, renames, read receipts —
+ *   the model may need to know eventually but never needs to act immediately.
+ */
+export function isActionableEvent(event: DeliveryEvent): boolean {
+  switch (event.type) {
+    case "dm":
+    case "room_message":
+    case "room_invite":
+    case "room_join_request":
+      return true;
+    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":
+      return false;
+    default:
+      return event satisfies never;
+  }
+}
+
+// ---------------------------------------------------------------------------
+// ensureRegistered — recover or create an agent identity
+// ---------------------------------------------------------------------------
+
+export interface RegistrationResult {
+  agentId: string;
+  store: CommsStore;
+  isNew: boolean;
+}
+
+/**
+ * Recover an existing identity (from `identity.json`) or register a new agent.
+ * Returns the agent ID and whether this was a fresh registration.
+ */
+export async function ensureRegistered(opts: {
+  store: CommsStore;
+  harness: string;
+  cwd: string;
+  defaultName: string;
+  visibility?: Visibility;
+  tags?: string[];
+}): Promise<RegistrationResult> {
+  await opts.store.init();
+
+  const identity = await opts.store.readIdentity(opts.harness, opts.cwd);
+  if (identity) {
+    await opts.store.updateAgent(identity.id, {
+      status: "active",
+      pid: process.pid,
+    });
+    await ensureProjectRoom(opts.store, identity.id, opts.cwd);
+    return { agentId: identity.id, store: opts.store, isNew: false };
+  }
+
+  const agent = await opts.store.registerAgent({
+    name: opts.defaultName,
+    harness: opts.harness,
+    cwd: opts.cwd,
+    pid: process.pid,
+    visibility: opts.visibility ?? "visible",
+    tags: opts.tags ?? [],
+  });
+  await ensureProjectRoom(opts.store, agent.id, opts.cwd);
+  return { agentId: agent.id, store: opts.store, isNew: true };
+}
+
+// ---------------------------------------------------------------------------
+// ensureProjectRoom — auto-create a room for the agent's working directory
+// ---------------------------------------------------------------------------
+
+/**
+ * Ensure a project room exists for the given cwd and the agent is a member. Creates the room if needed and joins the agent. No-op if already a member. Returns the room ID.
+ *
+ * Every agent computes an owner-rooted path with itself as owner, so two agents in the same cwd do not currently converge on one shared room -- a real, deliberately deferred regression from the pre-core/room behaviour (see the design doc's OQ-2: deterministic lowest-device-id ownership is P3.4's own responsibility, once gossiped presence data is wired up here).
+ */
+export async function ensureProjectRoom(
+  store: Readonly<CommsStore>,
+  agentId: string,
+  cwd: string,
+): Promise<string> {
+  const localName = slugRoomName(path.basename(cwd));
+  const id = ownerNamedRoomPath(agentId, localName);
+
+  // Check if the room already exists
+  const existing = await store.getRoom(id);
+  if (existing) {
+    // Room exists — verify it's a project room (description matches pattern)
+    if (!existing.members.includes(agentId)) {
+      await store.joinRoom(id, agentId);
+    }
+    return id;
+  }
+
+  // Create — createRoom auto-joins the owner
+  await store.createRoom({
+    name: localName,
+    type: "public",
+    owner: agentId,
+    description: `Project room for ${cwd}`,
+  });
+
+  return id;
+}
+
+// ---------------------------------------------------------------------------
+// drainAndFormat — drain delivery queue, return formatted lines
+// ---------------------------------------------------------------------------
+
+export async function drainAndFormat(
+  store: Readonly<CommsStore>,
+  agentId: string,
+): Promise<string[]> {
+  const events = await store.drainDelivery(agentId);
+  return events.map(formatDeliveryEvent);
+}