opencode-swarm-plugin 0.32.0 → 0.34.0

package/src/compaction-hook.ts

@@ -31,6 +31,28 @@
 
 import { getHiveAdapter, getHiveWorkingDirectory } from "./hive";
 import { checkSwarmHealth } from "swarm-mail";
+import { createChildLogger } from "./logger";
+
+let _logger: any | undefined;
+
+/**
+ * Get logger instance (lazy initialization for testability)
+ *
+ * Logs to: ~/.config/swarm-tools/logs/compaction.1log
+ *
+ * Log structure:
+ * - START: session_id, trigger
+ * - GATHER: source (swarm-mail|hive), duration_ms, stats/counts
+ * - DETECT: confidence, detected, reason_count, reasons
+ * - INJECT: confidence, context_length, context_type (full|fallback|none)
+ * - COMPLETE: duration_ms, success, detected, confidence, context_injected
+ */
+function getLog() {
+  if (!_logger) {
+    _logger = createChildLogger("compaction");
+  }
+  return _logger;
+}
 
 // ============================================================================
 // Compaction Context
@@ -145,6 +167,55 @@ Include this in your summary:
 "This is an active swarm. Check swarm_status and swarmmail_inbox immediately."
 `;
 
+// ============================================================================
+// Dynamic Context Building
+// ============================================================================
+
+/**
+ * Build dynamic swarm state section from detected state
+ * 
+ * This injects SPECIFIC values instead of placeholders, making the context
+ * immediately actionable on resume.
+ */
+function buildDynamicSwarmState(state: SwarmState): string {
+  const parts: string[] = [];
+  
+  parts.push("## 🐝 Current Swarm State\n");
+  
+  if (state.epicId && state.epicTitle) {
+    parts.push(`**Epic:** ${state.epicId} - ${state.epicTitle}`);
+    
+    const totalSubtasks = state.subtasks.closed + state.subtasks.in_progress + 
+                          state.subtasks.open + state.subtasks.blocked;
+    
+    if (totalSubtasks > 0) {
+      parts.push(`**Subtasks:**`);
+      if (state.subtasks.closed > 0) parts.push(`  - ${state.subtasks.closed} closed`);
+      if (state.subtasks.in_progress > 0) parts.push(`  - ${state.subtasks.in_progress} in_progress`);
+      if (state.subtasks.open > 0) parts.push(`  - ${state.subtasks.open} open`);
+      if (state.subtasks.blocked > 0) parts.push(`  - ${state.subtasks.blocked} blocked`);
+    }
+  }
+  
+  parts.push(`**Project:** ${state.projectPath}`);
+  
+  if (state.epicId) {
+    parts.push(`\n## 🎯 YOU ARE THE COORDINATOR`);
+    parts.push(``);
+    parts.push(`**Primary role:** Orchestrate workers, review their output, unblock dependencies.`);
+    parts.push(`**Spawn workers** for implementation tasks - don't do them yourself.`);
+    parts.push(``);
+    parts.push(`**RESUME STEPS:**`);
+    parts.push(`1. Check swarm status: \`swarm_status(epic_id="${state.epicId}", project_key="${state.projectPath}")\``);
+    parts.push(`2. Check inbox for worker messages: \`swarmmail_inbox(limit=5)\``);
+    parts.push(`3. For in_progress subtasks: Review worker results with \`swarm_review\``);
+    parts.push(`4. For open subtasks: Spawn workers with \`swarm_spawn_subtask\``);
+    parts.push(`5. For blocked subtasks: Investigate and unblock`);
+  }
+  
+  return parts.join("\n");
+}
+
 // ============================================================================
 // Swarm Detection
 // ============================================================================
@@ -156,6 +227,23 @@ interface SwarmDetection {
   detected: boolean;
   confidence: "high" | "medium" | "low" | "none";
   reasons: string[];
+  /** Specific swarm state data for context injection */
+  state?: SwarmState;
+}
+
+/**
+ * Specific swarm state captured during detection
+ */
+interface SwarmState {
+  epicId?: string;
+  epicTitle?: string;
+  projectPath: string;
+  subtasks: {
+    closed: number;
+    in_progress: number;
+    open: number;
+    blocked: number;
+  };
 }
 
 /**
@@ -173,13 +261,38 @@ async function detectSwarm(): Promise<SwarmDetection> {
   let highConfidence = false;
   let mediumConfidence = false;
   let lowConfidence = false;
+  let state: SwarmState | undefined;
 
   try {
     const projectKey = getHiveWorkingDirectory();
+    
+    // Initialize state with project path
+    state = {
+      projectPath: projectKey,
+      subtasks: {
+        closed: 0,
+        in_progress: 0,
+        open: 0,
+        blocked: 0,
+      },
+    };
 
     // Check 1: Active reservations in swarm-mail (HIGH confidence)
+    const swarmMailStart = Date.now();
     try {
       const health = await checkSwarmHealth(projectKey);
+      const duration = Date.now() - swarmMailStart;
+
+      getLog().debug(
+        {
+          source: "swarm-mail",
+          duration_ms: duration,
+          healthy: health.healthy,
+          stats: health.stats,
+        },
+        "checked swarm-mail health",
+      );
+
       if (health.healthy && health.stats) {
         if (health.stats.reservations > 0) {
           highConfidence = true;
@@ -194,14 +307,24 @@ async function detectSwarm(): Promise<SwarmDetection> {
           reasons.push(`${health.stats.messages} swarm messages`);
         }
       }
-    } catch {
+    } catch (error) {
+      getLog().debug(
+        {
+          source: "swarm-mail",
+          duration_ms: Date.now() - swarmMailStart,
+          error: error instanceof Error ? error.message : String(error),
+        },
+        "swarm-mail check failed",
+      );
       // Swarm-mail not available, continue with other checks
     }
 
     // Check 2: Hive cells (various confidence levels)
+    const hiveStart = Date.now();
     try {
       const adapter = await getHiveAdapter(projectKey);
       const cells = await adapter.queryCells(projectKey, {});
+      const duration = Date.now() - hiveStart;
 
       if (Array.isArray(cells) && cells.length > 0) {
         // HIGH: Any in_progress cells
@@ -213,7 +336,7 @@ async function detectSwarm(): Promise<SwarmDetection> {
 
         // MEDIUM: Open subtasks (cells with parent_id)
         const subtasks = cells.filter(
-          (c) => c.status === "open" && c.parent_id
+          (c) => c.status === "open" && c.parent_id,
         );
         if (subtasks.length > 0) {
           mediumConfidence = true;
@@ -222,11 +345,37 @@ async function detectSwarm(): Promise<SwarmDetection> {
 
         // MEDIUM: Unclosed epics
         const openEpics = cells.filter(
-          (c) => c.type === "epic" && c.status !== "closed"
+          (c) => c.type === "epic" && c.status !== "closed",
         );
         if (openEpics.length > 0) {
           mediumConfidence = true;
           reasons.push(`${openEpics.length} unclosed epics`);
+          
+          // Capture in_progress epic data for state
+          const inProgressEpic = openEpics.find((c) => c.status === "in_progress");
+          if (inProgressEpic && state) {
+            state.epicId = inProgressEpic.id;
+            state.epicTitle = inProgressEpic.title;
+            
+            // Count subtasks for this epic
+            const epicSubtasks = cells.filter((c) => c.parent_id === inProgressEpic.id);
+            state.subtasks.closed = epicSubtasks.filter((c) => c.status === "closed").length;
+            state.subtasks.in_progress = epicSubtasks.filter((c) => c.status === "in_progress").length;
+            state.subtasks.open = epicSubtasks.filter((c) => c.status === "open").length;
+            state.subtasks.blocked = epicSubtasks.filter((c) => c.status === "blocked").length;
+            
+            getLog().debug(
+              {
+                epic_id: state.epicId,
+                epic_title: state.epicTitle,
+                subtasks_closed: state.subtasks.closed,
+                subtasks_in_progress: state.subtasks.in_progress,
+                subtasks_open: state.subtasks.open,
+                subtasks_blocked: state.subtasks.blocked,
+              },
+              "captured epic state for context",
+            );
+          }
         }
 
         // MEDIUM: Recently updated cells (last hour)
@@ -242,14 +391,46 @@ async function detectSwarm(): Promise<SwarmDetection> {
           lowConfidence = true;
           reasons.push(`${cells.length} total cells in hive`);
         }
+
+        getLog().debug(
+          {
+            source: "hive",
+            duration_ms: duration,
+            total_cells: cells.length,
+            in_progress: inProgress.length,
+            open_subtasks: subtasks.length,
+            open_epics: openEpics.length,
+            recent_updates: recentCells.length,
+          },
+          "checked hive cells",
+        );
+      } else {
+        getLog().debug(
+          { source: "hive", duration_ms: duration, total_cells: 0 },
+          "hive empty",
+        );
       }
-    } catch {
+    } catch (error) {
+      getLog().debug(
+        {
+          source: "hive",
+          duration_ms: Date.now() - hiveStart,
+          error: error instanceof Error ? error.message : String(error),
+        },
+        "hive check failed",
+      );
       // Hive not available, continue
     }
-  } catch {
+  } catch (error) {
     // Project detection failed, use fallback
     lowConfidence = true;
     reasons.push("Could not detect project, using fallback");
+    getLog().debug(
+      {
+        error: error instanceof Error ? error.message : String(error),
+      },
+      "project detection failed",
+    );
   }
 
   // Determine overall confidence
@@ -264,11 +445,25 @@ async function detectSwarm(): Promise<SwarmDetection> {
     confidence = "none";
   }
 
-  return {
+  const result = {
     detected: confidence !== "none",
     confidence,
     reasons,
+    state,
   };
+
+  getLog().debug(
+    {
+      detected: result.detected,
+      confidence: result.confidence,
+      reason_count: result.reasons.length,
+      reasons: result.reasons,
+      has_state: !!result.state,
+    },
+    "swarm detection complete",
+  );
+
+  return result;
 }
 
 // ============================================================================
@@ -298,20 +493,98 @@ async function detectSwarm(): Promise<SwarmDetection> {
  */
 export function createCompactionHook() {
   return async (
-    _input: { sessionID: string },
+    input: { sessionID: string },
     output: { context: string[] },
   ): Promise<void> => {
-    const detection = await detectSwarm();
-
-    if (detection.confidence === "high" || detection.confidence === "medium") {
-      // Definite or probable swarm - inject full context
-      const header = `[Swarm detected: ${detection.reasons.join(", ")}]\n\n`;
-      output.context.push(header + SWARM_COMPACTION_CONTEXT);
-    } else if (detection.confidence === "low") {
-      // Possible swarm - inject fallback detection prompt
-      const header = `[Possible swarm: ${detection.reasons.join(", ")}]\n\n`;
-      output.context.push(header + SWARM_DETECTION_FALLBACK);
+    const startTime = Date.now();
+
+    getLog().info(
+      {
+        session_id: input.sessionID,
+        trigger: "session_compaction",
+      },
+      "compaction started",
+    );
+
+    try {
+      const detection = await detectSwarm();
+
+      if (
+        detection.confidence === "high" ||
+        detection.confidence === "medium"
+      ) {
+        // Definite or probable swarm - inject full context
+        const header = `[Swarm detected: ${detection.reasons.join(", ")}]\n\n`;
+        
+        // Build dynamic state section if we have specific data
+        let dynamicState = "";
+        if (detection.state && detection.state.epicId) {
+          dynamicState = buildDynamicSwarmState(detection.state) + "\n\n";
+        }
+        
+        const contextContent = header + dynamicState + SWARM_COMPACTION_CONTEXT;
+        output.context.push(contextContent);
+
+        getLog().info(
+          {
+            confidence: detection.confidence,
+            context_length: contextContent.length,
+            context_type: "full",
+            reasons: detection.reasons,
+            has_dynamic_state: !!dynamicState,
+            epic_id: detection.state?.epicId,
+          },
+          "injected swarm context",
+        );
+      } else if (detection.confidence === "low") {
+        // Possible swarm - inject fallback detection prompt
+        const header = `[Possible swarm: ${detection.reasons.join(", ")}]\n\n`;
+        const contextContent = header + SWARM_DETECTION_FALLBACK;
+        output.context.push(contextContent);
+
+        getLog().info(
+          {
+            confidence: detection.confidence,
+            context_length: contextContent.length,
+            context_type: "fallback",
+            reasons: detection.reasons,
+          },
+          "injected swarm context",
+        );
+      } else {
+        getLog().debug(
+          {
+            confidence: detection.confidence,
+            context_type: "none",
+          },
+          "no swarm detected, skipping injection",
+        );
+      }
+      // confidence === "none" - no injection, probably not a swarm
+
+      const duration = Date.now() - startTime;
+      getLog().info(
+        {
+          duration_ms: duration,
+          success: true,
+          detected: detection.detected,
+          confidence: detection.confidence,
+          context_injected: output.context.length > 0,
+        },
+        "compaction complete",
+      );
+    } catch (error) {
+      const duration = Date.now() - startTime;
+      getLog().error(
+        {
+          duration_ms: duration,
+          success: false,
+          error: error instanceof Error ? error.message : String(error),
+          stack: error instanceof Error ? error.stack : undefined,
+        },
+        "compaction failed",
+      );
+      // Don't throw - compaction hook failures shouldn't break the session
     }
-    // confidence === "none" - no injection, probably not a swarm
   };
 }

package/src/index.ts

@@ -47,6 +47,8 @@ import { repoCrawlTools } from "./repo-crawl";
 import { skillsTools, setSkillsProjectDirectory } from "./skills";
 import { mandateTools } from "./mandates";
 import { memoryTools } from "./memory-tools";
+import { observabilityTools } from "./observability-tools";
+import { researchTools } from "./swarm-research";
 import {
   guardrailOutput,
   DEFAULT_GUARDRAIL_CONFIG,
@@ -154,7 +156,7 @@ export const SwarmPlugin: Plugin = async (
  * - mandate:file, mandate:vote, mandate:query, etc.
  * - semantic-memory:store, semantic-memory:find, semantic-memory:get, etc.
  */
-    tool: {
+     tool: {
       ...hiveTools,
       ...swarmMailTools,
       ...structuredTools,
@@ -165,6 +167,8 @@ export const SwarmPlugin: Plugin = async (
       ...skillsTools,
       ...mandateTools,
       ...memoryTools,
+      ...observabilityTools,
+      ...researchTools,
     },
 
     /**
@@ -679,3 +683,52 @@ export {
   type OperationResult,
 } from "./memory-tools";
 export type { Memory, SearchResult, SearchOptions } from "swarm-mail";
+
+/**
+ * Re-export logger infrastructure
+ *
+ * Includes:
+ * - getLogger - Gets or creates the main logger instance
+ * - createChildLogger - Creates a module-specific child logger with separate log file
+ * - logger - Default logger instance for immediate use
+ *
+ * Features:
+ * - Daily log rotation via pino-roll (numeric format: swarm.1log, swarm.2log, etc.)
+ * - 14-day retention
+ * - Module-specific child loggers
+ * - Pretty mode for development (SWARM_LOG_PRETTY=1)
+ * - Logs to ~/.config/swarm-tools/logs/
+ *
+ * @example
+ * ```typescript
+ * import { logger, createChildLogger } from "opencode-swarm-plugin";
+ *
+ * // Use default logger
+ * logger.info("Application started");
+ *
+ * // Create module-specific logger
+ * const compactionLog = createChildLogger("compaction");
+ * compactionLog.info("Compaction started");
+ * ```
+ */
+export { getLogger, createChildLogger, logger } from "./logger";
+
+/**
+ * Re-export swarm-research module
+ *
+ * Includes:
+ * - discoverDocTools - Discover available documentation tools
+ * - getInstalledVersions - Get installed package versions from lockfile
+ * - researchTools - Plugin tools for tool discovery and version detection
+ *
+ * Types:
+ * - DiscoveredTool - Tool discovery result interface
+ * - VersionInfo - Package version information
+ */
+export {
+  discoverDocTools,
+  getInstalledVersions,
+  researchTools,
+  type DiscoveredTool,
+  type VersionInfo,
+} from "./swarm-research";

package/src/logger.test.ts

@@ -0,0 +1,189 @@
+import { describe, test, expect, beforeEach, afterEach } from "bun:test";
+import { mkdir, rm, readdir } from "node:fs/promises";
+import { existsSync } from "node:fs";
+import { join } from "node:path";
+import { homedir } from "node:os";
+
+describe("Logger Infrastructure", () => {
+  const testLogDir = join(homedir(), ".config", "swarm-tools", "logs-test");
+  let originalEnv: string | undefined;
+
+  beforeEach(async () => {
+    // Clean up test log directory
+    if (existsSync(testLogDir)) {
+      await rm(testLogDir, { recursive: true, force: true });
+    }
+    await mkdir(testLogDir, { recursive: true });
+    originalEnv = process.env.SWARM_LOG_PRETTY;
+
+    // Clear module cache to reset logger instances
+    delete require.cache[require.resolve("./logger")];
+  });
+
+  afterEach(async () => {
+    // Restore environment
+    if (originalEnv !== undefined) {
+      process.env.SWARM_LOG_PRETTY = originalEnv;
+    } else {
+      delete process.env.SWARM_LOG_PRETTY;
+    }
+
+    // Clean up test directory
+    if (existsSync(testLogDir)) {
+      await rm(testLogDir, { recursive: true, force: true });
+    }
+  });
+
+  describe("getLogger", () => {
+    test("returns a valid Pino logger instance", async () => {
+      const { getLogger } = await import("./logger");
+      const logger = getLogger(testLogDir);
+
+      expect(logger).toBeDefined();
+      expect(typeof logger.info).toBe("function");
+      expect(typeof logger.error).toBe("function");
+      expect(typeof logger.debug).toBe("function");
+      expect(typeof logger.warn).toBe("function");
+    });
+
+    test("creates log directory if it doesn't exist", async () => {
+      const newDir = join(testLogDir, "nested", "path");
+      const { getLogger } = await import("./logger");
+
+      getLogger(newDir);
+
+      expect(existsSync(newDir)).toBe(true);
+    });
+
+    test("creates log file with numeric rotation pattern", async () => {
+      const { getLogger } = await import("./logger");
+      const logger = getLogger(testLogDir);
+
+      // Write a log to force file creation
+      logger.info("test message");
+
+      // Wait for async file creation (pino-roll is async)
+      await new Promise((resolve) => setTimeout(resolve, 500));
+
+      const files = await readdir(testLogDir);
+      // pino-roll format: {filename}.{number}log (e.g., swarm.1log)
+      const logFile = files.find((f) => f.match(/^swarm\.\d+log$/));
+
+      expect(logFile).toBeDefined();
+    });
+
+    test("writes log entries to file", async () => {
+      const { getLogger } = await import("./logger");
+      const logger = getLogger(testLogDir);
+
+      logger.info("test log entry");
+      logger.error("test error entry");
+
+      // Wait for async file writes
+      await new Promise((resolve) => setTimeout(resolve, 500));
+
+      const files = await readdir(testLogDir);
+      expect(files.length).toBeGreaterThan(0);
+    });
+  });
+
+  describe("createChildLogger", () => {
+    test("creates child logger with module namespace", async () => {
+      const { getLogger, createChildLogger } = await import("./logger");
+      getLogger(testLogDir); // Initialize main logger
+
+      const childLogger = createChildLogger("compaction", testLogDir);
+
+      expect(childLogger).toBeDefined();
+      expect(typeof childLogger.info).toBe("function");
+    });
+
+    test("child logger writes to module-specific file", async () => {
+      const { getLogger, createChildLogger } = await import("./logger");
+      getLogger(testLogDir);
+
+      const childLogger = createChildLogger("compaction", testLogDir);
+      childLogger.info("compaction test message");
+
+      // Wait for async file writes
+      await new Promise((resolve) => setTimeout(resolve, 500));
+
+      const files = await readdir(testLogDir);
+      // pino-roll format: {module}.{number}log (e.g., compaction.1log)
+      const compactionLog = files.find((f) => f.match(/^compaction\.\d+log$/));
+
+      expect(compactionLog).toBeDefined();
+    });
+
+    test("multiple child loggers write to separate files", async () => {
+      const { getLogger, createChildLogger } = await import("./logger");
+      getLogger(testLogDir);
+
+      const compactionLogger = createChildLogger("compaction", testLogDir);
+      const cliLogger = createChildLogger("cli", testLogDir);
+
+      compactionLogger.info("compaction message");
+      cliLogger.info("cli message");
+
+      // Wait for async file writes
+      await new Promise((resolve) => setTimeout(resolve, 500));
+
+      const files = await readdir(testLogDir);
+      // pino-roll format: {module}.{number}log
+      const compactionLog = files.find((f) => f.match(/^compaction\.\d+log$/));
+      const cliLog = files.find((f) => f.match(/^cli\.\d+log$/));
+
+      expect(compactionLog).toBeDefined();
+      expect(cliLog).toBeDefined();
+    });
+  });
+
+  describe("Pretty mode", () => {
+    test("respects SWARM_LOG_PRETTY=1 environment variable", async () => {
+      process.env.SWARM_LOG_PRETTY = "1";
+
+      // Force reimport to pick up env var
+      delete require.cache[require.resolve("./logger")];
+      const { getLogger } = await import("./logger");
+
+      const logger = getLogger(testLogDir);
+
+      // If pretty mode is enabled, logger should have prettyPrint config
+      // We can't easily inspect Pino internals, but we can verify it doesn't throw
+      expect(logger).toBeDefined();
+      expect(typeof logger.info).toBe("function");
+
+      logger.info("pretty test message");
+    });
+
+    test("works without pretty mode by default", async () => {
+      delete process.env.SWARM_LOG_PRETTY;
+
+      // Force reimport
+      delete require.cache[require.resolve("./logger")];
+      const { getLogger } = await import("./logger");
+
+      const logger = getLogger(testLogDir);
+
+      expect(logger).toBeDefined();
+      logger.info("normal mode message");
+    });
+  });
+
+  describe("Log rotation", () => {
+    test("sets up daily rotation with 14-day retention", async () => {
+      const { getLogger } = await import("./logger");
+      const logger = getLogger(testLogDir);
+
+      // Write logs to trigger rotation setup
+      logger.info("rotation test");
+
+      // Wait for async file creation
+      await new Promise((resolve) => setTimeout(resolve, 500));
+
+      // Verify log file exists (rotation config is internal to pino-roll)
+      const files = await readdir(testLogDir);
+      expect(files.length).toBeGreaterThan(0);
+    });
+  });
+});