opencode-swarm-plugin 0.35.0 → 0.36.1

package/src/planning-guardrails.ts

@@ -7,6 +7,8 @@
  * @module planning-guardrails
  */
 
+import { captureCoordinatorEvent } from "./eval-capture.js";
+
 /**
  * Patterns that suggest file modification work
  * These indicate the todo is about implementation, not tracking
@@ -147,3 +149,290 @@ Swarm workers can complete these ${fileModificationCount} tasks in parallel.
 export function shouldAnalyzeTool(toolName: string): boolean {
   return toolName === "todowrite" || toolName === "TodoWrite";
 }
+
+/**
+ * Violation patterns for coordinator behavior detection
+ *
+ * These patterns identify when a coordinator is performing work
+ * that should be delegated to worker agents.
+ *
+ * @example
+ * ```ts
+ * // Bad: Coordinator editing files
+ * if (VIOLATION_PATTERNS.FILE_MODIFICATION_TOOLS.includes("edit")) { ... }
+ *
+ * // Good: Worker editing files
+ * // (no violation when agentContext === "worker")
+ * ```
+ */
+export const VIOLATION_PATTERNS = {
+  /**
+   * Tool names that modify files
+   *
+   * Coordinators should NEVER call these tools directly.
+   * Workers reserve files and make modifications.
+   */
+  FILE_MODIFICATION_TOOLS: ["edit", "write"],
+
+  /**
+   * Tool names for file reservations
+   *
+   * Coordinators don't reserve files - workers do this
+   * before editing to prevent conflicts.
+   */
+  RESERVATION_TOOLS: ["swarmmail_reserve", "agentmail_reserve"],
+
+  /**
+   * Regex patterns that indicate test execution in bash commands
+   *
+   * Coordinators review test results, workers run tests.
+   * Matches common test runners and test file patterns.
+   */
+  TEST_EXECUTION_PATTERNS: [
+    /\bbun\s+test\b/i,
+    /\bnpm\s+(run\s+)?test/i,
+    /\byarn\s+(run\s+)?test/i,
+    /\bpnpm\s+(run\s+)?test/i,
+    /\bjest\b/i,
+    /\bvitest\b/i,
+    /\bmocha\b/i,
+    /\bava\b/i,
+    /\btape\b/i,
+    /\.test\.(ts|js|tsx|jsx)\b/i,
+    /\.spec\.(ts|js|tsx|jsx)\b/i,
+  ],
+} as const;
+
+/**
+ * Result of violation detection
+ */
+export interface ViolationDetectionResult {
+  /** Whether a violation was detected */
+  isViolation: boolean;
+
+  /** Type of violation if detected */
+  violationType?:
+    | "coordinator_edited_file"
+    | "coordinator_ran_tests"
+    | "coordinator_reserved_files"
+    | "no_worker_spawned";
+
+  /** Human-readable message */
+  message?: string;
+
+  /** Payload data for the violation */
+  payload?: Record<string, unknown>;
+}
+
+/**
+ * Detect coordinator violations in real-time
+ *
+ * Checks for patterns that indicate a coordinator is doing work
+ * that should be delegated to workers:
+ * 1. Edit/Write tool calls (coordinators plan, workers implement)
+ * 2. Test execution (workers verify, coordinators review)
+ * 3. File reservations (workers reserve before editing)
+ * 4. No worker spawned after decomposition (coordinators must delegate)
+ *
+ * When a violation is detected, captures it via captureCoordinatorEvent().
+ *
+ * @param params - Detection parameters
+ * @returns Violation detection result
+ */
+export function detectCoordinatorViolation(params: {
+  sessionId: string;
+  epicId: string;
+  toolName: string;
+  toolArgs: Record<string, unknown>;
+  agentContext: "coordinator" | "worker";
+  checkNoSpawn?: boolean;
+}): ViolationDetectionResult {
+  const { sessionId, epicId, toolName, toolArgs, agentContext, checkNoSpawn = false } = params;
+
+  // Only check coordinator violations
+  if (agentContext !== "coordinator") {
+    return { isViolation: false };
+  }
+
+  // Check for file modification violation
+  if (VIOLATION_PATTERNS.FILE_MODIFICATION_TOOLS.includes(toolName as any)) {
+    const file = (toolArgs.filePath as string) || "";
+    const payload = { tool: toolName, file };
+
+    captureCoordinatorEvent({
+      session_id: sessionId,
+      epic_id: epicId,
+      timestamp: new Date().toISOString(),
+      event_type: "VIOLATION",
+      violation_type: "coordinator_edited_file",
+      payload,
+    });
+
+    return {
+      isViolation: true,
+      violationType: "coordinator_edited_file",
+      message: `⚠️ Coordinator should not edit files directly. Coordinators should spawn workers to implement changes.`,
+      payload,
+    };
+  }
+
+  // Check for test execution violation
+  if (toolName === "bash") {
+    const command = (toolArgs.command as string) || "";
+    const isTestCommand = VIOLATION_PATTERNS.TEST_EXECUTION_PATTERNS.some((pattern) =>
+      pattern.test(command),
+    );
+
+    if (isTestCommand) {
+      const payload = { tool: toolName, command };
+
+      captureCoordinatorEvent({
+        session_id: sessionId,
+        epic_id: epicId,
+        timestamp: new Date().toISOString(),
+        event_type: "VIOLATION",
+        violation_type: "coordinator_ran_tests",
+        payload,
+      });
+
+      return {
+        isViolation: true,
+        violationType: "coordinator_ran_tests",
+        message: `⚠️ Coordinator should not run tests directly. Workers run tests as part of their implementation verification.`,
+        payload,
+      };
+    }
+  }
+
+  // Check for file reservation violation
+  if (VIOLATION_PATTERNS.RESERVATION_TOOLS.includes(toolName as any)) {
+    const paths = (toolArgs.paths as string[]) || [];
+    const payload = { tool: toolName, paths };
+
+    captureCoordinatorEvent({
+      session_id: sessionId,
+      epic_id: epicId,
+      timestamp: new Date().toISOString(),
+      event_type: "VIOLATION",
+      violation_type: "coordinator_reserved_files",
+      payload,
+    });
+
+    return {
+      isViolation: true,
+      violationType: "coordinator_reserved_files",
+      message: `⚠️ Coordinator should not reserve files. Workers reserve files before editing to prevent conflicts.`,
+      payload,
+    };
+  }
+
+  // Check for no worker spawned after decomposition
+  if (toolName === "hive_create_epic" && checkNoSpawn) {
+    const epicTitle = (toolArgs.epic_title as string) || "";
+    const subtasks = (toolArgs.subtasks as unknown[]) || [];
+    const payload = { epic_title: epicTitle, subtask_count: subtasks.length };
+
+    captureCoordinatorEvent({
+      session_id: sessionId,
+      epic_id: epicId,
+      timestamp: new Date().toISOString(),
+      event_type: "VIOLATION",
+      violation_type: "no_worker_spawned",
+      payload,
+    });
+
+    return {
+      isViolation: true,
+      violationType: "no_worker_spawned",
+      message: `⚠️ Coordinator created decomposition without spawning workers. After hive_create_epic, use swarm_spawn_subtask for each task.`,
+      payload,
+    };
+  }
+
+  return { isViolation: false };
+}
+
+/**
+ * Coordinator context state
+ * 
+ * Tracks whether the current session is acting as a swarm coordinator.
+ * Set when an epic is created or when swarm tools are used.
+ */
+interface CoordinatorContext {
+  /** Whether we're in coordinator mode */
+  isCoordinator: boolean;
+  /** Active epic ID if any */
+  epicId?: string;
+  /** Session ID for event capture */
+  sessionId?: string;
+  /** When coordinator mode was activated */
+  activatedAt?: number;
+}
+
+/** Global coordinator context state */
+let coordinatorContext: CoordinatorContext = {
+  isCoordinator: false,
+};
+
+/**
+ * Set coordinator context
+ * 
+ * Called when swarm coordination begins (e.g., after hive_create_epic or swarm_decompose).
+ * 
+ * @param ctx - Coordinator context to set
+ */
+export function setCoordinatorContext(ctx: Partial<CoordinatorContext>): void {
+  coordinatorContext = {
+    ...coordinatorContext,
+    ...ctx,
+    activatedAt: ctx.isCoordinator ? Date.now() : coordinatorContext.activatedAt,
+  };
+}
+
+/**
+ * Get current coordinator context
+ * 
+ * @returns Current coordinator context state
+ */
+export function getCoordinatorContext(): CoordinatorContext {
+  return { ...coordinatorContext };
+}
+
+/**
+ * Clear coordinator context
+ * 
+ * Called when swarm coordination ends (e.g., epic closed or session ends).
+ */
+export function clearCoordinatorContext(): void {
+  coordinatorContext = {
+    isCoordinator: false,
+  };
+}
+
+/**
+ * Check if we're in coordinator context
+ * 
+ * Returns true if:
+ * 1. Coordinator context was explicitly set
+ * 2. Context was set within the last 4 hours (session timeout)
+ * 
+ * @returns Whether we're currently in coordinator mode
+ */
+export function isInCoordinatorContext(): boolean {
+  if (!coordinatorContext.isCoordinator) {
+    return false;
+  }
+  
+  // Check for session timeout (4 hours)
+  const COORDINATOR_TIMEOUT_MS = 4 * 60 * 60 * 1000;
+  if (coordinatorContext.activatedAt) {
+    const elapsed = Date.now() - coordinatorContext.activatedAt;
+    if (elapsed > COORDINATOR_TIMEOUT_MS) {
+      // Session timed out, clear context
+      clearCoordinatorContext();
+      return false;
+    }
+  }
+  
+  return true;
+}

package/src/plugin.ts

@@ -1,23 +1,23 @@
 /**
  * OpenCode Plugin Entry Point
  *
- * CRITICAL: Only export the plugin function from this file.
+ * CRITICAL: Only export the plugin function as DEFAULT from this file.
  *
  * OpenCode's plugin loader calls ALL exports as functions during initialization.
- * Exporting classes, constants, or non-function values will cause the plugin
- * to fail to load with cryptic errors.
+ * If you export both named AND default pointing to the same function, the plugin
+ * gets registered TWICE, causing hooks to fire multiple times.
  *
  * If you need to export utilities for external use, add them to src/index.ts instead.
  *
  * @example
- * // ✅ CORRECT - only export the plugin function
+ * // ✅ CORRECT - only default export
  * export default SwarmPlugin;
  *
- * // ❌ WRONG - will break plugin loading
- * export const VERSION = "1.0.0";
- * export class Helper {}
+ * // ❌ WRONG - causes double registration
+ * export { SwarmPlugin };
+ * export default SwarmPlugin;
  */
-import { SwarmPlugin } from "./index";
+import SwarmPlugin from "./index";
 
-// Only export the plugin function - nothing else!
-export { SwarmPlugin };
+// Only default export - no named exports!
+export default SwarmPlugin;

package/src/schemas/task.ts

@@ -87,7 +87,6 @@ export type TaskDecomposition = z.infer<typeof TaskDecompositionSchema>;
  */
 export const DecomposeArgsSchema = z.object({
   task: z.string().min(1),
-  max_subtasks: z.number().int().min(1).default(5),
   context: z.string().optional(),
 });
 export type DecomposeArgs = z.infer<typeof DecomposeArgsSchema>;

package/src/swarm-decompose.ts

@@ -20,6 +20,7 @@ import {
   NEGATIVE_MARKERS,
   type DecompositionStrategy,
 } from "./swarm-strategies";
+import { captureCoordinatorEvent } from "./eval-capture.js";
 
 // ============================================================================
 // Decomposition Prompt (temporary - will be moved to swarm-prompts.ts)
@@ -690,12 +691,6 @@ export const swarm_delegate_planning = tool({
       .string()
       .optional()
       .describe("Additional context to include"),
-    max_subtasks: tool.schema
-      .number()
-      .int()
-      .min(1)
-      .optional()
-      .describe("Suggested max subtasks (optional - LLM decides if not specified)"),
     strategy: tool.schema
       .enum(["auto", "file-based", "feature-based", "risk-based"])
       .optional()
@@ -728,6 +723,25 @@ export const swarm_delegate_planning = tool({
       strategyReasoning = selection.reasoning;
     }
 
+    // Capture strategy selection decision
+    try {
+      captureCoordinatorEvent({
+        session_id: process.env.OPENCODE_SESSION_ID || "unknown",
+        epic_id: "planning", // No epic ID yet - this is pre-decomposition
+        timestamp: new Date().toISOString(),
+        event_type: "DECISION",
+        decision_type: "strategy_selected",
+        payload: {
+          strategy: selectedStrategy,
+          reasoning: strategyReasoning,
+          task_preview: args.task.slice(0, 100),
+        },
+      });
+    } catch (error) {
+      // Non-fatal - don't block planning if capture fails
+      console.warn("[swarm_delegate_planning] Failed to capture strategy_selected:", error);
+    }
+
     // Query CASS for similar past tasks
     let cassContext = "";
     let cassResultInfo: {
@@ -797,8 +811,7 @@ export const swarm_delegate_planning = tool({
       .replace("{strategy_guidelines}", strategyGuidelines)
       .replace("{context_section}", contextSection)
       .replace("{cass_history}", cassContext || "")
-      .replace("{skills_context}", skillsContext || "")
-      .replace("{max_subtasks}", (args.max_subtasks ?? 5).toString());
+      .replace("{skills_context}", skillsContext || "");
 
     // Add strict JSON-only instructions for the subagent
     const subagentInstructions = `

package/src/swarm-orchestrate.ts

@@ -83,6 +83,7 @@ import {
   isReviewApproved,
   getReviewStatus,
 } from "./swarm-review";
+import { captureCoordinatorEvent } from "./eval-capture.js";
 
 // ============================================================================
 // Helper Functions
@@ -1709,6 +1710,28 @@ Files touched: ${args.files_touched?.join(", ") || "none recorded"}`,
             },
       };
 
+      // Capture subtask completion outcome
+      try {
+        const durationMs = args.start_time ? Date.now() - args.start_time : 0;
+        captureCoordinatorEvent({
+          session_id: process.env.OPENCODE_SESSION_ID || "unknown",
+          epic_id: epicId,
+          timestamp: new Date().toISOString(),
+          event_type: "OUTCOME",
+          outcome_type: "subtask_success",
+          payload: {
+            bead_id: args.bead_id,
+            duration_ms: durationMs,
+            files_touched: args.files_touched || [],
+            verification_passed: verificationResult?.passed ?? false,
+            verification_skipped: args.skip_verification ?? false,
+          },
+        });
+      } catch (error) {
+        // Non-fatal - don't block completion if capture fails
+        console.warn("[swarm_complete] Failed to capture subtask_success:", error);
+      }
+
       return JSON.stringify(response, null, 2);
     } catch (error) {
       // CRITICAL: Notify coordinator of failure via swarm mail
@@ -1796,6 +1819,27 @@ Files touched: ${args.files_touched?.join(", ") || "none recorded"}`,
         console.error(`[swarm_complete] Original error:`, error);
       }
 
+      // Capture subtask failure outcome
+      try {
+        const durationMs = args.start_time ? Date.now() - args.start_time : 0;
+        captureCoordinatorEvent({
+          session_id: process.env.OPENCODE_SESSION_ID || "unknown",
+          epic_id: epicId,
+          timestamp: new Date().toISOString(),
+          event_type: "OUTCOME",
+          outcome_type: "subtask_failed",
+          payload: {
+            bead_id: args.bead_id,
+            duration_ms: durationMs,
+            failed_step: failedStep,
+            error_message: errorMessage.slice(0, 500),
+          },
+        });
+      } catch (captureError) {
+        // Non-fatal - don't block error return if capture fails
+        console.warn("[swarm_complete] Failed to capture subtask_failed:", captureError);
+      }
+
       // Return structured error instead of throwing
       // This ensures the agent sees the actual error message
       return JSON.stringify(

package/src/swarm-prompts.ts

@@ -14,6 +14,7 @@
 
 import { tool } from "@opencode-ai/plugin";
 import { generateWorkerHandoff } from "./swarm-orchestrate";
+import { captureCoordinatorEvent } from "./eval-capture.js";
 
 // ============================================================================
 // Prompt Templates
@@ -1107,6 +1108,25 @@ export const swarm_spawn_subtask = tool({
       .replace(/{files_touched}/g, filesJoined)
       .replace(/{worker_id}/g, "worker");  // Will be filled by actual worker name
 
+    // Capture worker spawn decision
+    try {
+      captureCoordinatorEvent({
+        session_id: process.env.OPENCODE_SESSION_ID || "unknown",
+        epic_id: args.epic_id,
+        timestamp: new Date().toISOString(),
+        event_type: "DECISION",
+        decision_type: "worker_spawned",
+        payload: {
+          bead_id: args.bead_id,
+          files: args.files,
+          worker_model: selectedModel,
+        },
+      });
+    } catch (error) {
+      // Non-fatal - don't block spawn if capture fails
+      console.warn("[swarm_spawn_subtask] Failed to capture worker_spawned:", error);
+    }
+
     return JSON.stringify(
       {
         prompt,

package/src/swarm-review.ts

@@ -18,6 +18,7 @@ import { tool } from "@opencode-ai/plugin";
 import { z } from "zod";
 import { sendSwarmMessage, type HiveAdapter } from "swarm-mail";
 import { getHiveAdapter } from "./hive";
+import { captureCoordinatorEvent } from "./eval-capture.js";
 
 // ============================================================================
 // Types & Schemas
@@ -508,6 +509,25 @@ export const swarm_review_feedback = tool({
       // Mark as approved and clear attempts
       markReviewApproved(args.task_id);
 
+      // Capture review approval decision
+      try {
+        captureCoordinatorEvent({
+          session_id: process.env.OPENCODE_SESSION_ID || "unknown",
+          epic_id: epicId,
+          timestamp: new Date().toISOString(),
+          event_type: "DECISION",
+          decision_type: "review_completed",
+          payload: {
+            task_id: args.task_id,
+            status: "approved",
+            retry_count: 0,
+          },
+        });
+      } catch (error) {
+        // Non-fatal - don't block approval if capture fails
+        console.warn("[swarm_review_feedback] Failed to capture review_completed:", error);
+      }
+
       // Send approval message
       await sendSwarmMessage({
         projectPath: args.project_key,
@@ -539,6 +559,27 @@ You may now complete the task with \`swarm_complete\`.`,
     const attemptNumber = incrementAttempt(args.task_id);
     const remaining = MAX_REVIEW_ATTEMPTS - attemptNumber;
 
+    // Capture review rejection decision
+    try {
+      captureCoordinatorEvent({
+        session_id: process.env.OPENCODE_SESSION_ID || "unknown",
+        epic_id: epicId,
+        timestamp: new Date().toISOString(),
+        event_type: "DECISION",
+        decision_type: "review_completed",
+        payload: {
+          task_id: args.task_id,
+          status: "needs_changes",
+          retry_count: attemptNumber,
+          remaining_attempts: remaining,
+          issues_count: parsedIssues.length,
+        },
+      });
+    } catch (error) {
+      // Non-fatal - don't block feedback if capture fails
+      console.warn("[swarm_review_feedback] Failed to capture review_completed:", error);
+    }
+
     // Check if task should fail
     if (remaining <= 0) {
       // Mark task as blocked using HiveAdapter

package/src/swarm.integration.test.ts

@@ -79,7 +79,6 @@ describe("swarm_decompose", () => {
     const result = await swarm_decompose.execute(
       {
         task: "Add user authentication with OAuth",
-        max_subtasks: 3,
       },
       mockContext,
     );
@@ -97,7 +96,6 @@ describe("swarm_decompose", () => {
     const result = await swarm_decompose.execute(
       {
         task: "Refactor the API routes",
-        max_subtasks: 5,
         context: "Using Next.js App Router with RSC",
       },
       mockContext,
@@ -109,20 +107,6 @@ describe("swarm_decompose", () => {
     expect(parsed.prompt).toContain("Additional Context");
   });
 
-  it("uses default max_subtasks when not provided", async () => {
-    const result = await swarm_decompose.execute(
-      {
-        task: "Simple task",
-        max_subtasks: 5, // Explicit default since schema requires it
-      },
-      mockContext,
-    );
-
-    const parsed = JSON.parse(result);
-
-    // Prompt should say "as many as needed" (max_subtasks no longer in template)
-    expect(parsed.prompt).toContain("as many as needed");
-  });
 });
 
 // ============================================================================
@@ -262,7 +246,6 @@ describe("swarm_plan_prompt", () => {
     const result = await swarm_plan_prompt.execute(
       {
         task: "Add user settings page",
-        max_subtasks: 3,
         query_cass: false, // Disable CASS to isolate test
       },
       mockContext,
@@ -281,7 +264,6 @@ describe("swarm_plan_prompt", () => {
       {
         task: "Do something",
         strategy: "risk-based",
-        max_subtasks: 3,
         query_cass: false,
       },
       mockContext,
@@ -296,7 +278,6 @@ describe("swarm_plan_prompt", () => {
     const result = await swarm_plan_prompt.execute(
       {
         task: "Refactor the codebase",
-        max_subtasks: 4,
         query_cass: false,
       },
       mockContext,
@@ -314,7 +295,6 @@ describe("swarm_plan_prompt", () => {
     const result = await swarm_plan_prompt.execute(
       {
         task: "Build new feature",
-        max_subtasks: 3,
         query_cass: false,
       },
       mockContext,
@@ -330,7 +310,6 @@ describe("swarm_plan_prompt", () => {
     const result = await swarm_plan_prompt.execute(
       {
         task: "Some task",
-        max_subtasks: 5,
         query_cass: false,
       },
       mockContext,
@@ -350,7 +329,6 @@ describe("swarm_plan_prompt", () => {
     const result = await swarm_plan_prompt.execute(
       {
         task: "Add feature",
-        max_subtasks: 3,
       },
       mockContext,
     );
@@ -375,7 +353,6 @@ describe("swarm_plan_prompt", () => {
     const result = await swarm_plan_prompt.execute(
       {
         task: "Add user profile",
-        max_subtasks: 3,
         context: "We use Next.js App Router with server components",
         query_cass: false,
       },
@@ -387,19 +364,6 @@ describe("swarm_plan_prompt", () => {
     expect(parsed.prompt).toContain("server components");
   });
 
-  it("includes max_subtasks in prompt", async () => {
-    const result = await swarm_plan_prompt.execute(
-      {
-        task: "Build something",
-        max_subtasks: 7,
-        query_cass: false,
-      },
-      mockContext,
-    );
-    const parsed = JSON.parse(result);
-
-    expect(parsed.prompt).toContain("as many as needed");
-  });
 });
 
 describe("swarm_validate_decomposition", () => {
@@ -920,7 +884,6 @@ describe("full swarm flow (integration)", () => {
         const decomposeResult = await swarm_decompose.execute(
           {
             task: "Add unit tests for auth module",
-            max_subtasks: 2,
           },
           ctx,
         );
@@ -1228,7 +1191,6 @@ describe("swarm_init", () => {
     const result = await swarm_decompose.execute(
       {
         task: "Add user authentication",
-        max_subtasks: 3,
         query_cass: true, // Request CASS but it may not be available
       },
       mockContext,
@@ -1249,7 +1211,6 @@ describe("swarm_init", () => {
     const result = await swarm_decompose.execute(
       {
         task: "Add user authentication",
-        max_subtasks: 3,
         query_cass: false, // Explicitly skip CASS
       },
       mockContext,
@@ -1264,7 +1225,6 @@ describe("swarm_init", () => {
     const result = await swarm_decompose.execute(
       {
         task: "Build feature X",
-        max_subtasks: 3,
       },
       mockContext,
     );