opencode-swarm-plugin 0.39.1 → 0.40.0

package/.hive/issues.jsonl

@@ -37,3 +37,19 @@
 {"id":"opencode-swarm-plugin--ys7z8-mjkwt9s6xoa","title":"Run migration and verify data integrity","status":"closed","priority":2,"issue_type":"task","created_at":"2025-12-25T03:55:11.430Z","updated_at":"2025-12-25T04:14:16.676Z","closed_at":"2025-12-25T04:14:16.676Z","parent_id":"opencode-swarm-plugin--ys7z8-mjkwt9rqf2s","dependencies":[],"labels":[],"comments":[]}
 {"id":"opencode-swarm-plugin--ys7z8-mjkyhrqmecc","title":"Add quality gate filters to eval session loader","description":"Filter eval sessions by quality signals: minEvents >= 3, hasWorkerSpawn, hasReviewCompleted. Currently 67 of 82 sessions are noise (<3 events). Quality gate will keep ~15 high-signal sessions.","status":"closed","priority":1,"issue_type":"epic","created_at":"2025-12-25T04:42:14.062Z","updated_at":"2025-12-25T04:49:40.809Z","closed_at":"2025-12-25T04:49:40.809Z","dependencies":[],"labels":[],"comments":[]}
 {"id":"opencode-swarm-plugin--ys7z8-mjkyhrr2qm7","title":"Add quality filter options to loadCapturedSessions with TDD","status":"closed","priority":0,"issue_type":"task","created_at":"2025-12-25T04:42:14.078Z","updated_at":"2025-12-25T04:49:39.904Z","closed_at":"2025-12-25T04:49:39.904Z","parent_id":"opencode-swarm-plugin--ys7z8-mjkyhrqmecc","dependencies":[],"labels":[],"comments":[]}
+{"id":"opencode-swarm-plugin--ys7z8-mjl04zmvv7c","title":"Eval System Improvements: Tool + Event Capture + Scorers","description":"Improve eval system with:\n1. Plugin tool for running evals (eval_run)\n2. Capture decomposition_complete events\n3. Capture VIOLATION events\n4. Improve compaction prompt structure\n5. Add review efficiency scorer\n6. Enforce knowledge gathering validation\n\nTarget: 70% → 85% overall eval score","status":"open","priority":1,"issue_type":"epic","created_at":"2025-12-25T05:28:16.999Z","updated_at":"2025-12-25T05:28:16.999Z","dependencies":[],"labels":[],"comments":[]}
+{"id":"opencode-swarm-plugin--ys7z8-mjl04zn4u31","title":"Add eval_run plugin tool","status":"open","priority":1,"issue_type":"task","created_at":"2025-12-25T05:28:17.008Z","updated_at":"2025-12-25T05:28:17.008Z","parent_id":"opencode-swarm-plugin--ys7z8-mjl04zmvv7c","dependencies":[],"labels":[],"comments":[]}
+{"id":"opencode-swarm-plugin--ys7z8-mjl04znglws","title":"Capture VIOLATION events for coordinator discipline","status":"open","priority":1,"issue_type":"task","created_at":"2025-12-25T05:28:17.020Z","updated_at":"2025-12-25T05:28:17.020Z","parent_id":"opencode-swarm-plugin--ys7z8-mjl04zmvv7c","dependencies":[],"labels":[],"comments":[]}
+{"id":"opencode-swarm-plugin--ys7z8-mjl04znlxzw","title":"Improve compaction prompt structure","status":"open","priority":2,"issue_type":"task","created_at":"2025-12-25T05:28:17.025Z","updated_at":"2025-12-25T05:28:17.025Z","parent_id":"opencode-swarm-plugin--ys7z8-mjl04zmvv7c","dependencies":[],"labels":[],"comments":[]}
+{"id":"opencode-swarm-plugin--ys7z8-mjl04zn8by5","title":"Capture decomposition_complete event","status":"closed","priority":1,"issue_type":"task","created_at":"2025-12-25T05:28:17.012Z","updated_at":"2025-12-25T05:38:07.026Z","closed_at":"2025-12-25T05:38:07.026Z","parent_id":"opencode-swarm-plugin--ys7z8-mjl04zmvv7c","dependencies":[],"labels":[],"comments":[]}
+{"id":"opencode-swarm-plugin--ys7z8-mjl04znn0uk","title":"Add review efficiency scorer","status":"in_progress","priority":2,"issue_type":"task","created_at":"2025-12-25T05:28:17.027Z","updated_at":"2025-12-25T05:37:03.084Z","parent_id":"opencode-swarm-plugin--ys7z8-mjl04zmvv7c","dependencies":[],"labels":[],"comments":[]}
+{"id":"opencode-swarm-plugin--ys7z8-mjl04znqie9","title":"Update spawnEfficiency scorer fallback","status":"closed","priority":2,"issue_type":"task","created_at":"2025-12-25T05:28:17.030Z","updated_at":"2025-12-25T05:29:34.561Z","closed_at":"2025-12-25T05:29:34.561Z","parent_id":"opencode-swarm-plugin--ys7z8-mjl04zmvv7c","dependencies":[],"labels":[],"comments":[]}
+{"id":"opencode-swarm-plugin--ys7z8-mjljadmo9mg","title":"ADR-009: Pattern Catalog and Innovation Documentation","description":"Comprehensive analysis of opencode-swarm-plugin to document all patterns, innovations, and ideas. Each research worker analyzes a specific domain, then a synthesis worker consolidates findings into ADR-009.","status":"open","priority":1,"issue_type":"epic","created_at":"2025-12-25T14:24:21.120Z","updated_at":"2025-12-25T14:24:21.120Z","dependencies":[],"labels":[],"comments":[]}
+{"id":"opencode-swarm-plugin--ys7z8-mjljadmu3bx","title":"Research: Learning Systems (confidence decay, pattern maturity, anti-patterns)","status":"open","priority":1,"issue_type":"task","created_at":"2025-12-25T14:24:21.126Z","updated_at":"2025-12-25T14:24:21.126Z","parent_id":"opencode-swarm-plugin--ys7z8-mjljadmo9mg","dependencies":[],"labels":[],"comments":[]}
+{"id":"opencode-swarm-plugin--ys7z8-mjljadmw66u","title":"Research: Swarm Coordination (decomposition, orchestration, review, worktree)","status":"open","priority":1,"issue_type":"task","created_at":"2025-12-25T14:24:21.128Z","updated_at":"2025-12-25T14:24:21.128Z","parent_id":"opencode-swarm-plugin--ys7z8-mjljadmo9mg","dependencies":[],"labels":[],"comments":[]}
+{"id":"opencode-swarm-plugin--ys7z8-mjljadmyadr","title":"Research: Memory & Context Preservation (compaction, semantic memory)","status":"open","priority":1,"issue_type":"task","created_at":"2025-12-25T14:24:21.130Z","updated_at":"2025-12-25T14:24:21.130Z","parent_id":"opencode-swarm-plugin--ys7z8-mjljadmo9mg","dependencies":[],"labels":[],"comments":[]}
+{"id":"opencode-swarm-plugin--ys7z8-mjljadn06xp","title":"Research: Observability & Evaluation (logging, eval capture, gates)","status":"open","priority":1,"issue_type":"task","created_at":"2025-12-25T14:24:21.132Z","updated_at":"2025-12-25T14:24:21.132Z","parent_id":"opencode-swarm-plugin--ys7z8-mjljadmo9mg","dependencies":[],"labels":[],"comments":[]}
+{"id":"opencode-swarm-plugin--ys7z8-mjljadn1c2k","title":"Research: Skills System & Knowledge Injection","status":"open","priority":1,"issue_type":"task","created_at":"2025-12-25T14:24:21.133Z","updated_at":"2025-12-25T14:24:21.133Z","parent_id":"opencode-swarm-plugin--ys7z8-mjljadmo9mg","dependencies":[],"labels":[],"comments":[]}
+{"id":"opencode-swarm-plugin--ys7z8-mjljadn7knk","title":"Research: Mandates, Guardrails & Structured Output","status":"open","priority":1,"issue_type":"task","created_at":"2025-12-25T14:24:21.139Z","updated_at":"2025-12-25T14:24:21.139Z","parent_id":"opencode-swarm-plugin--ys7z8-mjljadmo9mg","dependencies":[],"labels":[],"comments":[]}
+{"id":"opencode-swarm-plugin--ys7z8-mjljadn8e6u","title":"Research: Existing ADRs & Documentation Gaps","status":"open","priority":1,"issue_type":"task","created_at":"2025-12-25T14:24:21.140Z","updated_at":"2025-12-25T14:24:21.140Z","parent_id":"opencode-swarm-plugin--ys7z8-mjljadmo9mg","dependencies":[],"labels":[],"comments":[]}
+{"id":"opencode-swarm-plugin--ys7z8-mjljadnaj6o","title":"Synthesize: Write ADR-009 Pattern Catalog","status":"open","priority":0,"issue_type":"task","created_at":"2025-12-25T14:24:21.142Z","updated_at":"2025-12-25T14:24:21.142Z","parent_id":"opencode-swarm-plugin--ys7z8-mjljadmo9mg","dependencies":[],"labels":[],"comments":[]}

package/CHANGELOG.md

@@ -1,5 +1,57 @@
 # opencode-swarm-plugin
 
+## 0.40.0
+
+### Minor Changes
+
+- [`948e031`](https://github.com/joelhooks/swarm-tools/commit/948e0318fe5e2c1a5d695a56533fc2a2a7753887) Thanks [@joelhooks](https://github.com/joelhooks)! - ## 🔭 Observability Swarm: See What the Bees Are Doing
+
+  > "The unexamined swarm is not worth coordinating." — Socrates, probably
+
+  Four parallel workers descended on the observability stack and emerged victorious. The compaction hook no longer runs in darkness, coordinator sessions are now viewable, and the docs finally explain what all those JSONL files are for.
+
+  ### What's New
+
+  **Compaction Observability** (`src/compaction-observability.ts`)
+
+  - Metrics collector tracks phases: START → GATHER → DETECT → INJECT → COMPLETE
+  - Pattern extraction/skipping with reasons ("why didn't this get captured?")
+  - Timing breakdown per phase (analysis vs extraction vs storage)
+  - 15 tests (11 unit + 4 integration)
+
+  **`swarm log sessions` CLI**
+
+  - `swarm log sessions` — list all captured coordinator sessions
+  - `swarm log sessions <id>` — view events for a session (partial ID matching)
+  - `swarm log sessions --latest` — quick access to most recent
+  - `--type`, `--since`, `--limit`, `--json` filters
+  - 64 tests covering parsing, listing, filtering
+
+  **Coordinator Observability Docs**
+
+  - AGENTS.md: overview with quick commands
+  - evals/README.md: deep dive with ASCII flow diagrams, event type reference, JSONL examples, jq recipes
+
+  **Research: Coordinator Prompt Eval** (`.hive/analysis/coordinator-prompt-eval-research.md`)
+
+  - 26KB analysis of prompt iteration strategies
+  - Recommends: versioning + evalite (defer LLM-as-Judge to v0.34+)
+  - Implementation plan with effort estimates
+
+  ### The Observability Story
+
+  ```
+  CAPTURE ──────────► VIEW ──────────► SCORE
+  (eval-capture.ts)   (swarm log       (coordinator
+                       sessions)        evals)
+  ```
+
+  Now you can answer:
+
+  - "What did the last 10 compaction runs extract?"
+  - "Why didn't this pattern get captured?"
+  - "Which coordinator sessions had violations?"
+
 ## 0.39.1
 
 ### Patch Changes

package/bin/swarm.test.ts

@@ -197,6 +197,412 @@ READ-ONLY research agent. Never modifies code - only gathers intel and stores fi
 // Log Command Tests (TDD)
 // ============================================================================
 
+// ============================================================================
+// Session Log Tests (TDD)
+// ============================================================================
+
+import type { CoordinatorEvent } from "../src/eval-capture";
+
+const TEST_SESSIONS_DIR = join(tmpdir(), "swarm-test-sessions");
+
+describe("swarm log sessions", () => {
+  beforeEach(() => {
+    // Create test sessions directory
+    if (!existsSync(TEST_SESSIONS_DIR)) {
+      mkdirSync(TEST_SESSIONS_DIR, { recursive: true });
+    }
+  });
+
+  afterEach(() => {
+    // Cleanup test directory
+    if (existsSync(TEST_SESSIONS_DIR)) {
+      rmSync(TEST_SESSIONS_DIR, { recursive: true, force: true });
+    }
+  });
+
+  // ========================================================================
+  // Helper Functions (to be implemented in swarm.ts)
+  // ========================================================================
+
+  function createTestSession(
+    sessionId: string,
+    epicId: string,
+    eventCount: number,
+    baseTimestamp?: number,
+  ): void {
+    const filePath = join(TEST_SESSIONS_DIR, `${sessionId}.jsonl`);
+    const lines: string[] = [];
+    const base = baseTimestamp || Date.now();
+
+    for (let i = 0; i < eventCount; i++) {
+      const event: CoordinatorEvent = {
+        session_id: sessionId,
+        epic_id: epicId,
+        timestamp: new Date(base - (eventCount - i) * 1000).toISOString(),
+        event_type: "DECISION",
+        decision_type: "worker_spawned",
+        payload: { worker_id: `worker-${i}` },
+      };
+      lines.push(JSON.stringify(event));
+    }
+
+    writeFileSync(filePath, lines.join("\n") + "\n");
+  }
+
+  /**
+   * Parse a session file and return events
+   */
+  function parseSessionFile(filePath: string): CoordinatorEvent[] {
+    if (!existsSync(filePath)) {
+      throw new Error(`Session file not found: ${filePath}`);
+    }
+
+    const content = readFileSync(filePath, "utf-8");
+    const lines = content.split("\n").filter((line) => line.trim());
+    const events: CoordinatorEvent[] = [];
+
+    for (const line of lines) {
+      try {
+        const parsed = JSON.parse(line);
+        events.push(parsed);
+      } catch {
+        // Skip invalid JSON lines
+      }
+    }
+
+    return events;
+  }
+
+  /**
+   * List all session files in a directory
+   */
+  function listSessionFiles(
+    dir: string,
+  ): Array<{
+    session_id: string;
+    file_path: string;
+    event_count: number;
+    start_time: string;
+    end_time?: string;
+  }> {
+    if (!existsSync(dir)) return [];
+
+    const files = readdirSync(dir).filter((f) => f.endsWith(".jsonl"));
+    const sessions: Array<{
+      session_id: string;
+      file_path: string;
+      event_count: number;
+      start_time: string;
+      end_time?: string;
+    }> = [];
+
+    for (const file of files) {
+      const filePath = join(dir, file);
+      try {
+        const events = parseSessionFile(filePath);
+        if (events.length === 0) continue;
+
+        const timestamps = events.map((e) => new Date(e.timestamp).getTime());
+        const startTime = new Date(Math.min(...timestamps)).toISOString();
+        const endTime =
+          timestamps.length > 1
+            ? new Date(Math.max(...timestamps)).toISOString()
+            : undefined;
+
+        sessions.push({
+          session_id: events[0].session_id,
+          file_path: filePath,
+          event_count: events.length,
+          start_time: startTime,
+          end_time: endTime,
+        });
+      } catch {
+        // Skip invalid files
+      }
+    }
+
+    // Sort by start time (newest first)
+    return sessions.sort((a, b) =>
+      new Date(b.start_time).getTime() - new Date(a.start_time).getTime()
+    );
+  }
+
+  /**
+   * Get the latest session file
+   */
+  function getLatestSession(
+    dir: string,
+  ): {
+    session_id: string;
+    file_path: string;
+    event_count: number;
+    start_time: string;
+    end_time?: string;
+  } | null {
+    const sessions = listSessionFiles(dir);
+    return sessions.length > 0 ? sessions[0] : null;
+  }
+
+  /**
+   * Filter events by type
+   */
+  function filterEventsByType(
+    events: CoordinatorEvent[],
+    eventType: string,
+  ): CoordinatorEvent[] {
+    if (eventType === "all") return events;
+    return events.filter((e) => e.event_type === eventType.toUpperCase());
+  }
+
+  /**
+   * Filter events by time
+   */
+  function filterEventsSince(
+    events: CoordinatorEvent[],
+    sinceMs: number,
+  ): CoordinatorEvent[] {
+    const cutoffTime = Date.now() - sinceMs;
+    return events.filter((e) =>
+      new Date(e.timestamp).getTime() >= cutoffTime
+    );
+  }
+
+  // ========================================================================
+  // Tests
+  // ========================================================================
+
+  describe("listSessionFiles", () => {
+    test("returns empty array when directory doesn't exist", () => {
+      const result = listSessionFiles("/nonexistent/directory");
+      expect(result).toEqual([]);
+    });
+
+    test("returns empty array when directory is empty", () => {
+      const result = listSessionFiles(TEST_SESSIONS_DIR);
+      expect(result).toEqual([]);
+    });
+
+    test("lists all session files with metadata", () => {
+      createTestSession("ses_abc123", "epic-1", 5);
+      createTestSession("ses_def456", "epic-2", 3);
+
+      const result = listSessionFiles(TEST_SESSIONS_DIR);
+
+      expect(result).toHaveLength(2);
+      expect(result[0].session_id).toMatch(/^ses_/);
+      expect(result[0].event_count).toBeGreaterThan(0);
+      expect(result[0].start_time).toBeTruthy();
+    });
+
+    test("calculates event count correctly", () => {
+      createTestSession("ses_test", "epic-1", 10);
+
+      const result = listSessionFiles(TEST_SESSIONS_DIR);
+
+      expect(result[0].event_count).toBe(10);
+    });
+
+    test("extracts start and end times from events", () => {
+      createTestSession("ses_test", "epic-1", 5);
+
+      const result = listSessionFiles(TEST_SESSIONS_DIR);
+
+      expect(result[0].start_time).toBeTruthy();
+      expect(new Date(result[0].start_time).getTime()).toBeLessThan(Date.now());
+    });
+
+    test("sorts sessions by start time (newest first)", () => {
+      // Create sessions with explicit different timestamps
+      const oldTime = Date.now() - 60000; // 1 minute ago
+      const newTime = Date.now();
+      
+      createTestSession("ses_old", "epic-1", 2, oldTime);
+      createTestSession("ses_new", "epic-2", 2, newTime);
+
+      const result = listSessionFiles(TEST_SESSIONS_DIR);
+
+      expect(result[0].session_id).toBe("ses_new");
+      expect(result[1].session_id).toBe("ses_old");
+    });
+  });
+
+  describe("parseSessionFile", () => {
+    test("parses valid JSONL session file", () => {
+      createTestSession("ses_parse", "epic-1", 3);
+      const filePath = join(TEST_SESSIONS_DIR, "ses_parse.jsonl");
+
+      const events = parseSessionFile(filePath);
+
+      expect(events).toHaveLength(3);
+      expect(events[0].session_id).toBe("ses_parse");
+      expect(events[0].event_type).toBe("DECISION");
+    });
+
+    test("handles file with trailing newlines", () => {
+      const filePath = join(TEST_SESSIONS_DIR, "ses_trailing.jsonl");
+      writeFileSync(
+        filePath,
+        '{"session_id":"test","epic_id":"e1","timestamp":"2025-01-01T00:00:00Z","event_type":"DECISION","decision_type":"worker_spawned","payload":{}}\n\n\n',
+      );
+
+      const events = parseSessionFile(filePath);
+
+      expect(events).toHaveLength(1);
+    });
+
+    test("skips invalid JSON lines", () => {
+      const filePath = join(TEST_SESSIONS_DIR, "ses_invalid.jsonl");
+      writeFileSync(
+        filePath,
+        '{"session_id":"test","epic_id":"e1","timestamp":"2025-01-01T00:00:00Z","event_type":"DECISION","decision_type":"worker_spawned","payload":{}}\ninvalid json\n{"session_id":"test","epic_id":"e1","timestamp":"2025-01-01T00:00:00Z","event_type":"OUTCOME","outcome_type":"subtask_success","payload":{}}\n',
+      );
+
+      const events = parseSessionFile(filePath);
+
+      expect(events).toHaveLength(2);
+    });
+
+    test("throws error for non-existent file", () => {
+      expect(() => parseSessionFile("/nonexistent/file.jsonl")).toThrow();
+    });
+  });
+
+  describe("getLatestSession", () => {
+    test("returns null when directory is empty", () => {
+      const result = getLatestSession(TEST_SESSIONS_DIR);
+      expect(result).toBeNull();
+    });
+
+    test("returns the most recent session", () => {
+      const oldTime = Date.now() - 60000; // 1 minute ago
+      const newTime = Date.now();
+      
+      createTestSession("ses_old", "epic-1", 2, oldTime);
+      createTestSession("ses_new", "epic-2", 3, newTime);
+
+      const result = getLatestSession(TEST_SESSIONS_DIR);
+
+      expect(result).not.toBeNull();
+      expect(result!.session_id).toBe("ses_new");
+    });
+  });
+
+  describe("filterEventsByType", () => {
+    test("filters DECISION events only", () => {
+      const events: CoordinatorEvent[] = [
+        {
+          session_id: "s1",
+          epic_id: "e1",
+          timestamp: "2025-01-01T00:00:00Z",
+          event_type: "DECISION",
+          decision_type: "worker_spawned",
+          payload: {},
+        },
+        {
+          session_id: "s1",
+          epic_id: "e1",
+          timestamp: "2025-01-01T00:01:00Z",
+          event_type: "VIOLATION",
+          violation_type: "coordinator_edited_file",
+          payload: {},
+        },
+        {
+          session_id: "s1",
+          epic_id: "e1",
+          timestamp: "2025-01-01T00:02:00Z",
+          event_type: "DECISION",
+          decision_type: "review_completed",
+          payload: {},
+        },
+      ];
+
+      const result = filterEventsByType(events, "DECISION");
+
+      expect(result).toHaveLength(2);
+      expect(result.every((e) => e.event_type === "DECISION")).toBe(true);
+    });
+
+    test("returns all events when type is 'all'", () => {
+      const events: CoordinatorEvent[] = [
+        {
+          session_id: "s1",
+          epic_id: "e1",
+          timestamp: "2025-01-01T00:00:00Z",
+          event_type: "DECISION",
+          decision_type: "worker_spawned",
+          payload: {},
+        },
+        {
+          session_id: "s1",
+          epic_id: "e1",
+          timestamp: "2025-01-01T00:01:00Z",
+          event_type: "VIOLATION",
+          violation_type: "coordinator_edited_file",
+          payload: {},
+        },
+      ];
+
+      const result = filterEventsByType(events, "all");
+
+      expect(result).toHaveLength(2);
+    });
+  });
+
+  describe("filterEventsSince", () => {
+    test("filters events within time window", () => {
+      const now = Date.now();
+      const events: CoordinatorEvent[] = [
+        {
+          session_id: "s1",
+          epic_id: "e1",
+          timestamp: new Date(now - 10000).toISOString(), // 10s ago
+          event_type: "DECISION",
+          decision_type: "worker_spawned",
+          payload: {},
+        },
+        {
+          session_id: "s1",
+          epic_id: "e1",
+          timestamp: new Date(now - 60000).toISOString(), // 1m ago
+          event_type: "VIOLATION",
+          violation_type: "coordinator_edited_file",
+          payload: {},
+        },
+        {
+          session_id: "s1",
+          epic_id: "e1",
+          timestamp: new Date(now - 3000).toISOString(), // 3s ago
+          event_type: "OUTCOME",
+          outcome_type: "subtask_success",
+          payload: {},
+        },
+      ];
+
+      const result = filterEventsSince(events, 30000); // Last 30s
+
+      expect(result).toHaveLength(2); // 10s and 3s ago
+    });
+
+    test("returns all events when sinceMs is very large", () => {
+      const now = Date.now();
+      const events: CoordinatorEvent[] = [
+        {
+          session_id: "s1",
+          epic_id: "e1",
+          timestamp: new Date(now - 1000).toISOString(),
+          event_type: "DECISION",
+          decision_type: "worker_spawned",
+          payload: {},
+        },
+      ];
+
+      const result = filterEventsSince(events, 86400000); // 1 day
+
+      expect(result).toHaveLength(1);
+    });
+  });
+});
+
 // ============================================================================
 // Cells Command Tests (TDD)
 // ============================================================================