opencode-swarm-plugin 0.36.0 → 0.37.0

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/hive.integration.test.ts

@@ -1895,6 +1895,154 @@ describe("beads integration", () => {
     });
   });
 
+  describe("hive_cells", () => {
+    let testCellId: string;
+
+    beforeEach(async () => {
+      // Create a test cell for hive_cells tests
+      const result = await hive_create.execute(
+        { title: "Cells tool test", type: "task" },
+        mockContext,
+      );
+      const cell = parseResponse<Cell>(result);
+      testCellId = cell.id;
+      createdBeadIds.push(testCellId);
+    });
+
+    it("lists all cells with no filters", async () => {
+      const { hive_cells } = await import("./hive");
+      
+      const result = await hive_cells.execute({}, mockContext);
+      const cells = parseResponse<Cell[]>(result);
+
+      expect(Array.isArray(cells)).toBe(true);
+      expect(cells.length).toBeGreaterThan(0);
+    });
+
+    it("filters by status", async () => {
+      const { hive_cells } = await import("./hive");
+      
+      const result = await hive_cells.execute({ status: "open" }, mockContext);
+      const cells = parseResponse<Cell[]>(result);
+
+      expect(Array.isArray(cells)).toBe(true);
+      expect(cells.every((c) => c.status === "open")).toBe(true);
+    });
+
+    it("filters by type", async () => {
+      const { hive_cells } = await import("./hive");
+      
+      // Create a bug cell
+      const bugResult = await hive_create.execute(
+        { title: "Bug for cells test", type: "bug" },
+        mockContext,
+      );
+      const bug = parseResponse<Cell>(bugResult);
+      createdBeadIds.push(bug.id);
+
+      const result = await hive_cells.execute({ type: "bug" }, mockContext);
+      const cells = parseResponse<Cell[]>(result);
+
+      expect(Array.isArray(cells)).toBe(true);
+      expect(cells.every((c) => c.issue_type === "bug")).toBe(true);
+    });
+
+    it("returns next ready cell when ready=true", async () => {
+      const { hive_cells } = await import("./hive");
+      
+      const result = await hive_cells.execute({ ready: true }, mockContext);
+      const cells = parseResponse<Cell[]>(result);
+
+      expect(Array.isArray(cells)).toBe(true);
+      // Should return 0 or 1 cells (the next ready one)
+      expect(cells.length).toBeLessThanOrEqual(1);
+      if (cells.length === 1) {
+        expect(["open", "in_progress"]).toContain(cells[0].status);
+      }
+    });
+
+    it("looks up cell by partial ID", async () => {
+      const { hive_cells } = await import("./hive");
+      
+      // Extract hash from full ID (6-char segment before the last hyphen)
+      const lastHyphenIndex = testCellId.lastIndexOf("-");
+      const beforeLast = testCellId.substring(0, lastHyphenIndex);
+      const secondLastHyphenIndex = beforeLast.lastIndexOf("-");
+      const hash = testCellId.substring(secondLastHyphenIndex + 1, lastHyphenIndex);
+      
+      // Use last 6 chars of hash (or full hash if short)
+      const shortHash = hash.substring(Math.max(0, hash.length - 6));
+
+      try {
+        const result = await hive_cells.execute({ id: shortHash }, mockContext);
+        const cells = parseResponse<Cell[]>(result);
+
+        // Should return exactly one cell matching the ID
+        expect(cells).toHaveLength(1);
+        expect(cells[0].id).toBe(testCellId);
+      } catch (error) {
+        // If ambiguous, verify error message is helpful
+        if (error instanceof Error && error.message.includes("Ambiguous")) {
+          expect(error.message).toMatch(/ambiguous.*multiple/i);
+          expect(error.message).toContain(shortHash);
+        } else {
+          throw error;
+        }
+      }
+    });
+
+    it("looks up cell by full ID", async () => {
+      const { hive_cells } = await import("./hive");
+      
+      const result = await hive_cells.execute({ id: testCellId }, mockContext);
+      const cells = parseResponse<Cell[]>(result);
+
+      expect(cells).toHaveLength(1);
+      expect(cells[0].id).toBe(testCellId);
+      expect(cells[0].title).toBe("Cells tool test");
+    });
+
+    it("throws error for non-existent ID", async () => {
+      const { hive_cells } = await import("./hive");
+      
+      await expect(
+        hive_cells.execute({ id: "nonexistent999" }, mockContext),
+      ).rejects.toThrow(/not found|no cell|nonexistent999/i);
+    });
+
+    it("respects limit parameter", async () => {
+      const { hive_cells } = await import("./hive");
+      
+      const result = await hive_cells.execute({ limit: 2 }, mockContext);
+      const cells = parseResponse<Cell[]>(result);
+
+      expect(cells.length).toBeLessThanOrEqual(2);
+    });
+
+    it("combines filters (status + type + limit)", async () => {
+      const { hive_cells } = await import("./hive");
+      
+      // Create some task cells
+      for (let i = 0; i < 3; i++) {
+        const r = await hive_create.execute(
+          { title: `Task ${i}`, type: "task" },
+          mockContext,
+        );
+        const c = parseResponse<Cell>(r);
+        createdBeadIds.push(c.id);
+      }
+
+      const result = await hive_cells.execute(
+        { status: "open", type: "task", limit: 2 },
+        mockContext,
+      );
+      const cells = parseResponse<Cell[]>(result);
+
+      expect(cells.length).toBeLessThanOrEqual(2);
+      expect(cells.every((c) => c.status === "open" && c.issue_type === "task")).toBe(true);
+    });
+  });
+
   describe("bigint to Date conversion", () => {
     it("should handle PGLite bigint timestamps correctly in hive_query", async () => {
       const { mkdirSync, rmSync } = await import("node:fs");

package/src/hive.ts

@@ -1092,6 +1092,94 @@ export const hive_ready = tool({
   },
 });
 
+/**
+ * Query cells from the hive database with flexible filtering
+ */
+export const hive_cells = tool({
+  description: `Query cells from the hive database with flexible filtering.
+
+USE THIS TOOL TO:
+- List all open cells: hive_cells()
+- Find cells by status: hive_cells({ status: "in_progress" })
+- Find cells by type: hive_cells({ type: "bug" })
+- Get a specific cell by partial ID: hive_cells({ id: "mjkmd" })
+- Get the next ready (unblocked) cell: hive_cells({ ready: true })
+- Combine filters: hive_cells({ status: "open", type: "task" })
+
+RETURNS: Array of cells with id, title, status, priority, type, parent_id, created_at, updated_at
+
+PREFER THIS OVER hive_query when you need to:
+- See what work is available
+- Check status of multiple cells
+- Find cells matching criteria
+- Look up a cell by partial ID`,
+  args: {
+    id: tool.schema.string().optional().describe("Partial or full cell ID to look up"),
+    status: tool.schema.enum(["open", "in_progress", "blocked", "closed"]).optional().describe("Filter by status"),
+    type: tool.schema.enum(["task", "bug", "feature", "epic", "chore"]).optional().describe("Filter by type"),
+    ready: tool.schema.boolean().optional().describe("If true, return only the next unblocked cell"),
+    limit: tool.schema.number().optional().describe("Max cells to return (default 20)"),
+  },
+  async execute(args, ctx) {
+    const projectKey = getHiveWorkingDirectory();
+    const adapter = await getHiveAdapter(projectKey);
+    
+    try {
+      // If specific ID requested, resolve and return single cell
+      if (args.id) {
+        const fullId = await resolvePartialId(adapter, projectKey, args.id) || args.id;
+        const cell = await adapter.getCell(projectKey, fullId);
+        if (!cell) {
+          throw new HiveError(`No cell found matching ID '${args.id}'`, "hive_cells");
+        }
+        const formatted = formatCellForOutput(cell);
+        return JSON.stringify([formatted], null, 2);
+      }
+      
+      // If ready flag, return next unblocked cell
+      if (args.ready) {
+        const ready = await adapter.getNextReadyCell(projectKey);
+        if (!ready) {
+          return JSON.stringify([], null, 2);
+        }
+        const formatted = formatCellForOutput(ready);
+        return JSON.stringify([formatted], null, 2);
+      }
+      
+      // Query with filters
+      const cells = await adapter.queryCells(projectKey, {
+        status: args.status,
+        type: args.type,
+        limit: args.limit || 20,
+      });
+      
+      const formatted = cells.map(c => formatCellForOutput(c));
+      return JSON.stringify(formatted, null, 2);
+    } catch (error) {
+      const message = error instanceof Error ? error.message : String(error);
+      
+      // Provide helpful error messages
+      if (message.includes("Ambiguous hash")) {
+        throw new HiveError(
+          `Ambiguous ID '${args.id}': multiple cells match. Please provide more characters.`,
+          "hive_cells",
+        );
+      }
+      if (message.includes("Bead not found") || message.includes("Cell not found")) {
+        throw new HiveError(
+          `No cell found matching ID '${args.id || "unknown"}'`,
+          "hive_cells",
+        );
+      }
+      
+      throw new HiveError(
+        `Failed to query cells: ${message}`,
+        "hive_cells",
+      );
+    }
+  },
+});
+
 /**
  * Sync hive to git and push
  */
@@ -1345,6 +1433,7 @@ export const hiveTools = {
   hive_close,
   hive_start,
   hive_ready,
+  hive_cells,
   hive_sync,
   hive_link_thread,
 };

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