opencode-swarm-plugin 0.45.0 → 0.45.2

package/examples/plugin-wrapper-template.ts

@@ -1,16 +1,37 @@
 /**
- * OpenCode Swarm Plugin Wrapper
+ * ╔═══════════════════════════════════════════════════════════════════════════╗
+ * ║                                                                           ║
+ * ║   🐝 OPENCODE SWARM PLUGIN WRAPPER 🐝                                     ║
+ * ║                                                                           ║
+ * ║   This file lives at: ~/.config/opencode/plugin/swarm.ts                  ║
+ * ║   Generated by: swarm setup                                               ║
+ * ║                                                                           ║
+ * ╠═══════════════════════════════════════════════════════════════════════════╣
+ * ║                                                                           ║
+ * ║   ⚠️  CRITICAL: THIS FILE MUST BE 100% SELF-CONTAINED  ⚠️                 ║
+ * ║                                                                           ║
+ * ║   ❌ NEVER import from "opencode-swarm-plugin" npm package                ║
+ * ║   ❌ NEVER import from any package with transitive deps (evalite, etc)    ║
+ * ║   ❌ NEVER add dependencies that aren't provided by OpenCode              ║
+ * ║                                                                           ║
+ * ║   ✅ ONLY import from: @opencode-ai/plugin, @opencode-ai/sdk, node:*      ║
+ * ║   ✅ Shell out to `swarm` CLI for all tool execution                      ║
+ * ║   ✅ Inline any logic that would otherwise require imports                ║
+ * ║                                                                           ║
+ * ║   WHY? The npm package has dependencies (evalite, etc) that aren't        ║
+ * ║   available in OpenCode's plugin context. Importing causes:               ║
+ * ║   "Cannot find module 'evalite/runner'" → trace trap → OpenCode crash     ║
+ * ║                                                                           ║
+ * ║   PATTERN: Plugin wrapper is DUMB. CLI is SMART.                          ║
+ * ║   - Wrapper: thin shell, no logic, just bridges to CLI                    ║
+ * ║   - CLI: all the smarts, all the deps, runs in its own context            ║
+ * ║                                                                           ║
+ * ╚═══════════════════════════════════════════════════════════════════════════╝
  *
- * This is a thin wrapper that shells out to the `swarm` CLI for all tool execution.
- * Generated by: swarm setup
- *
- * The plugin only depends on @opencode-ai/plugin (provided by OpenCode).
- * All tool logic lives in the npm package - this just bridges to it.
- *
- * Environment variables:
- * - OPENCODE_SESSION_ID: Passed to CLI for session state persistence
- * - OPENCODE_MESSAGE_ID: Passed to CLI for context
- * - OPENCODE_AGENT: Passed to CLI for context
+ * Environment variables passed to CLI:
+ * - OPENCODE_SESSION_ID: Session state persistence
+ * - OPENCODE_MESSAGE_ID: Message context
+ * - OPENCODE_AGENT: Agent context
  * - SWARM_PROJECT_DIR: Project directory (critical for database path)
  */
 import type { Plugin, PluginInput, Hooks } from "@opencode-ai/plugin";
@@ -21,15 +42,267 @@ import { appendFileSync, mkdirSync, existsSync } from "node:fs";
 import { join } from "node:path";
 import { homedir } from "node:os";
 
-// Import swarm signature projection for deterministic swarm detection
-import {
-  projectSwarmState,
-  hasSwarmSignature,
-  isSwarmActive,
-  getSwarmSummary,
-  type SwarmProjection,
-  type ToolCallEvent,
-} from "opencode-swarm-plugin";
+// =============================================================================
+// Swarm Signature Detection (INLINED - do not import from opencode-swarm-plugin)
+// =============================================================================
+
+/**
+ * Subtask lifecycle status derived from events
+ */
+type SubtaskStatus = "created" | "spawned" | "in_progress" | "completed" | "closed";
+
+/**
+ * Subtask state projected from events
+ */
+interface SubtaskState {
+  id: string;
+  title: string;
+  status: SubtaskStatus;
+  files: string[];
+  worker?: string;
+  spawnedAt?: number;
+  completedAt?: number;
+}
+
+/**
+ * Epic state projected from events
+ */
+interface EpicState {
+  id: string;
+  title: string;
+  status: "open" | "in_progress" | "closed";
+  createdAt: number;
+}
+
+/**
+ * Complete swarm state projected from session events
+ */
+interface SwarmProjection {
+  isSwarm: boolean;
+  epic?: EpicState;
+  subtasks: Map<string, SubtaskState>;
+  projectPath?: string;
+  coordinatorName?: string;
+  lastEventAt?: number;
+  counts: {
+    total: number;
+    created: number;
+    spawned: number;
+    inProgress: number;
+    completed: number;
+    closed: number;
+  };
+}
+
+/**
+ * Tool call event extracted from session messages
+ */
+interface ToolCallEvent {
+  tool: string;
+  input: Record<string, unknown>;
+  output: string;
+  timestamp: number;
+}
+
+/** Parse epic ID from hive_create_epic output */
+function parseEpicId(output: string): string | undefined {
+  try {
+    const parsed = JSON.parse(output);
+    return parsed.epic?.id || parsed.id;
+  } catch {
+    return undefined;
+  }
+}
+
+/** Parse subtask IDs from hive_create_epic output */
+function parseSubtaskIds(output: string): string[] {
+  try {
+    const parsed = JSON.parse(output);
+    const subtasks = parsed.subtasks || parsed.epic?.subtasks || [];
+    return subtasks
+      .map((s: unknown) => {
+        if (typeof s === "object" && s !== null && "id" in s) {
+          return (s as { id: string }).id;
+        }
+        return undefined;
+      })
+      .filter((id: unknown): id is string => typeof id === "string");
+  } catch {
+    return [];
+  }
+}
+
+/**
+ * Project swarm state from session tool call events
+ */
+function projectSwarmState(events: ToolCallEvent[]): SwarmProjection {
+  const state: SwarmProjection = {
+    isSwarm: false,
+    subtasks: new Map(),
+    counts: { total: 0, created: 0, spawned: 0, inProgress: 0, completed: 0, closed: 0 },
+  };
+
+  let hasEpic = false;
+  let hasSpawn = false;
+
+  for (const event of events) {
+    state.lastEventAt = event.timestamp;
+
+    switch (event.tool) {
+      case "hive_create_epic": {
+        const epicId = parseEpicId(event.output);
+        const epicTitle = typeof event.input.epic_title === "string" ? event.input.epic_title : undefined;
+
+        if (epicId) {
+          state.epic = { id: epicId, title: epicTitle || "Unknown Epic", status: "open", createdAt: event.timestamp };
+          hasEpic = true;
+
+          const subtasks = event.input.subtasks;
+          if (Array.isArray(subtasks)) {
+            for (const subtask of subtasks) {
+              if (typeof subtask === "object" && subtask !== null) {
+                state.counts.created++;
+                state.counts.total++;
+              }
+            }
+          }
+
+          const subtaskIds = parseSubtaskIds(event.output);
+          for (const id of subtaskIds) {
+            if (!state.subtasks.has(id)) {
+              state.subtasks.set(id, { id, title: "Unknown", status: "created", files: [] });
+              state.counts.total++;
+              state.counts.created++;
+            }
+          }
+        }
+        break;
+      }
+
+      case "swarm_spawn_subtask": {
+        const beadId = typeof event.input.bead_id === "string" ? event.input.bead_id : undefined;
+        const title = typeof event.input.subtask_title === "string" ? event.input.subtask_title : "Unknown";
+        const files = Array.isArray(event.input.files) ? (event.input.files as string[]) : [];
+
+        if (beadId) {
+          hasSpawn = true;
+          const existing = state.subtasks.get(beadId);
+          if (existing) {
+            if (existing.status === "created") { state.counts.created--; state.counts.spawned++; }
+            existing.status = "spawned";
+            existing.title = title;
+            existing.files = files;
+            existing.spawnedAt = event.timestamp;
+          } else {
+            state.subtasks.set(beadId, { id: beadId, title, status: "spawned", files, spawnedAt: event.timestamp });
+            state.counts.total++;
+            state.counts.spawned++;
+          }
+
+          const epicId = typeof event.input.epic_id === "string" ? event.input.epic_id : undefined;
+          if (epicId && !state.epic) {
+            state.epic = { id: epicId, title: "Unknown Epic", status: "in_progress", createdAt: event.timestamp };
+          }
+        }
+        break;
+      }
+
+      case "hive_start": {
+        const id = typeof event.input.id === "string" ? event.input.id : undefined;
+        if (id) {
+          const subtask = state.subtasks.get(id);
+          if (subtask && subtask.status !== "completed" && subtask.status !== "closed") {
+            if (subtask.status === "created") state.counts.created--;
+            else if (subtask.status === "spawned") state.counts.spawned--;
+            subtask.status = "in_progress";
+            state.counts.inProgress++;
+          }
+          if (state.epic && state.epic.id === id) state.epic.status = "in_progress";
+        }
+        break;
+      }
+
+      case "swarm_complete": {
+        const beadId = typeof event.input.bead_id === "string" ? event.input.bead_id : undefined;
+        if (beadId) {
+          const subtask = state.subtasks.get(beadId);
+          if (subtask && subtask.status !== "closed") {
+            if (subtask.status === "created") state.counts.created--;
+            else if (subtask.status === "spawned") state.counts.spawned--;
+            else if (subtask.status === "in_progress") state.counts.inProgress--;
+            subtask.status = "completed";
+            subtask.completedAt = event.timestamp;
+            state.counts.completed++;
+          }
+        }
+        break;
+      }
+
+      case "hive_close": {
+        const id = typeof event.input.id === "string" ? event.input.id : undefined;
+        if (id) {
+          const subtask = state.subtasks.get(id);
+          if (subtask) {
+            if (subtask.status === "created") state.counts.created--;
+            else if (subtask.status === "spawned") state.counts.spawned--;
+            else if (subtask.status === "in_progress") state.counts.inProgress--;
+            else if (subtask.status === "completed") state.counts.completed--;
+            subtask.status = "closed";
+            state.counts.closed++;
+          }
+          if (state.epic && state.epic.id === id) state.epic.status = "closed";
+        }
+        break;
+      }
+
+      case "swarmmail_init": {
+        try {
+          const parsed = JSON.parse(event.output);
+          if (parsed.agent_name) state.coordinatorName = parsed.agent_name;
+          if (parsed.project_key) state.projectPath = parsed.project_key;
+        } catch { /* skip */ }
+        break;
+      }
+    }
+  }
+
+  state.isSwarm = hasEpic && hasSpawn;
+  return state;
+}
+
+/** Quick check for swarm signature without full projection */
+function hasSwarmSignature(events: ToolCallEvent[]): boolean {
+  let hasEpic = false;
+  let hasSpawn = false;
+  for (const event of events) {
+    if (event.tool === "hive_create_epic") hasEpic = true;
+    else if (event.tool === "swarm_spawn_subtask") hasSpawn = true;
+    if (hasEpic && hasSpawn) return true;
+  }
+  return false;
+}
+
+/** Check if swarm is still active (has pending work) */
+function isSwarmActive(projection: SwarmProjection): boolean {
+  if (!projection.isSwarm) return false;
+  return projection.counts.created > 0 || projection.counts.spawned > 0 ||
+         projection.counts.inProgress > 0 || projection.counts.completed > 0;
+}
+
+/** Get human-readable swarm status summary */
+function getSwarmSummary(projection: SwarmProjection): string {
+  if (!projection.isSwarm) return "No swarm detected";
+  const { counts, epic } = projection;
+  const parts: string[] = [];
+  if (epic) parts.push(`Epic: ${epic.id} - ${epic.title} [${epic.status}]`);
+  parts.push(`Subtasks: ${counts.total} total (${counts.spawned} spawned, ${counts.inProgress} in_progress, ${counts.completed} completed, ${counts.closed} closed)`);
+  parts.push(isSwarmActive(projection) ? "Status: ACTIVE - has pending work" : "Status: COMPLETE - all work closed");
+  return parts.join("\n");
+}
+
+// =============================================================================
+// Constants
+// =============================================================================
 
 const SWARM_CLI = "swarm";
 
@@ -76,10 +349,10 @@ function logCompaction(
 }
 
 /**
- * Capture compaction event for evals (non-fatal dynamic import)
+ * Capture compaction event for evals via CLI
  * 
- * Uses dynamic import to avoid circular dependencies and keep the plugin wrapper
- * self-contained. Captures COMPACTION events to session JSONL for eval analysis.
+ * Shells out to `swarm capture` command to avoid import issues.
+ * The CLI handles all the logic - plugin wrapper stays dumb.
  * 
  * @param sessionID - Session ID
  * @param epicID - Epic ID (or "unknown" if not detected)
@@ -93,14 +366,22 @@ async function captureCompaction(
   payload: any,
 ): Promise<void> {
   try {
-    // Dynamic import to avoid circular deps (plugin wrapper → src → plugin wrapper)
-    const { captureCompactionEvent } = await import("../src/eval-capture");
-    captureCompactionEvent({
-      session_id: sessionID,
-      epic_id: epicID,
-      compaction_type: compactionType,
-      payload,
+    // Shell out to CLI - no imports needed, version always matches
+    const args = [
+      "capture",
+      "--session", sessionID,
+      "--epic", epicID,
+      "--type", compactionType,
+      "--payload", JSON.stringify(payload),
+    ];
+    
+    const proc = spawn(SWARM_CLI, args, {
+      env: { ...process.env, SWARM_PROJECT_DIR: projectDirectory },
+      stdio: ["ignore", "ignore", "ignore"], // Fire and forget
     });
+    
+    // Don't wait - capture is non-blocking
+    proc.unref();
   } catch (err) {
     // Non-fatal - capture failures shouldn't break compaction
     logCompaction("warn", "compaction_capture_failed", {
@@ -2063,6 +2344,97 @@ Extract from session context:
 **You are not waiting for instructions. You are the coordinator. Coordinate.**
 `;
 
+/**
+ * Build dynamic swarm state section from snapshot
+ * 
+ * This creates a concrete state summary with actual IDs and status
+ * to prepend to the static compaction context.
+ */
+function buildDynamicStateFromSnapshot(snapshot: SwarmStateSnapshot): string {
+  if (!snapshot.epic) {
+    return "";
+  }
+
+  const parts: string[] = [];
+  
+  // Header with epic info
+  parts.push(`## 🐝 Current Swarm State\n`);
+  parts.push(`**Epic:** ${snapshot.epic.id} - ${snapshot.epic.title}`);
+  parts.push(`**Status:** ${snapshot.epic.status}`);
+  parts.push(`**Project:** ${projectDirectory}\n`);
+  
+  // Subtask breakdown
+  const subtasks = snapshot.epic.subtasks || [];
+  const completed = subtasks.filter(s => s.status === "closed");
+  const inProgress = subtasks.filter(s => s.status === "in_progress");
+  const blocked = subtasks.filter(s => s.status === "blocked");
+  const pending = subtasks.filter(s => s.status === "open");
+  
+  parts.push(`**Progress:** ${completed.length}/${subtasks.length} subtasks complete\n`);
+  
+  // Immediate actions with real IDs
+  parts.push(`## 1️⃣ IMMEDIATE ACTIONS (Do These FIRST)\n`);
+  parts.push(`1. \`swarm_status(epic_id="${snapshot.epic.id}", project_key="${projectDirectory}")\` - Get current state`);
+  parts.push(`2. \`swarmmail_inbox(limit=5)\` - Check for worker messages`);
+  
+  if (inProgress.length > 0) {
+    parts.push(`3. Review in-progress work when workers complete`);
+  }
+  if (pending.length > 0) {
+    const next = pending[0];
+    parts.push(`4. Spawn next subtask: \`swarm_spawn_subtask(bead_id="${next.id}", ...)\``);
+  }
+  if (blocked.length > 0) {
+    parts.push(`5. Unblock: ${blocked.map(s => s.id).join(", ")}`);
+  }
+  parts.push("");
+  
+  // Detailed subtask status
+  if (inProgress.length > 0) {
+    parts.push(`### 🚧 In Progress (${inProgress.length})`);
+    for (const s of inProgress) {
+      const files = s.files?.length ? ` (${s.files.slice(0, 3).join(", ")}${s.files.length > 3 ? "..." : ""})` : "";
+      parts.push(`- ${s.id}: ${s.title}${files}`);
+    }
+    parts.push("");
+  }
+  
+  if (blocked.length > 0) {
+    parts.push(`### 🚫 Blocked (${blocked.length})`);
+    for (const s of blocked) {
+      parts.push(`- ${s.id}: ${s.title}`);
+    }
+    parts.push("");
+  }
+  
+  if (pending.length > 0) {
+    parts.push(`### ⏳ Ready to Spawn (${pending.length})`);
+    for (const s of pending.slice(0, 5)) { // Show first 5
+      const files = s.files?.length ? ` (${s.files.slice(0, 2).join(", ")}${s.files.length > 2 ? "..." : ""})` : "";
+      parts.push(`- ${s.id}: ${s.title}${files}`);
+    }
+    if (pending.length > 5) {
+      parts.push(`- ... and ${pending.length - 5} more`);
+    }
+    parts.push("");
+  }
+  
+  if (completed.length > 0) {
+    parts.push(`### ✅ Completed (${completed.length})`);
+    for (const s of completed.slice(-3)) { // Show last 3
+      parts.push(`- ${s.id}: ${s.title} ✓`);
+    }
+    if (completed.length > 3) {
+      parts.push(`- ... and ${completed.length - 3} more`);
+    }
+    parts.push("");
+  }
+  
+  parts.push("---\n");
+  
+  return parts.join("\n");
+}
+
 /**
  * Fallback detection prompt - tells the compactor what to look for
  * 
@@ -2329,6 +2701,9 @@ const SwarmPlugin: Plugin = async (
           has_projection: !!sessionScan.projection?.isSwarm,
         });
 
+        // Hoist snapshot outside try block so it's available in fallback path
+        let snapshot: SwarmStateSnapshot | undefined;
+        
         try {
           // =======================================================================
           // PREFER PROJECTION (ground truth from events) OVER HIVE QUERY
@@ -2336,8 +2711,6 @@ const SwarmPlugin: Plugin = async (
           // The projection is derived from session events - it's the source of truth.
           // Hive query may show all cells closed even if swarm was active.
           
-          let snapshot: SwarmStateSnapshot;
-          
           if (sessionScan.projection?.isSwarm) {
             // Use projection as primary source - convert to snapshot format
             const proj = sessionScan.projection;
@@ -2520,9 +2893,12 @@ const SwarmPlugin: Plugin = async (
           });
         }
 
-        // Level 3: Fall back to static context
+        // Level 3: Fall back to static context WITH dynamic state from snapshot
         const header = `[Swarm detected: ${detection.reasons.join(", ")}]\n\n`;
-        const staticContent = header + SWARM_COMPACTION_CONTEXT;
+        
+        // Build dynamic state section if we have snapshot data
+        const dynamicState = snapshot ? buildDynamicStateFromSnapshot(snapshot) : "";
+        const staticContent = header + dynamicState + SWARM_COMPACTION_CONTEXT;
         output.context.push(staticContent);
 
         // =======================================================================
@@ -2530,13 +2906,16 @@ const SwarmPlugin: Plugin = async (
         // =======================================================================
         await captureCompaction(
           input.sessionID,
-          "unknown", // No snapshot available in this path
+          snapshot?.epic?.id || "unknown",
           "context_injected",
           {
             full_content: staticContent,
             content_length: staticContent.length,
             injection_method: "output.context.push",
-            context_type: "static_swarm_context",
+            context_type: "static_with_dynamic_state",
+            has_dynamic_state: !!dynamicState,
+            epic_id: snapshot?.epic?.id,
+            subtask_count: snapshot?.epic?.subtasks?.length ?? 0,
           },
         );
 
@@ -2545,9 +2924,12 @@ const SwarmPlugin: Plugin = async (
           session_id: input.sessionID,
           total_duration_ms: totalDuration,
           confidence: detection.confidence,
-          context_type: "static_swarm_context",
+          context_type: dynamicState ? "static_with_dynamic_state" : "static_swarm_context",
           content_length: staticContent.length,
           context_count_after: output.context.length,
+          has_dynamic_state: !!dynamicState,
+          epic_id: snapshot?.epic?.id,
+          subtask_count: snapshot?.epic?.subtasks?.length ?? 0,
         });
       } else if (detection.confidence === "low") {
         // Level 4: Possible swarm - inject fallback detection prompt

package/package.json

@@ -1,12 +1,12 @@
 {
   "name": "opencode-swarm-plugin",
-  "version": "0.45.0",
+  "version": "0.45.2",
   "description": "Multi-agent swarm coordination for OpenCode with learning capabilities, beads integration, and Agent Mail",
   "type": "module",
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",
   "bin": {
-    "swarm": "./bin/swarm.ts"
+    "swarm": "./dist/bin/swarm.js"
   },
   "exports": {
     ".": {
@@ -63,7 +63,7 @@
     "minimatch": "^10.1.1",
     "pino": "^9.6.0",
     "pino-roll": "^1.3.0",
-    "swarm-mail": "1.6.1",
+    "swarm-mail": "1.6.2",
     "yaml": "^2.8.2",
     "zod": "4.1.8"
   },