opencode-swarm-plugin 0.39.1 → 0.42.0

package/src/compaction-observability.integration.test.ts

@@ -0,0 +1,139 @@
+/**
+ * Integration tests for compaction hook observability
+ * 
+ * Tests the full integration of metrics collection with the compaction hook.
+ */
+
+import { afterEach, beforeEach, describe, expect, it, mock } from "bun:test";
+import { createCompactionHook } from "./compaction-hook";
+
+// Track log calls
+let logCalls: Array<{ level: string; data: unknown; message?: string }> = [];
+
+const createMockLogger = () => ({
+  info: (data: unknown, message?: string) => {
+    logCalls.push({ level: "info", data, message });
+  },
+  debug: (data: unknown, message?: string) => {
+    logCalls.push({ level: "debug", data, message });
+  },
+  warn: (data: unknown, message?: string) => {
+    logCalls.push({ level: "warn", data, message });
+  },
+  error: (data: unknown, message?: string) => {
+    logCalls.push({ level: "error", data, message });
+  },
+});
+
+// Mock dependencies
+mock.module("./hive", () => ({
+  getHiveWorkingDirectory: () => "/test/project",
+  getHiveAdapter: async () => ({
+    queryCells: async () => [],
+  }),
+}));
+
+mock.module("swarm-mail", () => ({
+  checkSwarmHealth: async () => ({
+    healthy: true,
+    database: "connected",
+    stats: {
+      events: 0,
+      agents: 0,
+      messages: 0,
+      reservations: 0,
+    },
+  }),
+}));
+
+mock.module("./logger", () => ({
+  createChildLogger: () => createMockLogger(),
+}));
+
+describe("Compaction Hook with Observability", () => {
+  beforeEach(() => {
+    logCalls = [];
+  });
+
+  afterEach(() => {
+    logCalls = [];
+  });
+
+  it("logs structured metrics on compaction run", async () => {
+    const hook = createCompactionHook();
+    const input = { sessionID: "test-session-123" };
+    const output = { context: [] as string[] };
+
+    await hook(input, output);
+
+    // Should have START log
+    const startLog = logCalls.find(
+      (log) => log.level === "info" && log.message === "compaction started",
+    );
+    expect(startLog).toBeDefined();
+    expect((startLog?.data as { session_id?: string })?.session_id).toBe("test-session-123");
+
+    // Should have COMPLETE log
+    const completeLog = logCalls.find(
+      (log) => log.level === "info" && log.message === "compaction complete",
+    );
+    expect(completeLog).toBeDefined();
+    expect((completeLog?.data as { duration_ms?: number })?.duration_ms).toBeGreaterThanOrEqual(0);
+    expect((completeLog?.data as { success?: boolean })?.success).toBe(true);
+  });
+
+  it("logs timing breakdown for each phase", async () => {
+    const hook = createCompactionHook();
+    await hook({ sessionID: "test" }, { context: [] });
+
+    // Should have debug logs for swarm-mail and hive checks
+    const swarmMailLog = logCalls.find(
+      (log) => log.level === "debug" && (log.data as { source?: string })?.source === "swarm-mail",
+    );
+    expect(swarmMailLog).toBeDefined();
+    expect((swarmMailLog?.data as { duration_ms?: number })?.duration_ms).toBeGreaterThanOrEqual(0);
+
+    const hiveLog = logCalls.find(
+      (log) => log.level === "debug" && (log.data as { source?: string })?.source === "hive",
+    );
+    expect(hiveLog).toBeDefined();
+    expect((hiveLog?.data as { duration_ms?: number })?.duration_ms).toBeGreaterThanOrEqual(0);
+  });
+
+  it("logs pattern extraction/skipping decisions", async () => {
+    const hook = createCompactionHook();
+    await hook({ sessionID: "test" }, { context: [] });
+
+    // Should have detection complete log
+    const detectionLog = logCalls.find(
+      (log) => log.level === "debug" && log.message === "swarm detection complete",
+    );
+    expect(detectionLog).toBeDefined();
+    expect((detectionLog?.data as { confidence?: string })?.confidence).toBeDefined();
+  });
+
+  it("captures metrics summary in completion log", async () => {
+    const hook = createCompactionHook();
+    await hook({ sessionID: "test-metrics" }, { context: [] });
+
+    const completeLog = logCalls.find(
+      (log) => log.level === "info" && log.message === "compaction complete",
+    );
+    expect(completeLog).toBeDefined();
+
+    const data = completeLog?.data as {
+      duration_ms?: number;
+      success?: boolean;
+      detected?: boolean;
+      confidence?: string;
+      context_injected?: boolean;
+    };
+
+    // Should have complete metrics
+    expect(data.duration_ms).toBeGreaterThanOrEqual(0);
+    expect(data.success).toBe(true);
+    expect(data.detected).toBeDefined();
+    expect(data.confidence).toBeDefined();
+    expect(data.context_injected).toBeDefined();
+  });
+});

package/src/compaction-observability.test.ts

@@ -0,0 +1,187 @@
+/**
+ * Tests for Compaction Observability
+ * 
+ * TDD for adding structured metrics, timing breakdown, and queryable history
+ * to the pre-compaction hook.
+ */
+
+import { describe, expect, it } from "bun:test";
+import {
+  CompactionPhase,
+  createMetricsCollector,
+  getMetricsSummary,
+  recordPatternExtracted,
+  recordPatternSkipped,
+  recordPhaseComplete,
+  recordPhaseStart,
+} from "./compaction-observability";
+
+describe("CompactionMetrics", () => {
+  describe("Phase timing", () => {
+    it("tracks timing for each phase", () => {
+      const metrics = createMetricsCollector();
+      
+      recordPhaseStart(metrics, CompactionPhase.DETECT);
+      // Simulate work
+      recordPhaseComplete(metrics, CompactionPhase.DETECT);
+      
+      const summary = getMetricsSummary(metrics);
+      
+      expect(summary.phases.DETECT).toBeDefined();
+      expect(summary.phases.DETECT.duration_ms).toBeGreaterThanOrEqual(0);
+      expect(summary.phases.DETECT.success).toBe(true);
+    });
+
+    it("tracks multiple phases independently", () => {
+      const metrics = createMetricsCollector();
+      
+      recordPhaseStart(metrics, CompactionPhase.GATHER_SWARM_MAIL);
+      recordPhaseComplete(metrics, CompactionPhase.GATHER_SWARM_MAIL);
+      
+      recordPhaseStart(metrics, CompactionPhase.GATHER_HIVE);
+      recordPhaseComplete(metrics, CompactionPhase.GATHER_HIVE);
+      
+      const summary = getMetricsSummary(metrics);
+      
+      expect(summary.phases.GATHER_SWARM_MAIL).toBeDefined();
+      expect(summary.phases.GATHER_HIVE).toBeDefined();
+    });
+
+    it("tracks phase failures", () => {
+      const metrics = createMetricsCollector();
+      
+      recordPhaseStart(metrics, CompactionPhase.INJECT);
+      recordPhaseComplete(metrics, CompactionPhase.INJECT, { 
+        success: false, 
+        error: "Context injection failed" 
+      });
+      
+      const summary = getMetricsSummary(metrics);
+      
+      expect(summary.phases.INJECT.success).toBe(false);
+      expect(summary.phases.INJECT.error).toBe("Context injection failed");
+    });
+  });
+
+  describe("Pattern extraction tracking", () => {
+    it("records extracted patterns with reasons", () => {
+      const metrics = createMetricsCollector();
+      
+      recordPatternExtracted(metrics, "epic_state", "Epic bd-123 in_progress");
+      recordPatternExtracted(metrics, "agent_name", "BoldWind registered");
+      
+      const summary = getMetricsSummary(metrics);
+      
+      expect(summary.patterns_extracted).toBe(2);
+      expect(summary.extracted_patterns).toContain("epic_state");
+      expect(summary.extracted_patterns).toContain("agent_name");
+    });
+
+    it("records skipped patterns with reasons", () => {
+      const metrics = createMetricsCollector();
+      
+      recordPatternSkipped(metrics, "subtask_details", "No subtasks found");
+      
+      const summary = getMetricsSummary(metrics);
+      
+      expect(summary.patterns_skipped).toBe(1);
+      expect(summary.skipped_patterns).toContain("subtask_details");
+    });
+
+    it("tracks extraction success rate", () => {
+      const metrics = createMetricsCollector();
+      
+      recordPatternExtracted(metrics, "epic_state", "Found epic");
+      recordPatternExtracted(metrics, "agent_name", "Found agent");
+      recordPatternSkipped(metrics, "reservations", "None active");
+      
+      const summary = getMetricsSummary(metrics);
+      
+      expect(summary.patterns_extracted).toBe(2);
+      expect(summary.patterns_skipped).toBe(1);
+      expect(summary.extraction_success_rate).toBeCloseTo(0.67, 1);
+    });
+  });
+
+  describe("Overall metrics", () => {
+    it("tracks total duration from start to complete", () => {
+      const metrics = createMetricsCollector();
+      const startTime = Date.now();
+      
+      recordPhaseStart(metrics, CompactionPhase.START);
+      recordPhaseComplete(metrics, CompactionPhase.START);
+      
+      recordPhaseStart(metrics, CompactionPhase.DETECT);
+      recordPhaseComplete(metrics, CompactionPhase.DETECT);
+      
+      recordPhaseStart(metrics, CompactionPhase.COMPLETE);
+      recordPhaseComplete(metrics, CompactionPhase.COMPLETE);
+      
+      const summary = getMetricsSummary(metrics);
+      
+      expect(summary.total_duration_ms).toBeGreaterThanOrEqual(0);
+      expect(summary.total_duration_ms).toBeLessThan(Date.now() - startTime + 10);
+    });
+
+    it("captures session metadata", () => {
+      const metrics = createMetricsCollector({
+        session_id: "test-session-123",
+        has_sdk_client: true,
+      });
+      
+      const summary = getMetricsSummary(metrics);
+      
+      expect(summary.session_id).toBe("test-session-123");
+      expect(summary.has_sdk_client).toBe(true);
+    });
+
+    it("captures final detection confidence", () => {
+      const metrics = createMetricsCollector();
+      
+      recordPhaseComplete(metrics, CompactionPhase.DETECT, {
+        confidence: "high",
+        detected: true,
+      });
+      
+      const summary = getMetricsSummary(metrics);
+      
+      expect(summary.confidence).toBe("high");
+      expect(summary.detected).toBe(true);
+    });
+  });
+
+  describe("Debug mode", () => {
+    it("records verbose decision details when enabled", () => {
+      const metrics = createMetricsCollector({ debug: true });
+      
+      recordPatternExtracted(metrics, "epic_state", "Epic bd-123 in_progress", {
+        cell_id: "bd-123",
+        cell_status: "in_progress",
+        subtask_count: 5,
+      });
+      
+      const summary = getMetricsSummary(metrics);
+      
+      // Debug details should be captured
+      expect(summary.debug_info).toBeDefined();
+      expect(summary.debug_info.length).toBeGreaterThan(0);
+    });
+  });
+});
+
+describe("Metrics persistence", () => {
+  it("can serialize metrics to JSON", () => {
+    const metrics = createMetricsCollector({ session_id: "test-123" });
+    
+    recordPhaseStart(metrics, CompactionPhase.DETECT);
+    recordPhaseComplete(metrics, CompactionPhase.DETECT);
+    recordPatternExtracted(metrics, "epic_state", "Found epic");
+    
+    const summary = getMetricsSummary(metrics);
+    const json = JSON.stringify(summary);
+    
+    expect(json).toContain("test-123");
+    expect(json).toContain("DETECT");
+    expect(json).toContain("epic_state");
+  });
+});

package/src/compaction-observability.ts

@@ -0,0 +1,324 @@
+/**
+ * Compaction Hook Observability
+ * 
+ * Structured logging, metrics, and queryable history for the pre-compaction hook.
+ * 
+ * **Philosophy:** Make the invisible visible. When patterns aren't extracted,
+ * when detection fails, when timing explodes - we need to know WHY.
+ * 
+ * @example
+ * ```typescript
+ * const metrics = createMetricsCollector({ session_id: "abc123" });
+ * 
+ * recordPhaseStart(metrics, CompactionPhase.DETECT);
+ * // ... detection logic ...
+ * recordPhaseComplete(metrics, CompactionPhase.DETECT, { confidence: "high" });
+ * 
+ * recordPatternExtracted(metrics, "epic_state", "Found epic bd-123");
+ * 
+ * const summary = getMetricsSummary(metrics);
+ * console.log(`Detected: ${summary.detected}, Confidence: ${summary.confidence}`);
+ * ```
+ */
+
+/**
+ * Compaction phases - aligned with existing log structure
+ * 
+ * From compaction-hook.ts:
+ * - 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
+ */
+export enum CompactionPhase {
+  START = "START",
+  GATHER_SWARM_MAIL = "GATHER_SWARM_MAIL",
+  GATHER_HIVE = "GATHER_HIVE",
+  DETECT = "DETECT",
+  INJECT = "INJECT",
+  COMPLETE = "COMPLETE",
+}
+
+/**
+ * Phase timing and outcome
+ */
+interface PhaseMetrics {
+  duration_ms: number;
+  success: boolean;
+  error?: string;
+  /** Additional phase-specific data */
+  metadata?: Record<string, unknown>;
+}
+
+/**
+ * Pattern extraction record
+ */
+interface PatternRecord {
+  pattern_type: string;
+  reason: string;
+  /** Debug details (only captured if debug mode enabled) */
+  details?: Record<string, unknown>;
+  timestamp: number;
+}
+
+/**
+ * Compaction metrics collector
+ * 
+ * Mutable state object that accumulates metrics during a compaction run.
+ */
+export interface CompactionMetrics {
+  /** Session metadata */
+  session_id?: string;
+  has_sdk_client?: boolean;
+  debug?: boolean;
+  
+  /** Phase timings */
+  phases: Map<CompactionPhase, {
+    start_time: number;
+    end_time?: number;
+    metadata?: Record<string, unknown>;
+    error?: string;
+  }>;
+  
+  /** Pattern extraction tracking */
+  extracted: PatternRecord[];
+  skipped: PatternRecord[];
+  
+  /** Final detection result */
+  confidence?: "high" | "medium" | "low" | "none";
+  detected?: boolean;
+  
+  /** Overall timing */
+  start_time: number;
+  end_time?: number;
+}
+
+/**
+ * Metrics summary (read-only snapshot)
+ */
+export interface CompactionMetricsSummary {
+  session_id?: string;
+  has_sdk_client?: boolean;
+  
+  /** Phase breakdown */
+  phases: Record<string, PhaseMetrics>;
+  
+  /** Pattern extraction stats */
+  patterns_extracted: number;
+  patterns_skipped: number;
+  extraction_success_rate: number;
+  extracted_patterns: string[];
+  skipped_patterns: string[];
+  
+  /** Detection outcome */
+  confidence?: "high" | "medium" | "low" | "none";
+  detected?: boolean;
+  
+  /** Timing */
+  total_duration_ms: number;
+  
+  /** Debug info (only if debug mode enabled) */
+  debug_info?: Array<{
+    phase: string;
+    pattern: string;
+    details: Record<string, unknown>;
+  }>;
+}
+
+/**
+ * Create a metrics collector
+ * 
+ * @param metadata - Session metadata to capture
+ * @returns Mutable metrics collector
+ */
+export function createMetricsCollector(metadata?: {
+  session_id?: string;
+  has_sdk_client?: boolean;
+  debug?: boolean;
+}): CompactionMetrics {
+  return {
+    session_id: metadata?.session_id,
+    has_sdk_client: metadata?.has_sdk_client,
+    debug: metadata?.debug,
+    phases: new Map(),
+    extracted: [],
+    skipped: [],
+    start_time: Date.now(),
+  };
+}
+
+/**
+ * Record phase start
+ * 
+ * @param metrics - Metrics collector
+ * @param phase - Phase being started
+ */
+export function recordPhaseStart(
+  metrics: CompactionMetrics,
+  phase: CompactionPhase,
+): void {
+  metrics.phases.set(phase, {
+    start_time: Date.now(),
+  });
+}
+
+/**
+ * Record phase completion
+ * 
+ * @param metrics - Metrics collector
+ * @param phase - Phase being completed
+ * @param result - Phase outcome
+ */
+export function recordPhaseComplete(
+  metrics: CompactionMetrics,
+  phase: CompactionPhase,
+  result?: {
+    success?: boolean;
+    error?: string;
+    confidence?: "high" | "medium" | "low" | "none";
+    detected?: boolean;
+    [key: string]: unknown;
+  },
+): void {
+  let phaseData = metrics.phases.get(phase);
+  if (!phaseData) {
+    // Phase wasn't started, record it now
+    phaseData = {
+      start_time: Date.now(),
+      end_time: Date.now(),
+      error: "Phase completed without start",
+    };
+    metrics.phases.set(phase, phaseData);
+  } else {
+    phaseData.end_time = Date.now();
+  }
+  
+  if (result) {
+    if (result.error) {
+      phaseData.error = result.error;
+    }
+    
+    // Extract known fields
+    // biome-ignore lint/correctness/noUnusedVariables: extracting for spread
+    const { success, error, confidence, detected, ...rest } = result;
+    
+    if (Object.keys(rest).length > 0) {
+      phaseData.metadata = rest;
+    }
+    
+    // Update top-level detection result if provided in result
+    if (confidence) {
+      metrics.confidence = confidence;
+    }
+    if (detected !== undefined) {
+      metrics.detected = detected;
+    }
+  }
+}
+
+/**
+ * Record an extracted pattern
+ * 
+ * @param metrics - Metrics collector
+ * @param pattern_type - Type of pattern extracted (e.g., "epic_state", "agent_name")
+ * @param reason - Human-readable reason for extraction
+ * @param details - Debug details (only captured if debug mode enabled)
+ */
+export function recordPatternExtracted(
+  metrics: CompactionMetrics,
+  pattern_type: string,
+  reason: string,
+  details?: Record<string, unknown>,
+): void {
+  const record: PatternRecord = {
+    pattern_type,
+    reason,
+    timestamp: Date.now(),
+  };
+  
+  if (metrics.debug && details) {
+    record.details = details;
+  }
+  
+  metrics.extracted.push(record);
+}
+
+/**
+ * Record a skipped pattern
+ * 
+ * @param metrics - Metrics collector
+ * @param pattern_type - Type of pattern that was skipped
+ * @param reason - Human-readable reason for skipping
+ */
+export function recordPatternSkipped(
+  metrics: CompactionMetrics,
+  pattern_type: string,
+  reason: string,
+): void {
+  metrics.skipped.push({
+    pattern_type,
+    reason,
+    timestamp: Date.now(),
+  });
+}
+
+/**
+ * Get metrics summary (read-only snapshot)
+ * 
+ * Computes derived metrics like success rates and total duration.
+ * 
+ * @param metrics - Metrics collector
+ * @returns Immutable summary
+ */
+export function getMetricsSummary(metrics: CompactionMetrics): CompactionMetricsSummary {
+  // Compute phase breakdown
+  const phases: Record<string, PhaseMetrics> = {};
+  for (const [phase, data] of metrics.phases) {
+    const duration = data.end_time ? data.end_time - data.start_time : 0;
+    phases[phase] = {
+      duration_ms: duration,
+      success: !data.error,
+      error: data.error,
+      metadata: data.metadata,
+    };
+  }
+  
+  // Compute extraction stats
+  const totalPatterns = metrics.extracted.length + metrics.skipped.length;
+  const extractionSuccessRate = totalPatterns > 0 
+    ? metrics.extracted.length / totalPatterns 
+    : 0;
+  
+  // Compute total duration
+  const totalDuration = metrics.end_time 
+    ? metrics.end_time - metrics.start_time 
+    : Date.now() - metrics.start_time;
+  
+  const summary: CompactionMetricsSummary = {
+    session_id: metrics.session_id,
+    has_sdk_client: metrics.has_sdk_client,
+    phases,
+    patterns_extracted: metrics.extracted.length,
+    patterns_skipped: metrics.skipped.length,
+    extraction_success_rate: extractionSuccessRate,
+    extracted_patterns: metrics.extracted.map(p => p.pattern_type),
+    skipped_patterns: metrics.skipped.map(p => p.pattern_type),
+    confidence: metrics.confidence,
+    detected: metrics.detected,
+    total_duration_ms: totalDuration,
+  };
+  
+  // Add debug info if enabled
+  if (metrics.debug) {
+    summary.debug_info = metrics.extracted
+      .filter(p => p.details !== undefined)
+      .map(p => ({
+        phase: "EXTRACT",
+        pattern: p.pattern_type,
+        details: p.details as Record<string, unknown>,
+      }));
+  }
+  
+  return summary;
+}

package/src/compaction-prompt-scorers.test.ts

@@ -173,16 +173,17 @@ describe("forbiddenToolsPresent scorer", () => {
 - Edit (use swarm_spawn_subtask)
 - Write (use swarm_spawn_subtask)
 - swarmmail_reserve (only workers reserve)
-- bash with git commit (workers commit)`,
+- git commit (workers commit)
+- bash (for file modifications)`,
 		};
 
 		const result = scoreForbiddenToolsPresent(prompt);
 
 		expect(result.score).toBe(1.0);
-		expect(result.message).toContain("All 4 forbidden tools");
+		expect(result.message).toContain("All 5 forbidden tools");
 	});
 
-	test("scores 0.75 when 3 out of 4 tools listed", () => {
+	test("scores 0.6 when 3 out of 5 tools listed", () => {
 		const prompt: CompactionPrompt = {
 			content: `🚫 FORBIDDEN TOOLS:
 - Edit
@@ -192,19 +193,19 @@ describe("forbiddenToolsPresent scorer", () => {
 
 		const result = scoreForbiddenToolsPresent(prompt);
 
-		expect(result.score).toBe(0.75);
-		expect(result.message).toContain("3/4");
+		expect(result.score).toBe(0.6);
+		expect(result.message).toContain("3/5");
 	});
 
-	test("scores 0.5 when 2 out of 4 tools listed", () => {
+	test("scores 0.4 when 2 out of 5 tools listed", () => {
 		const prompt: CompactionPrompt = {
 			content: `Don't use Edit or Write directly.`,
 		};
 
 		const result = scoreForbiddenToolsPresent(prompt);
 
-		expect(result.score).toBe(0.5);
-		expect(result.message).toContain("2/4");
+		expect(result.score).toBe(0.4);
+		expect(result.message).toContain("2/5");
 	});
 
 	test("scores 0.0 when no forbidden tools listed", () => {
@@ -215,7 +216,7 @@ describe("forbiddenToolsPresent scorer", () => {
 		const result = scoreForbiddenToolsPresent(prompt);
 
 		expect(result.score).toBe(0.0);
-		expect(result.message).toContain("0/4");
+		expect(result.message).toContain("0/5");
 	});
 });