opencode-swarm-plugin 0.12.4 → 0.12.7

package/examples/commands/swarm.md

@@ -2,282 +2,117 @@
 description: Decompose task into parallel subtasks and coordinate agents
 ---
 
-You are a swarm coordinator. Take a complex task, break it into beads, and unleash parallel agents.
+You are a swarm coordinator. Decompose the task into beads and spawn parallel agents.
 
-## Usage
+## Task
 
-```
-/swarm <task description or bead-id>
-/swarm --to-main <task>  # Skip PR, push directly to main (use sparingly)
-/swarm --no-sync <task>  # Skip mid-task context sync (for simple independent tasks)
-```
-
-**Default behavior: Feature branch + PR with context sync.** All swarm work goes to a feature branch, agents share context mid-task, and creates a PR for review.
-
-## Step 1: Initialize Session
-
-Use the plugin's agent-mail tools to register:
-
-```
-agentmail_init with project_path=$PWD, task_description="Swarm coordinator: <task>"
-```
-
-This returns your agent name and session state. Remember it.
-
-## Step 2: Create Feature Branch
-
-**CRITICAL: Never push directly to main.**
-
-```bash
-# Create branch from bead ID or task name
-git checkout -b swarm/<bead-id>  # e.g., swarm/trt-buddy-d7d
-# Or for ad-hoc tasks:
-git checkout -b swarm/<short-description>  # e.g., swarm/contextual-checkins
-
-git push -u origin HEAD
-```
-
-## Step 3: Understand the Task
-
-If given a bead-id:
+$ARGUMENTS
 
-```
-beads_query with id=<bead-id>
-```
+## Flags (parse from task above)
 
-If given a description, analyze it to understand scope.
+- `--to-main` - Push directly to main, skip PR
+- `--no-sync` - Skip mid-task context sharing
 
-## Step 4: Select Strategy & Decompose
+**Default: Feature branch + PR with context sync.**
 
-### Option A: Use the Planner Agent (Recommended)
+## Workflow
 
-Spawn the `@swarm-planner` agent to handle decomposition:
+### 1. Initialize
 
 ```
-Task(
-  subagent_type="general",
-  description="Plan swarm decomposition",
-  prompt="You are @swarm-planner. Decompose this task: <task description>. Use swarm_select_strategy and swarm_plan_prompt to guide your decomposition. Return ONLY valid BeadTree JSON."
-)
+agentmail_init(project_path="$PWD", task_description="Swarm: <task summary>")
 ```
 
-### Option B: Manual Decomposition
-
-1. **Select strategy**:
+### 2. Create Feature Branch (unless --to-main)
 
-```
-swarm_select_strategy with task="<task description>"
-```
-
-2. **Get planning prompt**:
-
-```
-swarm_plan_prompt with task="<task description>", strategy="<selected or auto>"
+```bash
+git checkout -b swarm/<short-task-name>
+git push -u origin HEAD
 ```
 
-3. **Create decomposition** following the prompt guidelines
+### 3. Decompose Task
 
-4. **Validate**:
+Use strategy selection and planning:
 
 ```
-swarm_validate_decomposition with response="<your BeadTree JSON>"
+swarm_select_strategy(task="<the task>")
+swarm_plan_prompt(task="<the task>", strategy="<auto or selected>")
 ```
 
-### Create Beads
-
-Once you have a valid BeadTree:
+Follow the prompt to create a BeadTree, then validate:
 
 ```
-beads_create_epic with epic_title="<parent task>", subtasks=[{title, description, files, priority}...]
+swarm_validate_decomposition(response="<your BeadTree JSON>")
 ```
 
-**Decomposition rules:**
-
-- Each bead should be completable by one agent
-- Beads should be independent (parallelizable) where possible
-- If there are dependencies, order them in the subtasks array
-- Aim for 3-7 beads per swarm (too few = not parallel, too many = coordination overhead)
-
-## Step 5: Reserve Files
-
-For each subtask, reserve the files it will touch:
+### 4. Create Beads
 
 ```
-agentmail_reserve with paths=[<files>], reason="<bead-id>: <brief description>"
+beads_create_epic(epic_title="<task>", subtasks=[{title, files, priority}...])
 ```
 
-**Conflict prevention:**
-
-- No two agents should edit the same file
-- If overlap exists, merge beads or sequence them
-
-## Step 6: Spawn the Swarm
-
-**CRITICAL: Spawn ALL agents in a SINGLE message with multiple Task calls.**
-
-Use the prompt generator for each subtask:
+Rules:
 
-```
-swarm_spawn_subtask with bead_id="<bead-id>", epic_id="<epic-id>", subtask_title="<title>", subtask_description="<description>", files=[<files>], shared_context="Branch: swarm/<id>, sync_enabled: true"
-```
+- Each bead completable by one agent
+- Independent where possible (parallelizable)
+- 3-7 beads per swarm
 
-Then spawn agents with the generated prompts:
+### 5. Reserve Files
 
 ```
-Task(
-  subagent_type="general",
-  description="Swarm worker: <bead-title>",
-  prompt="<output from swarm_spawn_subtask>"
-)
+agentmail_reserve(paths=[<files>], reason="<bead-id>: <description>")
 ```
 
-Spawn ALL agents in parallel in a single response.
-
-## Step 7: Monitor Progress (unless --no-sync)
+No two agents should edit the same file.
 
-Check swarm status:
+### 6. Spawn Agents
 
-```
-swarm_status with epic_id="<parent-bead-id>"
-```
+**CRITICAL: Spawn ALL in a SINGLE message with multiple Task calls.**
 
-Monitor inbox for progress updates:
+For each subtask:
 
 ```
-agentmail_inbox
+swarm_spawn_subtask(bead_id="<id>", epic_id="<epic>", subtask_title="<title>", files=[...])
 ```
 
-**When you receive progress updates:**
-
-1. **Review decisions made** - Are agents making compatible choices?
-2. **Check for pattern conflicts** - Different approaches to the same problem?
-3. **Identify shared concerns** - Common blockers or discoveries?
-
-**If you spot incompatibilities, broadcast shared context:**
+Then spawn:
 
 ```
-agentmail_send with to=["*"], subject="Coordinator Update", body="<guidance>", thread_id="<epic-id>", importance="high"
+Task(subagent_type="swarm-worker", description="<bead-title>", prompt="<from swarm_spawn_subtask>")
 ```
 
-## Step 8: Collect Results
-
-When agents complete, they send completion messages. Summarize the thread:
+### 7. Monitor (unless --no-sync)
 
 ```
-agentmail_summarize_thread with thread_id="<epic-id>"
+swarm_status(epic_id="<epic-id>")
+agentmail_inbox()
 ```
 
-## Step 9: Complete Swarm
-
-Use the swarm completion tool:
+If incompatibilities spotted, broadcast:
 
 ```
-swarm_complete with project_key=$PWD, agent_name=<YOUR_NAME>, bead_id="<epic-id>", summary="<what was accomplished>", files_touched=[<all files>]
+agentmail_send(to=["*"], subject="Coordinator Update", body="<guidance>", importance="high")
 ```
 
-This:
-
-- Runs [UBS (Ultimate Bug Scanner)](https://github.com/Dicklesworthstone/ultimate_bug_scanner) on touched files to detect bugs before completion
-- Releases file reservations
-- Closes the bead
-- Records outcome for learning
-
-> **Note:** UBS is optional but recommended. If not installed, swarm completion proceeds with a warning that manual review is advised. Install via:
-> ```bash
-> curl -fsSL "https://raw.githubusercontent.com/Dicklesworthstone/ultimate_bug_scanner/master/install.sh" | bash
-> ```
-> See the [UBS repo](https://github.com/Dicklesworthstone/ultimate_bug_scanner) for more options (Docker, Nix, etc.).
-
-Then sync beads:
+### 8. Complete
 
 ```
-beads_sync
+swarm_complete(project_key="$PWD", agent_name="<your-name>", bead_id="<epic-id>", summary="<done>", files_touched=[...])
+beads_sync()
 ```
 
-## Step 10: Create PR
+### 9. Create PR (unless --to-main)
 
 ```bash
-gh pr create --title "feat: <epic title>" --body "$(cat <<'EOF'
-## Summary
-<1-3 bullet points from swarm results>
-
-## Beads Completed
-- <bead-id>: <summary>
-- <bead-id>: <summary>
-
-## Files Changed
-<aggregate list>
-
-## Testing
-- [ ] Type check passes
-- [ ] Tests pass (if applicable)
-EOF
-)"
-```
-
-Report summary:
-
-```markdown
-## Swarm Complete: <task>
-
-### PR: #<number>
-
-### Agents Spawned: N
-
-### Beads Closed: N
-
-### Work Completed
-
-- [bead-id]: [summary]
-
-### Files Changed
-
-- [aggregate list]
+gh pr create --title "feat: <epic title>" --body "## Summary\n<bullets>\n\n## Beads\n<list>"
 ```
 
-## Failure Handling
-
-If an agent fails:
-
-- Check its messages: `agentmail_inbox`
-- The bead remains in-progress
-- Manually investigate or re-spawn
-
-If file conflicts occur:
-
-- Agent Mail reservations should prevent this
-- If it happens, one agent needs to wait
-
-## Direct-to-Main Mode (--to-main)
-
-Only use when explicitly requested. Skips branch/PR:
-
-- Trivial fixes across many files
-- Automated migrations with high confidence
-- User explicitly says "push to main"
-
-## No-Sync Mode (--no-sync)
-
-Skip mid-task context sharing when tasks are truly independent:
-
-- Simple mechanical changes (find/replace, formatting, lint fixes)
-- Tasks with zero integration points
-- Completely separate feature areas with no shared types
-
-In this mode:
-
-- Agents skip the mid-task progress message
-- Coordinator skips Step 7 (monitoring)
-- Faster execution, less coordination overhead
-
-**Default is sync ON** - prefer sharing context. Use `--no-sync` deliberately.
-
 ## Strategy Reference
 
-| Strategy          | Best For                    | Auto-Detected Keywords                         |
-| ----------------- | --------------------------- | ---------------------------------------------- |
-| **file-based**    | Refactoring, migrations     | refactor, migrate, rename, update all, convert |
-| **feature-based** | New features, functionality | add, implement, build, create, feature, new    |
-| **risk-based**    | Bug fixes, security         | fix, bug, security, critical, urgent, hotfix   |
+| Strategy      | Best For                | Keywords                              |
+| ------------- | ----------------------- | ------------------------------------- |
+| file-based    | Refactoring, migrations | refactor, migrate, rename, update all |
+| feature-based | New features            | add, implement, build, create, new    |
+| risk-based    | Bug fixes, security     | fix, bug, security, critical, urgent  |
 
-Use `swarm_select_strategy` to see which strategy is recommended and why.
+Begin decomposition now.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "opencode-swarm-plugin",
-  "version": "0.12.4",
+  "version": "0.12.7",
   "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

@@ -38,10 +38,10 @@ const RETRY_CONFIG = {
 
 // Server recovery configuration
 const RECOVERY_CONFIG = {
-  /** Max consecutive failures before attempting restart */
-  failureThreshold: 2,
-  /** Cooldown between restart attempts (ms) */
-  restartCooldownMs: 30000,
+  /** Max consecutive failures before attempting restart (1 = restart on first "unexpected error") */
+  failureThreshold: 1,
+  /** Cooldown between restart attempts (ms) - 10 seconds */
+  restartCooldownMs: 10000,
   /** Whether auto-restart is enabled */
   enabled: process.env.OPENCODE_AGENT_MAIL_AUTO_RESTART !== "false",
 };
@@ -107,8 +107,10 @@ function loadSessionState(sessionID: string): AgentMailState | null {
 
 /**
  * Save session state to disk
+ *
+ * @returns true if save succeeded, false if failed
  */
-function saveSessionState(sessionID: string, state: AgentMailState): void {
+function saveSessionState(sessionID: string, state: AgentMailState): boolean {
   try {
     // Ensure directory exists
     if (!existsSync(SESSION_STATE_DIR)) {
@@ -116,9 +118,16 @@ function saveSessionState(sessionID: string, state: AgentMailState): void {
     }
     const path = getSessionStatePath(sessionID);
     writeFileSync(path, JSON.stringify(state, null, 2));
+    return true;
   } catch (error) {
     // Non-fatal - state just won't persist
-    console.warn(`[agent-mail] Could not save session state: ${error}`);
+    console.error(
+      `[agent-mail] CRITICAL: Could not save session state: ${error}`,
+    );
+    console.error(
+      `[agent-mail] Session state will not persist across CLI invocations!`,
+    );
+    return false;
   }
 }
 
@@ -718,6 +727,9 @@ export async function mcpCall<T>(
       // Track consecutive failures
       consecutiveFailures++;
 
+      // Check if error is retryable FIRST
+      const retryable = isRetryableError(error);
+
       // Check if we should attempt server restart
       if (
         consecutiveFailures >= RECOVERY_CONFIG.failureThreshold &&
@@ -734,15 +746,18 @@ export async function mcpCall<T>(
           if (restarted) {
             // Reset availability cache since server restarted
             agentMailAvailable = null;
-            // Don't count this attempt against retries - try again
-            attempt--;
-            continue;
+            // Only retry if the error was retryable in the first place
+            if (retryable) {
+              // Don't count this attempt against retries - try again
+              attempt--;
+              continue;
+            }
           }
         }
       }
 
-      // Check if error is retryable
-      if (!isRetryableError(error)) {
+      // If error is not retryable, throw immediately
+      if (!retryable) {
         console.warn(
           `[agent-mail] Non-retryable error for ${toolName}: ${lastError.message}`,
         );
@@ -865,30 +880,88 @@ export const agentmail_init = tool({
       );
     }
 
-    // 1. Ensure project exists
-    const project = await mcpCall<ProjectInfo>("ensure_project", {
-      human_key: args.project_path,
-    });
+    // Retry loop with restart on failure
+    const MAX_INIT_RETRIES = 3;
+    let lastError: Error | null = null;
 
-    // 2. Register agent
-    const agent = await mcpCall<AgentInfo>("register_agent", {
-      project_key: args.project_path,
-      program: "opencode",
-      model: "claude-opus-4",
-      name: args.agent_name, // undefined = auto-generate
-      task_description: args.task_description || "",
-    });
+    for (let attempt = 1; attempt <= MAX_INIT_RETRIES; attempt++) {
+      try {
+        // 1. Ensure project exists
+        const project = await mcpCall<ProjectInfo>("ensure_project", {
+          human_key: args.project_path,
+        });
+
+        // 2. Register agent
+        const agent = await mcpCall<AgentInfo>("register_agent", {
+          project_key: args.project_path,
+          program: "opencode",
+          model: "claude-opus-4",
+          name: args.agent_name, // undefined = auto-generate
+          task_description: args.task_description || "",
+        });
+
+        // 3. Store state using sessionID
+        const state: AgentMailState = {
+          projectKey: args.project_path,
+          agentName: agent.name,
+          reservations: [],
+          startedAt: new Date().toISOString(),
+        };
+        setState(ctx.sessionID, state);
+
+        // Success - if we retried, log it
+        if (attempt > 1) {
+          console.warn(
+            `[agent-mail] Init succeeded on attempt ${attempt} after restart`,
+          );
+        }
 
-    // 3. Store state using sessionID
-    const state: AgentMailState = {
-      projectKey: args.project_path,
-      agentName: agent.name,
-      reservations: [],
-      startedAt: new Date().toISOString(),
-    };
-    setState(ctx.sessionID, state);
+        return JSON.stringify({ project, agent, available: true }, null, 2);
+      } catch (error) {
+        lastError = error instanceof Error ? error : new Error(String(error));
+        const isUnexpectedError = lastError.message
+          .toLowerCase()
+          .includes("unexpected error");
+
+        console.warn(
+          `[agent-mail] Init attempt ${attempt}/${MAX_INIT_RETRIES} failed: ${lastError.message}`,
+        );
 
-    return JSON.stringify({ project, agent, available: true }, null, 2);
+        // If it's an "unexpected error" and we have retries left, restart and retry
+        if (isUnexpectedError && attempt < MAX_INIT_RETRIES) {
+          console.warn(
+            "[agent-mail] Detected 'unexpected error', restarting server...",
+          );
+          const restarted = await restartServer();
+          if (restarted) {
+            // Clear cache and retry
+            agentMailAvailable = null;
+            consecutiveFailures = 0;
+            // Small delay to let server stabilize
+            await new Promise((resolve) => setTimeout(resolve, 1000));
+            continue;
+          }
+        }
+
+        // For non-unexpected errors or if restart failed, don't retry
+        if (!isUnexpectedError) {
+          break;
+        }
+      }
+    }
+
+    // All retries exhausted
+    return JSON.stringify(
+      {
+        error: `Agent Mail init failed after ${MAX_INIT_RETRIES} attempts`,
+        available: false,
+        lastError: lastError?.message,
+        hint: "Manually restart Agent Mail: pkill -f agent-mail && agent-mail serve",
+        fallback: "Swarm will continue without multi-agent coordination.",
+      },
+      null,
+      2,
+    );
   },
 });
 
@@ -1006,18 +1079,18 @@ export const agentmail_read_message = tool({
       message_id: args.message_id,
     });
 
-    // Fetch with body - we need to use fetch_inbox with specific message
-    // Since there's no get_message, we'll use search
+    // Fetch with body - fetch more messages to find the requested one
+    // Since there's no get_message endpoint, we need to fetch a reasonable batch
     const messages = await mcpCall<MessageHeader[]>("fetch_inbox", {
       project_key: state.projectKey,
       agent_name: state.agentName,
-      limit: 1,
+      limit: 50, // Fetch more messages to increase chance of finding the target
       include_bodies: true, // Only for single message fetch
     });
 
     const message = messages.find((m) => m.id === args.message_id);
     if (!message) {
-      return `Message ${args.message_id} not found`;
+      return `Message ${args.message_id} not found in recent 50 messages. Try using agentmail_search to locate it.`;
     }
 
     // Record successful request
@@ -1255,7 +1328,12 @@ export const agentmail_health = tool({
     try {
       const response = await fetch(`${AGENT_MAIL_URL}/health/liveness`);
       if (response.ok) {
-        return "Agent Mail is running";
+        // Also check if MCP is functional
+        const functional = await isServerFunctional();
+        if (functional) {
+          return "Agent Mail is running and functional";
+        }
+        return "Agent Mail health OK but MCP not responding - consider restart";
       }
       return `Agent Mail returned status ${response.status}`;
     } catch (error) {
@@ -1264,6 +1342,73 @@ export const agentmail_health = tool({
   },
 });
 
+/**
+ * Manually restart Agent Mail server
+ *
+ * Use when server is in bad state (health OK but MCP failing).
+ * This kills the existing process and starts a fresh one.
+ */
+export const agentmail_restart = tool({
+  description:
+    "Manually restart Agent Mail server (use when getting 'unexpected error')",
+  args: {
+    force: tool.schema
+      .boolean()
+      .optional()
+      .describe(
+        "Force restart even if server appears healthy (default: false)",
+      ),
+  },
+  async execute(args) {
+    // Check if restart is needed
+    if (!args.force) {
+      const functional = await isServerFunctional();
+      if (functional) {
+        return JSON.stringify(
+          {
+            restarted: false,
+            reason: "Server is functional, no restart needed",
+            hint: "Use force=true to restart anyway",
+          },
+          null,
+          2,
+        );
+      }
+    }
+
+    // Attempt restart
+    console.warn("[agent-mail] Manual restart requested...");
+    const success = await restartServer();
+
+    // Clear caches
+    agentMailAvailable = null;
+    consecutiveFailures = 0;
+
+    if (success) {
+      return JSON.stringify(
+        {
+          restarted: true,
+          success: true,
+          message: "Agent Mail server restarted successfully",
+        },
+        null,
+        2,
+      );
+    }
+
+    return JSON.stringify(
+      {
+        restarted: true,
+        success: false,
+        error: "Restart attempted but server did not come back up",
+        hint: "Check server logs or manually start: agent-mail serve",
+      },
+      null,
+      2,
+    );
+  },
+});
+
 // ============================================================================
 // Export all tools
 // ============================================================================
@@ -1279,6 +1424,7 @@ export const agentMailTools = {
   agentmail_ack: agentmail_ack,
   agentmail_search: agentmail_search,
   agentmail_health: agentmail_health,
+  agentmail_restart: agentmail_restart,
 };
 
 // ============================================================================