opencode-swarm-plugin 0.12.4 → 0.12.7

package/src/swarm.ts

@@ -31,9 +31,13 @@ import {
   DecompositionStrategySchema,
   scoreImplicitFeedback,
   outcomeToFeedback,
+  ErrorAccumulator,
+  ErrorEntrySchema,
   type OutcomeSignals,
   type ScoredOutcome,
   type FeedbackEvent,
+  type ErrorEntry,
+  type ErrorType,
   type DecompositionStrategy as LearningDecompositionStrategy,
   DEFAULT_LEARNING_CONFIG,
 } from "./learning";
@@ -604,6 +608,8 @@ Begin work on your subtask now.`;
  *
  * This is a cleaner version of SUBTASK_PROMPT that's easier to parse.
  * Agents MUST use Agent Mail for communication and beads for tracking.
+ *
+ * Supports {error_context} placeholder for retry prompts.
  */
 export const SUBTASK_PROMPT_V2 = `You are a swarm agent working on: **{subtask_title}**
 
@@ -622,6 +628,10 @@ Only modify these files. Need others? Message the coordinator.
 ## Context
 {shared_context}
 
+{compressed_context}
+
+{error_context}
+
 ## MANDATORY: Use These Tools
 
 ### Agent Mail - communicate with the swarm
@@ -663,12 +673,20 @@ export function formatSubtaskPromptV2(params: {
   subtask_description: string;
   files: string[];
   shared_context?: string;
+  compressed_context?: string;
+  error_context?: string;
 }): string {
   const fileList =
     params.files.length > 0
       ? params.files.map((f) => `- \`${f}\``).join("\n")
       : "(no specific files - use judgment)";
 
+  const compressedSection = params.compressed_context
+    ? params.compressed_context
+    : "";
+
+  const errorSection = params.error_context ? params.error_context : "";
+
   return SUBTASK_PROMPT_V2.replace(/{bead_id}/g, params.bead_id)
     .replace(/{epic_id}/g, params.epic_id)
     .replace("{subtask_title}", params.subtask_title)
@@ -677,7 +695,9 @@ export function formatSubtaskPromptV2(params: {
       params.subtask_description || "(see title)",
     )
     .replace("{file_list}", fileList)
-    .replace("{shared_context}", params.shared_context || "(none)");
+    .replace("{shared_context}", params.shared_context || "(none)")
+    .replace("{compressed_context}", compressedSection)
+    .replace("{error_context}", errorSection);
 }
 
 /**
@@ -1343,6 +1363,19 @@ export const swarm_validate_decomposition = tool({
       for (let i = 0; i < validated.subtasks.length; i++) {
         const deps = validated.subtasks[i].dependencies;
         for (const dep of deps) {
+          // Check bounds first
+          if (dep < 0 || dep >= validated.subtasks.length) {
+            return JSON.stringify(
+              {
+                valid: false,
+                error: `Invalid dependency: subtask ${i} depends on ${dep}, but only ${validated.subtasks.length} subtasks exist (indices 0-${validated.subtasks.length - 1})`,
+                hint: "Dependency index is out of bounds",
+              },
+              null,
+              2,
+            );
+          }
+          // Check forward references
           if (dep >= i) {
             return JSON.stringify(
               {
@@ -1893,6 +1926,9 @@ export const swarm_record_outcome = tool({
       DEFAULT_LEARNING_CONFIG,
     );
 
+    // Get error patterns from accumulator
+    const errorStats = await globalErrorAccumulator.getErrorStats(args.bead_id);
+
     // Generate feedback events for each criterion
     const criteriaToScore = args.criteria ?? [
       "type_safe",
@@ -1907,6 +1943,14 @@ export const swarm_record_outcome = tool({
         event.context =
           `${event.context || ""} [strategy: ${args.strategy}]`.trim();
       }
+      // Include error patterns in feedback context
+      if (errorStats.total > 0) {
+        const errorSummary = Object.entries(errorStats.by_type)
+          .map(([type, count]) => `${type}:${count}`)
+          .join(", ");
+        event.context =
+          `${event.context || ""} [errors: ${errorSummary}]`.trim();
+      }
       return event;
     });
 
@@ -1922,6 +1966,7 @@ export const swarm_record_outcome = tool({
           },
         },
         feedback_events: feedbackEvents,
+        error_patterns: errorStats,
         summary: {
           feedback_type: scored.type,
           duration_seconds: Math.round(args.duration_ms / 1000),
@@ -1929,6 +1974,8 @@ export const swarm_record_outcome = tool({
           retry_count: args.retry_count ?? 0,
           success: args.success,
           strategy: args.strategy,
+          accumulated_errors: errorStats.total,
+          unresolved_errors: errorStats.unresolved,
         },
         note: "Feedback events should be stored for criterion weight calculation. Use learning.ts functions to apply weights.",
       },
@@ -2209,6 +2256,144 @@ export const swarm_evaluation_prompt = tool({
   },
 });
 
+// ============================================================================
+// Error Accumulator
+// ============================================================================
+
+/**
+ * Global error accumulator for tracking errors across subtasks
+ *
+ * This is a session-level singleton that accumulates errors during
+ * swarm execution for feeding into retry prompts.
+ */
+const globalErrorAccumulator = new ErrorAccumulator();
+
+/**
+ * Record an error during subtask execution
+ *
+ * Implements pattern from "Patterns for Building AI Agents" p.40:
+ * "Good agents examine and correct errors when something goes wrong"
+ *
+ * Errors are accumulated and can be fed into retry prompts to help
+ * agents learn from past failures.
+ */
+export const swarm_accumulate_error = tool({
+  description:
+    "Record an error during subtask execution. Errors feed into retry prompts.",
+  args: {
+    bead_id: tool.schema.string().describe("Bead ID where error occurred"),
+    error_type: tool.schema
+      .enum(["validation", "timeout", "conflict", "tool_failure", "unknown"])
+      .describe("Category of error"),
+    message: tool.schema.string().describe("Human-readable error message"),
+    stack_trace: tool.schema
+      .string()
+      .optional()
+      .describe("Stack trace for debugging"),
+    tool_name: tool.schema.string().optional().describe("Tool that failed"),
+    context: tool.schema
+      .string()
+      .optional()
+      .describe("What was happening when error occurred"),
+  },
+  async execute(args) {
+    const entry = await globalErrorAccumulator.recordError(
+      args.bead_id,
+      args.error_type as ErrorType,
+      args.message,
+      {
+        stack_trace: args.stack_trace,
+        tool_name: args.tool_name,
+        context: args.context,
+      },
+    );
+
+    return JSON.stringify(
+      {
+        success: true,
+        error_id: entry.id,
+        bead_id: entry.bead_id,
+        error_type: entry.error_type,
+        message: entry.message,
+        timestamp: entry.timestamp,
+        note: "Error recorded for retry context. Use swarm_get_error_context to retrieve accumulated errors.",
+      },
+      null,
+      2,
+    );
+  },
+});
+
+/**
+ * Get accumulated errors for a bead to feed into retry prompts
+ *
+ * Returns formatted error context that can be injected into retry prompts
+ * to help agents learn from past failures.
+ */
+export const swarm_get_error_context = tool({
+  description:
+    "Get accumulated errors for a bead. Returns formatted context for retry prompts.",
+  args: {
+    bead_id: tool.schema.string().describe("Bead ID to get errors for"),
+    include_resolved: tool.schema
+      .boolean()
+      .optional()
+      .describe("Include resolved errors (default: false)"),
+  },
+  async execute(args) {
+    const errorContext = await globalErrorAccumulator.getErrorContext(
+      args.bead_id,
+      args.include_resolved ?? false,
+    );
+
+    const stats = await globalErrorAccumulator.getErrorStats(args.bead_id);
+
+    return JSON.stringify(
+      {
+        bead_id: args.bead_id,
+        error_context: errorContext,
+        stats: {
+          total_errors: stats.total,
+          unresolved: stats.unresolved,
+          by_type: stats.by_type,
+        },
+        has_errors: errorContext.length > 0,
+        usage:
+          "Inject error_context into retry prompt using {error_context} placeholder",
+      },
+      null,
+      2,
+    );
+  },
+});
+
+/**
+ * Mark an error as resolved
+ *
+ * Call this after an agent successfully addresses an error to update
+ * the accumulator state.
+ */
+export const swarm_resolve_error = tool({
+  description:
+    "Mark an error as resolved after fixing it. Updates error accumulator state.",
+  args: {
+    error_id: tool.schema.string().describe("Error ID to mark as resolved"),
+  },
+  async execute(args) {
+    await globalErrorAccumulator.resolveError(args.error_id);
+
+    return JSON.stringify(
+      {
+        success: true,
+        error_id: args.error_id,
+        resolved: true,
+      },
+      null,
+      2,
+    );
+  },
+});
+
 /**
  * Initialize swarm and check tool availability
  *
@@ -2315,4 +2500,7 @@ export const swarmTools = {
   swarm_spawn_subtask: swarm_spawn_subtask,
   swarm_complete_subtask: swarm_complete_subtask,
   swarm_evaluation_prompt: swarm_evaluation_prompt,
+  swarm_accumulate_error: swarm_accumulate_error,
+  swarm_get_error_context: swarm_get_error_context,
+  swarm_resolve_error: swarm_resolve_error,
 };

package/examples/agents/swarm-planner.md

@@ -1,138 +0,0 @@
----
-name: swarm-planner
-description: Strategic task decomposition for swarm coordination
-model: claude-sonnet-4-5
----
-
-You are a swarm planner. Your job is to decompose complex tasks into optimal parallel subtasks.
-
-## Your Role
-
-You analyze tasks and create decomposition plans that:
-
-- Maximize parallelization (agents work independently)
-- Minimize conflicts (no file overlap between subtasks)
-- Follow the best strategy for the task type
-
-## Workflow
-
-1. **Analyze** - Call `swarm_select_strategy` to understand the task
-2. **Plan** - Call `swarm_plan_prompt` to get strategy-specific guidance
-3. **Decompose** - Create a BeadTree following the guidelines
-4. **Validate** - Ensure no file conflicts or circular dependencies
-
-## Strategy Selection
-
-The plugin auto-selects strategies based on task keywords:
-
-| Strategy          | Best For                                     | Keywords                               |
-| ----------------- | -------------------------------------------- | -------------------------------------- |
-| **file-based**    | Refactoring, migrations, pattern changes     | refactor, migrate, rename, update all  |
-| **feature-based** | New features, adding functionality           | add, implement, build, create, feature |
-| **risk-based**    | Bug fixes, security issues, critical changes | fix, bug, security, critical, urgent   |
-
-You can override with explicit strategy if the auto-detection is wrong.
-
-## Output Format
-
-Return ONLY valid JSON matching the BeadTree schema:
-
-```json
-{
-  "epic": {
-    "title": "Epic title for beads tracker",
-    "description": "Brief description of the overall goal"
-  },
-  "subtasks": [
-    {
-      "title": "What this subtask accomplishes",
-      "description": "Detailed instructions for the agent",
-      "files": ["src/path/to/file.ts", "src/path/to/file.test.ts"],
-      "dependencies": [],
-      "estimated_complexity": 2
-    }
-  ]
-}
-```
-
-**CRITICAL**: Return ONLY the JSON. No markdown, no explanation, no code blocks.
-
-## Decomposition Rules
-
-1. **2-7 subtasks** - Too few = not parallel, too many = coordination overhead
-2. **No file overlap** - Each file appears in exactly one subtask
-3. **Include tests** - Put test files with the code they test
-4. **Order by dependency** - If B needs A's output, A comes first (lower index)
-5. **Estimate complexity** - 1 (trivial) to 5 (complex)
-
-## Anti-Patterns to Avoid
-
-- Don't split tightly coupled files across subtasks
-- Don't create subtasks that can't be tested independently
-- Don't forget shared types/utilities that multiple files depend on
-- Don't make one subtask do everything while others are trivial
-
-## Example Decomposition
-
-**Task**: "Add user authentication with OAuth"
-
-**Strategy**: feature-based (detected from "add" keyword)
-
-**Result**:
-
-```json
-{
-  "epic": {
-    "title": "Add user authentication with OAuth",
-    "description": "Implement OAuth-based authentication flow with session management"
-  },
-  "subtasks": [
-    {
-      "title": "Set up OAuth provider configuration",
-      "description": "Configure OAuth provider (Google/GitHub), add environment variables, create auth config",
-      "files": ["src/auth/config.ts", "src/auth/providers.ts", ".env.example"],
-      "dependencies": [],
-      "estimated_complexity": 2
-    },
-    {
-      "title": "Implement session management",
-      "description": "Create session store, JWT handling, cookie management",
-      "files": [
-        "src/auth/session.ts",
-        "src/auth/jwt.ts",
-        "src/middleware/auth.ts"
-      ],
-      "dependencies": [0],
-      "estimated_complexity": 3
-    },
-    {
-      "title": "Add protected route wrapper",
-      "description": "Create HOC/middleware for protecting routes, redirect logic",
-      "files": ["src/components/ProtectedRoute.tsx", "src/hooks/useAuth.ts"],
-      "dependencies": [1],
-      "estimated_complexity": 2
-    },
-    {
-      "title": "Create login/logout UI",
-      "description": "Login page, logout button, auth state display",
-      "files": ["src/app/login/page.tsx", "src/components/AuthButton.tsx"],
-      "dependencies": [0],
-      "estimated_complexity": 2
-    }
-  ]
-}
-```
-
-## Usage
-
-The coordinator invokes you like this:
-
-```
-@swarm-planner "Add user authentication with OAuth"
-```
-
-You respond with the BeadTree JSON. The coordinator then:
-
-1. Validates with `swarm_validate_decomposition`
-2. Creates beads with `beads_create_epic`
-3. Spawns worker agents for each subtask