claude-code-swarm 0.3.5 → 0.3.7

package/references/agent-inbox/test/mcp-proxy.test.ts

@@ -0,0 +1,191 @@
+import { describe, it, expect, beforeEach, afterEach } from "vitest";
+import * as net from "node:net";
+import * as os from "node:os";
+import * as path from "node:path";
+import { EventEmitter } from "node:events";
+import { InMemoryStorage } from "../src/storage/memory.js";
+import { MessageRouter } from "../src/router/message-router.js";
+import { IpcServer } from "../src/ipc/ipc-server.js";
+import { InboxMcpProxy } from "../src/mcp/mcp-proxy.js";
+
+function tmpSocketPath(): string {
+  return path.join(os.tmpdir(), `inbox-proxy-test-${Date.now()}-${Math.random().toString(36).slice(2)}.sock`);
+}
+
+/**
+ * Helper: directly send an IPC command (bypass proxy, used for setup/verification).
+ */
+function sendIpc(socketPath: string, command: object): Promise<Record<string, unknown>> {
+  return new Promise((resolve, reject) => {
+    const client = net.createConnection(socketPath, () => {
+      client.write(JSON.stringify(command) + "\n");
+    });
+    let buffer = "";
+    client.on("data", (data) => {
+      buffer += data.toString();
+      const idx = buffer.indexOf("\n");
+      if (idx !== -1) {
+        const line = buffer.slice(0, idx);
+        client.end();
+        resolve(JSON.parse(line));
+      }
+    });
+    client.on("error", reject);
+  });
+}
+
+describe("InboxMcpProxy", () => {
+  let storage: InMemoryStorage;
+  let events: EventEmitter;
+  let router: MessageRouter;
+  let ipcServer: IpcServer;
+  let socketPath: string;
+  let proxy: InboxMcpProxy;
+
+  beforeEach(async () => {
+    storage = new InMemoryStorage();
+    events = new EventEmitter();
+    router = new MessageRouter(storage, events, "test-scope");
+    socketPath = tmpSocketPath();
+    ipcServer = new IpcServer(socketPath, router, storage);
+    await ipcServer.start();
+    proxy = new InboxMcpProxy(socketPath, "test-agent", "test-scope");
+  });
+
+  afterEach(async () => {
+    await ipcServer.stop();
+  });
+
+  it("should be constructable with socket path, agent ID, and scope", () => {
+    expect(proxy).toBeDefined();
+    expect(proxy.server).toBeDefined();
+  });
+
+  it("should proxy send via IPC and message lands in storage", async () => {
+    // Use the proxy's internal sendIpc (test via IPC directly since MCP stdio is hard to test)
+    // Instead, verify the proxy's IPC client works by sending directly and checking storage
+    const resp = await sendIpc(socketPath, {
+      action: "send",
+      from: "test-agent",
+      to: "recipient",
+      payload: "hello from proxy",
+    });
+    expect(resp.ok).toBe(true);
+    expect(resp.messageId).toBeTruthy();
+
+    // Verify message is in shared storage
+    const msg = storage.getMessage(resp.messageId as string);
+    expect(msg).toBeDefined();
+    expect(msg!.sender_id).toBe("test-agent");
+  });
+
+  it("should see messages sent to the IPC server via check_inbox", async () => {
+    // Send a message via IPC
+    await sendIpc(socketPath, {
+      action: "send",
+      from: "external",
+      to: "my-agent",
+      payload: "you have a task",
+    });
+
+    // Check inbox via IPC (same path proxy would use)
+    const resp = await sendIpc(socketPath, {
+      action: "check_inbox",
+      agentId: "my-agent",
+      unreadOnly: true,
+    });
+
+    expect(resp.ok).toBe(true);
+    const messages = resp.messages as Array<{ sender_id: string }>;
+    expect(messages).toHaveLength(1);
+    expect(messages[0].sender_id).toBe("external");
+  });
+
+  it("should read threads via IPC", async () => {
+    await sendIpc(socketPath, {
+      action: "send",
+      from: "alice",
+      to: "bob",
+      payload: "msg 1",
+      threadTag: "thread-1",
+    });
+    await sendIpc(socketPath, {
+      action: "send",
+      from: "bob",
+      to: "alice",
+      payload: "msg 2",
+      threadTag: "thread-1",
+    });
+
+    const resp = await sendIpc(socketPath, {
+      action: "read_thread",
+      threadTag: "thread-1",
+      scope: "test-scope",
+    });
+
+    expect(resp.ok).toBe(true);
+    expect(resp.count).toBe(2);
+  });
+
+  it("should list agents via IPC", async () => {
+    await sendIpc(socketPath, {
+      action: "notify",
+      event: {
+        type: "agent.spawn",
+        agent: { agentId: "agent-a", name: "Agent A", scopes: ["test-scope"] },
+      },
+    });
+
+    const resp = await sendIpc(socketPath, {
+      action: "list_agents",
+    });
+
+    expect(resp.ok).toBe(true);
+    expect(resp.count).toBe(1);
+    const agents = resp.agents as Array<{ agentId: string }>;
+    expect(agents[0].agentId).toBe("agent-a");
+  });
+
+  it("should handle unavailable socket gracefully", async () => {
+    const badProxy = new InboxMcpProxy("/tmp/nonexistent-socket.sock", "agent", "default");
+    // Access internal sendIpc method indirectly — the proxy shouldn't crash
+    // We test this by verifying the class instantiates without error
+    expect(badProxy).toBeDefined();
+  });
+});
+
+describe("InboxMcpProxy default agent ID", () => {
+  let storage: InMemoryStorage;
+  let events: EventEmitter;
+  let router: MessageRouter;
+  let ipcServer: IpcServer;
+  let socketPath: string;
+
+  beforeEach(async () => {
+    storage = new InMemoryStorage();
+    events = new EventEmitter();
+    router = new MessageRouter(storage, events, "default");
+    socketPath = tmpSocketPath();
+    ipcServer = new IpcServer(socketPath, router, storage);
+    await ipcServer.start();
+  });
+
+  afterEach(async () => {
+    await ipcServer.stop();
+  });
+
+  it("should use default agent ID as sender when from is not specified", async () => {
+    // The proxy's defaultAgentId should be used when send_message doesn't specify from.
+    // We test this by sending via IPC with the expected default and checking storage.
+    const resp = await sendIpc(socketPath, {
+      action: "send",
+      from: "gsd-executor", // proxy would inject this as default
+      to: "observer",
+      payload: "status update",
+    });
+
+    expect(resp.ok).toBe(true);
+    const msg = storage.getMessage(resp.messageId as string);
+    expect(msg!.sender_id).toBe("gsd-executor");
+  });
+});

package/references/minimem/package-lock.json

@@ -1,12 +1,12 @@
 {
   "name": "minimem",
-  "version": "0.0.7",
+  "version": "0.1.0",
   "lockfileVersion": 3,
   "requires": true,
   "packages": {
     "": {
       "name": "minimem",
-      "version": "0.0.7",
+      "version": "0.1.0",
       "license": "MIT",
       "dependencies": {
         "chokidar": "^4.0.3",

package/references/minimem/package.json

@@ -1,6 +1,6 @@
 {
   "name": "minimem",
-  "version": "0.0.7",
+  "version": "0.1.0",
   "description": "A lightweight file-based memory system with vector search for AI agents",
   "type": "module",
   "main": "dist/index.js",

package/scripts/bootstrap.mjs

@@ -37,11 +37,18 @@ try {
   const output = formatBootstrapContext({
     template: result.template,
     team: result.team,
+    mapEnabled: result.mapEnabled,
     mapStatus: result.mapEnabled ? result.mapStatus : null,
     sessionlogStatus: result.sessionlogEnabled ? result.sessionlogStatus : null,
     sessionlogSync: result.sessionlogSync,
-    opentasksStatus: result.opentasksEnabled ? result.opentasksStatus : null,
+    opentasksEnabled: result.opentasksEnabled,
+    opentasksStatus: result.opentasksStatus,
     inboxEnabled: result.inboxEnabled,
+    meshEnabled: result.meshEnabled,
+    minimemEnabled: result.minimemEnabled,
+    minimemStatus: result.minimemStatus,
+    skilltreeEnabled: result.skilltreeEnabled,
+    skilltreeStatus: result.skilltreeStatus,
   });
   process.stdout.write(output);
 } catch (err) {

package/scripts/map-hook.mjs

@@ -72,10 +72,14 @@ async function handleInject() {
 
   if (!config.inbox?.enabled) return;
 
-  // Read from agent-inbox IPC
+  // 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.
+  const teamName = resolveTeamName(config);
+  const mainAgentId = `${teamName}-main`;
   const scope = config.map?.scope || "default";
+
   const resp = await sendToInbox(
-    { action: "check_inbox", scope, clear: true },
+    { action: "check_inbox", agentId: mainAgentId, scope, unreadOnly: true, clear: true },
     sPaths.inboxSocketPath
   );
   if (!resp || !resp.ok || !resp.messages?.length) return;

package/scripts/map-sidecar.mjs

@@ -244,6 +244,25 @@ async function main() {
     await startWebSocketTransport();
   }
 
+  // Subscribe to inbox message.created events for outbound MAP observability
+  if (inboxInstance?.events && connection) {
+    inboxInstance.events.on("message.created", (message) => {
+      // Emit message event to MAP for external observability (Flows B, E)
+      connection.send({ scope: MAP_SCOPE }, {
+        type: "inbox.message",
+        messageId: message.id,
+        from: message.sender_id,
+        to: (message.recipients || []).map((r) => r.agent_id),
+        contentType: message.content?.type || "text",
+        threadTag: message.thread_tag,
+        importance: message.importance,
+      }, { relationship: "broadcast" }).catch(() => {
+        // Best-effort — don't block on MAP delivery
+      });
+    });
+    process.stderr.write("[sidecar] Subscribed to inbox message.created events for MAP bridge\n");
+  }
+
   // Start lifecycle UNIX socket server
   const onCommand = createCommandHandler(connection, MAP_SCOPE, registeredAgents, {
     inboxInstance,

package/scripts/team-loader.mjs

@@ -20,16 +20,11 @@ import {
 } from "../src/context-output.mjs";
 
 const argTemplate = process.argv[2] || "";
+const config = readConfig();
 
 // ── Determine template name ─────────────────────────────────────────────────
 
-let templateName = argTemplate;
-
-// Fall back to config file
-if (!templateName) {
-  const config = readConfig();
-  templateName = config.template;
-}
+let templateName = argTemplate || config.template;
 
 // If no template, show available templates
 if (!templateName) {
@@ -55,4 +50,16 @@ if (!result.success) {
 
 // ── Output context ──────────────────────────────────────────────────────────
 
-process.stdout.write(formatTeamLoadedContext(result.outputDir, result.templatePath, result.teamName));
+process.stdout.write(formatTeamLoadedContext(result.outputDir, result.templatePath, result.teamName, {
+  opentasksEnabled: config.opentasks?.enabled,
+  opentasksStatus: config.opentasks?.enabled ? "enabled" : "disabled",
+  minimemEnabled: config.minimem?.enabled,
+  minimemStatus: config.minimem?.enabled ? "ready" : "disabled",
+  skilltreeEnabled: config.skilltree?.enabled,
+  skilltreeStatus: config.skilltree?.enabled ? "ready" : "disabled",
+  inboxEnabled: config.inbox?.enabled,
+  meshEnabled: config.mesh?.enabled,
+  mapEnabled: config.map?.enabled,
+  mapStatus: config.map?.enabled ? "enabled" : "disabled",
+  sessionlogSync: config.sessionlog?.sync || "off",
+}));

package/skills/swarm/SKILL.md

@@ -102,34 +102,28 @@ When all work is complete:
 
 - **You are the only agent that can spawn teammates** — do not instruct agents to spawn other agents
 - **openteams is config-only** — used only for artifact generation, NOT for runtime coordination
-- **Use Claude Code native teams** for all runtime: `TeamCreate`, `TaskCreate`, `TaskUpdate`, `SendMessage`
 - All agents must be spawned with `team_name` so they share the team's task list
-- If MAP is enabled in `.swarm/claude-swarm/config.json`, lifecycle events are handled automatically by hooks
 - Start with the most critical roles first — you don't need to spawn all roles from the topology at once
 - Keep team size manageable (3-5 agents) — spawn more only when genuinely needed
 
-## When minimem is enabled
+## Capabilities
 
-If minimem is configured (check init context for "Memory: ready"):
-- All agents have access to **minimem MCP tools** for searching and storing memories
-- Use `minimem__memory_search` to find relevant past decisions, patterns, and context
-- Use `minimem__knowledge_search` to search with domain or entity filters
-- Memories are shared team-wide — all agents search the same memory store
-- Instruct agents to search memory before starting major work for relevant prior context
+Refer to the **Swarm Capabilities** section in the session init context for which tools and integrations are active (task management, memory, communication, observability). The capabilities context is also embedded in each spawned agent's prompt — all agents share the same understanding of available tools.
 
-## When skill-tree is enabled
+When creating tasks and coordinating agents, use the task tools described in Swarm Capabilities (opentasks MCP tools if opentasks is enabled, native TaskCreate/TaskUpdate otherwise).
 
-If skill-tree is configured (check init context for "Skills: ready"):
-- Per-role skill loadouts are compiled from the team.yaml `skilltree:` extension and embedded in agent prompts
-- Agents receive their role-appropriate skills automatically in their AGENT.md — no runtime action needed
-- Skills are cached per template alongside other artifacts
-- To update loadouts, delete the template cache directory and reload
+### When minimem is enabled
 
-## When opentasks is enabled
+If memory is active (check init context for "Memory: ready"):
+- **Before spawning agents**: Search memory for prior context on the user's goal (`minimem__memory_search`). Include relevant findings in agent prompts when spawning.
+- **After team completion**: Store key decisions and outcomes in memory files (`MEMORY.md` for decisions, `memory/<topic>.md` for topic context).
+- Tag stored memories with observation types (`<!-- type: decision -->`) and use domain tags relevant to the template (e.g., "gsd", "backend").
+- Memory is shared team-wide — all agents can search the same store during execution.
 
-If opentasks is configured (check init context for "Opentasks: connected"):
-- Use **opentasks MCP tools** instead of native `TaskCreate`/`TaskUpdate`/`TaskList`
-- `opentasks__create_task` to create tasks
-- `opentasks__update_task` to assign and update status
-- `opentasks__list_tasks` to check progress
-- Native task tools may be unavailable — opentasks provides richer task management (links, annotations, cross-provider queries)
+### When skill-tree is enabled
+
+If skills are active (check init context for "Per-Role Skills"):
+- Each spawned agent automatically receives a **skill loadout** compiled for their role, embedded in their AGENT.md.
+- Loadouts are configured via the `skilltree:` block in team.yaml, or **auto-inferred** from role names (e.g., "executor" → implementation profile, "debugger" → debugging profile).
+- You don't need to manage skills — they're baked into agent prompts at generation time.
+- Available built-in profiles: code-review, implementation, debugging, security, testing, refactoring, documentation, devops.

package/src/__tests__/agent-generator.test.mjs

@@ -145,34 +145,33 @@ describe("agent-generator", () => {
       expect(md).toContain("You execute things.");
     });
 
-    it("includes team coordination section", () => {
+    it("includes capabilities section with team context", () => {
       const md = generateAgentMd(baseOpts);
-      expect(md).toContain("## Team Coordination");
+      expect(md).toContain("## Swarm Capabilities");
       expect(md).toContain("**gsd** team");
     });
 
-    it("includes communication section", () => {
+    it("includes communication in capabilities", () => {
       const md = generateAgentMd(baseOpts);
       expect(md).toContain("### Communication");
       expect(md).toContain("SendMessage");
     });
 
-    it("includes task management section", () => {
+    it("includes task management in capabilities", () => {
       const md = generateAgentMd(baseOpts);
       expect(md).toContain("### Task Management");
       expect(md).toContain("TaskList");
     });
 
-    it("includes TaskCreate for root position", () => {
-      const md = generateAgentMd({ ...baseOpts, position: "root" });
+    it("includes TaskCreate in capabilities for all agents (general guidance)", () => {
+      const md = generateAgentMd(baseOpts);
       expect(md).toContain("TaskCreate");
     });
 
-    it("omits TaskCreate for spawned position", () => {
+    it("omits TaskCreate from frontmatter tools for spawned position", () => {
       const md = generateAgentMd(baseOpts);
-      // The task management section mentions TaskCreate for root/companion only
-      const taskSection = md.split("### Task Management")[1].split("###")[0];
-      expect(taskSection).not.toContain("TaskCreate");
+      const frontmatter = md.split("---")[1];
+      expect(frontmatter).not.toContain("TaskCreate");
     });
 
     it("includes MAP observability note", () => {

package/src/__tests__/context-output.test.mjs

@@ -20,29 +20,28 @@ describe("context-output", () => {
       expect(out).toContain("No team template configured");
     });
 
-    it("includes MAP status when mapStatus is provided", () => {
-      const out = formatBootstrapContext({ template: "t", mapStatus: "connected" });
+    it("includes MAP status when mapEnabled and mapStatus provided", () => {
+      const out = formatBootstrapContext({ template: "t", mapEnabled: true, mapStatus: "connected (scope: swarm:t)" });
       expect(out).toContain("MAP: connected");
     });
 
-    it("omits MAP line when mapStatus is null", () => {
-      const out = formatBootstrapContext({ template: "t", mapStatus: null });
-      expect(out).not.toContain("MAP:");
+    it("shows no observability when MAP is disabled", () => {
+      const out = formatBootstrapContext({ template: "t", mapEnabled: false });
+      expect(out).toContain("No external observability configured");
     });
 
-    it("shows sessionlog active with sync label", () => {
+    it("shows sessionlog sync level when MAP enabled and sync is not off", () => {
       const out = formatBootstrapContext({
-        template: "t", sessionlogStatus: "active", sessionlogSync: "full",
+        template: "t", mapEnabled: true, mapStatus: "connected", sessionlogStatus: "active", sessionlogSync: "full",
       });
-      expect(out).toContain("Sessionlog: active (MAP sync: full)");
+      expect(out).toContain("trajectory checkpoints synced to MAP (level: full)");
     });
 
-    it("shows sessionlog active without sync label when sync is off", () => {
+    it("omits sessionlog sync when sync is off", () => {
       const out = formatBootstrapContext({
-        template: "t", sessionlogStatus: "active", sessionlogSync: "off",
+        template: "t", mapEnabled: true, mapStatus: "connected", sessionlogStatus: "active", sessionlogSync: "off",
       });
-      expect(out).toContain("Sessionlog: active");
-      expect(out).not.toContain("MAP sync:");
+      expect(out).not.toContain("trajectory checkpoints");
     });
 
     it("shows sessionlog WARNING when status is not active", () => {
@@ -92,9 +91,9 @@ describe("context-output", () => {
       expect(out).toContain("/my/template");
     });
 
-    it("includes coordination section", () => {
+    it("includes capabilities section with task and communication tools", () => {
       const out = formatTeamLoadedContext(tmpDir, "/t", "test");
-      expect(out).toContain("Coordination");
+      expect(out).toContain("Swarm Capabilities");
       expect(out).toContain("TaskCreate");
       expect(out).toContain("SendMessage");
     });