claude-code-swarm 0.3.22 → 0.3.24

package/.claude-plugin/marketplace.json

@@ -1,6 +1,6 @@
 {
   "name": "claude-code-swarm",
-  "version": "0.3.22",
+  "version": "0.3.24",
   "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.22",
+  "version": "0.3.24",
   "author": {
     "name": "alexngai"
   },

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "claude-code-swarm",
-  "version": "0.3.22",
+  "version": "0.3.24",
   "description": "Claude Code plugin for launching agent teams from openteams topologies with MAP observability",
   "type": "module",
   "exports": {
@@ -24,7 +24,7 @@
   },
   "peerDependencies": {
     "agent-inbox": "*",
-    "opentasks": "*",
+    "opentasks": ">=0.1.1",
     "swarmkit": "*"
   },
   "peerDependenciesMeta": {
@@ -55,7 +55,7 @@
   "devDependencies": {
     "agent-inbox": "^0.1.9",
     "minimem": "^0.1.1",
-    "opentasks": "^0.0.8",
+    "opentasks": "^0.1.2",
     "skill-tree": "^0.1.5",
     "vitest": "^4.0.18",
     "ws": "^8.0.0"

package/scripts/map-sidecar.mjs

@@ -24,6 +24,7 @@ import { SOCKET_PATH, PID_PATH, INBOX_SOCKET_PATH, sessionPaths, pluginDir } fro
 import { connectToMAP } from "../src/map-connection.mjs";
 import { createMeshPeer, createMeshInbox } from "../src/mesh-connection.mjs";
 import { createSocketServer, createCommandHandler } from "../src/sidecar-server.mjs";
+import { startOpenTasksEventBridge } from "../src/opentasks-bridge.mjs";
 import { createContentProvider } from "../src/content-provider.mjs";
 import { startMemoryWatcher } from "../src/memory-watcher.mjs";
 import { readConfig } from "../src/config.mjs";
@@ -123,6 +124,7 @@ let inboxInstance = null;
 let inactivityTimer = null;
 let reconnectInterval = null;
 let transportMode = "websocket"; // "mesh" or "websocket"
+let opentasksBridge = null; // Daemon watch → MAP event bridge (Option A)
 const registeredAgents = new Map();
 
 // ── Inactivity Timer ────────────────────────────────────────────────────────
@@ -143,6 +145,13 @@ async function shutdown() {
   if (inactivityTimer) clearTimeout(inactivityTimer);
   if (reconnectInterval) clearInterval(reconnectInterval);
 
+  // Stop opentasks event bridge before the MAP connection drops — the
+  // bridge needs a live connection to send its unsubscribe over.
+  if (opentasksBridge) {
+    try { await opentasksBridge.stop(); } catch { /* ignore */ }
+    opentasksBridge = null;
+  }
+
   // Stop agent-inbox first (it borrows the connection/peer, doesn't own it)
   if (inboxInstance) {
     try { await inboxInstance.stop(); } catch { /* ignore */ }
@@ -242,6 +251,19 @@ function startSlowReconnectLoop() {
         // Re-subscribe inbox events to the new connection
         subscribeInboxEvents(newConn);
 
+        // Re-attach opentasks event bridge to the fresh connection —
+        // the previous bridge was bound to the dead one.
+        if (opentasksBridge) {
+          try { await opentasksBridge.stop(); } catch { /* ignore */ }
+          opentasksBridge = null;
+        }
+        if (PROJECT_CONTEXT.task_graph) {
+          opentasksBridge = await startOpenTasksEventBridge(newConn, {
+            scope: MAP_SCOPE,
+            onActivity: resetInactivityTimer,
+          });
+        }
+
         log.info("reconnected to MAP server");
       }
     } catch (err) {
@@ -428,6 +450,18 @@ async function startWebSocketTransport() {
     await registerOpenTasksHandler(connection);
   }
 
+  // Start the opentasks → MAP event bridge — surfaces every graph
+  // change (context/spec nodes in particular) as a MAP event over the
+  // shared connection. Task-event emission is suppressed inside the
+  // bridge to avoid double-sending alongside the existing PostToolUse
+  // `bridge-task-*` command chain.
+  if (connection && PROJECT_CONTEXT.task_graph) {
+    opentasksBridge = await startOpenTasksEventBridge(connection, {
+      scope: MAP_SCOPE,
+      onActivity: resetInactivityTimer,
+    });
+  }
+
   // Start agent-inbox with MAP connection (legacy mode)
   if (INBOX_CONFIG && connection) {
     inboxInstance = await startLegacyAgentInbox(connection);

package/src/opentasks-bridge.mjs

@@ -0,0 +1,140 @@
+/**
+ * opentasks-bridge.mjs — Opentasks MAP event bridge for the sidecar
+ *
+ * Attaches opentasks' `createMAPEventBridge` to the local daemon's watch
+ * stream so every graph change surfaces as a `task.*` / `context.*` MAP
+ * event over the shared MAP connection. The bridge is kind-agnostic for
+ * contexts — downstream consumers (e.g. OpenHive's hub) route by
+ * `metadata.kind` to classify specs vs plain contexts.
+ *
+ * This is the "Option A" daemon-wired path — no explicit `bridge-*`
+ * sidecar command is needed for contexts. For tasks, the existing
+ * PostToolUse(TaskCreate) → `bridge-task-*` command chain remains the
+ * active path (matches the filters in sidecar-server.mjs and avoids
+ * double-emission when both hooks and the watcher fire for the same
+ * change).
+ *
+ * Extracted from map-sidecar.mjs for testability.
+ */
+
+import { createLogger } from "./log.mjs";
+
+const log = createLogger("opentasks-bridge");
+
+/**
+ * Start the opentasks MAP event bridge.
+ *
+ * Connects to the local opentasks daemon, subscribes to graph changes,
+ * and forwards every event through the MAP event bridge so connected
+ * observers (OpenHive hub, peer swarms) see them as standard MAP events.
+ *
+ * Safe to call when the daemon isn't running or when MAP connection is
+ * absent — returns `null` and logs at debug level.
+ *
+ * @param {object} conn - MAP connection (AgentConnection or MeshPeer connection)
+ * @param {object} options
+ * @param {string} options.scope - MAP scope (e.g. "swarm:gsd")
+ * @param {() => void} [options.onActivity] - Called on each bridged event
+ * @param {() => Promise<object>} [options.importOpentasks] - Override for `await import("opentasks")`
+ * @param {() => Promise<object>} [options.importOpentasksClient] - Override for `./opentasks-client.mjs` import
+ * @returns {Promise<{ stop: () => Promise<void> } | null>}
+ */
+export async function startOpenTasksEventBridge(conn, options = {}) {
+  if (!conn) return null;
+
+  const {
+    scope = "swarm:default",
+    onActivity,
+    importOpentasks,
+    importOpentasksClient,
+  } = options;
+
+  let opentasks;
+  try {
+    opentasks = importOpentasks
+      ? await importOpentasks()
+      : await import("opentasks");
+  } catch (err) {
+    log.debug("opentasks package not available", { error: err.message });
+    return null;
+  }
+
+  const { createMAPEventBridge, createIPCClient } = opentasks || {};
+  if (!createMAPEventBridge || !createIPCClient) {
+    log.debug("opentasks event-bridge exports missing");
+    return null;
+  }
+
+  let socketPath;
+  try {
+    const opentasksClient = importOpentasksClient
+      ? await importOpentasksClient()
+      : await import("./opentasks-client.mjs");
+    socketPath = opentasksClient.findSocketPath();
+  } catch (err) {
+    log.debug("could not resolve opentasks socket path", { error: err.message });
+    return null;
+  }
+
+  const client = createIPCClient(socketPath);
+  try {
+    await client.connect();
+  } catch (err) {
+    log.debug("opentasks daemon not reachable, bridge disabled", {
+      socketPath,
+      error: err.message,
+    });
+    return null;
+  }
+
+  const bridge = createMAPEventBridge({
+    connection: conn,
+    scope,
+    agentId: `${scope}-sidecar`,
+    // Suppress bridge task.* events — the sidecar's existing
+    // `bridge-task-*` command chain (driven by PostToolUse hooks) is the
+    // canonical path for tasks. Emitting here too would duplicate every
+    // task event. Contexts have no hook counterpart, so they only flow
+    // via this watcher.
+    filter: (type) => !type.startsWith("task."),
+  });
+
+  const offNotif = client.onNotification((method, params) => {
+    if (method !== "watch.event") return;
+    if (onActivity) onActivity();
+    log.debug("watch.event received", {
+      kind: params?.type,
+      nodeId: params?.nodeId,
+      nodeType: params?.node?.type,
+    });
+    try {
+      bridge.handleProviderChange("native", { kind: "node", event: params });
+    } catch (err) {
+      log.debug("bridge.handleProviderChange threw", { error: err.message });
+    }
+  });
+
+  try {
+    await client.request("watch.subscribe", {});
+  } catch (err) {
+    log.debug("watch.subscribe failed, bridge disabled", { error: err.message });
+    offNotif();
+    try { client.disconnect(); } catch { /* ignore */ }
+    return null;
+  }
+
+  log.info("opentasks event bridge active", { scope, socketPath });
+
+  return {
+    async stop() {
+      try {
+        await client.request("watch.unsubscribe", {});
+      } catch {
+        // ignore — we're shutting down anyway
+      }
+      offNotif();
+      bridge.stop();
+      try { client.disconnect(); } catch { /* ignore */ }
+    },
+  };
+}

package/plan.md

@@ -1,214 +0,0 @@
-# Refactor: Replace custom `swarm.*` events with MAP SDK primitives
-
-## Goal
-
-Eliminate all custom `swarm.*` event types by using the MAP SDK's built-in `AgentConnection` methods (`spawn()`, `done()`, `updateState()`, `updateMetadata()`, `send()`) and the server's automatic event emission (`agent_registered`, `agent_state_changed`, etc.). This means MAP clients only need to subscribe to standard MAP event types — zero swarm-specific integration.
-
-## Guiding principle
-
-**No new message types.** All swarm-specific context goes into `metadata` on agents and `payload` on messages — never into custom event type strings.
-
----
-
-## Current state → Target state mapping
-
-| Current custom event | Target SDK primitive | Auto server event |
-|---|---|---|
-| `swarm.agent.registered` (sidecar broadcasts) | `conn.spawn({ name, role, parent, scopes, metadata })` | `agent_registered` |
-| `swarm.agent.unregistered` (sidecar broadcasts) | `spawnedAgent.done({ exitReason })` or sidecar tracks + calls `conn.callExtension(...)` to unregister | `agent_unregistered` |
-| `swarm.agent.spawned` (emitEvent broadcast) | Replaced by `spawn()` above — no separate event needed | `agent_registered` |
-| `swarm.agent.completed` (emitEvent broadcast) | Replaced by agent `done()` above | `agent_state_changed` → `stopped` |
-| `swarm.task.dispatched` (emitEvent broadcast) | `conn.send({ scope }, { type: "task.dispatched", ... })` — typed payload in regular message | `message_sent` |
-| `swarm.task.completed` (emitEvent broadcast) | `conn.send({ scope }, { type: "task.completed", ... })` | `message_sent` |
-| `swarm.task.status_completed` (emitEvent broadcast) | `conn.send({ scope }, { type: "task.completed", ... })` with richer payload | `message_sent` |
-| `swarm.turn.completed` (emitEvent broadcast) | `conn.idle()` + `conn.updateMetadata({ lastStopReason })` | `agent_state_changed` → `idle` |
-| `swarm.subagent.started` (emitEvent broadcast) | `conn.spawn({ role: "subagent", metadata: { agentType, sessionId } })` | `agent_registered` |
-| `swarm.subagent.stopped` (emitEvent broadcast) | `spawned.done({ exitReason })` | `agent_state_changed` → `stopped` |
-| `swarm.teammate.idle` (emitEvent broadcast) | `agent.updateState("idle")` (via sidecar) | `agent_state_changed` → `idle` |
-| `swarm.sessionlog.sync` (broadcast fallback) | `conn.callExtension("trajectory/checkpoint", ...)` — keep existing; fallback sends as regular message payload instead of custom event type | `trajectory.checkpoint` |
-
----
-
-## Implementation steps
-
-### Step 1: Refactor `sidecar-server.mjs` — replace `register`/`unregister` with `spawn`/`done`
-
-**File:** `src/sidecar-server.mjs`
-
-Replace the `register` command handler:
-- **Before:** `conn.send({ scope }, { type: "swarm.agent.registered", ... })` — broadcasts a custom message
-- **After:** `conn.spawn({ agentId, name, role, scopes, metadata })` — uses SDK primitive; server auto-emits `agent_registered`
-- Store spawned agent references in a `Map<agentId, AgentSpawnResult>` instead of just a `Set<agentId>`
-
-Replace the `unregister` command handler:
-- **Before:** `conn.send({ scope }, { type: "swarm.agent.unregistered", ... })` — broadcasts custom message
-- **After:** Use `conn.callExtension("agents/unregister", { agentId, reason })` or track spawned agent IDs and send a deregistration request. Since the sidecar is the parent, it can manage child agent lifecycle.
-- Actually, the simplest approach: call `conn.send()` with method `"map/agents/unregister"` as a request, or use the lower-level approach of sending a state update. Since the sidecar owns the spawned agents, we'll call `conn.callExtension("map/agents/unregister", { agentId, reason })`.
-- Remove from tracked agents map
-
-Replace the `trajectory-checkpoint` fallback:
-- **Before:** Falls back to `conn.send({ scope }, { type: "swarm.sessionlog.sync", ... })`
-- **After:** Falls back to `conn.send({ scope }, { type: "trajectory.checkpoint.fallback", checkpoint })` — still a regular message but with a standardized payload shape, not a custom event type. Or even simpler: just use `{ type: "trajectory.checkpoint", ... }` as the message payload since this is informational.
-
-Keep `emit` command handler for now (backward compat) but mark as deprecated — it's the generic "send arbitrary payload" path.
-
-Keep `state` and `ping` handlers unchanged.
-
-### Step 2: Refactor `map-events.mjs` — replace builders with SDK-aligned builders
-
-**File:** `src/map-events.mjs`
-
-This is where the core change happens. Replace the custom event builders with functions that produce either:
-- **Sidecar commands** (for `spawn`/`done`/state updates) — structured for the sidecar socket protocol
-- **Message payloads** (for task lifecycle) — sent via `conn.send()` as regular MAP messages
-
-New functions:
-
-```javascript
-// Agent lifecycle — produce sidecar commands
-export function buildSpawnCommand(agentName, matchedRole, teamName, hookData) → { action: "spawn", agent: { ... } }
-export function buildDoneCommand(agentName, matchedRole, teamName) → { action: "done", agentId, reason }
-export function buildSubagentSpawnCommand(hookData, teamName) → { action: "spawn", agent: { role: "subagent", ... } }
-export function buildSubagentDoneCommand(hookData, teamName) → { action: "done", agentId, reason }
-
-// State updates — produce sidecar commands
-export function buildStateCommand(agentId, state, metadata?) → { action: "state", agentId, state, metadata? }
-
-// Task lifecycle — produce message payloads (sent via "emit" or "send")
-export function buildTaskDispatchedPayload(hookData, teamName, matchedRole, agentName) → { type: "task.dispatched", ... }
-export function buildTaskCompletedPayload(hookData, teamName, matchedRole, agentName) → { type: "task.completed", ... }
-export function buildTaskStatusPayload(hookData, teamName, matchedRole) → { type: "task.completed", ... }
-```
-
-Remove `emitEvent()` wrapper for agent lifecycle events — those go directly as sidecar commands.
-Keep `emitEvent()` only for task-related message payloads (these are still sent as MAP messages to scope, which is fine).
-
-### Step 3: Refactor `map-hook.mjs` — update action handlers
-
-**File:** `scripts/map-hook.mjs`
-
-`handleAgentSpawning()`:
-- **Before:** `sendToSidecar({ action: "register", agent: {...} })` + `emitEvent(buildSpawnEvent)` + `emitEvent(buildTaskDispatchedEvent)`
-- **After:** `sendToSidecar(buildSpawnCommand(...))` + `emitEvent(buildTaskDispatchedPayload(...))`
-- The spawn command replaces both the register and the spawn event — one operation, server auto-emits the event
-
-`handleAgentCompleted()`:
-- **Before:** `sendToSidecar({ action: "unregister", ... })` + `emitEvent(buildCompletedEvent)` + `emitEvent(buildTaskCompletedEvent)`
-- **After:** `sendToSidecar(buildDoneCommand(...))` + `emitEvent(buildTaskCompletedPayload(...))`
-
-`handleTurnCompleted()`:
-- **Before:** `sendToSidecar({ action: "state", state: "idle" })` + `emitEvent(buildTurnCompletedEvent)`
-- **After:** `sendToSidecar(buildStateCommand(sidecarId, "idle", { lastStopReason }))` — just a state+metadata update, server auto-emits `agent_state_changed`
-
-`handleSubagentStart()`:
-- **Before:** `emitEvent(buildSubagentStartEvent)`
-- **After:** `sendToSidecar(buildSubagentSpawnCommand(...))` — spawn in MAP for observability
-
-`handleSubagentStop()`:
-- **Before:** `emitEvent(buildSubagentStopEvent)`
-- **After:** `sendToSidecar(buildSubagentDoneCommand(...))`
-
-`handleTeammateIdle()`:
-- **Before:** `sendToSidecar({ action: "state" })` + `emitEvent(buildTeammateIdleEvent)`
-- **After:** `sendToSidecar(buildStateCommand(agentId, "idle"))` — state change only, server auto-emits
-
-`handleTaskCompleted()`:
-- **Before:** `emitEvent(buildTaskStatusCompletedEvent)`
-- **After:** `emitEvent(buildTaskStatusPayload(...))`
-
-### Step 4: Refactor `map-connection.mjs` — update `fireAndForget` and trajectory fallback
-
-**File:** `src/map-connection.mjs`
-
-`fireAndForget()`:
-- Keep as-is but now it sends typed message payloads (for task events) rather than custom event types
-
-`fireAndForgetTrajectory()`:
-- **Before:** Fallback broadcasts `{ type: "swarm.sessionlog.sync", ... }`
-- **After:** Fallback sends `{ type: "trajectory.checkpoint", checkpoint: {...} }` as a regular message payload — clients looking for trajectory data can filter on this
-
-### Step 5: Update `sidecar-server.mjs` command handler — add `spawn`/`done` commands
-
-**File:** `src/sidecar-server.mjs`
-
-Add new command cases:
-
-```javascript
-case "spawn": {
-  if (conn) {
-    const result = await conn.spawn({
-      agentId: command.agent.agentId,
-      name: command.agent.name,
-      role: command.agent.role,
-      scopes: command.agent.scopes,
-      metadata: command.agent.metadata,
-    });
-    registeredAgents.set(command.agent.agentId, result);
-  }
-  respond(client, { ok: true });
-  break;
-}
-
-case "done": {
-  if (conn) {
-    // Unregister the spawned child agent
-    try {
-      await conn.callExtension("map/agents/unregister", {
-        agentId: command.agentId,
-        reason: command.reason || "completed",
-      });
-    } catch {
-      // Agent may already be gone
-    }
-    registeredAgents.delete(command.agentId);
-  }
-  respond(client, { ok: true });
-  break;
-}
-```
-
-Change `registeredAgents` from `Set` to `Map` in `scripts/map-sidecar.mjs`.
-
-Keep old `register`/`unregister` commands working (deprecated) for backward compat during rollout.
-
-### Step 6: Update tests
-
-**Files:**
-- `src/__tests__/map-events.test.mjs` — Update for new function signatures and return shapes
-- `src/__tests__/sidecar-server.test.mjs` — Add tests for `spawn`/`done` commands, update `register`/`unregister` tests
-
-### Step 7: Update `CLAUDE.md` documentation
-
-Update the "MAP hooks" section to reflect:
-- No custom `swarm.*` event types
-- Agent lifecycle uses `spawn()`/`done()` SDK primitives
-- Task lifecycle uses typed message payloads
-- Turn lifecycle uses `updateState()` + `updateMetadata()`
-- Clients subscribe to standard MAP events only
-
----
-
-## What stays the same
-
-- **Sidecar architecture** — persistent process with socket IPC, unchanged
-- **Hook wiring** — same hooks, same scripts, same conditions in `hooks.json`
-- **Trajectory checkpoints** — same `callExtension("trajectory/checkpoint")` with broadcast fallback
-- **Inbox system** — unchanged (read/clear/format/write)
-- **Role matching** — unchanged (`roles.mjs`)
-- **Config system** — unchanged (`config.mjs`)
-- **Bootstrap flow** — unchanged (`bootstrap.mjs`)
-- **Fire-and-forget recovery** — same sidecar → recovery → direct pattern
-
-## What changes
-
-- **No custom event types** — everything uses MAP SDK primitives or typed message payloads
-- **Sidecar registers agents properly** — `conn.spawn()` instead of broadcasting fake events
-- **Server emits lifecycle events automatically** — clients see `agent_registered`, `agent_state_changed`, etc.
-- **Task events are messages, not events** — sent via `conn.send()` with typed payloads
-- **Cleaner client integration** — subscribe to standard MAP events, no `swarm.*` parsing needed
-
-## Risk / rollback
-
-- The refactor is fully backward-compatible at the config level (`.claude-swarm.json` unchanged)
-- Old `register`/`unregister` sidecar commands still work during transition
-- If `conn.spawn()` fails (e.g., server doesn't support it), we can fall back to the old broadcast approach