agent-comms 8.15.9 → 8.15.10

package/src/bridges/mcp/server.ts

@@ -0,0 +1,137 @@
+/**
+ * Agent Comms — generic MCP tool server.
+ *
+ * Standard MCP server that works with any MCP-compatible harness.
+ * Uses TCP mesh for state sync. Pending messages are drained and
+ * appended to every tool response so the agent sees them.
+ *
+ * Run via: npx agent-comms bridge mcp
+ */
+
+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,
+  type BridgeRunOptions,
+} 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";
+
+/** Length of the random suffix appended to a default `mcp-<suffix>` agent name when no explicit name is registered. */
+const DEFAULT_AGENT_NAME_SUFFIX_LENGTH = 4;
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+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: "mcp",
+    cwd: process.cwd(),
+  };
+  const { store, tool } = await createBridgeMesh(identitySlot, options?.mesh);
+  store.onError = createMeshErrorReporter();
+  store.onCoordinatorRoleChanged = wireDefaultCcPeerFront(store);
+  let agentId: string | undefined;
+
+  const mcp = new McpServer(
+    { name: "agent-comms", version: "1.1.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
+            : `mcp-${nanoid(DEFAULT_AGENT_NAME_SUFFIX_LENGTH)}`;
+        const reg = await ensureRegistered({
+          cwd: process.cwd(),
+          store,
+          harness: "mcp",
+          defaultName: name,
+        });
+        agentId = reg.agentId;
+      }
+
+      const action = buildAction(params);
+      const result = await tool.handle(
+        { agentId, harness: "mcp", 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, "mcp");
+  tool.getWebUrlStatus = () => getWebUrlStatus(webHandle);
+  await mcp.connect(new StdioServerTransport());
+
+  const reg = await ensureRegistered({
+    cwd: process.cwd(),
+    store,
+    harness: "mcp",
+    defaultName: `mcp-${nanoid(DEFAULT_AGENT_NAME_SUFFIX_LENGTH)}`,
+  });
+  agentId = reg.agentId;
+
+  installShutdownSignalHandlers({
+    shutdown: async () => {
+      if (agentId !== undefined) await store.setAgentOffline(agentId);
+      await store.shutdown();
+      releaseIdentityLock(identitySlot);
+    },
+    disposition: "exit",
+  });
+}

package/src/bridges/opencode/plugin.ts

@@ -0,0 +1,130 @@
+/**
+ * Agent Comms — OpenCode plugin bridge.
+ *
+ * Receives incoming messages via TCP mesh push and injects them
+ * into the OpenCode TUI via tui.prompt.append + tui.submitPrompt.
+ *
+ * Install (project):  ln -s ~/Developer/agent-comms/src/bridges/opencode/plugin.ts .opencode/plugins/agent-comms.ts
+ * Install (global):   ln -s ~/Developer/agent-comms/src/bridges/opencode/plugin.ts ~/.config/opencode/plugins/agent-comms.ts
+ */
+
+import {
+  createBridgeMesh,
+  createMeshErrorReporter,
+  ensureRegistered,
+  formatDeliveryEvent,
+  installShutdownSignalHandlers,
+} 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 } from "../user/web/server.js";
+import { nanoid } from "../../core/nanoid.js";
+
+// Persistent identity for this slot: a stable device-id means the agent ID survives restarts, so peers can keep targeting us. A plugin unload has no hook here, so an unload that is not a process exit still leaves a stale lock, which self-heals via the pid probe.
+const identitySlot: IdentitySlot = { harness: "opencode", cwd: process.cwd() };
+
+// Length (in characters) of the random suffix appended to the default auto-generated agent name.
+const DEFAULT_NAME_SUFFIX_LENGTH = 4;
+
+// Minimal interface for the OpenCode SDK client we actually use
+interface OpenCodeClient {
+  tui: {
+    appendPrompt: (body: Readonly<{ text: string }>) => Promise<unknown>;
+    submitPrompt: () => Promise<unknown>;
+  };
+  session: {
+    list: () => Promise<{ data: { id: string }[] }>;
+    prompt: (
+      opts: Readonly<{
+        path: { id: string };
+        body: { parts: { type: string; text: string }[] };
+      }>,
+    ) => Promise<unknown>;
+  };
+}
+
+function isOpenCodeClient(value: unknown): value is OpenCodeClient {
+  if (typeof value !== "object" || value === null) return false;
+  if (!("tui" in value)) return false;
+  if (!("session" in value)) return false;
+  return true;
+}
+
+export const AgentCommsPlugin = async (opts: {
+  project: unknown;
+  client: unknown;
+  $: unknown;
+  directory: string;
+  worktree: string;
+}) => {
+  if (!isOpenCodeClient(opts.client)) {
+    throw new Error("Agent Comms plugin requires a valid OpenCode client");
+  }
+  const client = opts.client;
+
+  const { store } = await createBridgeMesh(identitySlot);
+  store.onError = createMeshErrorReporter();
+  store.onCoordinatorRoleChanged = wireDefaultCcPeerFront(store);
+  await store.init();
+  await tryStartBridgeWebServer(store, "opencode");
+
+  const reg = await ensureRegistered({
+    cwd: process.cwd(),
+    store,
+    harness: "opencode",
+    defaultName: `opencode-${nanoid(DEFAULT_NAME_SUFFIX_LENGTH)}`,
+  });
+  const agentId = reg.agentId;
+
+  // "reraise", not "exit": this plugin runs inside OpenCode's own process, and registering a signal listener at all removes Node's default terminate behaviour, so exiting here would pre-empt the host and doing nothing would swallow its Ctrl-C.
+  installShutdownSignalHandlers({
+    shutdown: async () => {
+      await store.setAgentOffline(agentId);
+      await store.shutdown();
+      releaseIdentityLock(identitySlot);
+    },
+    disposition: "reraise",
+    onError: createMeshErrorReporter(),
+  });
+
+  // Incoming messages arrive via TCP mesh — push to TUI immediately
+  store.onDelivery = async (_targetId: string, event) => {
+    const line = formatDeliveryEvent(event);
+    const message = `📬 Agent Comms: ${line}`;
+    try {
+      await client.tui.appendPrompt({ text: message });
+      await client.tui.submitPrompt();
+    } catch {
+      // Fallback: prompt the current session directly
+      const sessions = await client.session.list();
+      const current = sessions.data[0];
+      if (current) {
+        await client.session.prompt({
+          path: { id: current.id },
+          body: {
+            parts: [{ type: "text", text: message }],
+          },
+        });
+      }
+    }
+  };
+
+  return {
+    event: async ({ event }: { event: { type: string } }) => {
+      if (event.type === "session.idle") {
+        // Drain any remaining undelivered messages on idle
+        const events = await store.drainDelivery(agentId);
+        for (const e of events) {
+          const line = formatDeliveryEvent(e);
+          try {
+            await client.tui.appendPrompt({ text: `📬 ${line}` });
+            await client.tui.submitPrompt();
+          } catch {
+            /* best effort */
+          }
+        }
+      }
+    },
+  };
+};

package/src/bridges/pi/extension.ts

@@ -0,0 +1,330 @@
+/**
+ * Agent Comms — pi bridge extension.
+ *
+ * Provides the `agent_comms` tool and receives incoming messages
+ * via TCP mesh push. Actionable events (DMs, room messages, invites)
+ * wake the model via sendMessage() with a custom type; informational
+ * events are buffered and drained on the next tool call.
+ *
+ * Install: symlink into ~/.pi/agent/extensions/ with pi.extensions
+ * pointing to this file.
+ */
+
+import type {
+  ExtensionAPI,
+  ExtensionUIContext,
+} from "@earendil-works/pi-coding-agent";
+import * as path from "node:path";
+import { Type } from "typebox";
+import { StringEnum } from "@earendil-works/pi-ai";
+
+import {
+  createBridgeMeshSync,
+  createMeshErrorReporter,
+  buildAction,
+  ensureProjectRoom,
+  ensureRegistered,
+  extractStreamingBehavior,
+  formatDeliveryEvent,
+  isActionableEvent,
+} from "../../core/index.js";
+import {
+  releaseIdentityLock,
+  type IdentitySlot,
+} from "../../core/identity-store.js";
+import { wireDefaultCcPeerFront } from "../cc-peer/default-front.js";
+import {
+  tryStartBridgeWebServer,
+  getWebPort,
+  getWebUrlStatus,
+  type WebServerHandle,
+} from "../user/web/server.js";
+import { nanoid } from "../../core/nanoid.js";
+
+export default function (pi: ExtensionAPI) {
+  // 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: "pi", cwd: process.cwd() };
+  const { store, tool, attachIdentity } = createBridgeMeshSync(identitySlot);
+  store.onCoordinatorRoleChanged = wireDefaultCcPeerFront(store);
+
+  let agentId: string | undefined;
+  let webHandle: WebServerHandle | undefined;
+  tool.getWebUrlStatus = () => getWebUrlStatus(webHandle);
+  let uiCtx: ExtensionUIContext | undefined;
+  // The extension runs inside pi's own terminal UI, so mesh errors surface as pi notifications rather than raw stderr writes that would corrupt its display.
+  store.onError = createMeshErrorReporter((line) => {
+    uiCtx?.notify(line.trimEnd(), "error");
+  });
+  let projectRoom: string | undefined;
+  const informationalBuffer: string[] = [];
+
+  // LRU-style dedup for delivery events
+  const recentDeliveries = new Set<string>();
+  const MAX_DEDUP_ENTRIES = 100;
+  const AUTO_NAME_SUFFIX_LENGTH = 4;
+
+  function refreshStatus(): void {
+    if (!uiCtx) return;
+    const parts: string[] = [];
+    if (projectRoom !== undefined) parts.push(`💬 ${projectRoom}`);
+    if (webHandle) {
+      const port = getWebPort(webHandle);
+      if (port !== undefined && port !== 0)
+        parts.push(`http://127.0.0.1:${String(port)}`);
+    }
+    if (informationalBuffer.length > 0) {
+      parts.push(`📬 ${String(informationalBuffer.length)}`);
+    }
+    uiCtx.setStatus("comms", parts.length > 0 ? parts.join("  ") : undefined);
+  }
+
+  store.onDelivery = (_targetId: string, event) => {
+    const key = `${event.type}:${formatDeliveryEvent(event)}`;
+    if (recentDeliveries.has(key)) return;
+    recentDeliveries.add(key);
+    if (recentDeliveries.size > MAX_DEDUP_ENTRIES) {
+      // Evict oldest entries (simple approach: clear half)
+      const entries = Array.from(recentDeliveries);
+      const half = Math.floor(entries.length / 2);
+      for (let i = 0; i < half; i++) {
+        const entry = entries[i];
+        if (entry !== undefined) recentDeliveries.delete(entry);
+      }
+    }
+
+    const line = formatDeliveryEvent(event);
+    const hint = extractStreamingBehavior(event);
+
+    // Pick deliverAs from sender hint; fall back to event-type heuristic
+    const deliverAs: "steer" | "followUp" | undefined =
+      hint === "followUp"
+        ? "followUp"
+        : hint === "steer" || (!hint && isActionableEvent(event))
+          ? "steer"
+          : undefined;
+
+    if (deliverAs !== undefined) {
+      pi.sendMessage(
+        {
+          content: `📬 ${line}`,
+          customType: "comms-delivery",
+          display: false,
+        },
+        { triggerTurn: true, deliverAs },
+      );
+    } else {
+      // info or non-actionable with no hint — buffer for next tool call
+      informationalBuffer.push(line);
+    }
+
+    uiCtx?.notify(`📬 ${line}`, "info");
+    refreshStatus();
+  };
+
+  // -----------------------------------------------------------------------
+  // Lifecycle
+  // -----------------------------------------------------------------------
+
+  let meshReady = false;
+
+  pi.on("session_start", async (_event, ctx) => {
+    uiCtx = ctx.ui;
+
+    await attachIdentity();
+    await store.init();
+    meshReady = store.connected;
+
+    if (!meshReady) {
+      ctx.ui.notify(
+        "Agent Comms: mesh unavailable (no coordinator). Running without mesh.",
+        "warning",
+      );
+    }
+
+    if (meshReady) {
+      const reg = await ensureRegistered({
+        store,
+        cwd: process.cwd(),
+        harness: "pi",
+        defaultName: `pi-${nanoid(AUTO_NAME_SUFFIX_LENGTH)}`,
+      });
+      agentId = reg.agentId;
+
+      // Auto-create and join a project room for the working directory
+      await ensureProjectRoom(store, agentId, process.cwd());
+      projectRoom = path.basename(process.cwd());
+
+      // Start web UI sharing the same mesh peer and agent identity
+      webHandle = await tryStartBridgeWebServer(store, "pi");
+    }
+
+    refreshStatus();
+
+    if (meshReady) {
+      ctx.ui.notify("Agent Comms: connected", "info");
+    }
+  });
+
+  pi.on("session_shutdown", async () => {
+    uiCtx?.setStatus("comms", undefined);
+    uiCtx = undefined;
+    // Shut down the web server before the bridge store so the web
+    // controller's coordinator connection can close cleanly.
+    if (webHandle) {
+      webHandle.wss.close();
+      webHandle.server.close();
+      webHandle = undefined;
+    }
+    if (agentId !== undefined) {
+      await store.setAgentOffline(agentId);
+    }
+    releaseIdentityLock(identitySlot);
+    await store.shutdown();
+  });
+
+  // -----------------------------------------------------------------------
+  // Commands
+  // -----------------------------------------------------------------------
+
+  pi.registerCommand("comms-url", {
+    description: "Show the Agent Comms web UI URL",
+    handler: async (_args, ctx) => {
+      if (!webHandle) {
+        ctx.ui.notify("Web UI is not running.", "error");
+        return Promise.resolve();
+      }
+      const port = getWebPort(webHandle);
+      if (port === undefined || port === 0) {
+        ctx.ui.notify("Web UI port not yet assigned.", "error");
+        return Promise.resolve();
+      }
+      ctx.ui.notify(`http://127.0.0.1:${String(port)}`, "info");
+      return Promise.resolve();
+    },
+  });
+
+  // -----------------------------------------------------------------------
+  // Tool registration
+  // -----------------------------------------------------------------------
+
+  pi.registerTool({
+    name: "agent_comms",
+    label: "Agent Comms",
+    description: [
+      "Cross-harness agent communication mesh. Send messages to rooms and DM other agents.",
+      "Actions: register, update, whoami, create_room, list_rooms, join_room, leave_room,",
+      "send, dm, list_agents, read_room, invite, decline_invite, kick, destroy_room, web_url.",
+      "Register first, then join or create rooms to communicate.",
+    ].join(" "),
+    promptSnippet: "Communicate with other LLM agents via rooms and DMs",
+    promptGuidelines: [
+      "Use agent_comms to coordinate with other running agents. Register on session start, join rooms for collaboration.",
+    ],
+    parameters: Type.Object({
+      action: StringEnum(
+        [
+          "register",
+          "update",
+          "whoami",
+          "create_room",
+          "list_rooms",
+          "join_room",
+          "leave_room",
+          "send",
+          "dm",
+          "list_agents",
+          "read_room",
+          "invite",
+          "decline_invite",
+          "kick",
+          "destroy_room",
+          "web_url",
+        ],
+        { description: "Action to perform" },
+      ),
+      name: Type.Optional(
+        Type.String({
+          description: "Agent display name (for register/update)",
+        }),
+      ),
+      visibility: Type.Optional(
+        StringEnum(["visible", "hidden", "ghost"], {
+          description: "Visibility to other agents",
+        }),
+      ),
+      tags: Type.Optional(
+        Type.Array(Type.String(), { description: "Agent capability tags" }),
+      ),
+      status: Type.Optional(
+        StringEnum(["active", "idle", "busy"], {
+          description: "Agent status (for update)",
+        }),
+      ),
+      room: Type.Optional(Type.String({ description: "Room name/ID" })),
+      type: Type.Optional(
+        StringEnum(["public", "private", "secret"], {
+          description: "Room type (for create_room)",
+        }),
+      ),
+      description: Type.Optional(
+        Type.String({ description: "Room description (for create_room)" }),
+      ),
+      target: Type.Optional(
+        Type.String({ description: "Target room name or agent ID" }),
+      ),
+      content: Type.Optional(Type.String({ description: "Message content" })),
+      replyTo: Type.Optional(
+        Type.String({ description: "Message ID to reply to" }),
+      ),
+      agent: Type.Optional(
+        Type.String({ description: "Target agent ID (for invite/kick)" }),
+      ),
+      since: Type.Optional(
+        Type.String({
+          description: "ISO timestamp to read messages since",
+        }),
+      ),
+      reason: Type.Optional(
+        Type.String({
+          description: "Reason for declining an invite (for decline_invite)",
+        }),
+      ),
+      streamingBehavior: Type.Optional(
+        StringEnum(["steer", "followUp", "info"], {
+          description:
+            "Delivery timing hint: steer (act now), followUp (act when idle), info (whenever convenient)",
+        }),
+      ),
+    }),
+
+    async execute(_toolCallId, params) {
+      if (agentId === undefined) {
+        return {
+          content: [{ type: "text", text: "Error: not registered" }],
+          details: { action: params.action },
+          isError: true,
+        };
+      }
+
+      const action = buildAction(params);
+      const result = await tool.handle(
+        { agentId, harness: "pi", cwd: process.cwd(), pid: process.pid },
+        action,
+      );
+
+      // Drain buffered informational events and prepend to the response
+      const pending = informationalBuffer.splice(0);
+      refreshStatus();
+      const prefix =
+        pending.length > 0
+          ? `[comms] Pending events:\n${pending.map((l: string) => `  📬 ${l}`).join("\n")}\n\n`
+          : "";
+
+      return {
+        content: [{ type: "text", text: `${prefix}${result.content}` }],
+        details: { action: params.action },
+        isError: result.isError,
+      };
+    },
+  });
+}

package/src/bridges/registry.ts

@@ -0,0 +1,17 @@
+import * as claudeCode from "./claude-code/channel.js";
+import * as codex from "./codex/tool.js";
+import * as mcp from "./mcp/server.js";
+import * as ccPeer from "./cc-peer/run.js";
+import type { BridgeRunOptions } from "../core/index.js";
+
+export interface Bridge {
+  /** Starts the bridge. Only a test passes options; a real launch runs it bare. */
+  run: (options?: Readonly<BridgeRunOptions>) => void | Promise<void>;
+}
+
+export const bridges: Record<string, Bridge> = {
+  "claude-code": claudeCode,
+  codex,
+  mcp,
+  "cc-peer": ccPeer,
+};

package/src/bridges/user/cli.ts

@@ -0,0 +1,87 @@
+/**
+ * Non-interactive CLI — one-shot commands that register, execute, print, and exit.
+ *
+ * Usage:
+ *   agent-comms send <room> <message>
+ *   agent-comms dm <agent> <message>
+ *   agent-comms rooms
+ *   agent-comms agents
+ *   agent-comms read <room> [--since <iso>]
+ */
+
+import { ChatController } from "./controller.js";
+
+export async function runCli(
+  command: string,
+  args: readonly string[],
+  userName: string,
+): Promise<void> {
+  const controller = new ChatController(userName);
+
+  try {
+    await controller.init();
+
+    const result = await dispatch(controller, command, args);
+
+    if (result.isError) {
+      console.error(result.content);
+      process.exit(1);
+    } else {
+      console.log(result.content);
+    }
+  } finally {
+    await controller.shutdown();
+  }
+}
+
+async function dispatch(
+  controller: ChatController,
+  command: string,
+  args: readonly string[],
+): Promise<{ content: string; isError: boolean }> {
+  switch (command) {
+    case "send": {
+      const room = args[0];
+      const content = args.slice(1).join(" ");
+      if (room === undefined || room === "" || !content) {
+        return {
+          content: "Usage: agent-comms send <room> <message>",
+          isError: true,
+        };
+      }
+      // Ensure we're in the room
+      const joinResult = await controller.switchRoom(room);
+      if (joinResult.isError) return joinResult;
+      return controller.send(room, content);
+    }
+    case "dm": {
+      const agent = args[0];
+      const content = args.slice(1).join(" ");
+      if (agent === undefined || agent === "" || !content) {
+        return {
+          content: "Usage: agent-comms dm <agent-id> <message>",
+          isError: true,
+        };
+      }
+      return controller.dm(agent, content);
+    }
+    case "rooms":
+      return controller.listRooms();
+    case "agents":
+      return controller.listAgents();
+    case "read": {
+      const room = args[0];
+      if (room === undefined || room === "") {
+        return {
+          content: "Usage: agent-comms read <room> [--since <iso>]",
+          isError: true,
+        };
+      }
+      const sinceIdx = args.indexOf("--since");
+      const since = sinceIdx !== -1 ? args[sinceIdx + 1] : undefined;
+      return controller.readRoom({ roomId: room, since });
+    }
+    default:
+      return { content: `Unknown command: ${command}`, isError: true };
+  }
+}