opencode-swarm-plugin 0.12.31 → 0.13.1

package/src/swarm.integration.test.ts

@@ -1315,24 +1315,29 @@ describe("Swarm Prompt V2 (with Agent Mail/Beads)", () => {
   describe("SUBTASK_PROMPT_V2", () => {
     it("contains expected sections", () => {
       // Check all main sections are present in the template
-      expect(SUBTASK_PROMPT_V2).toContain("## Task");
+      expect(SUBTASK_PROMPT_V2).toContain("[TASK]");
       expect(SUBTASK_PROMPT_V2).toContain("{subtask_title}");
       expect(SUBTASK_PROMPT_V2).toContain("{subtask_description}");
 
-      expect(SUBTASK_PROMPT_V2).toContain("## Files");
+      expect(SUBTASK_PROMPT_V2).toContain("[FILES]");
       expect(SUBTASK_PROMPT_V2).toContain("{file_list}");
 
-      expect(SUBTASK_PROMPT_V2).toContain("## Context");
+      expect(SUBTASK_PROMPT_V2).toContain("[CONTEXT]");
       expect(SUBTASK_PROMPT_V2).toContain("{shared_context}");
 
-      expect(SUBTASK_PROMPT_V2).toContain("## Workflow");
+      expect(SUBTASK_PROMPT_V2).toContain("[WORKFLOW]");
     });
 
-    it("DOES contain Agent Mail instructions", () => {
-      // V2 prompt tells agents to USE Agent Mail
-      expect(SUBTASK_PROMPT_V2).toContain("Agent Mail");
-      expect(SUBTASK_PROMPT_V2).toContain("agentmail_send");
+    it("DOES contain Swarm Mail instructions (MANDATORY)", () => {
+      // V2 prompt tells agents to USE Swarm Mail - this is non-negotiable
+      expect(SUBTASK_PROMPT_V2).toContain("SWARM MAIL");
+      expect(SUBTASK_PROMPT_V2).toContain("swarmmail_init");
+      expect(SUBTASK_PROMPT_V2).toContain("swarmmail_send");
+      expect(SUBTASK_PROMPT_V2).toContain("swarmmail_inbox");
+      expect(SUBTASK_PROMPT_V2).toContain("swarmmail_reserve");
+      expect(SUBTASK_PROMPT_V2).toContain("swarmmail_release");
       expect(SUBTASK_PROMPT_V2).toContain("thread_id");
+      expect(SUBTASK_PROMPT_V2).toContain("non-negotiable");
     });
 
     it("DOES contain beads instructions", () => {
@@ -1344,10 +1349,11 @@ describe("Swarm Prompt V2 (with Agent Mail/Beads)", () => {
       expect(SUBTASK_PROMPT_V2).toContain("swarm_complete");
     });
 
-    it("instructs agents to communicate", () => {
+    it("instructs agents to communicate via swarmmail", () => {
       expect(SUBTASK_PROMPT_V2).toContain("Never work silently");
-      expect(SUBTASK_PROMPT_V2).toContain("Report progress");
+      expect(SUBTASK_PROMPT_V2).toContain("progress");
       expect(SUBTASK_PROMPT_V2).toContain("coordinator");
+      expect(SUBTASK_PROMPT_V2).toContain("CRITICAL");
     });
   });
 });

package/src/swarm.ts

@@ -25,7 +25,12 @@ import {
   type SpawnedAgent,
   type Bead,
 } from "./schemas";
-import { mcpCall, mcpCallWithAutoInit, requireState } from "./agent-mail";
+import {
+  sendSwarmMessage,
+  getSwarmInbox,
+  readSwarmMessage,
+  releaseSwarmFiles,
+} from "./streams/swarm-mail";
 import {
   OutcomeSignalsSchema,
   DecompositionStrategySchema,
@@ -704,21 +709,64 @@ Only modify these files. Need others? Message the coordinator.
 
 {error_context}
 
-## [TOOLS]
-### Beads
-- beads_update (status: blocked)
-- beads_create (new bugs)
-- beads_close (via swarm_complete)
+## [MANDATORY: SWARM MAIL]
+
+**YOU MUST USE SWARM MAIL FOR ALL COORDINATION.** This is non-negotiable.
+
+### Initialize FIRST (before any work)
+\`\`\`
+swarmmail_init(project_path="$PWD", task_description="{subtask_title}")
+\`\`\`
+
+### Reserve Files (if not already reserved by coordinator)
+\`\`\`
+swarmmail_reserve(paths=[...files...], reason="{bead_id}: {subtask_title}")
+\`\`\`
+
+### Check Inbox Regularly
+\`\`\`
+swarmmail_inbox()  # Check for coordinator messages
+swarmmail_read_message(message_id=N)  # Read specific message
+\`\`\`
+
+### Report Progress (REQUIRED - don't work silently)
+\`\`\`
+swarmmail_send(
+  to=["coordinator"],
+  subject="Progress: {bead_id}",
+  body="<what you did, blockers, questions>",
+  thread_id="{epic_id}"
+)
+\`\`\`
+
+### When Blocked
+\`\`\`
+swarmmail_send(
+  to=["coordinator"],
+  subject="BLOCKED: {bead_id}",
+  body="<blocker description, what you need>",
+  importance="high",
+  thread_id="{epic_id}"
+)
+beads_update(id="{bead_id}", status="blocked")
+\`\`\`
+
+### Release Files When Done
+\`\`\`
+swarmmail_release()  # Or let swarm_complete handle it
+\`\`\`
 
-### Agent Mail
-- agentmail_send (thread_id: {epic_id})
+## [OTHER TOOLS]
+### Beads
+- beads_update(id, status) - Mark blocked if stuck
+- beads_create(title, type) - Log new bugs found
 
 ### Skills (if available)
-- skills_list (discover available skills)
-- skills_use (activate a skill for specialized guidance)
+- skills_list() - Discover available skills
+- skills_use(name) - Activate skill for specialized guidance
 
-### Completion
-- swarm_complete (REQUIRED when done)
+### Completion (REQUIRED)
+- swarm_complete(project_key, agent_name, bead_id, summary, files_touched)
 
 ## [LEARNING]
 As you work, note reusable patterns, best practices, or domain insights:
@@ -727,15 +775,15 @@ As you work, note reusable patterns, best practices, or domain insights:
 - Good skills have clear "when to use" descriptions with actionable instructions
 - Skills make swarms smarter over time
 
-## [OUTPUT]
-1. Read files first
-2. Implement changes
-3. Verify (typecheck)
-4. Complete with swarm_complete
+## [WORKFLOW]
+1. **swarmmail_init** - Initialize session FIRST
+2. Read assigned files
+3. Implement changes
+4. **swarmmail_send** - Report progress to coordinator
+5. Verify (typecheck)
+6. **swarm_complete** - Mark done, release reservations
 
-Return: Summary of changes made. Note any patterns worth preserving as skills.
-
-**Never work silently.** Communicate progress and blockers immediately.
+**CRITICAL: Never work silently. Send progress updates via swarmmail_send every significant milestone.**
 
 Begin now.`;
 
@@ -959,15 +1007,19 @@ async function querySwarmMessages(
   }
 
   try {
-    interface ThreadSummary {
-      summary: { total_messages: number };
-    }
-    const summary = await mcpCall<ThreadSummary>("summarize_thread", {
-      project_key: projectKey,
-      thread_id: threadId,
-      llm_mode: false, // Just need the count
+    // Use embedded swarm-mail inbox to count messages in thread
+    const inbox = await getSwarmInbox({
+      projectPath: projectKey,
+      agentName: "coordinator", // Dummy agent name for thread query
+      limit: 5,
+      includeBodies: false,
     });
-    return summary.summary.total_messages;
+
+    // Count messages that match the thread ID
+    const threadMessages = inbox.messages.filter(
+      (m) => m.thread_id === threadId,
+    );
+    return threadMessages.length;
   } catch (error) {
     // Thread might not exist yet, or query failed
     console.warn(
@@ -1312,9 +1364,10 @@ export const swarm_plan_prompt = tool({
 
     // Fetch skills context
     let skillsContext = "";
-    let skillsInfo: { included: boolean; count?: number; relevant?: string[] } = {
-      included: false,
-    };
+    let skillsInfo: { included: boolean; count?: number; relevant?: string[] } =
+      {
+        included: false,
+      };
 
     if (args.include_skills !== false) {
       const allSkills = await listSkills();
@@ -1769,15 +1822,14 @@ export const swarm_progress = tool({
       ? args.bead_id.split(".")[0]
       : args.bead_id;
 
-    // Send progress message to thread (with auto-reinit on server restart)
-    await mcpCallWithAutoInit("send_message", {
-      project_key: args.project_key,
-      agent_name: args.agent_name,
-      sender_name: args.agent_name,
-      to: [], // Coordinator will pick it up from thread
+    // Send progress message to thread using embedded swarm-mail
+    await sendSwarmMessage({
+      projectPath: args.project_key,
+      fromAgent: args.agent_name,
+      toAgents: [], // Coordinator will pick it up from thread
       subject: `Progress: ${args.bead_id} - ${args.status}`,
-      body_md: formatProgressMessage(validated),
-      thread_id: epicId,
+      body: formatProgressMessage(validated),
+      threadId: epicId,
       importance: args.status === "blocked" ? "high" : "normal",
     });
 
@@ -1895,6 +1947,12 @@ export const swarm_broadcast = tool({
   description:
     "Broadcast context update to all agents working on the same epic",
   args: {
+    project_path: tool.schema
+      .string()
+      .describe("Absolute path to project root"),
+    agent_name: tool.schema
+      .string()
+      .describe("Name of the agent broadcasting the message"),
     epic_id: tool.schema.string().describe("Epic ID (e.g., bd-abc123)"),
     message: tool.schema
       .string()
@@ -1909,18 +1967,14 @@ export const swarm_broadcast = tool({
       .describe("Files this context relates to"),
   },
   async execute(args, ctx) {
-    // Get agent state - requires prior initialization
-    const state = requireState(ctx.sessionID);
-
     // Extract bead_id from context if available (for traceability)
-    // In the swarm flow, ctx might have the current bead being worked on
     const beadId = (ctx as { beadId?: string }).beadId || "unknown";
 
     // Format the broadcast message
     const body = [
       `## Context Update`,
       "",
-      `**From**: ${state.agentName} (${beadId})`,
+      `**From**: ${args.agent_name} (${beadId})`,
       `**Priority**: ${args.importance.toUpperCase()}`,
       "",
       args.message,
@@ -1940,25 +1994,23 @@ export const swarm_broadcast = tool({
           ? "high"
           : "normal";
 
-    // Send as broadcast to thread (empty 'to' = all agents in thread)
-    // Uses auto-reinit wrapper to handle server restarts gracefully
-    await mcpCallWithAutoInit("send_message", {
-      project_key: state.projectKey,
-      agent_name: state.agentName,
-      sender_name: state.agentName,
-      to: [], // Broadcast to thread
-      subject: `[${args.importance.toUpperCase()}] Context update from ${state.agentName}`,
-      body_md: body,
-      thread_id: args.epic_id,
+    // Send as broadcast to thread using embedded swarm-mail
+    await sendSwarmMessage({
+      projectPath: args.project_path,
+      fromAgent: args.agent_name,
+      toAgents: [], // Broadcast to thread
+      subject: `[${args.importance.toUpperCase()}] Context update from ${args.agent_name}`,
+      body,
+      threadId: args.epic_id,
       importance: mailImportance,
-      ack_required: args.importance === "blocker", // Require ack for blockers
+      ackRequired: args.importance === "blocker",
     });
 
     return JSON.stringify(
       {
         broadcast: true,
         epic_id: args.epic_id,
-        from: state.agentName,
+        from: args.agent_name,
         bead_id: beadId,
         importance: args.importance,
         recipients: "all agents in epic",
@@ -2070,16 +2122,15 @@ export const swarm_complete = tool({
       );
     }
 
-    // Release file reservations for this agent
-    // Uses auto-reinit wrapper to handle server restarts - this was the original
-    // failure point that prompted the self-healing implementation
+    // Release file reservations for this agent using embedded swarm-mail
     try {
-      await mcpCallWithAutoInit("release_file_reservations", {
-        project_key: args.project_key,
-        agent_name: args.agent_name,
+      await releaseSwarmFiles({
+        projectPath: args.project_key,
+        agentName: args.agent_name,
+        // Release all reservations for this agent
       });
     } catch (error) {
-      // Even with auto-reinit, release might fail (e.g., no reservations existed)
+      // Release might fail (e.g., no reservations existed)
       // This is non-fatal - log and continue
       console.warn(
         `[swarm] Failed to release file reservations for ${args.agent_name}:`,
@@ -2092,7 +2143,7 @@ export const swarm_complete = tool({
       ? args.bead_id.split(".")[0]
       : args.bead_id;
 
-    // Send completion message
+    // Send completion message using embedded swarm-mail
     const completionBody = [
       `## Subtask Complete: ${args.bead_id}`,
       "",
@@ -2108,14 +2159,13 @@ export const swarm_complete = tool({
       .filter(Boolean)
       .join("\n");
 
-    await mcpCallWithAutoInit("send_message", {
-      project_key: args.project_key,
-      agent_name: args.agent_name,
-      sender_name: args.agent_name,
-      to: [], // Thread broadcast
+    await sendSwarmMessage({
+      projectPath: args.project_key,
+      fromAgent: args.agent_name,
+      toAgents: [], // Thread broadcast
       subject: `Complete: ${args.bead_id}`,
-      body_md: completionBody,
-      thread_id: epicId,
+      body: completionBody,
+      threadId: epicId,
       importance: "normal",
     });
 
@@ -2650,7 +2700,14 @@ This tool helps you formalize learnings into a skill that future agents can disc
       .string()
       .describe("Brief summary of what was learned (1-2 sentences)"),
     pattern_type: tool.schema
-      .enum(["code-pattern", "best-practice", "gotcha", "tool-usage", "domain-knowledge", "workflow"])
+      .enum([
+        "code-pattern",
+        "best-practice",
+        "gotcha",
+        "tool-usage",
+        "domain-knowledge",
+        "workflow",
+      ])
       .describe("Category of the learning"),
     details: tool.schema
       .string()
@@ -2669,7 +2726,9 @@ This tool helps you formalize learnings into a skill that future agents can disc
     create_skill: tool.schema
       .boolean()
       .optional()
-      .describe("Create a skill from this learning (default: false, just document)"),
+      .describe(
+        "Create a skill from this learning (default: false, just document)",
+      ),
     skill_name: tool.schema
       .string()
       .regex(/^[a-z0-9-]+$/)
@@ -2737,7 +2796,8 @@ ${args.files_context && args.files_context.length > 0 ? `## Reference Files\n\n$
             error: `Skill '${args.skill_name}' already exists`,
             existing_path: existing.path,
             learning: learning,
-            suggestion: "Use skills_update to add to existing skill, or choose a different name",
+            suggestion:
+              "Use skills_update to add to existing skill, or choose a different name",
           },
           null,
           2,
@@ -2745,7 +2805,12 @@ ${args.files_context && args.files_context.length > 0 ? `## Reference Files\n\n$
       }
 
       // Create skill directory and file
-      const skillDir = join(process.cwd(), ".opencode", "skills", args.skill_name);
+      const skillDir = join(
+        process.cwd(),
+        ".opencode",
+        "skills",
+        args.skill_name,
+      );
       const skillPath = join(skillDir, "SKILL.md");
 
       const frontmatter = [
@@ -2798,8 +2863,10 @@ ${args.files_context && args.files_context.length > 0 ? `## Reference Files\n\n$
         success: true,
         skill_created: false,
         learning: learning,
-        message: "Learning documented. Use create_skill=true to persist as a skill for future agents.",
-        suggested_skill_name: args.skill_name ||
+        message:
+          "Learning documented. Use create_skill=true to persist as a skill for future agents.",
+        suggested_skill_name:
+          args.skill_name ||
           args.summary
             .toLowerCase()
             .replace(/[^a-z0-9\s-]/g, "")
@@ -3029,7 +3096,8 @@ export const swarm_init = tool({
     if (availableSkills.length > 0) {
       skillsGuidance = `Found ${availableSkills.length} skill(s). Use skills_list to see details, skills_use to activate.`;
     } else {
-      skillsGuidance = "No skills found. Add skills to .opencode/skills/ or .claude/skills/ for specialized guidance.";
+      skillsGuidance =
+        "No skills found. Add skills to .opencode/skills/ or .claude/skills/ for specialized guidance.";
     }
 
     return JSON.stringify(

package/src/tool-availability.ts

@@ -9,14 +9,18 @@
  * - cass: Cross-agent session search for historical context
  * - ubs: Universal bug scanner for pre-commit checks
  * - beads (bd): Git-backed issue tracking
- * - agent-mail: Multi-agent coordination server
+ * - swarm-mail: Embedded multi-agent coordination (PGLite-based)
+ * - agent-mail: DEPRECATED - Legacy MCP server (use swarm-mail instead)
  */
 
+import { checkSwarmHealth } from "./streams/swarm-mail";
+
 export type ToolName =
   | "semantic-memory"
   | "cass"
   | "ubs"
   | "beads"
+  | "swarm-mail"
   | "agent-mail";
 
 export interface ToolStatus {
@@ -199,6 +203,32 @@ const toolCheckers: Record<ToolName, () => Promise<ToolStatus>> = {
     }
   },
 
+  "swarm-mail": async () => {
+    try {
+      // Note: checkSwarmHealth() accepts optional projectPath parameter.
+      // For tool availability checking, we call it without args to check global health.
+      // This is intentional - we're verifying the embedded Swarm Mail system is functional,
+      // not checking health for a specific project.
+      const healthResult = await checkSwarmHealth();
+      return {
+        available: healthResult.healthy,
+        checkedAt: new Date().toISOString(),
+        error: healthResult.healthy
+          ? undefined
+          : "Swarm Mail database not healthy",
+        version: "embedded",
+      };
+    } catch (e) {
+      return {
+        available: false,
+        checkedAt: new Date().toISOString(),
+        error: String(e),
+      };
+    }
+  },
+
+  // DEPRECATED: Use swarm-mail instead
+  // Kept for backward compatibility only
   "agent-mail": async () => {
     const reachable = await urlReachable(
       "http://127.0.0.1:8765/health/liveness",
@@ -220,8 +250,10 @@ const fallbackBehaviors: Record<ToolName, string> = {
   cass: "Decomposition proceeds without historical context from past sessions",
   ubs: "Subtask completion skips bug scanning - manual review recommended",
   beads: "Swarm cannot track issues - task coordination will be less reliable",
-  "agent-mail":
+  "swarm-mail":
     "Multi-agent coordination disabled - file conflicts possible if multiple agents active",
+  "agent-mail":
+    "DEPRECATED: Use swarm-mail instead. Legacy MCP server mode - file conflicts possible if multiple agents active",
 };
 
 /**
@@ -276,6 +308,7 @@ export async function checkAllTools(): Promise<
     "cass",
     "ubs",
     "beads",
+    "swarm-mail",
     "agent-mail",
   ];