opencode-swarm-plugin 0.12.6 → 0.12.8

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",
 };
@@ -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;
             }
@@ -880,30 +901,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}`,
+        );
+
+        // 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;
+        }
+      }
+    }
 
-    return JSON.stringify({ project, agent, available: true }, null, 2);
+    // 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,
+    );
   },
 });
 
@@ -1270,7 +1349,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) {
@@ -1279,6 +1363,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
 // ============================================================================
@@ -1294,6 +1445,7 @@ export const agentMailTools = {
   agentmail_ack: agentmail_ack,
   agentmail_search: agentmail_search,
   agentmail_health: agentmail_health,
+  agentmail_restart: agentmail_restart,
 };
 
 // ============================================================================

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,
 };