agent-comms 8.15.8 → 8.15.10

package/src/bridges/user/controller.ts

@@ -0,0 +1,345 @@
+/**
+ * ChatController — shared logic for user-facing UIs (TUI, web, CLI).
+ *
+ * Wraps MeshStore + CommsTool with an EventEmitter interface.
+ * UIs subscribe to events and call methods — no direct MeshStore access needed.
+ */
+
+import { EventEmitter } from "node:events";
+import type { MeshStore } from "../../core/index.js";
+import {
+  CommsTool,
+  createBridgeMesh,
+  ensureRegistered,
+  formatDeliveryEvent,
+  formatMeshError,
+} from "../../core/index.js";
+import {
+  releaseIdentityLock,
+  type IdentitySlot,
+} from "../../core/identity-store.js";
+import { wireDefaultCcPeerFront } from "../cc-peer/default-front.js";
+import type { CommsContext, CommsResult } from "../../core/tool.js";
+import type {
+  AgentIdentity,
+  DeliveryEvent,
+  Room,
+  RoomMessage,
+} from "../../core/types.js";
+
+// ---------------------------------------------------------------------------
+// Event types
+// ---------------------------------------------------------------------------
+
+export class ChatController extends EventEmitter {
+  // Assigned either by init() (this controller owns its identity, the createBridgeMesh path) or by fromExisting() (it wraps an already-built store) -- always populated before any other method runs, definite-assignment-asserted the same way ctx already was.
+  private store!: MeshStore;
+  /** Set only when this controller owns its persisted identity (standalone mode). */
+  private ownedIdentitySlot: IdentitySlot | undefined;
+
+  /** Expose the underlying MeshStore for handle cleanup. */
+  get meshStore(): MeshStore {
+    return this.store;
+  }
+  private tool!: CommsTool;
+  private ctx!: CommsContext;
+  private currentRoom: string | undefined;
+  private readonly userName: string;
+  private readonly coordinatorPort: number | undefined;
+  /** Overrides the hub this controller's own store dials (createBridgeMesh's own hubUrl, defaulting to DEFAULT_HUB_URL) -- every real bridge entry point wants the real public hub, but a test constructing a controller of its own wants a hermetic, deterministically-unreachable one instead of silently depending on live production infrastructure (see hub-helpers.ts's own unreachableHubUrl). */
+  private readonly hubUrl: string | undefined;
+  /** Overrides the UDP port this controller's own store runs first-contact presence on (createBridgeMesh's own firstContactPort, defaulting to the machine-wide well-known port). A test that runs several dashboards at once passes an OS-assigned port so they never discover each other. */
+  private readonly firstContactPort: number | undefined;
+
+  constructor(
+    userName: string,
+    options?: {
+      coordinatorPort?: number | undefined;
+      hubUrl?: string | undefined;
+      firstContactPort?: number | undefined;
+    },
+  ) {
+    super();
+    this.userName = userName;
+    this.coordinatorPort = options?.coordinatorPort;
+    this.hubUrl = options?.hubUrl;
+    this.firstContactPort = options?.firstContactPort;
+  }
+
+  /**
+   * Create a ChatController wrapping an existing MeshStore and identity.
+   *
+   * Used by bridges that already have a store and agent registration
+   * (e.g. pi, Claude Code) so the web UI shares the same mesh peer
+   * instead of creating a redundant one.
+   */
+  static fromExisting(
+    store: MeshStore,
+    ctx: Readonly<CommsContext>,
+  ): ChatController {
+    const ctrl = new ChatController("");
+    // Replace the store with the existing one
+    ctrl.store = store;
+    ctrl.tool = new CommsTool(store, {
+      discovery: store.discovery,
+      naming: store.naming,
+    });
+    ctrl.ctx = ctx;
+
+    // Push delivery events to UIs, alongside whatever the bridge that owns this store already does with them
+    store.addDeliveryListener((_agentId: string, event: DeliveryEvent) => {
+      ctrl.emit("message", event);
+    });
+
+    return ctrl;
+  }
+
+  async init(): Promise<void> {
+    // Persistent identity for the web user's slot so the chat identity survives relaunches of the standalone web CLI
+    const identitySlot: IdentitySlot = { harness: "user", cwd: process.cwd() };
+    this.ownedIdentitySlot = identitySlot;
+    const { store, tool } = await createBridgeMesh(identitySlot, {
+      coordinatorPort: this.coordinatorPort,
+      hubUrl: this.hubUrl,
+      firstContactPort: this.firstContactPort,
+    });
+    this.store = store;
+    this.tool = tool;
+    this.store.onError = (error) => {
+      // The TUI listens for "error". A host with no listener (the web-only server) would have an emitted "error" event throw out of the store's callback, so those get stderr instead.
+      if (this.listenerCount("error") > 0) {
+        this.emit("error", error);
+        return;
+      }
+      process.stderr.write(formatMeshError(error));
+    };
+    this.store.onCoordinatorRoleChanged = wireDefaultCcPeerFront(this.store, {
+      coordinatorPort: this.coordinatorPort,
+      hubUrl: this.hubUrl,
+    });
+
+    // Push delivery events to UIs
+    this.store.onDelivery = (_agentId: string, event: DeliveryEvent) => {
+      this.emit("message", event);
+    };
+
+    await this.store.init();
+
+    const reg = await ensureRegistered({
+      store: this.store,
+      cwd: process.cwd(),
+      harness: "user",
+      defaultName: `${this.userName} (user)`,
+      visibility: "visible",
+      tags: ["user"],
+    });
+
+    this.ctx = {
+      agentId: reg.agentId,
+      harness: "user",
+      cwd: process.cwd(),
+      pid: process.pid,
+    };
+  }
+
+  get agentId(): string {
+    return this.ctx.agentId;
+  }
+
+  get activeRoom(): string | undefined {
+    return this.currentRoom;
+  }
+
+  // -----------------------------------------------------------------------
+  // Actions
+  // -----------------------------------------------------------------------
+
+  async listAgents(): Promise<CommsResult> {
+    return this.tool.handle(this.ctx, { action: "list_agents" });
+  }
+
+  async listRooms(): Promise<CommsResult> {
+    return this.tool.handle(this.ctx, { action: "list_rooms" });
+  }
+
+  async createRoom(
+    name: string,
+    options?: {
+      type?: "public" | "private" | "secret";
+      description?: string;
+    },
+  ): Promise<CommsResult> {
+    const { type = "public", description = "" } = options ?? {};
+    const result = await this.tool.handle(this.ctx, {
+      action: "create_room",
+      name,
+      type,
+      description,
+    });
+    // Auto-switch to the created room
+    this.currentRoom = name;
+    return result;
+  }
+
+  async joinRoom(roomId: string): Promise<CommsResult> {
+    const result = await this.tool.handle(this.ctx, {
+      action: "join_room",
+      room: roomId,
+    });
+    this.currentRoom = roomId;
+    return result;
+  }
+
+  async leaveRoom(roomId?: string): Promise<CommsResult> {
+    const target = roomId ?? this.currentRoom;
+    if (target === undefined || target === "") {
+      return { content: "No room to leave. Join a room first.", isError: true };
+    }
+    const result = await this.tool.handle(this.ctx, {
+      action: "leave_room",
+      room: target,
+    });
+    if (this.currentRoom === target) {
+      this.currentRoom = undefined;
+    }
+    return result;
+  }
+
+  async send(target: string, content: string): Promise<CommsResult> {
+    return this.tool.handle(this.ctx, { action: "send", target, content });
+  }
+
+  async sendToCurrentRoom(content: string): Promise<CommsResult> {
+    if (this.currentRoom === undefined || this.currentRoom === "") {
+      return { content: "No active room. Join a room first.", isError: true };
+    }
+    return this.send(this.currentRoom, content);
+  }
+
+  async dm(targetAgentId: string, content: string): Promise<CommsResult> {
+    return this.tool.handle(this.ctx, {
+      action: "dm",
+      target: targetAgentId,
+      content,
+    });
+  }
+
+  async readRoom(options?: {
+    roomId?: string | undefined;
+    since?: string | undefined;
+  }): Promise<CommsResult> {
+    const { roomId, since } = options ?? {};
+    const target = roomId ?? this.currentRoom;
+    if (target === undefined || target === "") {
+      return { content: "No room to read. Join a room first.", isError: true };
+    }
+    return this.tool.handle(this.ctx, {
+      action: "read_room",
+      room: target,
+      ...(since !== undefined && since !== "" && { since }),
+    });
+  }
+
+  async invite(roomId: string, agentId: string): Promise<CommsResult> {
+    return this.tool.handle(this.ctx, {
+      action: "invite",
+      room: roomId,
+      agent: agentId,
+    });
+  }
+
+  async declineInvite(roomId: string, reason: string): Promise<CommsResult> {
+    return this.tool.handle(this.ctx, {
+      action: "decline_invite",
+      room: roomId,
+      reason,
+    });
+  }
+
+  async kick(roomId: string, agentId: string): Promise<CommsResult> {
+    return this.tool.handle(this.ctx, {
+      action: "kick",
+      room: roomId,
+      agent: agentId,
+    });
+  }
+
+  async renameAgent(agentId: string, newName: string): Promise<CommsResult> {
+    const agent = await this.store.getAgent(agentId);
+    if (!agent) {
+      return { content: `Agent ${agentId} not found.`, isError: true };
+    }
+    const oldName = agent.name;
+    await this.store.updateAgent(agentId, { name: newName });
+    return {
+      content: `Renamed ${oldName} to ${newName}.`,
+      isError: false,
+    };
+  }
+
+  async destroyRoom(roomId: string): Promise<CommsResult> {
+    const result = await this.tool.handle(this.ctx, {
+      action: "destroy_room",
+      room: roomId,
+    });
+    if (this.currentRoom === roomId) {
+      this.currentRoom = undefined;
+    }
+    return result;
+  }
+
+  async switchRoom(roomId: string): Promise<CommsResult> {
+    // Check if already a member — if not, join first
+    const rooms = await this.store.listRooms(this.ctx.agentId);
+    const room = rooms.find((r) => r.id === roomId || r.name === roomId);
+    if (!room) {
+      return { content: `Room "${roomId}" not found.`, isError: true };
+    }
+
+    if (!room.members.includes(this.ctx.agentId)) {
+      const result = await this.joinRoom(room.id);
+      if (result.isError) return result;
+    }
+
+    this.currentRoom = room.id;
+    return {
+      content: `Switched to ${room.name}.`,
+      isError: false,
+    };
+  }
+
+  // -----------------------------------------------------------------------
+  // Raw access for web API
+  // -----------------------------------------------------------------------
+
+  async getAgents(): Promise<AgentIdentity[]> {
+    return this.store.listAgents(this.ctx.agentId);
+  }
+
+  async getRooms(): Promise<Room[]> {
+    return this.store.listRooms(this.ctx.agentId);
+  }
+
+  async getRoomMessages(
+    roomId: string,
+    since?: string,
+  ): Promise<RoomMessage[]> {
+    return this.store.readRoomMessages(roomId, since);
+  }
+
+  formatEvent(event: DeliveryEvent): string {
+    return formatDeliveryEvent(event);
+  }
+
+  // -----------------------------------------------------------------------
+  // Lifecycle
+  // -----------------------------------------------------------------------
+
+  async shutdown(): Promise<void> {
+    await this.store.setAgentOffline(this.ctx.agentId);
+    await this.store.shutdown();
+    if (this.ownedIdentitySlot !== undefined) {
+      releaseIdentityLock(this.ownedIdentitySlot);
+    }
+  }
+}

package/src/bridges/user/tui.ts

@@ -0,0 +1,300 @@
+/**
+ * TUI — terminal chat interface using readline + ANSI escape codes.
+ *
+ * Commands:
+ *   /join <room>      Join or switch to a room
+ *   /leave [room]     Leave the current (or specified) room
+ *   /rooms            List all rooms
+ *   /agents           List all agents
+ *   /read [room]      Read messages in current (or specified) room
+ *   /dm <agent> <msg> Send a direct message
+ *   /create <name>    Create a public room
+ *   /invite <room> <agent>  Invite an agent to a room
+ *   /decline <room> <reason> Decline a room invite
+ *   /kick <room> <agent>    Kick an agent from a room
+ *   /destroy <room>   Destroy a room
+ *   /help             Show commands
+ *   /quit             Exit
+ *
+ * Anything without / is sent to the current room.
+ */
+
+import * as readline from "node:readline";
+import { ChatController } from "./controller.js";
+import type { DeliveryEvent } from "../../core/types.js";
+import { describeDeliveryFor } from "../../core/send-outcome.js";
+
+// ANSI helpers
+const BOLD = "\x1b[1m";
+const DIM = "\x1b[2m";
+const CYAN = "\x1b[36m";
+const GREEN = "\x1b[32m";
+const YELLOW = "\x1b[33m";
+const RED = "\x1b[31m";
+const MAGENTA = "\x1b[35m";
+const RESET = "\x1b[0m";
+const CLEAR_LINE = "\r\x1b[2K";
+
+function prompt(controller: ChatController): string {
+  const room = controller.activeRoom;
+  return room !== undefined ? `${GREEN}${room}${RESET} > ` : `${DIM}>${RESET} `;
+}
+
+export async function runTui(userName: string): Promise<void> {
+  const controller = new ChatController(userName);
+
+  await controller.init();
+  console.log(
+    `${CYAN}Connected as ${BOLD}${userName} (user)${RESET} [${controller.agentId}]`,
+  );
+  console.log(
+    `${DIM}Type /help for commands. Anything else goes to the current room.${RESET}\n`,
+  );
+
+  const rl = readline.createInterface({
+    input: process.stdin,
+    output: process.stdout,
+  });
+
+  // Delivery event handler — print above the prompt
+  function onMessage(event: DeliveryEvent): void {
+    const line = formatForTerminal(event);
+    process.stdout.write(`${CLEAR_LINE}${line}\n${prompt(controller)}`);
+  }
+  controller.on("message", onMessage);
+
+  function onError(err: Error): void {
+    process.stdout.write(
+      `${CLEAR_LINE}${RED}Error: ${err.message}${RESET}\n${prompt(controller)}`,
+    );
+  }
+  controller.on("error", onError);
+
+  // Input loop
+  async function handleInput(input: string): Promise<void> {
+    const trimmed = input.trim();
+    if (trimmed.length === 0) return;
+
+    if (trimmed.startsWith("/")) {
+      await handleCommand(trimmed, controller);
+    } else if (controller.activeRoom !== undefined) {
+      const result = await controller.sendToCurrentRoom(trimmed);
+      if (result.isError) {
+        process.stdout.write(`${RED}${result.content}${RESET}\n`);
+      }
+    } else {
+      process.stdout.write(
+        `${YELLOW}No active room. /join a room first or use /dm.${RESET}\n`,
+      );
+    }
+  }
+
+  function ask(): void {
+    rl.question(prompt(controller), (input) => {
+      void handleInput(input).then(() => {
+        ask();
+      });
+    });
+  }
+
+  ask();
+
+  // Graceful shutdown
+  rl.on("close", () => {
+    controller.off("message", onMessage);
+    controller.off("error", onError);
+    void controller.shutdown().then(() => process.exit(0));
+  });
+}
+
+// ---------------------------------------------------------------------------
+// Command handler
+// ---------------------------------------------------------------------------
+
+async function handleCommand(input: string, c: ChatController): Promise<void> {
+  const parts = input.slice(1).split(/\s+/);
+  const cmd = parts[0]?.toLowerCase();
+  const arg1 = parts[1];
+  const arg2 = parts.slice(2).join(" ");
+
+  switch (cmd) {
+    case "join": {
+      if (arg1 === undefined) {
+        process.stdout.write(`${YELLOW}Usage: /join <room>${RESET}\n`);
+        return;
+      }
+      const result = await c.switchRoom(arg1);
+      printResult(result);
+      if (!result.isError) {
+        const read = await c.readRoom();
+        if (!read.isError && read.content !== "No messages.") {
+          process.stdout.write(`${DIM}${read.content}${RESET}\n`);
+        }
+      }
+      return;
+    }
+    case "leave": {
+      const result = await c.leaveRoom(arg1);
+      printResult(result);
+      return;
+    }
+    case "rooms": {
+      const result = await c.listRooms();
+      printResult(result);
+      return;
+    }
+    case "agents": {
+      const result = await c.listAgents();
+      printResult(result);
+      return;
+    }
+    case "read": {
+      const result = await c.readRoom({ roomId: arg1 });
+      printResult(result);
+      return;
+    }
+    case "dm": {
+      if (arg1 === undefined || !arg2) {
+        process.stdout.write(`${YELLOW}Usage: /dm <agent> <message>${RESET}\n`);
+        return;
+      }
+      const result = await c.dm(arg1, arg2);
+      printResult(result);
+      return;
+    }
+    case "create": {
+      if (arg1 === undefined) {
+        process.stdout.write(`${YELLOW}Usage: /create <name>${RESET}\n`);
+        return;
+      }
+      const result = await c.createRoom(arg1, {
+        type: "public",
+        description: arg2,
+      });
+      printResult(result);
+      return;
+    }
+    case "invite": {
+      const agentId = parts[2];
+      if (arg1 === undefined || agentId === undefined) {
+        process.stdout.write(
+          `${YELLOW}Usage: /invite <room> <agent>${RESET}\n`,
+        );
+        return;
+      }
+      const result = await c.invite(arg1, agentId);
+      printResult(result);
+      return;
+    }
+    case "decline": {
+      const reason = parts.slice(2).join(" ");
+      if (arg1 === undefined || !reason) {
+        process.stdout.write(
+          `${YELLOW}Usage: /decline <room> <reason>${RESET}\n`,
+        );
+        return;
+      }
+      const result = await c.declineInvite(arg1, reason);
+      printResult(result);
+      return;
+    }
+    case "kick": {
+      const agentId = parts[2];
+      if (arg1 === undefined || agentId === undefined) {
+        process.stdout.write(`${YELLOW}Usage: /kick <room> <agent>${RESET}\n`);
+        return;
+      }
+      const result = await c.kick(arg1, agentId);
+      printResult(result);
+      return;
+    }
+    case "destroy": {
+      if (arg1 === undefined) {
+        process.stdout.write(`${YELLOW}Usage: /destroy <room>${RESET}\n`);
+        return;
+      }
+      const result = await c.destroyRoom(arg1);
+      printResult(result);
+      return;
+    }
+    case "help":
+      process.stdout.write(`${CYAN}Commands:${RESET}
+  ${GREEN}/join${RESET} <room>         Join or switch to a room
+  ${GREEN}/leave${RESET} [room]        Leave current (or specified) room
+  ${GREEN}/rooms${RESET}               List all rooms
+  ${GREEN}/agents${RESET}              List all agents
+  ${GREEN}/read${RESET} [room]         Read messages in room
+  ${GREEN}/dm${RESET} <agent> <msg>    Send a direct message
+  ${GREEN}/create${RESET} <name>       Create a public room
+  ${GREEN}/invite${RESET} <room> <id>  Invite agent to room
+  ${GREEN}/decline${RESET} <room> <reason> Decline a room invite
+  ${GREEN}/kick${RESET} <room> <id>    Kick agent from room
+  ${GREEN}/destroy${RESET} <room>      Destroy a room
+  ${GREEN}/help${RESET}                Show this help
+  ${GREEN}/quit${RESET}                Exit
+\n${DIM}Anything without / is sent to the current room.${RESET}\n`);
+      return;
+    case "quit":
+      process.stdout.write(`${DIM}Goodbye!${RESET}\n`);
+      process.exit(0);
+      return;
+    case undefined:
+    default:
+      process.stdout.write(
+        `${YELLOW}Unknown command: /${String(cmd)}. Type /help for commands.${RESET}\n`,
+      );
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Formatting
+// ---------------------------------------------------------------------------
+
+function printResult(
+  result: Readonly<{ content: string; isError: boolean }>,
+): void {
+  if (result.isError) {
+    process.stdout.write(`${RED}${result.content}${RESET}\n`);
+  } else {
+    process.stdout.write(`${result.content}\n`);
+  }
+}
+
+function formatForTerminal(event: DeliveryEvent): string {
+  switch (event.type) {
+    case "room_message":
+      return `${BOLD}[${event.message.room}] ${event.message.from}:${RESET} ${event.message.content}`;
+    case "dm":
+      return `${MAGENTA}DM from ${event.message.from}:${RESET} ${event.message.content}`;
+    case "member_joined":
+      return `${GREEN}→ ${event.agent} joined ${event.room}${RESET}`;
+    case "member_left":
+      return `${YELLOW}← ${event.agent} left ${event.room}${RESET}`;
+    case "member_status":
+      return `${CYAN}● ${event.agent} is now ${event.status} in ${event.room}${RESET}`;
+    case "delivery_status":
+      return `${DIM}✓ Message ${event.messageId} ${describeDeliveryFor(event.delivery, event.agent)}${RESET}`;
+    case "room_invite": {
+      const desc = event.roomDescription ? ` — ${event.roomDescription}` : "";
+      return `${CYAN}✉ ${event.fromName} invited you to "${event.room}"${desc}${RESET}`;
+    }
+    case "invite_declined":
+      return `${YELLOW}✗ ${event.agentName} declined invite to ${event.room}: "${event.reason}"${RESET}`;
+    case "room_members": {
+      const names = event.members
+        .map((m) => `${m.name} (${m.status})`)
+        .join(", ");
+      return `${DIM}Members of ${event.room}: ${names}${RESET}`;
+    }
+    case "name_changed":
+      return `${CYAN}✎ ${event.oldName} is now ${event.newName}${RESET}`;
+    case "connection_request":
+      return `${CYAN}🔗 Connection request from ${event.peerId} (${event.name})${RESET}`;
+    case "capability_request":
+      return `${CYAN}🔑 ${event.requesterDevice} is asking for "${event.capability}" (${event.requestId})${RESET}`;
+    case "room_join_request":
+      return `${CYAN}🚪 ${event.requesterId} is asking to join ${event.room}${RESET}`;
+    default:
+      return event satisfies never;
+  }
+}