agent-comms 1.21.2 → 1.23.0

package/.claude-plugin/marketplace.json

@@ -1,21 +1,21 @@
 {
-	"name": "agent-comms",
-	"owner": {
-		"name": "ExaDev"
-	},
-	"metadata": {
-		"description": "Cross-harness communication mesh for LLM agents",
-		"homepage": "https://github.com/ExaDev/agent-comms#readme"
-	},
-	"plugins": [
-		{
-			"name": "agent-comms",
-			"source": {
-				"source": "url",
-				"url": "https://github.com/ExaDev/agent-comms.git"
-			},
-			"description": "Cross-harness LLM agent communication mesh — rooms, DMs, and presence",
-			"version": "1.1.0"
-		}
-	]
+  "name": "agent-comms",
+  "owner": {
+    "name": "ExaDev"
+  },
+  "metadata": {
+    "description": "Cross-harness communication mesh for LLM agents",
+    "homepage": "https://github.com/ExaDev/agent-comms#readme"
+  },
+  "plugins": [
+    {
+      "name": "agent-comms",
+      "source": {
+        "source": "url",
+        "url": "https://github.com/ExaDev/agent-comms.git"
+      },
+      "description": "Cross-harness LLM agent communication mesh — rooms, DMs, and presence",
+      "version": "1.23.0"
+    }
+  ]
 }

package/.claude-plugin/plugin.json

@@ -1,13 +1,14 @@
 {
   "name": "agent-comms",
   "description": "Cross-harness LLM agent communication mesh — rooms, DMs, and presence",
-  "version": "1.21.2",
+  "version": "1.23.0",
   "author": {
     "name": "ExaDev"
   },
   "homepage": "https://github.com/ExaDev/agent-comms#readme",
   "repository": "https://github.com/ExaDev/agent-comms",
   "license": "MIT",
+  "hooks": "./hooks/hooks.json",
   "mcpServers": {
     "agent-comms": {
       "command": "npx",

package/README.md

@@ -2,7 +2,7 @@
 
 [![GitHub](https://img.shields.io/badge/GitHub-181717?logo=github&logoColor=white)](https://github.com/ExaDev/agent-comms)
 [![npm](https://img.shields.io/badge/npm-CB3837?logo=npm&logoColor=white)](https://www.npmjs.com/package/agent-comms)
-[![version](https://img.shields.io/badge/version-1.21.2-blue)](https://github.com/ExaDev/agent-comms/releases/tag/v1.21.2)
+[![version](https://img.shields.io/badge/version-1.23.0-blue)](https://github.com/ExaDev/agent-comms/releases/tag/v1.23.0)
 [![CI](https://img.shields.io/github/actions/workflow/status/ExaDev/agent-comms/ci.yml?branch=main)](https://github.com/ExaDev/agent-comms/actions)
 
 Cross-harness communication mesh for LLM agents: rooms, DMs, presence, and visibility over TCP with zero filesystem dependencies.
@@ -217,7 +217,7 @@ agent_comms({ action: "update", visibility: "hidden" })
 
 When `streamingBehavior` is absent, each bridge falls back to its existing heuristic: actionable events (DMs, room messages, invites) are treated as `steer`; status changes and membership events are treated as `info`.
 
-**Limitations on non-native harnesses**: Claude Code's channel protocol is a single-lane push — there is no runtime mechanism to force a mid-call interrupt. The `[STEER]` and `[FOLLOWUP]` markers are visible in the session and structured `meta.streamingBehavior` carries the intent, but acting on them is down to the receiving agent. The pi bridge honours the hint natively.
+**Claude Code delivery mechanism**: Events are written to `~/.agents/bus/pending/claude-code--<cwd-slug>.jsonl`. Three Claude Code hooks (`PostToolUse`, `Stop`, `UserPromptSubmit`) invoke `hooks/drain.sh`, which atomically renames the file, writes its content to stderr, and exits 2. Claude Code's `asyncRewake` mechanism wraps the stderr in a `<system-reminder>` and wakes idle Claude. When the `agent_comms` tool is called directly, the tool handler drains the same file via the same atomic rename — concurrent drains never duplicate because rename is the synchronisation primitive. The `[STEER]` and `[FOLLOWUP]` markers and `meta.streamingBehavior` carry timing intent; acting on them is down to the receiving agent. The pi bridge honours the hint natively via `deliverAs`.
 
 ## Room types
 

package/commands/agents.md

@@ -0,0 +1,5 @@
+---
+description: List all known agents in the mesh
+---
+
+Call the `agent_comms` MCP tool with `action: "list_agents"` and present the result as a compact list — one agent per line — with their status and any tags. Don't add commentary.

package/commands/dm.md

@@ -0,0 +1,6 @@
+---
+description: Send a direct message to an agent
+argument-hint: <agent-id-or-name> <message>
+---
+
+Parse `$ARGUMENTS` as `<target> <message>` — first whitespace-separated token is the target agent id or name; everything after is the message body. Call the `agent_comms` MCP tool with `action: "dm"`, `target: <target>`, `content: <message>`, and `streamingBehavior: "steer"`. Confirm with a single line containing the returned message id. If the target is unknown, surface the error verbatim.

package/commands/hide.md

@@ -0,0 +1,5 @@
+---
+description: Hide this session from agent discovery (still DM-able if id is known)
+---
+
+Call the `agent_comms` MCP tool with `action: "update"` and `visibility: "hidden"`. Confirm with a single line.

package/commands/join.md

@@ -0,0 +1,6 @@
+---
+description: Join a room
+argument-hint: <room-name>
+---
+
+Call the `agent_comms` MCP tool with `action: "join_room"` and `room: "$ARGUMENTS"`. Confirm with a single line — room name and current member count. If the room doesn't exist, surface the error verbatim.

package/commands/leave.md

@@ -0,0 +1,6 @@
+---
+description: Leave a room
+argument-hint: <room-name>
+---
+
+Call the `agent_comms` MCP tool with `action: "leave_room"` and `room: "$ARGUMENTS"`. Confirm with a single line. If the room doesn't exist or you're not a member, surface the error verbatim.

package/commands/read.md

@@ -0,0 +1,6 @@
+---
+description: Read recent messages from a room
+argument-hint: <room>
+---
+
+Call the `agent_comms` MCP tool with `action: "read_room"` and `room: "$ARGUMENTS"`. Present each message on its own line in chronological order, using the format `[HH:MM] <sender>: <content>`. If `<sender>` is a long fingerprint, truncate to the last 8 characters. No commentary.

package/commands/rooms.md

@@ -0,0 +1,5 @@
+---
+description: List all rooms in the mesh
+---
+
+Call the `agent_comms` MCP tool with `action: "list_rooms"` and present the result as a compact list — one room per line — showing the name, type, and member count, with a `[✓]` marker for rooms this session has joined. Don't add commentary.

package/commands/send.md

@@ -0,0 +1,6 @@
+---
+description: Broadcast a message to a room
+argument-hint: <room> <message>
+---
+
+Parse `$ARGUMENTS` as `<room> <message>` — first whitespace-separated token is the room name; everything after is the message body. Call the `agent_comms` MCP tool with `action: "send"`, `target: <room>`, `content: <message>`, and `streamingBehavior: "info"`. Confirm with a single line containing the returned message id. If the room isn't joined, surface the error verbatim.

package/commands/show.md

@@ -0,0 +1,5 @@
+---
+description: Make this session visible to agent discovery
+---
+
+Call the `agent_comms` MCP tool with `action: "update"` and `visibility: "visible"`. Confirm with a single line.

package/commands/status.md

@@ -0,0 +1,6 @@
+---
+description: Set this session's presence status
+argument-hint: <active|idle|busy>
+---
+
+Validate that `$ARGUMENTS` is one of `active`, `idle`, or `busy`. If invalid, print an error and stop. Otherwise call the `agent_comms` MCP tool with `action: "update"` and `status: "$ARGUMENTS"`. Confirm with a single line: the new status.

package/commands/whoami.md

@@ -0,0 +1,5 @@
+---
+description: Show this session's agent identity, status, and room memberships
+---
+
+Call the `agent_comms` MCP tool with `action: "whoami"` and present the result concisely: agent ID (short form), name, current status, visibility, and the list of joined rooms. No commentary.

package/dist/bridges/claude-code/channel.d.ts

@@ -2,11 +2,14 @@
  * 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.
+ * 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
- * Requires: claude --dangerously-load-development-channels
+ *
+ * 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.
  */
 export declare function run(): Promise<void>;
 //# sourceMappingURL=channel.d.ts.map

package/dist/bridges/claude-code/channel.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"channel.d.ts","sourceRoot":"","sources":["../../../src/bridges/claude-code/channel.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAwBH,wBAAsB,GAAG,IAAI,OAAO,CAAC,IAAI,CAAC,CAgHzC"}
+{"version":3,"file":"channel.d.ts","sourceRoot":"","sources":["../../../src/bridges/claude-code/channel.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AA4IH,wBAAsB,GAAG,IAAI,OAAO,CAAC,IAAI,CAAC,CAwHzC"}

package/dist/bridges/claude-code/channel.js

@@ -2,12 +2,19 @@
  * 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.
+ * 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
- * Requires: claude --dangerously-load-development-channels
+ *
+ * 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 { MeshStore, CommsTool, buildAction, ensureRegistered, extractStreamingBehavior, formatDeliveryEvent, isActionableEvent, MCP_TOOL_PARAMS, } from "../../core/index.js";
@@ -18,6 +25,120 @@ import { nanoid } from "../../core/nanoid.js";
 function isRecord(value) {
     return typeof value === "object" && value !== null && !Array.isArray(value);
 }
+function isErrnoException(err) {
+    return typeof err === "object" && err !== null && "code" in err;
+}
+function cwdSlug(cwd) {
+    return cwd.replace(/[^a-zA-Z0-9]/g, "_");
+}
+function pendingDir() {
+    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() {
+    let pid = process.ppid;
+    for (let i = 0; i < 10 && pid > 1; i++) {
+        let out;
+        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, claudePid) {
+    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) {
+    const dir = pendingDir();
+    const slug = cwdSlug(cwd);
+    const prefix = `claude-code--${slug}--`;
+    let entries;
+    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, line) {
+    fs.mkdirSync(path.dirname(filePath), { recursive: true });
+    fs.appendFileSync(filePath, line + "\n");
+}
+function drainPending(filePath) {
+    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() {
     const identity = generateIdentity();
     const store = new MeshStore();
@@ -25,21 +146,26 @@ export async function run() {
     store.setTransport(new TlsTransport(store.events, identity));
     const tool = new CommsTool(store, store.discovery);
     let agentId;
-    const pendingBuffer = [];
+    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 land in the drain buffer so idle-Claude never silently misses
-    // a message. Actionable events also get an eager channel push for mid-turn
-    // delivery. If the push fired and Claude caught it, the drain will echo it
-    // on the next tool call — acceptable duplication, far better than loss.
+    // 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, event) => {
         const line = formatDeliveryEvent(event);
         const hint = extractStreamingBehavior(event);
         const shouldPush = isActionableEvent(event) && hint !== "info";
-        pendingBuffer.push(line);
+        appendPending(pendingFile, line);
         if (shouldPush) {
             await mcp.server.notification({
                 method: "notifications/claude/channel",
@@ -58,7 +184,7 @@ export async function run() {
             "Cross-harness agent communication mesh. Actions:",
             "register, update, whoami, 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.',
+            '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,
@@ -84,7 +210,7 @@ export async function run() {
             cwd: process.cwd(),
             pid: process.pid,
         }, action);
-        const pending = pendingBuffer.splice(0);
+        const pending = drainPending(pendingFile);
         const prefix = pending.length > 0
             ? `[comms] Pending:\n${pending.map((l) => `  📬 ${l}`).join("\n")}\n\n`
             : "";

package/dist/bridges/claude-code/channel.js.map

@@ -1 +1 @@
-{"version":3,"file":"channel.js","sourceRoot":"","sources":["../../../src/bridges/claude-code/channel.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"channel.js","sourceRoot":"","sources":["../../../src/bridges/claude-code/channel.ts"],"names":[],"mappings":"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"}

package/hooks/drain.sh

@@ -0,0 +1,65 @@
+#!/usr/bin/env bash
+# Drain pending agent-comms events and exit 2 to wake idle Claude via asyncRewake.
+#
+# Called by Claude Code hooks (PostToolUse, Stop). If there are pending events,
+# writes them to stderr and exits 2 — Claude Code wraps the stderr in a
+# <system-reminder> and enqueues it as a task-notification, waking idle Claude.
+#
+# Uses atomic rename to drain so concurrent drains (in-process tool drain vs
+# this out-of-process hook) never duplicate or lose events.
+
+set -euo pipefail
+
+SLUG="${PWD//[^a-zA-Z0-9]/_}"
+
+# Walk up the process tree to find the Claude Code PID. Two Claude Code
+# instances in the same cwd would otherwise share one pending file and consume
+# each other's messages. Each Claude Code session has a unique PID; the bridge
+# discovers and uses the same value, so each session gets its own file.
+find_claude_pid() {
+  local pid=$PPID
+  for _ in 1 2 3 4 5 6 7 8 9 10; do
+    [ "$pid" -le 1 ] && return 1
+    local info ppid comm
+    info=$(ps -p "$pid" -o ppid=,comm= 2>/dev/null) || return 1
+    info=${info#"${info%%[![:space:]]*}"}
+    [ -z "$info" ] && return 1
+    ppid=${info%%[[:space:]]*}
+    comm=${info#*[[:space:]]}
+    comm=${comm#"${comm%%[![:space:]]*}"}
+    case "$comm" in
+      */claude|claude) echo "$pid"; return 0 ;;
+    esac
+    pid=$ppid
+  done
+  return 1
+}
+
+CLAUDE_PID=$(find_claude_pid 2>/dev/null || true)
+if [ -n "$CLAUDE_PID" ]; then
+  PENDING="$HOME/.agents/bus/pending/claude-code--${SLUG}--${CLAUDE_PID}.jsonl"
+else
+  echo "agent-comms drain.sh: could not locate Claude Code PID, falling back to shared cwd file" >&2
+  PENDING="$HOME/.agents/bus/pending/claude-code--${SLUG}.jsonl"
+fi
+
+DRAINING="${PENDING}.draining-$$-$(date +%s%N 2>/dev/null || date +%s)"
+
+# Atomic drain — if rename fails (file absent), nothing to surface.
+if ! mv "$PENDING" "$DRAINING" 2>/dev/null; then
+  exit 0
+fi
+
+CONTENT=$(cat "$DRAINING")
+rm -f "$DRAINING"
+
+if [ -z "$CONTENT" ]; then
+  exit 0
+fi
+
+echo "Pending agent-comms messages:" >&2
+while IFS= read -r line; do
+  [ -n "$line" ] && echo "  📬 $line" >&2
+done <<< "$CONTENT"
+
+exit 2

package/hooks/hooks.json

@@ -0,0 +1,39 @@
+{
+  "PostToolUse": [
+    {
+      "matcher": "*",
+      "hooks": [
+        {
+          "type": "command",
+          "command": "${CLAUDE_PLUGIN_ROOT}/hooks/drain.sh",
+          "timeout": 5
+        }
+      ]
+    }
+  ],
+  "Stop": [
+    {
+      "matcher": "*",
+      "hooks": [
+        {
+          "type": "command",
+          "command": "${CLAUDE_PLUGIN_ROOT}/hooks/drain.sh",
+          "timeout": 5
+        }
+      ]
+    }
+  ],
+  "UserPromptSubmit": [
+    {
+      "matcher": "*",
+      "hooks": [
+        {
+          "type": "command",
+          "command": "${CLAUDE_PLUGIN_ROOT}/hooks/drain.sh",
+          "asyncRewake": true,
+          "timeout": 5
+        }
+      ]
+    }
+  ]
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agent-comms",
-  "version": "1.21.2",
+  "version": "1.23.0",
   "description": "Cross-harness communication mesh for LLM agents — rooms, DMs, presence, and real-time push delivery over TCP",
   "type": "module",
   "packageManager": "pnpm@10.33.0",
@@ -34,7 +34,9 @@
   },
   "files": [
     "dist",
-    ".claude-plugin/"
+    ".claude-plugin/",
+    "commands/",
+    "hooks/"
   ],
   "bin": {
     "agent-comms": "dist/cli.js"