opencode-swarm-plugin 0.13.2 → 0.15.0

package/examples/plugin-wrapper-template.ts

@@ -252,139 +252,7 @@ const beads_link_thread = tool({
 });
 
 // =============================================================================
-// Agent Mail Tools
-// =============================================================================
-
-const agentmail_init = tool({
-  description: "Initialize Agent Mail session",
-  args: {
-    project_path: tool.schema.string().describe("Absolute path to the project"),
-    agent_name: tool.schema.string().optional().describe("Custom agent name"),
-    task_description: tool.schema
-      .string()
-      .optional()
-      .describe("Task description"),
-  },
-  execute: (args, ctx) => execTool("agentmail_init", args, ctx),
-});
-
-const agentmail_send = tool({
-  description: "Send message to other agents",
-  args: {
-    to: tool.schema
-      .array(tool.schema.string())
-      .describe("Recipient agent names"),
-    subject: tool.schema.string().describe("Message subject"),
-    body: tool.schema.string().describe("Message body"),
-    thread_id: tool.schema
-      .string()
-      .optional()
-      .describe("Thread ID for grouping"),
-    importance: tool.schema
-      .enum(["low", "normal", "high", "urgent"])
-      .optional()
-      .describe("Message importance"),
-    ack_required: tool.schema
-      .boolean()
-      .optional()
-      .describe("Require acknowledgment"),
-  },
-  execute: (args, ctx) => execTool("agentmail_send", args, ctx),
-});
-
-const agentmail_inbox = tool({
-  description: "Fetch inbox (CONTEXT-SAFE: bodies excluded, limit 5)",
-  args: {
-    limit: tool.schema
-      .number()
-      .max(5)
-      .optional()
-      .describe("Max messages (max 5)"),
-    urgent_only: tool.schema
-      .boolean()
-      .optional()
-      .describe("Only urgent messages"),
-    since_ts: tool.schema
-      .string()
-      .optional()
-      .describe("Messages since timestamp"),
-  },
-  execute: (args, ctx) => execTool("agentmail_inbox", args, ctx),
-});
-
-const agentmail_read_message = tool({
-  description: "Fetch ONE message body by ID",
-  args: {
-    message_id: tool.schema.number().describe("Message ID"),
-  },
-  execute: (args, ctx) => execTool("agentmail_read_message", args, ctx),
-});
-
-const agentmail_summarize_thread = tool({
-  description: "Summarize thread (PREFERRED over fetching all messages)",
-  args: {
-    thread_id: tool.schema.string().describe("Thread ID"),
-    include_examples: tool.schema
-      .boolean()
-      .optional()
-      .describe("Include example messages"),
-  },
-  execute: (args, ctx) => execTool("agentmail_summarize_thread", args, ctx),
-});
-
-const agentmail_reserve = tool({
-  description: "Reserve file paths for exclusive editing",
-  args: {
-    paths: tool.schema
-      .array(tool.schema.string())
-      .describe("File paths/patterns"),
-    ttl_seconds: tool.schema.number().optional().describe("Reservation TTL"),
-    exclusive: tool.schema.boolean().optional().describe("Exclusive lock"),
-    reason: tool.schema.string().optional().describe("Reservation reason"),
-  },
-  execute: (args, ctx) => execTool("agentmail_reserve", args, ctx),
-});
-
-const agentmail_release = tool({
-  description: "Release file reservations",
-  args: {
-    paths: tool.schema
-      .array(tool.schema.string())
-      .optional()
-      .describe("Paths to release"),
-    reservation_ids: tool.schema
-      .array(tool.schema.number())
-      .optional()
-      .describe("Reservation IDs"),
-  },
-  execute: (args, ctx) => execTool("agentmail_release", args, ctx),
-});
-
-const agentmail_ack = tool({
-  description: "Acknowledge a message",
-  args: {
-    message_id: tool.schema.number().describe("Message ID"),
-  },
-  execute: (args, ctx) => execTool("agentmail_ack", args, ctx),
-});
-
-const agentmail_search = tool({
-  description: "Search messages by keyword",
-  args: {
-    query: tool.schema.string().describe("Search query"),
-    limit: tool.schema.number().optional().describe("Max results"),
-  },
-  execute: (args, ctx) => execTool("agentmail_search", args, ctx),
-});
-
-const agentmail_health = tool({
-  description: "Check if Agent Mail server is running",
-  args: {},
-  execute: (args, ctx) => execTool("agentmail_health", args, ctx),
-});
-
-// =============================================================================
-// Swarm Mail Tools (Embedded - Primary)
+// Swarm Mail Tools (Embedded)
 // =============================================================================
 
 const swarmmail_init = tool({
@@ -901,18 +769,7 @@ export const SwarmPlugin: Plugin = async (
       beads_ready,
       beads_sync,
       beads_link_thread,
-      // Agent Mail (Legacy MCP)
-      agentmail_init,
-      agentmail_send,
-      agentmail_inbox,
-      agentmail_read_message,
-      agentmail_summarize_thread,
-      agentmail_reserve,
-      agentmail_release,
-      agentmail_ack,
-      agentmail_search,
-      agentmail_health,
-      // Swarm Mail (Embedded - Primary)
+      // Swarm Mail (Embedded)
       swarmmail_init,
       swarmmail_send,
       swarmmail_inbox,

package/global-skills/swarm-coordination/SKILL.md

@@ -95,30 +95,76 @@ skills_list();
 
 Synthesize findings into `shared_context` for workers.
 
-### Phase 3: Decomposition
+### Phase 3: Decomposition (DELEGATE TO SUBAGENT)
+
+> **⚠️ CRITICAL: Context Preservation Pattern**
+>
+> **NEVER do planning inline in the coordinator thread.** Decomposition work (file reading, CASS searching, reasoning about task breakdown) consumes massive amounts of context and will exhaust your token budget on long swarms.
+>
+> **ALWAYS delegate planning to a `swarm/planner` subagent** and receive only the structured BeadTree JSON result back.
+
+**❌ Anti-Pattern (Context-Heavy):**
 
 ```typescript
-// Auto-select strategy and generate decomposition prompt
-const plan = await swarm_plan_prompt({
-  task: "Add user authentication with OAuth",
-  max_subtasks: 5,
-  query_cass: true, // searches history
-  include_skills: true, // lists relevant skills
+// DON'T DO THIS - pollutes main thread context
+const plan = await swarm_plan_prompt({ task, ... });
+// ... agent reasons about decomposition inline ...
+// ... context fills with file contents, analysis ...
+const validation = await swarm_validate_decomposition({ ... });
+```
+
+**✅ Correct Pattern (Context-Lean):**
+
+```typescript
+// 1. Create planning bead with full context
+await beads_create({
+  title: `Plan: ${taskTitle}`,
+  type: "task",
+  description: `Decompose into subtasks. Context: ${synthesizedContext}`,
 });
 
-// Agent responds with BeadTree JSON, then validate
-const validation = await swarm_validate_decomposition({
-  response: agentResponse,
+// 2. Delegate to swarm/planner subagent
+const planningResult = await Task({
+  subagent_type: "swarm/planner",
+  description: `Decompose task: ${taskTitle}`,
+  prompt: `
+You are a swarm planner. Generate a BeadTree for this task.
+
+## Task
+${taskDescription}
+
+## Synthesized Context
+${synthesizedContext}
+
+## Instructions
+1. Use swarm_plan_prompt(task="...", max_subtasks=5, query_cass=true)
+2. Reason about decomposition strategy
+3. Generate BeadTree JSON
+4. Validate with swarm_validate_decomposition
+5. Return ONLY the validated BeadTree JSON (no analysis, no file contents)
+
+Output format: Valid BeadTree JSON only.
+  `,
 });
 
-// Create epic + subtasks atomically
+// 3. Parse result (subagent already validated)
+const beadTree = JSON.parse(planningResult);
+
+// 4. Create epic + subtasks atomically
 await beads_create_epic({
-  epic_title: "Add OAuth Authentication",
-  epic_description: "...",
-  subtasks: validation.subtasks,
+  epic_title: beadTree.epic.title,
+  epic_description: beadTree.epic.description,
+  subtasks: beadTree.subtasks,
 });
 ```
 
+**Why This Matters:**
+
+- **Main thread context stays clean** - only receives final JSON, not reasoning
+- **Subagent context is disposable** - gets garbage collected after planning
+- **Scales to long swarms** - coordinator can manage 10+ workers without exhaustion
+- **Faster coordination** - less context = faster responses when monitoring workers
+
 ### Phase 4: Reserve Files (via Swarm Mail)
 
 ```typescript
@@ -263,12 +309,16 @@ One blocker affects multiple subtasks.
 
 ## Anti-Patterns
 
-| Anti-Pattern         | Symptom                          | Fix                           |
-| -------------------- | -------------------------------- | ----------------------------- |
-| **Mega-Coordinator** | Coordinator editing files        | Coordinator only orchestrates |
-| **Silent Swarm**     | No communication, late conflicts | Require updates, check inbox  |
-| **Over-Decomposed**  | 10 subtasks for 20 lines         | 2-5 subtasks max              |
-| **Under-Specified**  | "Implement backend"              | Clear goal, files, criteria   |
+| Anti-Pattern             | Symptom                                    | Fix                                  |
+| ------------------------ | ------------------------------------------ | ------------------------------------ |
+| **Mega-Coordinator**     | Coordinator editing files                  | Coordinator only orchestrates        |
+| **Silent Swarm**         | No communication, late conflicts           | Require updates, check inbox         |
+| **Over-Decomposed**      | 10 subtasks for 20 lines                   | 2-5 subtasks max                     |
+| **Under-Specified**      | "Implement backend"                        | Clear goal, files, criteria          |
+| **Inline Planning** ⚠️   | Context pollution, exhaustion on long runs | Delegate planning to subagent        |
+| **Heavy File Reading**   | Coordinator reading 10+ files              | Subagent reads, returns summary only |
+| **Deep CASS Drilling**   | Multiple cass_search calls inline          | Subagent searches, summarizes        |
+| **Manual Decomposition** | Hand-crafting subtasks without validation  | Use swarm_plan_prompt + validation   |
 
 ## Shared Context Template
 

package/global-skills/swarm-coordination/references/coordinator-patterns.md

@@ -49,7 +49,7 @@ For each subtask:
 ### 4. Progress Monitoring
 
 - Check `beads_query(status="in_progress")` for active work
-- Check `agentmail_inbox()` for worker messages
+- Check `swarmmail_inbox()` for worker messages
 - Intervene on blockers (see Intervention Patterns below)
 
 ### 5. Completion & Aggregation

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "opencode-swarm-plugin",
-  "version": "0.13.2",
+  "version": "0.15.0",
   "description": "Multi-agent swarm coordination for OpenCode with learning capabilities, beads integration, and Agent Mail",
   "type": "module",
   "main": "dist/index.js",

package/src/index.ts

@@ -135,7 +135,6 @@ export const SwarmPlugin: Plugin = async (
      */
     tool: {
       ...beadsTools,
-      ...agentMailTools,
       ...swarmMailTools,
       ...structuredTools,
       ...swarmTools,
@@ -357,7 +356,6 @@ export {
  */
 export const allTools = {
   ...beadsTools,
-  ...agentMailTools,
   ...swarmMailTools,
   ...structuredTools,
   ...swarmTools,

package/src/learning.integration.test.ts

@@ -1427,3 +1427,313 @@ describe("Storage Module", () => {
     });
   });
 });
+
+// ============================================================================
+// 3-Strike Detection Tests
+// ============================================================================
+
+import {
+  InMemoryStrikeStorage,
+  addStrike,
+  getStrikes,
+  isStrikedOut,
+  getArchitecturePrompt,
+  clearStrikes,
+  type StrikeStorage,
+} from "./learning";
+
+describe("3-Strike Detection", () => {
+  let storage: StrikeStorage;
+
+  beforeEach(() => {
+    storage = new InMemoryStrikeStorage();
+  });
+
+  describe("addStrike", () => {
+    it("records first strike", async () => {
+      const record = await addStrike(
+        "test-bead-1",
+        "Attempted null check fix",
+        "Still getting undefined errors",
+        storage,
+      );
+
+      expect(record.bead_id).toBe("test-bead-1");
+      expect(record.strike_count).toBe(1);
+      expect(record.failures).toHaveLength(1);
+      expect(record.failures[0].attempt).toBe("Attempted null check fix");
+      expect(record.failures[0].reason).toBe("Still getting undefined errors");
+      expect(record.first_strike_at).toBeDefined();
+      expect(record.last_strike_at).toBeDefined();
+    });
+
+    it("increments strike count on subsequent strikes", async () => {
+      await addStrike("test-bead-2", "Fix 1", "Failed 1", storage);
+      const record2 = await addStrike(
+        "test-bead-2",
+        "Fix 2",
+        "Failed 2",
+        storage,
+      );
+
+      expect(record2.strike_count).toBe(2);
+      expect(record2.failures).toHaveLength(2);
+    });
+
+    it("caps strike count at 3", async () => {
+      await addStrike("test-bead-3", "Fix 1", "Failed 1", storage);
+      await addStrike("test-bead-3", "Fix 2", "Failed 2", storage);
+      await addStrike("test-bead-3", "Fix 3", "Failed 3", storage);
+      const record4 = await addStrike(
+        "test-bead-3",
+        "Fix 4",
+        "Failed 4",
+        storage,
+      );
+
+      expect(record4.strike_count).toBe(3);
+      expect(record4.failures).toHaveLength(4); // Records all attempts
+    });
+
+    it("preserves first_strike_at timestamp", async () => {
+      const record1 = await addStrike(
+        "test-bead-4",
+        "Fix 1",
+        "Failed 1",
+        storage,
+      );
+      await new Promise((resolve) => setTimeout(resolve, 100));
+      const record2 = await addStrike(
+        "test-bead-4",
+        "Fix 2",
+        "Failed 2",
+        storage,
+      );
+
+      expect(record2.first_strike_at).toBe(record1.first_strike_at);
+      expect(record2.last_strike_at).not.toBe(record1.last_strike_at);
+    });
+  });
+
+  describe("getStrikes", () => {
+    it("returns 0 for bead with no strikes", async () => {
+      const count = await getStrikes("no-strikes-bead", storage);
+      expect(count).toBe(0);
+    });
+
+    it("returns correct strike count", async () => {
+      await addStrike("bead-with-strikes", "Fix 1", "Failed 1", storage);
+      await addStrike("bead-with-strikes", "Fix 2", "Failed 2", storage);
+
+      const count = await getStrikes("bead-with-strikes", storage);
+      expect(count).toBe(2);
+    });
+  });
+
+  describe("isStrikedOut", () => {
+    it("returns false for bead with < 3 strikes", async () => {
+      await addStrike("bead-safe", "Fix 1", "Failed 1", storage);
+      await addStrike("bead-safe", "Fix 2", "Failed 2", storage);
+
+      const strikedOut = await isStrikedOut("bead-safe", storage);
+      expect(strikedOut).toBe(false);
+    });
+
+    it("returns true for bead with 3 strikes", async () => {
+      await addStrike("bead-danger", "Fix 1", "Failed 1", storage);
+      await addStrike("bead-danger", "Fix 2", "Failed 2", storage);
+      await addStrike("bead-danger", "Fix 3", "Failed 3", storage);
+
+      const strikedOut = await isStrikedOut("bead-danger", storage);
+      expect(strikedOut).toBe(true);
+    });
+
+    it("returns false for bead with no strikes", async () => {
+      const strikedOut = await isStrikedOut("no-record", storage);
+      expect(strikedOut).toBe(false);
+    });
+  });
+
+  describe("getArchitecturePrompt", () => {
+    it("returns empty string for bead with < 3 strikes", async () => {
+      await addStrike("bead-prompt-1", "Fix 1", "Failed 1", storage);
+
+      const prompt = await getArchitecturePrompt("bead-prompt-1", storage);
+      expect(prompt).toBe("");
+    });
+
+    it("returns empty string for bead with no strikes", async () => {
+      const prompt = await getArchitecturePrompt("no-strikes", storage);
+      expect(prompt).toBe("");
+    });
+
+    it("generates architecture review prompt for struck out bead", async () => {
+      await addStrike(
+        "bead-prompt-2",
+        "Added null checks",
+        "Still crashes on undefined",
+        storage,
+      );
+      await addStrike(
+        "bead-prompt-2",
+        "Used optional chaining",
+        "Runtime error persists",
+        storage,
+      );
+      await addStrike(
+        "bead-prompt-2",
+        "Wrapped in try-catch",
+        "Error still happening",
+        storage,
+      );
+
+      const prompt = await getArchitecturePrompt("bead-prompt-2", storage);
+
+      expect(prompt).toContain("Architecture Review Required");
+      expect(prompt).toContain("bead-prompt-2");
+      expect(prompt).toContain("Added null checks");
+      expect(prompt).toContain("Still crashes on undefined");
+      expect(prompt).toContain("Used optional chaining");
+      expect(prompt).toContain("Runtime error persists");
+      expect(prompt).toContain("Wrapped in try-catch");
+      expect(prompt).toContain("Error still happening");
+      expect(prompt).toContain("architectural problem");
+      expect(prompt).toContain("DO NOT attempt Fix #4");
+      expect(prompt).toContain("Refactor architecture");
+      expect(prompt).toContain("Continue with Fix #4");
+      expect(prompt).toContain("Abandon this approach");
+    });
+
+    it("lists all failures in order", async () => {
+      await addStrike(
+        "bead-prompt-3",
+        "First attempt",
+        "First failure",
+        storage,
+      );
+      await addStrike(
+        "bead-prompt-3",
+        "Second attempt",
+        "Second failure",
+        storage,
+      );
+      await addStrike(
+        "bead-prompt-3",
+        "Third attempt",
+        "Third failure",
+        storage,
+      );
+
+      const prompt = await getArchitecturePrompt("bead-prompt-3", storage);
+
+      const lines = prompt.split("\n");
+      const failureLine1 = lines.find((l) => l.includes("First attempt"));
+      const failureLine2 = lines.find((l) => l.includes("Second attempt"));
+      const failureLine3 = lines.find((l) => l.includes("Third attempt"));
+
+      expect(failureLine1).toBeDefined();
+      expect(failureLine2).toBeDefined();
+      expect(failureLine3).toBeDefined();
+
+      // Check ordering
+      const idx1 = lines.indexOf(failureLine1!);
+      const idx2 = lines.indexOf(failureLine2!);
+      const idx3 = lines.indexOf(failureLine3!);
+
+      expect(idx1).toBeLessThan(idx2);
+      expect(idx2).toBeLessThan(idx3);
+    });
+  });
+
+  describe("clearStrikes", () => {
+    it("clears strikes for a bead", async () => {
+      await addStrike("bead-clear", "Fix 1", "Failed 1", storage);
+      await addStrike("bead-clear", "Fix 2", "Failed 2", storage);
+
+      expect(await getStrikes("bead-clear", storage)).toBe(2);
+
+      await clearStrikes("bead-clear", storage);
+
+      expect(await getStrikes("bead-clear", storage)).toBe(0);
+      expect(await isStrikedOut("bead-clear", storage)).toBe(false);
+    });
+
+    it("handles clearing non-existent bead gracefully", async () => {
+      await expect(clearStrikes("no-bead", storage)).resolves.toBeUndefined();
+    });
+  });
+
+  describe("InMemoryStrikeStorage", () => {
+    it("stores and retrieves strike records", async () => {
+      const storage = new InMemoryStrikeStorage();
+      const record = await addStrike("bead-1", "Fix", "Failed", storage);
+
+      const retrieved = await storage.get("bead-1");
+      expect(retrieved).not.toBeNull();
+      expect(retrieved!.bead_id).toBe("bead-1");
+      expect(retrieved!.strike_count).toBe(1);
+    });
+
+    it("returns null for non-existent bead", async () => {
+      const storage = new InMemoryStrikeStorage();
+      const retrieved = await storage.get("non-existent");
+      expect(retrieved).toBeNull();
+    });
+
+    it("lists all strike records", async () => {
+      const storage = new InMemoryStrikeStorage();
+      await addStrike("bead-1", "Fix", "Failed", storage);
+      await addStrike("bead-2", "Fix", "Failed", storage);
+
+      const all = await storage.getAll();
+      expect(all).toHaveLength(2);
+    });
+
+    it("clears specific bead strikes", async () => {
+      const storage = new InMemoryStrikeStorage();
+      await addStrike("bead-1", "Fix", "Failed", storage);
+      await addStrike("bead-2", "Fix", "Failed", storage);
+
+      await storage.clear("bead-1");
+
+      expect(await storage.get("bead-1")).toBeNull();
+      expect(await storage.get("bead-2")).not.toBeNull();
+    });
+  });
+
+  describe("3-Strike Rule Integration", () => {
+    it("follows complete workflow from no strikes to architecture review", async () => {
+      const beadId = "integration-bead";
+
+      // Start: No strikes
+      expect(await getStrikes(beadId, storage)).toBe(0);
+      expect(await isStrikedOut(beadId, storage)).toBe(false);
+      expect(await getArchitecturePrompt(beadId, storage)).toBe("");
+
+      // Strike 1
+      await addStrike(beadId, "Tried approach A", "Didn't work", storage);
+      expect(await getStrikes(beadId, storage)).toBe(1);
+      expect(await isStrikedOut(beadId, storage)).toBe(false);
+
+      // Strike 2
+      await addStrike(beadId, "Tried approach B", "Also failed", storage);
+      expect(await getStrikes(beadId, storage)).toBe(2);
+      expect(await isStrikedOut(beadId, storage)).toBe(false);
+
+      // Strike 3 - STRUCK OUT
+      await addStrike(beadId, "Tried approach C", "Still broken", storage);
+      expect(await getStrikes(beadId, storage)).toBe(3);
+      expect(await isStrikedOut(beadId, storage)).toBe(true);
+
+      // Architecture prompt should now be available
+      const prompt = await getArchitecturePrompt(beadId, storage);
+      expect(prompt).not.toBe("");
+      expect(prompt).toContain("Architecture Review Required");
+
+      // Clear strikes (e.g., after human intervention)
+      await clearStrikes(beadId, storage);
+      expect(await getStrikes(beadId, storage)).toBe(0);
+      expect(await isStrikedOut(beadId, storage)).toBe(false);
+    });
+  });
+});