opencode-swarm-plugin 0.36.0 → 0.37.0

package/src/planning-guardrails.test.ts

@@ -1,5 +1,17 @@
-import { describe, it, expect } from "bun:test";
-import { analyzeTodoWrite, shouldAnalyzeTool } from "./planning-guardrails";
+import { describe, it, expect, beforeEach, afterEach } from "bun:test";
+import {
+  analyzeTodoWrite,
+  shouldAnalyzeTool,
+  detectCoordinatorViolation,
+  setCoordinatorContext,
+  getCoordinatorContext,
+  clearCoordinatorContext,
+  isInCoordinatorContext,
+  type ViolationDetectionResult,
+} from "./planning-guardrails";
+import * as fs from "node:fs";
+import * as path from "node:path";
+import * as os from "os";
 
 describe("planning-guardrails", () => {
   describe("shouldAnalyzeTool", () => {
@@ -103,4 +115,377 @@ describe("planning-guardrails", () => {
       expect(result.totalCount).toBe(6);
     });
   });
+
+  describe("detectCoordinatorViolation", () => {
+    const sessionId = "test-session-123";
+    const epicId = "test-epic-456";
+
+    // Clean up session files after tests
+    afterEach(() => {
+      const sessionDir = path.join(os.homedir(), ".config", "swarm-tools", "sessions");
+      const sessionPath = path.join(sessionDir, `${sessionId}.jsonl`);
+      if (fs.existsSync(sessionPath)) {
+        fs.unlinkSync(sessionPath);
+      }
+    });
+
+    describe("coordinator_edited_file violation", () => {
+      it("detects Edit tool call from coordinator", () => {
+        const result = detectCoordinatorViolation({
+          sessionId,
+          epicId,
+          toolName: "edit",
+          toolArgs: { filePath: "/path/to/file.ts", oldString: "old", newString: "new" },
+          agentContext: "coordinator",
+        });
+
+        expect(result.isViolation).toBe(true);
+        expect(result.violationType).toBe("coordinator_edited_file");
+        expect(result.message).toContain("Coordinators should spawn workers");
+        expect(result.payload.tool).toBe("edit");
+        expect(result.payload.file).toBe("/path/to/file.ts");
+      });
+
+      it("detects Write tool call from coordinator", () => {
+        const result = detectCoordinatorViolation({
+          sessionId,
+          epicId,
+          toolName: "write",
+          toolArgs: { filePath: "/path/to/new-file.ts", content: "export const foo = 1;" },
+          agentContext: "coordinator",
+        });
+
+        expect(result.isViolation).toBe(true);
+        expect(result.violationType).toBe("coordinator_edited_file");
+        expect(result.message).toContain("Coordinators should spawn workers");
+        expect(result.payload.tool).toBe("write");
+        expect(result.payload.file).toBe("/path/to/new-file.ts");
+      });
+
+      it("does not detect edit from worker agent", () => {
+        const result = detectCoordinatorViolation({
+          sessionId,
+          epicId,
+          toolName: "edit",
+          toolArgs: { filePath: "/path/to/file.ts", oldString: "old", newString: "new" },
+          agentContext: "worker",
+        });
+
+        expect(result.isViolation).toBe(false);
+      });
+
+      it("does not detect Read tool (read-only)", () => {
+        const result = detectCoordinatorViolation({
+          sessionId,
+          epicId,
+          toolName: "read",
+          toolArgs: { filePath: "/path/to/file.ts" },
+          agentContext: "coordinator",
+        });
+
+        expect(result.isViolation).toBe(false);
+      });
+    });
+
+    describe("coordinator_ran_tests violation", () => {
+      it("detects bash test execution from coordinator", () => {
+        const result = detectCoordinatorViolation({
+          sessionId,
+          epicId,
+          toolName: "bash",
+          toolArgs: { command: "bun test src/module.test.ts" },
+          agentContext: "coordinator",
+        });
+
+        expect(result.isViolation).toBe(true);
+        expect(result.violationType).toBe("coordinator_ran_tests");
+        expect(result.message).toContain("Workers run tests");
+        expect(result.payload.command).toContain("bun test");
+      });
+
+      it("detects npm test from coordinator", () => {
+        const result = detectCoordinatorViolation({
+          sessionId,
+          epicId,
+          toolName: "bash",
+          toolArgs: { command: "npm run test:unit" },
+          agentContext: "coordinator",
+        });
+
+        expect(result.isViolation).toBe(true);
+        expect(result.violationType).toBe("coordinator_ran_tests");
+      });
+
+      it("detects jest from coordinator", () => {
+        const result = detectCoordinatorViolation({
+          sessionId,
+          epicId,
+          toolName: "bash",
+          toolArgs: { command: "jest --coverage" },
+          agentContext: "coordinator",
+        });
+
+        expect(result.isViolation).toBe(true);
+        expect(result.violationType).toBe("coordinator_ran_tests");
+      });
+
+      it("does not detect non-test bash commands", () => {
+        const result = detectCoordinatorViolation({
+          sessionId,
+          epicId,
+          toolName: "bash",
+          toolArgs: { command: "git status" },
+          agentContext: "coordinator",
+        });
+
+        expect(result.isViolation).toBe(false);
+      });
+
+      it("does not detect test execution from worker", () => {
+        const result = detectCoordinatorViolation({
+          sessionId,
+          epicId,
+          toolName: "bash",
+          toolArgs: { command: "bun test" },
+          agentContext: "worker",
+        });
+
+        expect(result.isViolation).toBe(false);
+      });
+    });
+
+    describe("coordinator_reserved_files violation", () => {
+      it("detects swarmmail_reserve from coordinator", () => {
+        const result = detectCoordinatorViolation({
+          sessionId,
+          epicId,
+          toolName: "swarmmail_reserve",
+          toolArgs: { paths: ["src/auth/**"], reason: "Working on auth" },
+          agentContext: "coordinator",
+        });
+
+        expect(result.isViolation).toBe(true);
+        expect(result.violationType).toBe("coordinator_reserved_files");
+        expect(result.message).toContain("Workers reserve files");
+        expect(result.payload.paths).toEqual(["src/auth/**"]);
+      });
+
+      it("detects agentmail_reserve from coordinator", () => {
+        const result = detectCoordinatorViolation({
+          sessionId,
+          epicId,
+          toolName: "agentmail_reserve",
+          toolArgs: { paths: ["src/lib/**"], reason: "Refactoring" },
+          agentContext: "coordinator",
+        });
+
+        expect(result.isViolation).toBe(true);
+        expect(result.violationType).toBe("coordinator_reserved_files");
+      });
+
+      it("does not detect reserve from worker", () => {
+        const result = detectCoordinatorViolation({
+          sessionId,
+          epicId,
+          toolName: "swarmmail_reserve",
+          toolArgs: { paths: ["src/auth/**"], reason: "Working on auth" },
+          agentContext: "worker",
+        });
+
+        expect(result.isViolation).toBe(false);
+      });
+    });
+
+    describe("no_worker_spawned violation", () => {
+      it("detects no spawn after decomposition", () => {
+        const result = detectCoordinatorViolation({
+          sessionId,
+          epicId,
+          toolName: "hive_create_epic",
+          toolArgs: {
+            epic_title: "Add feature",
+            subtasks: [
+              { title: "Task 1", files: ["a.ts"] },
+              { title: "Task 2", files: ["b.ts"] },
+            ],
+          },
+          agentContext: "coordinator",
+          checkNoSpawn: true,
+        });
+
+        expect(result.isViolation).toBe(true);
+        expect(result.violationType).toBe("no_worker_spawned");
+        expect(result.message).toContain("decomposition without spawning");
+        expect(result.payload.epic_title).toBe("Add feature");
+        expect(result.payload.subtask_count).toBe(2);
+      });
+
+      it("does not flag if workers were spawned", () => {
+        const result = detectCoordinatorViolation({
+          sessionId,
+          epicId,
+          toolName: "hive_create_epic",
+          toolArgs: {
+            epic_title: "Add feature",
+            subtasks: [
+              { title: "Task 1", files: ["a.ts"] },
+              { title: "Task 2", files: ["b.ts"] },
+            ],
+          },
+          agentContext: "coordinator",
+          checkNoSpawn: false, // Workers were spawned
+        });
+
+        expect(result.isViolation).toBe(false);
+      });
+
+      it("does not flag from worker agent", () => {
+        const result = detectCoordinatorViolation({
+          sessionId,
+          epicId,
+          toolName: "hive_create_epic",
+          toolArgs: {
+            epic_title: "Add feature",
+            subtasks: [{ title: "Task 1", files: ["a.ts"] }],
+          },
+          agentContext: "worker",
+          checkNoSpawn: true,
+        });
+
+        expect(result.isViolation).toBe(false);
+      });
+    });
+
+    describe("event capture integration", () => {
+      it("captures violation event to session file when violation detected", () => {
+        const result = detectCoordinatorViolation({
+          sessionId,
+          epicId,
+          toolName: "edit",
+          toolArgs: { filePath: "/test.ts", oldString: "a", newString: "b" },
+          agentContext: "coordinator",
+        });
+
+        expect(result.isViolation).toBe(true);
+
+        // Verify event was written to session file
+        const sessionDir = path.join(os.homedir(), ".config", "swarm-tools", "sessions");
+        const sessionPath = path.join(sessionDir, `${sessionId}.jsonl`);
+        expect(fs.existsSync(sessionPath)).toBe(true);
+
+        const content = fs.readFileSync(sessionPath, "utf-8");
+        const lines = content.trim().split("\n");
+        expect(lines.length).toBe(1);
+
+        const event = JSON.parse(lines[0]);
+        expect(event.event_type).toBe("VIOLATION");
+        expect(event.violation_type).toBe("coordinator_edited_file");
+        expect(event.session_id).toBe(sessionId);
+        expect(event.epic_id).toBe(epicId);
+        expect(event.payload.tool).toBe("edit");
+      });
+
+      it("does not capture event when no violation", () => {
+        const result = detectCoordinatorViolation({
+          sessionId,
+          epicId,
+          toolName: "read",
+          toolArgs: { filePath: "/test.ts" },
+          agentContext: "coordinator",
+        });
+
+        expect(result.isViolation).toBe(false);
+
+        // Verify no session file created
+        const sessionDir = path.join(os.homedir(), ".config", "swarm-tools", "sessions");
+        const sessionPath = path.join(sessionDir, `${sessionId}.jsonl`);
+        expect(fs.existsSync(sessionPath)).toBe(false);
+      });
+    });
+  });
+
+  describe("coordinator context", () => {
+    beforeEach(() => {
+      clearCoordinatorContext();
+    });
+
+    afterEach(() => {
+      clearCoordinatorContext();
+    });
+
+    describe("setCoordinatorContext", () => {
+      it("sets coordinator context", () => {
+        setCoordinatorContext({
+          isCoordinator: true,
+          epicId: "test-epic-123",
+          sessionId: "test-session-456",
+        });
+
+        const ctx = getCoordinatorContext();
+        expect(ctx.isCoordinator).toBe(true);
+        expect(ctx.epicId).toBe("test-epic-123");
+        expect(ctx.sessionId).toBe("test-session-456");
+        expect(ctx.activatedAt).toBeDefined();
+      });
+
+      it("merges with existing context", () => {
+        setCoordinatorContext({
+          isCoordinator: true,
+          sessionId: "session-1",
+        });
+
+        setCoordinatorContext({
+          epicId: "epic-1",
+        });
+
+        const ctx = getCoordinatorContext();
+        expect(ctx.isCoordinator).toBe(true);
+        expect(ctx.sessionId).toBe("session-1");
+        expect(ctx.epicId).toBe("epic-1");
+      });
+    });
+
+    describe("isInCoordinatorContext", () => {
+      it("returns false when not in coordinator context", () => {
+        expect(isInCoordinatorContext()).toBe(false);
+      });
+
+      it("returns true when in coordinator context", () => {
+        setCoordinatorContext({
+          isCoordinator: true,
+          epicId: "test-epic",
+        });
+
+        expect(isInCoordinatorContext()).toBe(true);
+      });
+
+      it("returns false after context is cleared", () => {
+        setCoordinatorContext({
+          isCoordinator: true,
+          epicId: "test-epic",
+        });
+
+        clearCoordinatorContext();
+
+        expect(isInCoordinatorContext()).toBe(false);
+      });
+    });
+
+    describe("clearCoordinatorContext", () => {
+      it("clears all context", () => {
+        setCoordinatorContext({
+          isCoordinator: true,
+          epicId: "test-epic",
+          sessionId: "test-session",
+        });
+
+        clearCoordinatorContext();
+
+        const ctx = getCoordinatorContext();
+        expect(ctx.isCoordinator).toBe(false);
+        expect(ctx.epicId).toBeUndefined();
+        expect(ctx.sessionId).toBeUndefined();
+      });
+    });
+  });
 });

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