opencode-swarm-plugin 0.12.7 → 0.12.9

package/.beads/issues.jsonl

@@ -305,6 +305,7 @@
 {"id":"opencode-swarm-plugin-5ukv1","title":"Bead to start","description":"","status":"closed","priority":2,"issue_type":"task","created_at":"2025-12-10T09:06:07.140527-08:00","updated_at":"2025-12-10T09:06:10.259329-08:00","closed_at":"2025-12-10T09:06:10.259329-08:00"}
 {"id":"opencode-swarm-plugin-5uvt","title":"Limit test bead 3","description":"","status":"closed","priority":2,"issue_type":"task","created_at":"2025-12-08T07:46:49.108567-08:00","updated_at":"2025-12-08T07:46:51.736011-08:00","closed_at":"2025-12-08T07:46:51.736011-08:00"}
 {"id":"opencode-swarm-plugin-5x8v","title":"Bead to start","description":"","status":"closed","priority":2,"issue_type":"task","created_at":"2025-12-08T11:10:53.928154-08:00","updated_at":"2025-12-08T11:10:56.008815-08:00","closed_at":"2025-12-08T11:10:56.008815-08:00"}
+{"id":"opencode-swarm-plugin-5xy17","title":"Swarm should support research task decomposition with pdf-brain","description":"Currently swarm coordinator treats \"research\" tasks as single-agent work. Should decompose research into parallel agents that:\n\n1. Search different sources (pdf-brain, repo-crawl, cass, web)\n2. Focus on different aspects of the question\n3. Synthesize findings into coherent answer\n\nExample decomposition for \"debug levers for agent mail\":\n- Agent 1: Search pdf-brain for \"agent debugging\", \"MCP server configuration\"\n- Agent 2: Crawl the repo README, .env.example, config.py\n- Agent 3: Search cass for past sessions dealing with agent-mail errors\n- Agent 4: Synthesize findings from other agents\n\nStrategy selection should recognize research keywords:\n- research, investigate, explore, find, discover, understand, learn, analyze\n\nTool availability check:\n- If pdf-brain available, include PDF search subtask\n- If repo-crawl available, include repo exploration subtask\n- If cass available, include history search subtask\n\nFiles: src/swarm.ts (add research strategy), src/tool-availability.ts","status":"closed","priority":1,"issue_type":"feature","created_at":"2025-12-10T10:59:41.26917-08:00","updated_at":"2025-12-10T11:01:35.90704-08:00","closed_at":"2025-12-10T11:01:35.90704-08:00"}
 {"id":"opencode-swarm-plugin-5ztv","title":"New feature request","description":"","status":"closed","priority":1,"issue_type":"feature","created_at":"2025-12-08T11:12:40.764593-08:00","updated_at":"2025-12-08T11:12:43.52524-08:00","closed_at":"2025-12-08T11:12:43.52524-08:00"}
 {"id":"opencode-swarm-plugin-61t","title":"Single subtask epic","description":"","status":"closed","priority":1,"issue_type":"epic","created_at":"2025-12-07T19:36:07.443401-08:00","updated_at":"2025-12-07T19:36:09.031886-08:00","closed_at":"2025-12-07T19:36:09.031886-08:00"}
 {"id":"opencode-swarm-plugin-62da","title":"Update test bead","description":"Updated description","status":"closed","priority":2,"issue_type":"task","created_at":"2025-12-08T11:11:38.733772-08:00","updated_at":"2025-12-08T11:11:41.037318-08:00","closed_at":"2025-12-08T11:11:41.037318-08:00"}
@@ -947,6 +948,7 @@
 {"id":"opencode-swarm-plugin-jbdj","title":"Thread link test bead","description":"[thread:test-thread-456]","status":"closed","priority":2,"issue_type":"task","created_at":"2025-12-08T11:10:54.731569-08:00","updated_at":"2025-12-08T11:10:56.43993-08:00","closed_at":"2025-12-08T11:10:56.43993-08:00"}
 {"id":"opencode-swarm-plugin-jc9y","title":"Query test bead","description":"","status":"closed","priority":2,"issue_type":"task","created_at":"2025-12-07T19:39:29.328372-08:00","updated_at":"2025-12-07T19:39:31.358211-08:00","closed_at":"2025-12-07T19:39:31.358211-08:00"}
 {"id":"opencode-swarm-plugin-jdj","title":"Update test bead","description":"Updated description","status":"closed","priority":2,"issue_type":"task","created_at":"2025-12-07T19:39:10.007126-08:00","updated_at":"2025-12-07T19:39:11.999539-08:00","closed_at":"2025-12-07T19:39:11.999539-08:00"}
+{"id":"opencode-swarm-plugin-jf6gz","title":"Add repo-crawl tools to swarm plugin","description":"repo-crawl is essential for research tasks. Should be part of the plugin rather than a separate MCP server.\n\nTools to add:\n- repo_readme(repo) - Get README content\n- repo_structure(repo) - Get repo structure and tech stack\n- repo_tree(repo, path?) - Get directory tree\n- repo_file(repo, path) - Get file content\n- repo_search(repo, query) - Search code in repo\n\nImplementation:\n- Use GitHub API (unauthenticated for public repos, GITHUB_TOKEN for private)\n- Add to tool-availability.ts checks\n- Integrate with research-based strategy\n\nFiles: src/repo-crawl.ts (new), src/index.ts, src/tool-availability.ts","status":"open","priority":2,"issue_type":"feature","created_at":"2025-12-10T11:01:29.213791-08:00","updated_at":"2025-12-10T11:01:29.213791-08:00"}
 {"id":"opencode-swarm-plugin-jg4c","title":"Thread link test bead","description":"[thread:test-thread-123]","status":"closed","priority":2,"issue_type":"task","created_at":"2025-12-08T08:22:18.157665-08:00","updated_at":"2025-12-08T08:22:19.932643-08:00","closed_at":"2025-12-08T08:22:19.932643-08:00"}
 {"id":"opencode-swarm-plugin-jhk","title":"Limit test bead 2","description":"","status":"closed","priority":2,"issue_type":"task","created_at":"2025-12-07T19:39:18.330876-08:00","updated_at":"2025-12-07T19:39:20.45981-08:00","closed_at":"2025-12-07T19:39:20.45981-08:00"}
 {"id":"opencode-swarm-plugin-jiqn","title":"Single subtask epic","description":"","status":"closed","priority":1,"issue_type":"epic","created_at":"2025-12-07T19:57:07.022149-08:00","updated_at":"2025-12-07T19:57:08.738869-08:00","closed_at":"2025-12-07T19:57:08.738869-08:00"}

package/dist/index.js

@@ -22931,6 +22931,7 @@ async function mcpCallOnce(toolName, args) {
 }
 async function mcpCall(toolName, args) {
   let lastError = null;
+  let restartAttempted = false;
   for (let attempt = 0;attempt <= RETRY_CONFIG.maxRetries; attempt++) {
     if (attempt > 0) {
       const delay = calculateBackoffDelay(attempt);
@@ -22943,13 +22944,28 @@ async function mcpCall(toolName, args) {
       return result;
     } catch (error45) {
       lastError = error45 instanceof Error ? error45 : new Error(String(error45));
+      const errorMessage = lastError.message.toLowerCase();
       consecutiveFailures++;
       const retryable = isRetryableError(error45);
-      if (consecutiveFailures >= RECOVERY_CONFIG.failureThreshold && RECOVERY_CONFIG.enabled) {
+      const isUnexpectedError = errorMessage.includes("unexpected error");
+      if (isUnexpectedError && !restartAttempted && RECOVERY_CONFIG.enabled) {
+        console.warn(`[agent-mail] "${toolName}" got unexpected error, restarting server immediately...`);
+        restartAttempted = true;
+        const restarted = await restartServer();
+        if (restarted) {
+          agentMailAvailable = null;
+          consecutiveFailures = 0;
+          await new Promise((resolve) => setTimeout(resolve, 1000));
+          attempt--;
+          continue;
+        }
+      }
+      if (!isUnexpectedError && consecutiveFailures >= RECOVERY_CONFIG.failureThreshold && RECOVERY_CONFIG.enabled && !restartAttempted) {
         console.warn(`[agent-mail] ${consecutiveFailures} consecutive failures, checking server health...`);
         const healthy = await isServerFunctional();
         if (!healthy) {
           console.warn("[agent-mail] Server unhealthy, attempting restart...");
+          restartAttempted = true;
           const restarted = await restartServer();
           if (restarted) {
             agentMailAvailable = null;
@@ -23758,7 +23774,8 @@ var ErrorEntrySchema = exports_external.object({
 var DecompositionStrategySchema = exports_external.enum([
   "file-based",
   "feature-based",
-  "risk-based"
+  "risk-based",
+  "research-based"
 ]);
 var OutcomeSignalsSchema = exports_external.object({
   bead_id: exports_external.string(),
@@ -24122,8 +24139,7 @@ var STRATEGIES = {
       "hotfix",
       "patch",
       "audit",
-      "review",
-      "investigate"
+      "review"
     ],
     guidelines: [
       "Write tests FIRST to capture expected behavior",
@@ -24142,6 +24158,47 @@ var STRATEGIES = {
       "Fix race condition \u2192 [Add test reproducing issue, Implement fix, Add concurrency tests]",
       "Security audit \u2192 [Scan for vulnerabilities, Fix critical issues, Document remaining risks]"
     ]
+  },
+  "research-based": {
+    name: "research-based",
+    description: "Parallel search across multiple sources, then synthesize. Best for investigation, learning, and discovery tasks.",
+    keywords: [
+      "research",
+      "investigate",
+      "explore",
+      "find",
+      "discover",
+      "understand",
+      "learn",
+      "analyze",
+      "what",
+      "how",
+      "why",
+      "compare",
+      "evaluate",
+      "study",
+      "look up",
+      "search"
+    ],
+    guidelines: [
+      "Split by information source (PDFs, repos, history, web)",
+      "Each agent searches with different query angles",
+      "Include a synthesis subtask that depends on all search subtasks",
+      "Use pdf-brain for documentation/books if available",
+      "Use repo-crawl for GitHub repos if URL provided",
+      "Use cass for past agent session history",
+      "Assign NO files to research subtasks (read-only)"
+    ],
+    antiPatterns: [
+      "Don't have one agent search everything sequentially",
+      "Don't skip synthesis - raw search results need consolidation",
+      "Don't forget to check tool availability before assigning sources"
+    ],
+    examples: [
+      "Research auth patterns \u2192 [Search PDFs, Search repos, Search history, Synthesize]",
+      "Investigate error \u2192 [Search cass for similar errors, Search repo for error handling, Synthesize]",
+      "Learn about library \u2192 [Search docs, Search examples, Search issues, Synthesize findings]"
+    ]
   }
 };
 function selectStrategy(task) {
@@ -24149,7 +24206,8 @@ function selectStrategy(task) {
   const scores = {
     "file-based": 0,
     "feature-based": 0,
-    "risk-based": 0
+    "risk-based": 0,
+    "research-based": 0
   };
   for (const [strategyName, definition] of Object.entries(STRATEGIES)) {
     const name = strategyName;
@@ -25096,7 +25154,7 @@ var swarm_record_outcome = tool({
     success: tool.schema.boolean().describe("Whether the subtask succeeded"),
     files_touched: tool.schema.array(tool.schema.string()).optional().describe("Files that were modified"),
     criteria: tool.schema.array(tool.schema.string()).optional().describe("Criteria to generate feedback for (default: all default criteria)"),
-    strategy: tool.schema.enum(["file-based", "feature-based", "risk-based"]).optional().describe("Decomposition strategy used for this task")
+    strategy: tool.schema.enum(["file-based", "feature-based", "risk-based", "research-based"]).optional().describe("Decomposition strategy used for this task")
   },
   async execute(args) {
     const signals = {

package/dist/plugin.js

@@ -22905,6 +22905,7 @@ async function mcpCallOnce(toolName, args) {
 }
 async function mcpCall(toolName, args) {
   let lastError = null;
+  let restartAttempted = false;
   for (let attempt = 0;attempt <= RETRY_CONFIG.maxRetries; attempt++) {
     if (attempt > 0) {
       const delay = calculateBackoffDelay(attempt);
@@ -22917,13 +22918,28 @@ async function mcpCall(toolName, args) {
       return result;
     } catch (error45) {
       lastError = error45 instanceof Error ? error45 : new Error(String(error45));
+      const errorMessage = lastError.message.toLowerCase();
       consecutiveFailures++;
       const retryable = isRetryableError(error45);
-      if (consecutiveFailures >= RECOVERY_CONFIG.failureThreshold && RECOVERY_CONFIG.enabled) {
+      const isUnexpectedError = errorMessage.includes("unexpected error");
+      if (isUnexpectedError && !restartAttempted && RECOVERY_CONFIG.enabled) {
+        console.warn(`[agent-mail] "${toolName}" got unexpected error, restarting server immediately...`);
+        restartAttempted = true;
+        const restarted = await restartServer();
+        if (restarted) {
+          agentMailAvailable = null;
+          consecutiveFailures = 0;
+          await new Promise((resolve) => setTimeout(resolve, 1000));
+          attempt--;
+          continue;
+        }
+      }
+      if (!isUnexpectedError && consecutiveFailures >= RECOVERY_CONFIG.failureThreshold && RECOVERY_CONFIG.enabled && !restartAttempted) {
         console.warn(`[agent-mail] ${consecutiveFailures} consecutive failures, checking server health...`);
         const healthy = await isServerFunctional();
         if (!healthy) {
           console.warn("[agent-mail] Server unhealthy, attempting restart...");
+          restartAttempted = true;
           const restarted = await restartServer();
           if (restarted) {
             agentMailAvailable = null;
@@ -23732,7 +23748,8 @@ var ErrorEntrySchema = exports_external.object({
 var DecompositionStrategySchema = exports_external.enum([
   "file-based",
   "feature-based",
-  "risk-based"
+  "risk-based",
+  "research-based"
 ]);
 var OutcomeSignalsSchema = exports_external.object({
   bead_id: exports_external.string(),
@@ -24080,8 +24097,7 @@ var STRATEGIES = {
       "hotfix",
       "patch",
       "audit",
-      "review",
-      "investigate"
+      "review"
     ],
     guidelines: [
       "Write tests FIRST to capture expected behavior",
@@ -24100,6 +24116,47 @@ var STRATEGIES = {
       "Fix race condition \u2192 [Add test reproducing issue, Implement fix, Add concurrency tests]",
       "Security audit \u2192 [Scan for vulnerabilities, Fix critical issues, Document remaining risks]"
     ]
+  },
+  "research-based": {
+    name: "research-based",
+    description: "Parallel search across multiple sources, then synthesize. Best for investigation, learning, and discovery tasks.",
+    keywords: [
+      "research",
+      "investigate",
+      "explore",
+      "find",
+      "discover",
+      "understand",
+      "learn",
+      "analyze",
+      "what",
+      "how",
+      "why",
+      "compare",
+      "evaluate",
+      "study",
+      "look up",
+      "search"
+    ],
+    guidelines: [
+      "Split by information source (PDFs, repos, history, web)",
+      "Each agent searches with different query angles",
+      "Include a synthesis subtask that depends on all search subtasks",
+      "Use pdf-brain for documentation/books if available",
+      "Use repo-crawl for GitHub repos if URL provided",
+      "Use cass for past agent session history",
+      "Assign NO files to research subtasks (read-only)"
+    ],
+    antiPatterns: [
+      "Don't have one agent search everything sequentially",
+      "Don't skip synthesis - raw search results need consolidation",
+      "Don't forget to check tool availability before assigning sources"
+    ],
+    examples: [
+      "Research auth patterns \u2192 [Search PDFs, Search repos, Search history, Synthesize]",
+      "Investigate error \u2192 [Search cass for similar errors, Search repo for error handling, Synthesize]",
+      "Learn about library \u2192 [Search docs, Search examples, Search issues, Synthesize findings]"
+    ]
   }
 };
 function selectStrategy(task) {
@@ -24107,7 +24164,8 @@ function selectStrategy(task) {
   const scores = {
     "file-based": 0,
     "feature-based": 0,
-    "risk-based": 0
+    "risk-based": 0,
+    "research-based": 0
   };
   for (const [strategyName, definition] of Object.entries(STRATEGIES)) {
     const name = strategyName;
@@ -25046,7 +25104,7 @@ var swarm_record_outcome = tool({
     success: tool.schema.boolean().describe("Whether the subtask succeeded"),
     files_touched: tool.schema.array(tool.schema.string()).optional().describe("Files that were modified"),
     criteria: tool.schema.array(tool.schema.string()).optional().describe("Criteria to generate feedback for (default: all default criteria)"),
-    strategy: tool.schema.enum(["file-based", "feature-based", "risk-based"]).optional().describe("Decomposition strategy used for this task")
+    strategy: tool.schema.enum(["file-based", "feature-based", "risk-based", "research-based"]).optional().describe("Decomposition strategy used for this task")
   },
   async execute(args) {
     const signals = {

package/package.json

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

package/src/agent-mail.ts

@@ -704,6 +704,7 @@ export async function mcpCall<T>(
   args: Record<string, unknown>,
 ): Promise<T> {
   let lastError: Error | null = null;
+  let restartAttempted = false;
 
   for (let attempt = 0; attempt <= RETRY_CONFIG.maxRetries; attempt++) {
     // Apply backoff delay (except first attempt)
@@ -723,17 +724,39 @@ export async function mcpCall<T>(
       return result;
     } catch (error) {
       lastError = error instanceof Error ? error : new Error(String(error));
+      const errorMessage = lastError.message.toLowerCase();
 
       // Track consecutive failures
       consecutiveFailures++;
 
-      // Check if error is retryable FIRST
+      // Check if error is retryable
       const retryable = isRetryableError(error);
 
-      // Check if we should attempt server restart
+      // AGGRESSIVE: If it's an "unexpected error", restart immediately (once per call)
+      const isUnexpectedError = errorMessage.includes("unexpected error");
+      if (isUnexpectedError && !restartAttempted && RECOVERY_CONFIG.enabled) {
+        console.warn(
+          `[agent-mail] "${toolName}" got unexpected error, restarting server immediately...`,
+        );
+        restartAttempted = true;
+        const restarted = await restartServer();
+        if (restarted) {
+          agentMailAvailable = null;
+          consecutiveFailures = 0;
+          // Small delay to let server stabilize
+          await new Promise((resolve) => setTimeout(resolve, 1000));
+          // Don't count this attempt - retry immediately
+          attempt--;
+          continue;
+        }
+      }
+
+      // Standard retry logic for other retryable errors
       if (
+        !isUnexpectedError &&
         consecutiveFailures >= RECOVERY_CONFIG.failureThreshold &&
-        RECOVERY_CONFIG.enabled
+        RECOVERY_CONFIG.enabled &&
+        !restartAttempted
       ) {
         console.warn(
           `[agent-mail] ${consecutiveFailures} consecutive failures, checking server health...`,
@@ -742,13 +765,11 @@ export async function mcpCall<T>(
         const healthy = await isServerFunctional();
         if (!healthy) {
           console.warn("[agent-mail] Server unhealthy, attempting restart...");
+          restartAttempted = true;
           const restarted = await restartServer();
           if (restarted) {
-            // Reset availability cache since server restarted
             agentMailAvailable = null;
-            // Only retry if the error was retryable in the first place
             if (retryable) {
-              // Don't count this attempt against retries - try again
               attempt--;
               continue;
             }

package/src/learning.ts

@@ -111,6 +111,7 @@ export const DecompositionStrategySchema = z.enum([
   "file-based",
   "feature-based",
   "risk-based",
+  "research-based",
 ]);
 export type DecompositionStrategy = z.infer<typeof DecompositionStrategySchema>;
 

package/src/swarm.ts

@@ -210,6 +210,7 @@ export type DecompositionStrategy =
   | "file-based"
   | "feature-based"
   | "risk-based"
+  | "research-based"
   | "auto";
 
 /**
@@ -316,7 +317,6 @@ export const STRATEGIES: Record<
       "patch",
       "audit",
       "review",
-      "investigate",
     ],
     guidelines: [
       "Write tests FIRST to capture expected behavior",
@@ -336,6 +336,48 @@ export const STRATEGIES: Record<
       "Security audit → [Scan for vulnerabilities, Fix critical issues, Document remaining risks]",
     ],
   },
+  "research-based": {
+    name: "research-based",
+    description:
+      "Parallel search across multiple sources, then synthesize. Best for investigation, learning, and discovery tasks.",
+    keywords: [
+      "research",
+      "investigate",
+      "explore",
+      "find",
+      "discover",
+      "understand",
+      "learn",
+      "analyze",
+      "what",
+      "how",
+      "why",
+      "compare",
+      "evaluate",
+      "study",
+      "look up",
+      "search",
+    ],
+    guidelines: [
+      "Split by information source (PDFs, repos, history, web)",
+      "Each agent searches with different query angles",
+      "Include a synthesis subtask that depends on all search subtasks",
+      "Use pdf-brain for documentation/books if available",
+      "Use repo-crawl for GitHub repos if URL provided",
+      "Use cass for past agent session history",
+      "Assign NO files to research subtasks (read-only)",
+    ],
+    antiPatterns: [
+      "Don't have one agent search everything sequentially",
+      "Don't skip synthesis - raw search results need consolidation",
+      "Don't forget to check tool availability before assigning sources",
+    ],
+    examples: [
+      "Research auth patterns → [Search PDFs, Search repos, Search history, Synthesize]",
+      "Investigate error → [Search cass for similar errors, Search repo for error handling, Synthesize]",
+      "Learn about library → [Search docs, Search examples, Search issues, Synthesize findings]",
+    ],
+  },
 };
 
 /**
@@ -360,6 +402,7 @@ export function selectStrategy(task: string): {
     "file-based": 0,
     "feature-based": 0,
     "risk-based": 0,
+    "research-based": 0,
   };
 
   for (const [strategyName, definition] of Object.entries(STRATEGIES)) {
@@ -1900,7 +1943,7 @@ export const swarm_record_outcome = tool({
         "Criteria to generate feedback for (default: all default criteria)",
       ),
     strategy: tool.schema
-      .enum(["file-based", "feature-based", "risk-based"])
+      .enum(["file-based", "feature-based", "risk-based", "research-based"])
       .optional()
       .describe("Decomposition strategy used for this task"),
   },