opencode-swarm-plugin 0.12.6 → 0.12.7

package/src/learning.ts

@@ -64,6 +64,46 @@ export const CriterionWeightSchema = z.object({
 });
 export type CriterionWeight = z.infer<typeof CriterionWeightSchema>;
 
+/**
+ * Error types that can occur during subtask execution
+ */
+export const ErrorTypeSchema = z.enum([
+  "validation",
+  "timeout",
+  "conflict",
+  "tool_failure",
+  "unknown",
+]);
+export type ErrorType = z.infer<typeof ErrorTypeSchema>;
+
+/**
+ * An error entry in the error accumulator
+ *
+ * Errors are accumulated during subtask execution and can be fed
+ * into retry prompts to help agents learn from past failures.
+ */
+export const ErrorEntrySchema = z.object({
+  /** Unique ID for this error entry */
+  id: z.string(),
+  /** The bead ID this error relates to */
+  bead_id: z.string(),
+  /** Type of error encountered */
+  error_type: ErrorTypeSchema,
+  /** Human-readable error message */
+  message: z.string(),
+  /** Optional stack trace for debugging */
+  stack_trace: z.string().optional(),
+  /** Tool that failed, if applicable */
+  tool_name: z.string().optional(),
+  /** When this error occurred */
+  timestamp: z.string(), // ISO-8601
+  /** Whether this error was resolved */
+  resolved: z.boolean().default(false),
+  /** Context about what was happening when error occurred */
+  context: z.string().optional(),
+});
+export type ErrorEntry = z.infer<typeof ErrorEntrySchema>;
+
 /**
  * Decomposition strategies for tracking which approach was used
  */
@@ -437,6 +477,241 @@ export class InMemoryFeedbackStorage implements FeedbackStorage {
   }
 }
 
+// ============================================================================
+// Error Accumulator
+// ============================================================================
+
+/**
+ * Storage interface for error entries
+ *
+ * Similar to FeedbackStorage but for tracking errors during execution.
+ */
+export interface ErrorStorage {
+  /** Store an error entry */
+  store(entry: ErrorEntry): Promise<void>;
+  /** Get all errors for a bead */
+  getByBead(beadId: string): Promise<ErrorEntry[]>;
+  /** Get unresolved errors for a bead */
+  getUnresolvedByBead(beadId: string): Promise<ErrorEntry[]>;
+  /** Mark an error as resolved */
+  markResolved(id: string): Promise<void>;
+  /** Get all errors */
+  getAll(): Promise<ErrorEntry[]>;
+}
+
+/**
+ * In-memory error storage
+ *
+ * Accumulates errors during subtask execution for feeding into retry prompts.
+ */
+export class InMemoryErrorStorage implements ErrorStorage {
+  private errors: ErrorEntry[] = [];
+
+  async store(entry: ErrorEntry): Promise<void> {
+    this.errors.push(entry);
+  }
+
+  async getByBead(beadId: string): Promise<ErrorEntry[]> {
+    return this.errors.filter((e) => e.bead_id === beadId);
+  }
+
+  async getUnresolvedByBead(beadId: string): Promise<ErrorEntry[]> {
+    return this.errors.filter((e) => e.bead_id === beadId && !e.resolved);
+  }
+
+  async markResolved(id: string): Promise<void> {
+    const error = this.errors.find((e) => e.id === id);
+    if (error) {
+      error.resolved = true;
+    }
+  }
+
+  async getAll(): Promise<ErrorEntry[]> {
+    return [...this.errors];
+  }
+}
+
+/**
+ * Error accumulator for tracking errors during subtask execution
+ *
+ * Implements patterns from "Patterns for Building AI Agents" p.40:
+ * - Examines and corrects errors when something goes wrong
+ * - Feeds error context into retry prompts
+ * - Tracks error patterns for learning
+ */
+export class ErrorAccumulator {
+  private storage: ErrorStorage;
+
+  constructor(storage?: ErrorStorage) {
+    this.storage = storage ?? new InMemoryErrorStorage();
+  }
+
+  /**
+   * Record an error during subtask execution
+   *
+   * @param beadId - Bead ID where error occurred
+   * @param errorType - Category of error
+   * @param message - Human-readable error message
+   * @param options - Additional context (stack trace, tool name, etc.)
+   * @returns The created error entry
+   */
+  async recordError(
+    beadId: string,
+    errorType: ErrorType,
+    message: string,
+    options?: {
+      stack_trace?: string;
+      tool_name?: string;
+      context?: string;
+    },
+  ): Promise<ErrorEntry> {
+    const entry: ErrorEntry = {
+      id: `${beadId}-${errorType}-${Date.now()}`,
+      bead_id: beadId,
+      error_type: errorType,
+      message,
+      stack_trace: options?.stack_trace,
+      tool_name: options?.tool_name,
+      timestamp: new Date().toISOString(),
+      resolved: false,
+      context: options?.context,
+    };
+
+    const validated = ErrorEntrySchema.parse(entry);
+    await this.storage.store(validated);
+
+    return validated;
+  }
+
+  /**
+   * Get all errors for a bead (resolved and unresolved)
+   */
+  async getErrors(beadId: string): Promise<ErrorEntry[]> {
+    return this.storage.getByBead(beadId);
+  }
+
+  /**
+   * Get only unresolved errors for a bead
+   */
+  async getUnresolvedErrors(beadId: string): Promise<ErrorEntry[]> {
+    return this.storage.getUnresolvedByBead(beadId);
+  }
+
+  /**
+   * Mark an error as resolved
+   */
+  async resolveError(errorId: string): Promise<void> {
+    await this.storage.markResolved(errorId);
+  }
+
+  /**
+   * Format errors as context for retry prompts
+   *
+   * Groups errors by type and provides structured feedback
+   * for the agent to learn from.
+   *
+   * @param beadId - Bead to get error context for
+   * @param includeResolved - Include resolved errors (default: false)
+   * @returns Formatted error context string
+   */
+  async getErrorContext(
+    beadId: string,
+    includeResolved = false,
+  ): Promise<string> {
+    const errors = includeResolved
+      ? await this.getErrors(beadId)
+      : await this.getUnresolvedErrors(beadId);
+
+    if (errors.length === 0) {
+      return "";
+    }
+
+    // Group errors by type
+    const byType = errors.reduce(
+      (acc, err) => {
+        const type = err.error_type;
+        if (!acc[type]) {
+          acc[type] = [];
+        }
+        acc[type].push(err);
+        return acc;
+      },
+      {} as Record<ErrorType, ErrorEntry[]>,
+    );
+
+    // Format as structured feedback
+    const lines = [
+      "## Previous Errors",
+      "",
+      "The following errors were encountered during execution:",
+      "",
+    ];
+
+    for (const [type, typeErrors] of Object.entries(byType)) {
+      lines.push(
+        `### ${type} (${typeErrors.length} error${typeErrors.length > 1 ? "s" : ""})`,
+      );
+      lines.push("");
+
+      for (const err of typeErrors) {
+        lines.push(`- **${err.message}**`);
+        if (err.context) {
+          lines.push(`  - Context: ${err.context}`);
+        }
+        if (err.tool_name) {
+          lines.push(`  - Tool: ${err.tool_name}`);
+        }
+        if (err.stack_trace) {
+          lines.push(`  - Stack: \`${err.stack_trace.slice(0, 100)}...\``);
+        }
+        lines.push(
+          `  - Time: ${new Date(err.timestamp).toLocaleString()}${err.resolved ? " (resolved)" : ""}`,
+        );
+        lines.push("");
+      }
+    }
+
+    lines.push(
+      "**Action Required**: Address these errors before proceeding. Consider:",
+    );
+    lines.push("- What caused each error?");
+    lines.push("- How can you prevent similar errors?");
+    lines.push("- Are there patterns across error types?");
+    lines.push("");
+
+    return lines.join("\n");
+  }
+
+  /**
+   * Get error statistics for outcome tracking
+   *
+   * @param beadId - Bead to get stats for
+   * @returns Error counts and patterns
+   */
+  async getErrorStats(beadId: string): Promise<{
+    total: number;
+    unresolved: number;
+    by_type: Record<ErrorType, number>;
+  }> {
+    const allErrors = await this.getErrors(beadId);
+    const unresolved = await this.getUnresolvedErrors(beadId);
+
+    const byType = allErrors.reduce(
+      (acc, err) => {
+        acc[err.error_type] = (acc[err.error_type] || 0) + 1;
+        return acc;
+      },
+      {} as Record<ErrorType, number>,
+    );
+
+    return {
+      total: allErrors.length,
+      unresolved: unresolved.length,
+      by_type: byType,
+    };
+  }
+}
+
 // ============================================================================
 // Exports
 // ============================================================================
@@ -448,4 +723,6 @@ export const learningSchemas = {
   OutcomeSignalsSchema,
   ScoredOutcomeSchema,
   DecompositionStrategySchema,
+  ErrorTypeSchema,
+  ErrorEntrySchema,
 };

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);
 }
 
 /**
@@ -1906,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",
@@ -1920,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;
     });
 
@@ -1935,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),
@@ -1942,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.",
       },
@@ -2222,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
  *
@@ -2328,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,
 };