claude-code-swarm 0.3.25 → 0.3.26

package/.claude-plugin/marketplace.json

@@ -1,6 +1,6 @@
 {
   "name": "claude-code-swarm",
-  "version": "0.3.25",
+  "version": "0.3.26",
   "description": "Launch Claude Code with swarmkit capabilities, including team orchestration, MAP observability, and session tracking.",
   "owner": {
     "name": "alexngai"

package/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "claude-code-swarm",
   "description": "Spin up Claude Code agent teams from openteams YAML topologies with optional MAP (Multi-Agent Protocol) observability and coordination. Provides hooks for session lifecycle, agent spawn/complete tracking, and a /swarm skill to launch team configurations.",
-  "version": "0.3.25",
+  "version": "0.3.26",
   "author": {
     "name": "alexngai"
   },

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "claude-code-swarm",
-  "version": "0.3.25",
+  "version": "0.3.26",
   "description": "Claude Code plugin for launching agent teams from openteams topologies with MAP observability",
   "type": "module",
   "exports": {
@@ -53,7 +53,7 @@
     "node": ">=18.0.0"
   },
   "devDependencies": {
-    "agent-inbox": "^0.1.9",
+    "agent-inbox": "^0.2.3",
     "minimem": "^0.1.1",
     "opentasks": "^0.1.2",
     "skill-tree": "^0.2.0",

package/scripts/map-hook.mjs

@@ -77,7 +77,29 @@ async function handleInject(hookData, sessionId) {
   const sPaths = sessionPaths(sessionId);
   const config = readConfig();
 
-  if (!config.inbox?.enabled) return;
+  // Check for dispatch thread nudges (advisory push from hub).
+  // Nudges arrive via x-dispatch/nudge MAP notifications; the sidecar
+  // stores them until this hook drains them. We check nudges even when
+  // inbox is disabled — the nudge path is independent.
+  // Uses sendToInbox (which waits for a response) on the sidecar socket.
+  let nudgeOutput = "";
+  try {
+    const nudgeResp = await sendToInbox(
+      { action: "check-nudge" },
+      sPaths.socketPath,
+    );
+    if (nudgeResp && nudgeResp.ok && nudgeResp.nudges?.length > 0) {
+      const ids = nudgeResp.nudges.map((n) => n.dispatch_id).join(", ");
+      nudgeOutput = `\n<dispatch-thread-nudge>\nYou have pending messages in dispatch coordination thread(s): ${ids}. Check your inbox for new turns.\n</dispatch-thread-nudge>\n`;
+    }
+  } catch {
+    // Best effort — nudge is advisory
+  }
+
+  if (!config.inbox?.enabled) {
+    if (nudgeOutput) process.stdout.write(nudgeOutput);
+    return;
+  }
 
   // Only check messages addressed to the main agent (not all scope messages).
   // Per-agent messages stay in storage for agents to pull via MCP tools.
@@ -89,10 +111,9 @@ async function handleInject(hookData, sessionId) {
     { action: "check_inbox", agentId: mainAgentId, scope, unreadOnly: true, clear: true },
     sPaths.inboxSocketPath
   );
-  if (!resp || !resp.ok || !resp.messages?.length) return;
 
   // Forward task.* events to opentasks graph if enabled
-  if (config.opentasks?.enabled) {
+  if (resp?.ok && resp.messages?.length && config.opentasks?.enabled) {
     const otSocketPath = findSocketPath();
     const taskEvents = resp.messages.filter(
       (m) => m.content?.type === "event" && m.content?.event?.startsWith("task.")
@@ -102,8 +123,12 @@ async function handleInject(hookData, sessionId) {
     }
   }
 
-  const output = formatInboxAsMarkdown(resp.messages);
-  if (output) process.stdout.write(output);
+  const inboxOutput = resp?.ok && resp.messages?.length
+    ? formatInboxAsMarkdown(resp.messages)
+    : "";
+
+  const output = (nudgeOutput + (inboxOutput || "")).trim();
+  if (output) process.stdout.write(output + "\n");
 }
 
 async function handleTurnCompleted(hookData, sessionId) {

package/scripts/map-sidecar.mjs

@@ -425,6 +425,34 @@ function registerContentHandler(conn) {
   });
 }
 
+/**
+ * Register the x-dispatch/nudge notification handler on a connection.
+ * When the hub sends a nudge (a dispatch thread received a new turn),
+ * the sidecar stores the nudge so the UserPromptSubmit hook can inject
+ * a hint about pending messages.
+ */
+function registerNudgeHandler(conn) {
+  if (!conn || typeof conn.onNotification !== "function") return;
+
+  conn.onNotification("x-dispatch/nudge", (params) => {
+    const dispatchId = params?.dispatch_id;
+    const conversationId = params?.conversation_id;
+    if (!dispatchId) return;
+
+    log.info("dispatch nudge received", { dispatchId, conversationId });
+    resetInactivityTimer();
+
+    // Store the nudge via the command handler's nudge command.
+    // Use a fake client since we don't need the response.
+    if (commandHandler) {
+      commandHandler(
+        { action: "nudge", dispatch_id: dispatchId, conversation_id: conversationId },
+        { write: () => {}, writable: true },
+      );
+    }
+  });
+}
+
 async function startWebSocketTransport() {
   connection = await connectToMAP({
     server: MAP_SERVER,
@@ -557,6 +585,10 @@ async function main() {
     return commandHandler(command, client);
   });
 
+  // Register dispatch nudge handler — must come after commandHandler is created
+  // so the notification can store nudge state via the command handler.
+  registerNudgeHandler(connection);
+
   // Start memory file watcher if minimem is enabled
   const sidecarConfig = readConfig();
   if (sidecarConfig.minimem?.enabled) {

package/src/__tests__/loadout-schema-bridge.test.mjs

@@ -4,8 +4,7 @@
  * Asserts that the openteams `loadout.skills` schema (SkillsConfig) and
  * skilltree-client's bridge mapping stay in sync. skill-tree is the
  * mechanism; openteams' `loadout.skills` is the declaration that
- * dispatches into it. See openhive's docs/LOADOUT_INTEGRATION.md for
- * the model.
+ * dispatches into it.
  *
  * What this test catches:
  *   - openteams adds a new field to SkillsConfig and the bridge doesn't

package/src/__tests__/sidecar-nudge.test.mjs

@@ -0,0 +1,137 @@
+/**
+ * Tests for dispatch thread nudge commands on the sidecar command handler.
+ *
+ * Covers Phase 7 of dispatch-inbox-threads:
+ * - nudge command stores nudge state
+ * - check-nudge returns and clears pending nudges
+ * - Multiple nudges accumulate independently
+ */
+
+import { describe, it, expect, beforeEach } from "vitest";
+import { createCommandHandler, respond } from "../sidecar-server.mjs";
+
+function createTestHandler() {
+  const registeredAgents = new Map();
+  return createCommandHandler(null, "swarm:test", registeredAgents, {
+    transportMode: "websocket",
+  });
+}
+
+function createFakeClient() {
+  let lastResponse = null;
+  return {
+    write(data) {
+      try {
+        lastResponse = JSON.parse(data.replace(/\n$/, ""));
+      } catch {
+        lastResponse = data;
+      }
+    },
+    writable: true,
+    getResponse() {
+      return lastResponse;
+    },
+  };
+}
+
+describe("sidecar nudge commands", () => {
+  let handler;
+
+  beforeEach(() => {
+    handler = createTestHandler();
+  });
+
+  it("check-nudge returns empty array when no nudges pending", async () => {
+    const client = createFakeClient();
+    await handler({ action: "check-nudge" }, client);
+
+    const resp = client.getResponse();
+    expect(resp.ok).toBe(true);
+    expect(resp.nudges).toEqual([]);
+  });
+
+  it("nudge stores state, check-nudge returns and clears it", async () => {
+    const fakeClient = { write: () => {}, writable: true };
+
+    // Store a nudge
+    await handler(
+      { action: "nudge", dispatch_id: "d1", conversation_id: "conv-d1" },
+      fakeClient,
+    );
+
+    // Check nudge should return it
+    const client = createFakeClient();
+    await handler({ action: "check-nudge" }, client);
+
+    const resp = client.getResponse();
+    expect(resp.ok).toBe(true);
+    expect(resp.nudges).toHaveLength(1);
+    expect(resp.nudges[0]).toEqual({
+      dispatch_id: "d1",
+      conversation_id: "conv-d1",
+    });
+
+    // Second check should be empty (cleared)
+    const client2 = createFakeClient();
+    await handler({ action: "check-nudge" }, client2);
+
+    const resp2 = client2.getResponse();
+    expect(resp2.nudges).toEqual([]);
+  });
+
+  it("accumulates multiple nudges for different dispatches", async () => {
+    const fakeClient = { write: () => {}, writable: true };
+
+    await handler(
+      { action: "nudge", dispatch_id: "d1", conversation_id: "conv-d1" },
+      fakeClient,
+    );
+    await handler(
+      { action: "nudge", dispatch_id: "d2", conversation_id: "conv-d2" },
+      fakeClient,
+    );
+
+    const client = createFakeClient();
+    await handler({ action: "check-nudge" }, client);
+
+    const resp = client.getResponse();
+    expect(resp.nudges).toHaveLength(2);
+    const ids = resp.nudges.map((n) => n.dispatch_id).sort();
+    expect(ids).toEqual(["d1", "d2"]);
+  });
+
+  it("overwrites nudge for same dispatch_id (latest wins)", async () => {
+    const fakeClient = { write: () => {}, writable: true };
+
+    await handler(
+      { action: "nudge", dispatch_id: "d1", conversation_id: "conv-old" },
+      fakeClient,
+    );
+    await handler(
+      { action: "nudge", dispatch_id: "d1", conversation_id: "conv-new" },
+      fakeClient,
+    );
+
+    const client = createFakeClient();
+    await handler({ action: "check-nudge" }, client);
+
+    const resp = client.getResponse();
+    expect(resp.nudges).toHaveLength(1);
+    expect(resp.nudges[0].conversation_id).toBe("conv-new");
+  });
+
+  it("ignores nudge with no dispatch_id", async () => {
+    const fakeClient = { write: () => {}, writable: true };
+
+    await handler(
+      { action: "nudge", conversation_id: "conv-x" },
+      fakeClient,
+    );
+
+    const client = createFakeClient();
+    await handler({ action: "check-nudge" }, client);
+
+    const resp = client.getResponse();
+    expect(resp.nudges).toEqual([]);
+  });
+});

package/src/bootstrap.mjs

@@ -244,16 +244,22 @@ async function startSessionSidecar(config, scope, dir, sessionId) {
 
   const ok = await startSidecar(config, dir, sessionId);
   if (ok) {
-    // Register the main Claude Code session agent with the MAP server
+    // Register the main Claude Code session agent with the MAP server.
+    // Use the inbox-derived ID (`${teamName}-main`) as the canonical agentId
+    // so MAP and inbox identities are unified — the hub can correlate a MAP
+    // agent with its inbox participant without a separate lookup table.
+    // The ephemeral sessionId is preserved in metadata for trajectory
+    // correlation and session storage.
     const teamName = resolveTeamName(config);
+    const inboxAgentId = `${teamName}-main`;
     sendCommand(config, {
       action: "spawn",
       agent: {
-        agentId: sessionId,
-        name: `${teamName}-main`,
+        agentId: inboxAgentId,
+        name: inboxAgentId,
         role: "orchestrator",
         scopes: [scope],
-        metadata: { isMain: true, sessionId },
+        metadata: { isMain: true, sessionId, inboxAgentId },
       },
     }, sessionId).catch(() => {});
 
@@ -307,9 +313,11 @@ export async function backgroundInit(config, scope, dir, sessionId) {
       }
     }
 
-    // Inbox registration
+    // Inbox registration — uses the same stable ID as the MAP registration
+    // above so both systems share a single canonical agent identity.
     if (config.map.enabled && config.inbox?.enabled) {
-      const teamName = resolveTeamName(config);
+      const inboxTeamName = resolveTeamName(config);
+      const inboxId = `${inboxTeamName}-main`;
       const sPaths = sessionId
         ? (await import("./paths.mjs")).sessionPaths(sessionId)
         : { inboxSocketPath: (await import("./paths.mjs")).INBOX_SOCKET_PATH };
@@ -319,11 +327,11 @@ export async function backgroundInit(config, scope, dir, sessionId) {
           event: {
             type: "agent.spawn",
             agent: {
-              agentId: `${teamName}-main`,
-              name: `${teamName}-main`,
+              agentId: inboxId,
+              name: inboxId,
               role: "orchestrator",
               scopes: [scope],
-              metadata: { isMain: true, sessionId },
+              metadata: { isMain: true, sessionId, inboxAgentId: inboxId },
             },
           },
         }, sPaths.inboxSocketPath).catch(() => {})

package/src/map-events.mjs

@@ -63,12 +63,18 @@ export async function emitPayload(config, payload, meta, sessionId) {
 
 /**
  * Build a "spawn" sidecar command for a subagent.
+ *
+ * The agentId is derived from hookData.agent_id when available (stable,
+ * set by the spawning agent) or falls back to a timestamp-based ID.
+ * `inboxAgentId` is included in metadata so the hub can correlate MAP
+ * and inbox identities.
  */
 export function buildSubagentSpawnCommand(hookData, teamName) {
+  const agentId = hookData.agent_id || `${teamName}-subagent-${Date.now()}`;
   return {
     action: "spawn",
     agent: {
-      agentId: hookData.agent_id || `${teamName}-subagent-${Date.now()}`,
+      agentId,
       name: hookData.agent_type || "subagent",
       role: "subagent",
       scopes: [`swarm:${teamName}`],
@@ -76,6 +82,7 @@ export function buildSubagentSpawnCommand(hookData, teamName) {
         agentType: hookData.agent_type || "",
         sessionId: hookData.session_id || "",
         isTeamRole: false,
+        inboxAgentId: agentId,
       },
     },
   };

package/src/sidecar-server.mjs

@@ -99,6 +99,11 @@ export function createCommandHandler(connection, scope, registeredAgents, opts =
   const { inboxInstance, meshPeer, transportMode = "websocket" } = opts;
   const useMeshRegistry = transportMode === "mesh" && inboxInstance;
 
+  // Dispatch thread nudge state — set by x-dispatch/nudge notifications,
+  // consumed by the UserPromptSubmit hook via the check-nudge command.
+  // Keyed by dispatch_id → { conversation_id, received_at }.
+  const _pendingNudges = new Map();
+
   // Connection-ready gate: commands that need `conn` await this promise.
   // If connection is already available, resolves immediately.
   // When connection arrives later (via setConnection), resolves the pending promise.
@@ -474,6 +479,37 @@ export function createCommandHandler(connection, scope, registeredAgents, opts =
           break;
         }
 
+        // --- Dispatch thread nudge ---
+        // Set by x-dispatch/nudge MAP notifications, consumed by hooks.
+
+        case "nudge": {
+          // Called internally when the notification handler fires.
+          const { dispatch_id, conversation_id } = command;
+          if (dispatch_id) {
+            _pendingNudges.set(dispatch_id, {
+              conversation_id,
+              received_at: Date.now(),
+            });
+          }
+          respond(client, { ok: true });
+          break;
+        }
+
+        case "check-nudge": {
+          // Called by UserPromptSubmit hook. Returns and clears all
+          // pending nudges so the hook can inject a hint.
+          const nudges = [];
+          for (const [dispatchId, info] of _pendingNudges) {
+            nudges.push({
+              dispatch_id: dispatchId,
+              conversation_id: info.conversation_id,
+            });
+          }
+          _pendingNudges.clear();
+          respond(client, { ok: true, nudges });
+          break;
+        }
+
         default:
           respond(client, { ok: false, error: `Unknown action: ${action}` });
       }

package/src/skilltree-client.mjs

@@ -155,7 +155,7 @@ export function inferProfileFromRole(roleName) {
 // The bridge between openteams `loadout.skills` (SkillsConfig in the
 // schema) and skill-tree's LoadoutCriteria. skill-tree is the
 // *mechanism*; openteams is the *declaration layer* that dispatches
-// into it. See openhive's docs/LOADOUT_INTEGRATION.md for the model.
+// into it.
 //
 // Bridged fields are locked in by src/__tests__/loadout-schema-bridge.test.mjs
 // which cross-references this list against openteams' SkillsConfig schema.