opencode-swarm-plugin 0.36.1 → 0.37.0

package/CHANGELOG.md

@@ -1,5 +1,47 @@
 # opencode-swarm-plugin
 
+## 0.37.0
+
+### Minor Changes
+
+- [`66b5795`](https://github.com/joelhooks/swarm-tools/commit/66b57951e2c114702c663b98829d5f7626607a16) Thanks [@joelhooks](https://github.com/joelhooks)! - ## 🐝 `swarm cells` - Query Your Hive Like a Pro
+
+  New CLI command AND plugin tool for querying cells directly from the database.
+
+  ### CLI: `swarm cells`
+
+  ```bash
+  swarm cells                      # List all cells (table format)
+  swarm cells --status open        # Filter by status
+  swarm cells --type bug           # Filter by type
+  swarm cells --ready              # Next unblocked cell
+  swarm cells mjkmd                # Partial ID lookup
+  swarm cells --json               # Raw JSON for scripting
+  ```
+
+  **Replaces:** The awkward `swarm tool hive_query --json '{"status":"open"}'` pattern.
+
+  ### Plugin Tool: `hive_cells`
+
+  ```typescript
+  // Agents can now query cells directly
+  hive_cells({ status: "open", type: "task" });
+  hive_cells({ id: "mjkmd" }); // Partial ID works!
+  hive_cells({ ready: true }); // Next unblocked
+  ```
+
+  **Why this matters:**
+
+  - Reads from DATABASE (fast, indexed) not JSONL files
+  - Partial ID resolution built-in
+  - Consistent JSON array output
+  - Rich descriptions encourage agentic use
+
+  ### Also Fixed
+
+  - `swarm_review_feedback` tests updated for coordinator-driven retry architecture
+  - 425 tests passing
+
 ## 0.36.1
 
 ### Patch Changes

package/bin/swarm.test.ts

@@ -197,6 +197,112 @@ READ-ONLY research agent. Never modifies code - only gathers intel and stores fi
 // Log Command Tests (TDD)
 // ============================================================================
 
+// ============================================================================
+// Cells Command Tests (TDD)
+// ============================================================================
+
+/**
+ * Format cells as table output
+ */
+function formatCellsTable(cells: Array<{
+  id: string;
+  title: string;
+  status: string;
+  priority: number;
+}>): string {
+  if (cells.length === 0) {
+    return "No cells found";
+  }
+
+  const rows = cells.map(c => ({
+    id: c.id,
+    title: c.title.length > 50 ? c.title.slice(0, 47) + "..." : c.title,
+    status: c.status,
+    priority: String(c.priority),
+  }));
+
+  // Calculate column widths
+  const widths = {
+    id: Math.max(2, ...rows.map(r => r.id.length)),
+    title: Math.max(5, ...rows.map(r => r.title.length)),
+    status: Math.max(6, ...rows.map(r => r.status.length)),
+    priority: Math.max(8, ...rows.map(r => r.priority.length)),
+  };
+
+  // Build header
+  const header = [
+    "ID".padEnd(widths.id),
+    "TITLE".padEnd(widths.title),
+    "STATUS".padEnd(widths.status),
+    "PRIORITY".padEnd(widths.priority),
+  ].join("  ");
+
+  const separator = "-".repeat(header.length);
+
+  // Build rows
+  const bodyRows = rows.map(r =>
+    [
+      r.id.padEnd(widths.id),
+      r.title.padEnd(widths.title),
+      r.status.padEnd(widths.status),
+      r.priority.padEnd(widths.priority),
+    ].join("  ")
+  );
+
+  return [header, separator, ...bodyRows].join("\n");
+}
+
+describe("Cells command", () => {
+  describe("formatCellsTable", () => {
+    test("formats cells as table with id, title, status, priority", () => {
+      const cells = [
+        {
+          id: "test-abc123-xyz",
+          title: "Fix bug",
+          status: "open",
+          priority: 0,
+          type: "bug",
+          created_at: 1234567890,
+          updated_at: 1234567890,
+        },
+        {
+          id: "test-def456-abc",
+          title: "Add feature",
+          status: "in_progress",
+          priority: 2,
+          type: "feature",
+          created_at: 1234567890,
+          updated_at: 1234567890,
+        },
+      ];
+
+      const table = formatCellsTable(cells);
+
+      // Should contain headers
+      expect(table).toContain("ID");
+      expect(table).toContain("TITLE");
+      expect(table).toContain("STATUS");
+      expect(table).toContain("PRIORITY");
+
+      // Should contain cell data
+      expect(table).toContain("test-abc123-xyz");
+      expect(table).toContain("Fix bug");
+      expect(table).toContain("open");
+      expect(table).toContain("0");
+
+      expect(table).toContain("test-def456-abc");
+      expect(table).toContain("Add feature");
+      expect(table).toContain("in_progress");
+      expect(table).toContain("2");
+    });
+
+    test("returns 'No cells found' for empty array", () => {
+      const table = formatCellsTable([]);
+      expect(table).toBe("No cells found");
+    });
+  });
+});
+
 describe("Log command helpers", () => {
   let testDir: string;
 

package/bin/swarm.ts

@@ -2722,6 +2722,7 @@ ${cyan("Commands:")}
   swarm config    Show paths to generated config files
   swarm agents    Update AGENTS.md with skill awareness
   swarm migrate   Migrate PGlite database to libSQL
+  swarm cells     List or get cells from database (replaces 'swarm tool hive_query')
   swarm log       View swarm logs with filtering
   swarm update    Update to latest version
   swarm version   Show version and banner
@@ -2733,6 +2734,14 @@ ${cyan("Tool Execution:")}
   swarm tool <name>                    Execute tool with no args
   swarm tool <name> --json '<args>'    Execute tool with JSON args
 
+${cyan("Cell Management:")}
+  swarm cells                          List cells from database (default: 20 most recent)
+  swarm cells <id>                     Get single cell by ID or partial hash
+  swarm cells --status <status>        Filter by status (open, in_progress, closed, blocked)
+  swarm cells --type <type>            Filter by type (task, bug, feature, epic, chore)
+  swarm cells --ready                  Show next ready (unblocked) cell
+  swarm cells --json                   Raw JSON output (array, no wrapper)
+
 ${cyan("Log Viewing:")}
   swarm log                            Tail recent logs (last 50 lines)
   swarm log <module>                   Filter by module (e.g., compaction)
@@ -3245,6 +3254,173 @@ function readLogFiles(dir: string): LogEntry[] {
   return entries;
 }
 
+/**
+ * Format cells as table output
+ */
+function formatCellsTable(cells: Array<{
+  id: string;
+  title: string;
+  status: string;
+  priority: number;
+}>): string {
+  if (cells.length === 0) {
+    return "No cells found";
+  }
+
+  const rows = cells.map(c => ({
+    id: c.id,
+    title: c.title.length > 50 ? c.title.slice(0, 47) + "..." : c.title,
+    status: c.status,
+    priority: String(c.priority),
+  }));
+
+  // Calculate column widths
+  const widths = {
+    id: Math.max(2, ...rows.map(r => r.id.length)),
+    title: Math.max(5, ...rows.map(r => r.title.length)),
+    status: Math.max(6, ...rows.map(r => r.status.length)),
+    priority: Math.max(8, ...rows.map(r => r.priority.length)),
+  };
+
+  // Build header
+  const header = [
+    "ID".padEnd(widths.id),
+    "TITLE".padEnd(widths.title),
+    "STATUS".padEnd(widths.status),
+    "PRIORITY".padEnd(widths.priority),
+  ].join("  ");
+
+  const separator = "-".repeat(header.length);
+
+  // Build rows
+  const bodyRows = rows.map(r =>
+    [
+      r.id.padEnd(widths.id),
+      r.title.padEnd(widths.title),
+      r.status.padEnd(widths.status),
+      r.priority.padEnd(widths.priority),
+    ].join("  ")
+  );
+
+  return [header, separator, ...bodyRows].join("\n");
+}
+
+/**
+ * List or get cells from database
+ */
+async function cells() {
+  const args = process.argv.slice(3);
+  
+  // Parse arguments
+  let cellId: string | null = null;
+  let statusFilter: string | null = null;
+  let typeFilter: string | null = null;
+  let readyOnly = false;
+  let jsonOutput = false;
+  
+  for (let i = 0; i < args.length; i++) {
+    const arg = args[i];
+    
+    if (arg === "--status" && i + 1 < args.length) {
+      statusFilter = args[++i];
+      if (!["open", "in_progress", "closed", "blocked"].includes(statusFilter)) {
+        p.log.error(`Invalid status: ${statusFilter}`);
+        p.log.message(dim("  Valid statuses: open, in_progress, closed, blocked"));
+        process.exit(1);
+      }
+    } else if (arg === "--type" && i + 1 < args.length) {
+      typeFilter = args[++i];
+      if (!["task", "bug", "feature", "epic", "chore"].includes(typeFilter)) {
+        p.log.error(`Invalid type: ${typeFilter}`);
+        p.log.message(dim("  Valid types: task, bug, feature, epic, chore"));
+        process.exit(1);
+      }
+    } else if (arg === "--ready") {
+      readyOnly = true;
+    } else if (arg === "--json") {
+      jsonOutput = true;
+    } else if (!arg.startsWith("--") && !arg.startsWith("-")) {
+      // Positional arg = cell ID (full or partial)
+      cellId = arg;
+    }
+  }
+  
+  // Get adapter using swarm-mail
+  const projectPath = process.cwd();
+  const { getSwarmMailLibSQL, createHiveAdapter, resolvePartialId } = await import("swarm-mail");
+  
+  try {
+    const swarmMail = await getSwarmMailLibSQL(projectPath);
+    const db = await swarmMail.getDatabase();
+    const adapter = createHiveAdapter(db, projectPath);
+    
+    // Run migrations to ensure schema exists
+    await adapter.runMigrations();
+    
+    // If cell ID provided, get single cell
+    if (cellId) {
+      // Resolve partial ID to full ID
+      const fullId = await resolvePartialId(adapter, projectPath, cellId) || cellId;
+      const cell = await adapter.getCell(projectPath, fullId);
+      
+      if (!cell) {
+        p.log.error(`Cell not found: ${cellId}`);
+        process.exit(1);
+      }
+      
+      if (jsonOutput) {
+        console.log(JSON.stringify([cell], null, 2));
+      } else {
+        const table = formatCellsTable([{
+          id: cell.id,
+          title: cell.title,
+          status: cell.status,
+          priority: cell.priority,
+        }]);
+        console.log(table);
+      }
+      return;
+    }
+    
+    // Otherwise query cells
+    let cells: Array<{ id: string; title: string; status: string; priority: number }>;
+    
+    if (readyOnly) {
+      const readyCell = await adapter.getNextReadyCell(projectPath);
+      cells = readyCell ? [{
+        id: readyCell.id,
+        title: readyCell.title,
+        status: readyCell.status,
+        priority: readyCell.priority,
+      }] : [];
+    } else {
+      const queriedCells = await adapter.queryCells(projectPath, {
+        status: statusFilter as any || undefined,
+        type: typeFilter as any || undefined,
+        limit: 20,
+      });
+      
+      cells = queriedCells.map(c => ({
+        id: c.id,
+        title: c.title,
+        status: c.status,
+        priority: c.priority,
+      }));
+    }
+    
+    if (jsonOutput) {
+      console.log(JSON.stringify(cells, null, 2));
+    } else {
+      const table = formatCellsTable(cells);
+      console.log(table);
+    }
+  } catch (error) {
+    const message = error instanceof Error ? error.message : String(error);
+    p.log.error(`Failed to query cells: ${message}`);
+    process.exit(1);
+  }
+}
+
 async function logs() {
   const args = process.argv.slice(3);
   
@@ -3614,6 +3790,9 @@ switch (command) {
   case "db":
     await db();
     break;
+  case "cells":
+    await cells();
+    break;
   case "log":
   case "logs":
     await logs();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "opencode-swarm-plugin",
-  "version": "0.36.1",
+  "version": "0.37.0",
   "description": "Multi-agent swarm coordination for OpenCode with learning capabilities, beads integration, and Agent Mail",
   "type": "module",
   "main": "./dist/index.js",

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,
 };