opencode-swarm-plugin 0.36.0 → 0.36.1

package/src/eval-capture.ts

@@ -9,12 +9,15 @@
  * 2. swarm_complete captures: outcome signals per subtask
  * 3. swarm_record_outcome captures: learning signals
  * 4. Human feedback (optional): accept/reject/modify
+ * 5. Coordinator events: decisions, violations, outcomes
+ * 6. Session capture: full coordinator session to ~/.config/swarm-tools/sessions/
  *
  * @module eval-capture
  */
+import * as fs from "node:fs";
+import * as os from "node:os";
+import * as path from "node:path";
 import { z } from "zod";
-import * as fs from "fs";
-import * as path from "path";
 
 // ============================================================================
 // Schemas
@@ -119,6 +122,67 @@ export type PartialEvalRecord = Partial<EvalRecord> & {
   task: string;
 };
 
+/**
+ * Coordinator Event - captures coordinator decisions, violations, and outcomes
+ */
+export const CoordinatorEventSchema = z.discriminatedUnion("event_type", [
+  // DECISION events
+  z.object({
+    session_id: z.string(),
+    epic_id: z.string(),
+    timestamp: z.string(),
+    event_type: z.literal("DECISION"),
+    decision_type: z.enum([
+      "strategy_selected",
+      "worker_spawned",
+      "review_completed",
+      "decomposition_complete",
+    ]),
+    payload: z.any(),
+  }),
+  // VIOLATION events
+  z.object({
+    session_id: z.string(),
+    epic_id: z.string(),
+    timestamp: z.string(),
+    event_type: z.literal("VIOLATION"),
+    violation_type: z.enum([
+      "coordinator_edited_file",
+      "coordinator_ran_tests",
+      "coordinator_reserved_files",
+      "no_worker_spawned",
+    ]),
+    payload: z.any(),
+  }),
+  // OUTCOME events
+  z.object({
+    session_id: z.string(),
+    epic_id: z.string(),
+    timestamp: z.string(),
+    event_type: z.literal("OUTCOME"),
+    outcome_type: z.enum([
+      "subtask_success",
+      "subtask_retry",
+      "subtask_failed",
+      "epic_complete",
+    ]),
+    payload: z.any(),
+  }),
+]);
+export type CoordinatorEvent = z.infer<typeof CoordinatorEventSchema>;
+
+/**
+ * Coordinator Session - wraps a full coordinator session
+ */
+export const CoordinatorSessionSchema = z.object({
+  session_id: z.string(),
+  epic_id: z.string(),
+  start_time: z.string(),
+  end_time: z.string().optional(),
+  events: z.array(CoordinatorEventSchema),
+});
+export type CoordinatorSession = z.infer<typeof CoordinatorSessionSchema>;
+
 // ============================================================================
 // Storage
 // ============================================================================
@@ -155,7 +219,7 @@ export function appendEvalRecord(
 ): void {
   ensureEvalDataDir(projectPath);
   const evalPath = getEvalDataPath(projectPath);
-  const line = JSON.stringify(record) + "\n";
+  const line = `${JSON.stringify(record)}\n`;
   fs.appendFileSync(evalPath, line, "utf-8");
 }
 
@@ -211,7 +275,7 @@ export function updateEvalRecord(
 
   // Rewrite the file
   const evalPath = getEvalDataPath(projectPath);
-  const content = records.map((r) => JSON.stringify(r)).join("\n") + "\n";
+  const content = `${records.map((r) => JSON.stringify(r)).join("\n")}\n`;
   fs.writeFileSync(evalPath, content, "utf-8");
 
   return true;
@@ -484,3 +548,98 @@ export function getEvalDataStats(projectPath: string): {
     avgTimeBalance,
   };
 }
+
+// ============================================================================
+// Coordinator Session Capture
+// ============================================================================
+
+/**
+ * Get the session directory path
+ */
+export function getSessionDir(): string {
+  return path.join(os.homedir(), ".config", "swarm-tools", "sessions");
+}
+
+/**
+ * Get the session file path for a session ID
+ */
+export function getSessionPath(sessionId: string): string {
+  return path.join(getSessionDir(), `${sessionId}.jsonl`);
+}
+
+/**
+ * Ensure the session directory exists
+ */
+export function ensureSessionDir(): void {
+  const sessionDir = getSessionDir();
+  if (!fs.existsSync(sessionDir)) {
+    fs.mkdirSync(sessionDir, { recursive: true });
+  }
+}
+
+/**
+ * Capture a coordinator event to the session file
+ *
+ * Appends the event as a JSONL line to ~/.config/swarm-tools/sessions/{session_id}.jsonl
+ */
+export function captureCoordinatorEvent(event: CoordinatorEvent): void {
+  // Validate event
+  CoordinatorEventSchema.parse(event);
+
+  // Ensure directory exists
+  ensureSessionDir();
+
+  // Append to session file
+  const sessionPath = getSessionPath(event.session_id);
+  const line = `${JSON.stringify(event)}\n`;
+  fs.appendFileSync(sessionPath, line, "utf-8");
+}
+
+/**
+ * Read all events from a session file
+ */
+export function readSessionEvents(sessionId: string): CoordinatorEvent[] {
+  const sessionPath = getSessionPath(sessionId);
+  if (!fs.existsSync(sessionPath)) {
+    return [];
+  }
+
+  const content = fs.readFileSync(sessionPath, "utf-8");
+  const lines = content.trim().split("\n").filter(Boolean);
+
+  return lines.map((line) => {
+    const parsed = JSON.parse(line);
+    return CoordinatorEventSchema.parse(parsed);
+  });
+}
+
+/**
+ * Save a session - wraps all events in a CoordinatorSession structure
+ *
+ * Reads all events from the session file and wraps them in a session object.
+ * Returns null if the session file doesn't exist.
+ */
+export function saveSession(params: {
+  session_id: string;
+  epic_id: string;
+}): CoordinatorSession | null {
+  const events = readSessionEvents(params.session_id);
+  if (events.length === 0) {
+    return null;
+  }
+
+  // Get timestamps from events
+  const timestamps = events.map((e) => new Date(e.timestamp).getTime());
+  const startTime = new Date(Math.min(...timestamps)).toISOString();
+  const endTime = new Date(Math.max(...timestamps)).toISOString();
+
+  const session: CoordinatorSession = {
+    session_id: params.session_id,
+    epic_id: params.epic_id,
+    start_time: startTime,
+    end_time: endTime,
+    events,
+  };
+
+  return session;
+}

package/src/index.ts

@@ -57,6 +57,11 @@ import {
 import {
   analyzeTodoWrite,
   shouldAnalyzeTool,
+  detectCoordinatorViolation,
+  isInCoordinatorContext,
+  getCoordinatorContext,
+  setCoordinatorContext,
+  clearCoordinatorContext,
 } from "./planning-guardrails";
 import { createCompactionHook } from "./compaction-hook";
 
@@ -78,7 +83,7 @@ import { createCompactionHook } from "./compaction-hook";
  * @param input - Plugin context from OpenCode
  * @returns Plugin hooks including tools, events, and tool execution hooks
  */
-export const SwarmPlugin: Plugin = async (
+const SwarmPlugin: Plugin = async (
   input: PluginInput,
 ): Promise<Hooks> => {
   const { $, directory, client } = input;
@@ -190,6 +195,8 @@ export const SwarmPlugin: Plugin = async (
      *
      * Warns when agents are about to make planning mistakes:
      * - Using todowrite for multi-file implementation (should use swarm)
+     * - Coordinator editing files directly (should spawn workers)
+     * - Coordinator running tests (workers should run tests)
      */
     "tool.execute.before": async (input, output) => {
       const toolName = input.tool;
@@ -201,6 +208,36 @@ export const SwarmPlugin: Plugin = async (
           console.warn(`[swarm-plugin] ${analysis.warning}`);
         }
       }
+
+      // Check for coordinator violations when in coordinator context
+      if (isInCoordinatorContext()) {
+        const ctx = getCoordinatorContext();
+        const violation = detectCoordinatorViolation({
+          sessionId: ctx.sessionId || "unknown",
+          epicId: ctx.epicId || "unknown",
+          toolName,
+          toolArgs: output.args as Record<string, unknown>,
+          agentContext: "coordinator",
+        });
+
+        if (violation.isViolation) {
+          console.warn(`[swarm-plugin] ${violation.message}`);
+        }
+      }
+
+      // Activate coordinator context when swarm tools are used
+      if (toolName === "hive_create_epic" || toolName === "swarm_decompose") {
+        setCoordinatorContext({
+          isCoordinator: true,
+          sessionId: input.sessionID,
+        });
+      }
+
+      // Capture epic ID when epic is created
+      if (toolName === "hive_create_epic" && output.args) {
+        const args = output.args as { epic_title?: string };
+        // Epic ID will be set after execution in tool.execute.after
+      }
     },
 
     /**
@@ -258,6 +295,36 @@ export const SwarmPlugin: Plugin = async (
         await releaseReservations();
       }
 
+      // Capture epic ID when epic is created (for coordinator context)
+      if (toolName === "hive_create_epic" && output.output) {
+        try {
+          const result = JSON.parse(output.output);
+          if (result.epic?.id) {
+            setCoordinatorContext({
+              isCoordinator: true,
+              epicId: result.epic.id,
+              sessionId: input.sessionID,
+            });
+          }
+        } catch {
+          // Parsing failed - ignore
+        }
+      }
+
+      // Clear coordinator context when epic is closed
+      if (toolName === "hive_close" && output.output && isInCoordinatorContext()) {
+        const ctx = getCoordinatorContext();
+        try {
+          // Check if the closed cell is the active epic
+          const result = JSON.parse(output.output);
+          if (result.id === ctx.epicId) {
+            clearCoordinatorContext();
+          }
+        } catch {
+          // Parsing failed - ignore
+        }
+      }
+
       // Note: hive_sync should be called explicitly at session end
       // Auto-sync was removed because bd CLI is deprecated
       // The hive_sync tool handles flushing to JSONL and git commit/push

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