opencode-swarm-plugin 0.12.2 → 0.12.6

package/examples/commands/swarm.md

@@ -2,276 +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.
+$ARGUMENTS
 
-## Step 2: Create Feature Branch
+## Flags (parse from task above)
 
-**CRITICAL: Never push directly to main.**
+- `--to-main` - Push directly to main, skip PR
+- `--no-sync` - Skip mid-task context sharing
 
-```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
+**Default: Feature branch + PR with context sync.**
 
-git push -u origin HEAD
-```
+## Workflow
 
-## Step 3: Understand the Task
-
-If given a bead-id:
+### 1. Initialize
 
 ```
-beads_query with id=<bead-id>
+agentmail_init(project_path="$PWD", task_description="Swarm: <task summary>")
 ```
 
-If given a description, analyze it to understand scope.
-
-## Step 4: Select Strategy & Decompose
+### 2. Create Feature Branch (unless --to-main)
 
-### Option A: Use the Planner Agent (Recommended)
-
-Spawn the `@swarm-planner` agent to handle decomposition:
-
-```
-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."
-)
+```bash
+git checkout -b swarm/<short-task-name>
+git push -u origin HEAD
 ```
 
-### Option B: Manual Decomposition
+### 3. Decompose Task
 
-1. **Select strategy**:
+Use strategy selection and planning:
 
 ```
-swarm_select_strategy with task="<task description>"
+swarm_select_strategy(task="<the task>")
+swarm_plan_prompt(task="<the task>", strategy="<auto or selected>")
 ```
 
-2. **Get planning prompt**:
+Follow the prompt to create a BeadTree, then validate:
 
 ```
-swarm_plan_prompt with task="<task description>", strategy="<selected or auto>"
+swarm_validate_decomposition(response="<your BeadTree JSON>")
 ```
 
-3. **Create decomposition** following the prompt guidelines
-
-4. **Validate**:
+### 4. Create Beads
 
 ```
-swarm_validate_decomposition with response="<your BeadTree JSON>"
+beads_create_epic(epic_title="<task>", subtasks=[{title, files, priority}...])
 ```
 
-### Create Beads
-
-Once you have a valid BeadTree:
+Rules:
 
-```
-beads_create_epic with epic_title="<parent task>", subtasks=[{title, description, files, priority}...]
-```
+- Each bead completable by one agent
+- Independent where possible (parallelizable)
+- 3-7 beads per swarm
 
-**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:
+### 5. Reserve Files
 
 ```
-agentmail_reserve with paths=[<files>], reason="<bead-id>: <brief description>"
+agentmail_reserve(paths=[<files>], reason="<bead-id>: <description>")
 ```
 
-**Conflict prevention:**
-
-- No two agents should edit the same file
-- If overlap exists, merge beads or sequence them
+No two agents should edit the same file.
 
-## Step 6: Spawn the Swarm
+### 6. Spawn Agents
 
-**CRITICAL: Spawn ALL agents in a SINGLE message with multiple Task calls.**
+**CRITICAL: Spawn ALL in a SINGLE message with multiple Task calls.**
 
-Use the prompt generator for each subtask:
+For each subtask:
 
 ```
-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"
+swarm_spawn_subtask(bead_id="<id>", epic_id="<epic>", subtask_title="<title>", files=[...])
 ```
 
-Then spawn agents with the generated prompts:
+Then spawn:
 
 ```
-Task(
-  subagent_type="general",
-  description="Swarm worker: <bead-title>",
-  prompt="<output from swarm_spawn_subtask>"
-)
+Task(subagent_type="swarm-worker", description="<bead-title>", prompt="<from swarm_spawn_subtask>")
 ```
 
-Spawn ALL agents in parallel in a single response.
-
-## Step 7: Monitor Progress (unless --no-sync)
-
-Check swarm status:
+### 7. Monitor (unless --no-sync)
 
 ```
-swarm_status with epic_id="<parent-bead-id>"
+swarm_status(epic_id="<epic-id>")
+agentmail_inbox()
 ```
 
-Monitor inbox for progress updates:
+If incompatibilities spotted, broadcast:
 
 ```
-agentmail_inbox
+agentmail_send(to=["*"], subject="Coordinator Update", body="<guidance>", importance="high")
 ```
 
-**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:**
-
-```
-agentmail_send with to=["*"], subject="Coordinator Update", body="<guidance>", thread_id="<epic-id>", importance="high"
-```
-
-## Step 8: Collect Results
-
-When agents complete, they send completion messages. Summarize the thread:
+### 8. Complete
 
 ```
-agentmail_summarize_thread with thread_id="<epic-id>"
+swarm_complete(project_key="$PWD", agent_name="<your-name>", bead_id="<epic-id>", summary="<done>", files_touched=[...])
+beads_sync()
 ```
 
-## Step 9: Complete Swarm
-
-Use the swarm completion tool:
-
-```
-swarm_complete with project_key=$PWD, agent_name=<YOUR_NAME>, bead_id="<epic-id>", summary="<what was accomplished>", files_touched=[<all files>]
-```
-
-This:
-
-- Runs UBS bug scan on touched files
-- Releases file reservations
-- Closes the bead
-- Records outcome for learning
-
-Then sync beads:
-
-```
-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
-)"
+gh pr create --title "feat: <epic title>" --body "## Summary\n<bullets>\n\n## Beads\n<list>"
 ```
 
-Report summary:
-
-```markdown
-## Swarm Complete: <task>
-
-### PR: #<number>
-
-### Agents Spawned: N
-
-### Beads Closed: N
-
-### Work Completed
-
-- [bead-id]: [summary]
-
-### Files Changed
-
-- [aggregate 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.2",
+  "version": "0.12.6",
   "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

@@ -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}`,
         );
@@ -1006,18 +1021,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

package/src/beads.ts

@@ -55,6 +55,10 @@ export class BeadValidationError extends Error {
 
 /**
  * Build a bd create command from args
+ *
+ * Note: Bun's `$` template literal properly escapes arguments when passed as array.
+ * Each array element is treated as a separate argument, preventing shell injection.
+ * Example: ["bd", "create", "; rm -rf /"] becomes: bd create "; rm -rf /"
  */
 function buildCreateCommand(args: BeadCreateArgs): string[] {
   const parts = ["bd", "create", args.title];
@@ -250,25 +254,40 @@ export const beads_create_epic = tool({
 
       return JSON.stringify(result, null, 2);
     } catch (error) {
-      // Partial failure - return what was created with rollback hint
-      const rollbackHint = created
-        .map((b) => `bd close ${b.id} --reason "Rollback partial epic"`)
-        .join("\n");
+      // Partial failure - execute rollback automatically
+      const rollbackCommands: string[] = [];
+
+      for (const bead of created) {
+        try {
+          const closeCmd = [
+            "bd",
+            "close",
+            bead.id,
+            "--reason",
+            "Rollback partial epic",
+            "--json",
+          ];
+          await Bun.$`${closeCmd}`.quiet().nothrow();
+          rollbackCommands.push(
+            `bd close ${bead.id} --reason "Rollback partial epic"`,
+          );
+        } catch (rollbackError) {
+          // Log rollback failure but continue
+          console.error(`Failed to rollback bead ${bead.id}:`, rollbackError);
+        }
+      }
 
-      const result: EpicCreateResult = {
-        success: false,
-        epic: created[0] || ({} as Bead),
-        subtasks: created.slice(1),
-        rollback_hint: rollbackHint,
-      };
+      // Throw error with rollback info
+      const errorMsg = error instanceof Error ? error.message : String(error);
+      const rollbackInfo =
+        rollbackCommands.length > 0
+          ? `\n\nRolled back ${rollbackCommands.length} bead(s):\n${rollbackCommands.join("\n")}`
+          : "\n\nNo beads to rollback.";
 
-      return JSON.stringify(
-        {
-          ...result,
-          error: error instanceof Error ? error.message : String(error),
-        },
-        null,
-        2,
+      throw new BeadError(
+        `Epic creation failed: ${errorMsg}${rollbackInfo}`,
+        "beads_create_epic",
+        1,
       );
     }
   },
@@ -487,10 +506,38 @@ export const beads_sync = tool({
   },
   async execute(args, ctx) {
     const autoPull = args.auto_pull ?? true;
+    const TIMEOUT_MS = 30000; // 30 seconds
+
+    /**
+     * Helper to run a command with timeout
+     */
+    const withTimeout = async <T>(
+      promise: Promise<T>,
+      timeoutMs: number,
+      operation: string,
+    ): Promise<T> => {
+      const timeoutPromise = new Promise<never>((_, reject) =>
+        setTimeout(
+          () =>
+            reject(
+              new BeadError(
+                `Operation timed out after ${timeoutMs}ms`,
+                operation,
+              ),
+            ),
+          timeoutMs,
+        ),
+      );
+      return Promise.race([promise, timeoutPromise]);
+    };
 
     // 1. Pull if requested
     if (autoPull) {
-      const pullResult = await Bun.$`git pull --rebase`.quiet().nothrow();
+      const pullResult = await withTimeout(
+        Bun.$`git pull --rebase`.quiet().nothrow(),
+        TIMEOUT_MS,
+        "git pull --rebase",
+      );
       if (pullResult.exitCode !== 0) {
         throw new BeadError(
           `Failed to pull: ${pullResult.stderr.toString()}`,
@@ -501,7 +548,11 @@ export const beads_sync = tool({
     }
 
     // 2. Sync beads
-    const syncResult = await Bun.$`bd sync`.quiet().nothrow();
+    const syncResult = await withTimeout(
+      Bun.$`bd sync`.quiet().nothrow(),
+      TIMEOUT_MS,
+      "bd sync",
+    );
     if (syncResult.exitCode !== 0) {
       throw new BeadError(
         `Failed to sync beads: ${syncResult.stderr.toString()}`,
@@ -511,7 +562,11 @@ export const beads_sync = tool({
     }
 
     // 3. Push
-    const pushResult = await Bun.$`git push`.quiet().nothrow();
+    const pushResult = await withTimeout(
+      Bun.$`git push`.quiet().nothrow(),
+      TIMEOUT_MS,
+      "git push",
+    );
     if (pushResult.exitCode !== 0) {
       throw new BeadError(
         `Failed to push: ${pushResult.stderr.toString()}`,

package/src/rate-limiter.ts

@@ -122,9 +122,15 @@ export function getLimitsForEndpoint(endpoint: string): EndpointLimits {
   const perHourEnv =
     process.env[`OPENCODE_RATE_LIMIT_${upperEndpoint}_PER_HOUR`];
 
+  // Parse and validate env vars, fall back to defaults on NaN
+  const parsedPerMinute = perMinuteEnv ? parseInt(perMinuteEnv, 10) : NaN;
+  const parsedPerHour = perHourEnv ? parseInt(perHourEnv, 10) : NaN;
+
   return {
-    perMinute: perMinuteEnv ? parseInt(perMinuteEnv, 10) : defaults.perMinute,
-    perHour: perHourEnv ? parseInt(perHourEnv, 10) : defaults.perHour,
+    perMinute: Number.isNaN(parsedPerMinute)
+      ? defaults.perMinute
+      : parsedPerMinute,
+    perHour: Number.isNaN(parsedPerHour) ? defaults.perHour : parsedPerHour,
   };
 }
 
@@ -211,10 +217,11 @@ export class RedisRateLimiter implements RateLimiter {
     const windowDuration = this.getWindowDuration(window);
     const windowStart = now - windowDuration;
 
-    // Remove expired entries and count current ones in a pipeline
+    // Remove expired entries, count current ones, and fetch oldest in a single pipeline
     const pipeline = this.redis.pipeline();
     pipeline.zremrangebyscore(key, 0, windowStart);
     pipeline.zcard(key);
+    pipeline.zrange(key, 0, 0, "WITHSCORES"); // Fetch oldest entry atomically
 
     const results = await pipeline.exec();
     if (!results) {
@@ -225,11 +232,10 @@ export class RedisRateLimiter implements RateLimiter {
     const remaining = Math.max(0, limit - count);
     const allowed = count < limit;
 
-    // Calculate reset time based on oldest entry in window
+    // Calculate reset time based on oldest entry in window (fetched atomically)
     let resetAt = now + windowDuration;
     if (!allowed) {
-      // Get the oldest entry's timestamp to calculate precise reset
-      const oldest = await this.redis.zrange(key, 0, 0, "WITHSCORES");
+      const oldest = (results[2]?.[1] as string[]) || [];
       if (oldest.length >= 2) {
         const oldestTimestamp = parseInt(oldest[1], 10);
         resetAt = oldestTimestamp + windowDuration;

package/src/schemas/bead.ts

@@ -42,15 +42,15 @@ export type BeadDependency = z.infer<typeof BeadDependencySchema>;
 export const BeadSchema = z.object({
   id: z
     .string()
-    .regex(/^[a-z0-9-]+-[a-z0-9]+(\.\d+)?$/, "Invalid bead ID format"),
+    .regex(/^[a-z0-9]+(-[a-z0-9]+)+(\.\d+)?$/, "Invalid bead ID format"),
   title: z.string().min(1, "Title required"),
   description: z.string().optional().default(""),
   status: BeadStatusSchema.default("open"),
   priority: z.number().int().min(0).max(3).default(2),
   issue_type: BeadTypeSchema.default("task"),
-  created_at: z.string(), // ISO-8601
-  updated_at: z.string().optional(),
-  closed_at: z.string().optional(),
+  created_at: z.string().datetime({ offset: true }), // ISO-8601 with timezone offset
+  updated_at: z.string().datetime({ offset: true }).optional(),
+  closed_at: z.string().datetime({ offset: true }).optional(),
   parent_id: z.string().optional(),
   dependencies: z.array(BeadDependencySchema).optional().default([]),
   metadata: z.record(z.string(), z.unknown()).optional(),

package/src/schemas/evaluation.ts

@@ -53,7 +53,7 @@ export const EvaluationSchema = z.object({
   criteria: z.record(z.string(), CriterionEvaluationSchema),
   overall_feedback: z.string(),
   retry_suggestion: z.string().nullable(),
-  timestamp: z.string().optional(), // ISO-8601
+  timestamp: z.string().datetime({ offset: true }).optional(), // ISO-8601 with timezone
 });
 export type Evaluation = z.infer<typeof EvaluationSchema>;
 
@@ -91,7 +91,7 @@ export const WeightedEvaluationSchema = z.object({
   criteria: z.record(z.string(), WeightedCriterionEvaluationSchema),
   overall_feedback: z.string(),
   retry_suggestion: z.string().nullable(),
-  timestamp: z.string().optional(), // ISO-8601
+  timestamp: z.string().datetime({ offset: true }).optional(), // ISO-8601 with timezone
   /** Average weight across all criteria (indicates overall confidence) */
   average_weight: z.number().min(0).max(1).optional(),
   /** Raw score before weighting */

package/src/schemas/task.ts

@@ -94,7 +94,7 @@ export const SwarmSpawnResultSchema = z.object({
   coordinator_name: z.string(), // Agent Mail name of coordinator
   thread_id: z.string(), // Agent Mail thread for this swarm
   agents: z.array(SpawnedAgentSchema),
-  started_at: z.string(), // ISO-8601
+  started_at: z.string().datetime({ offset: true }), // ISO-8601 with timezone
 });
 export type SwarmSpawnResult = z.infer<typeof SwarmSpawnResultSchema>;
 
@@ -109,7 +109,7 @@ export const AgentProgressSchema = z.object({
   message: z.string().optional(),
   files_touched: z.array(z.string()).optional(),
   blockers: z.array(z.string()).optional(),
-  timestamp: z.string(), // ISO-8601
+  timestamp: z.string().datetime({ offset: true }), // ISO-8601 with timezone
 });
 export type AgentProgress = z.infer<typeof AgentProgressSchema>;
 
@@ -124,6 +124,6 @@ export const SwarmStatusSchema = z.object({
   failed: z.number().int().min(0),
   blocked: z.number().int().min(0),
   agents: z.array(SpawnedAgentSchema),
-  last_update: z.string(), // ISO-8601
+  last_update: z.string().datetime({ offset: true }), // ISO-8601 with timezone
 });
 export type SwarmStatus = z.infer<typeof SwarmStatusSchema>;