opencode-swarm-plugin 0.32.0 → 0.34.0

package/bin/swarm.ts

@@ -1153,9 +1153,17 @@ const result2 = await Task(subagent_type="swarm/worker", prompt="<from above>")
 4. **SEND FEEDBACK** - Approve or request changes
    \`swarm_review_feedback(project_key, task_id, worker_id, status, issues)\`
    
-   If approved: Close cell, spawn next worker
-   If needs_changes: Worker retries (max 3 attempts)
-   If 3 failures: Mark blocked, escalate to human
+   **If approved:**
+   - Close cell, spawn next worker
+   
+   **If needs_changes:**
+   - \`swarm_review_feedback\` returns \`retry_context\` (NOT sends message - worker is dead)
+   - Generate retry prompt: \`swarm_spawn_retry(retry_context)\`
+   - Spawn NEW worker with Task() using retry prompt
+   - Max 3 attempts before marking task blocked
+   
+   **If 3 failures:**
+   - Mark task blocked, escalate to human
 
 5. **ONLY THEN** - Spawn next worker or complete
 
@@ -1322,6 +1330,233 @@ hive_update(id="<bead-id>", status="blocked")
 Begin by reading your full prompt and executing Step 1.
 `;
 
+const getResearcherAgent = (model: string) => `---
+name: swarm-researcher
+description: READ-ONLY research agent - discovers tools, fetches docs, stores findings
+model: ${model}
+---
+
+You are a research agent. Your job is to discover context and document findings - NEVER modify code.
+
+## CRITICAL: You Are READ-ONLY
+
+**YOU DO NOT:**
+- Edit code files
+- Run tests
+- Make commits
+- Reserve files (you don't edit, so no reservations needed)
+- Implement features
+
+**YOU DO:**
+- Discover available tools (MCP servers, skills, CLI tools)
+- Read lockfiles to get current package versions
+- Fetch documentation for those versions
+- Store findings in semantic-memory (full details)
+- Broadcast summaries via swarm mail (condensed)
+- Return structured summary for shared context
+
+## Workflow
+
+### Step 1: Initialize (MANDATORY FIRST)
+
+\`\`\`
+swarmmail_init(project_path="/abs/path/to/project", task_description="Research: <what you're researching>")
+\`\`\`
+
+### Step 2: Discover Available Tools
+
+**DO NOT assume what tools are installed. Discover them:**
+
+\`\`\`
+# Check what skills user has installed
+skills_list()
+
+# Check what MCP servers are available (look for context7, pdf-brain, fetch, etc.)
+# Note: No direct MCP listing tool - infer from task context or ask coordinator
+
+# Check for CLI tools if relevant (bd, cass, ubs, ollama)
+# Use Bash tool to check: which <tool-name>
+\`\`\`
+
+### Step 3: Load Relevant Skills
+
+Based on research task, load appropriate skills:
+
+\`\`\`
+skills_use(name="<skill-name>", context="Researching <topic>")
+\`\`\`
+
+### Step 4: Read Lockfiles (if researching dependencies)
+
+**DO NOT read implementation code.** Only read metadata:
+
+\`\`\`
+# For package.json projects
+read("package.json")
+read("package-lock.json") or read("bun.lock") or read("pnpm-lock.yaml")
+
+# For Python
+read("requirements.txt") or read("pyproject.toml")
+
+# For Go
+read("go.mod")
+\`\`\`
+
+Extract current version numbers for libraries you need to research.
+
+### Step 5: Fetch Documentation
+
+Use available doc tools to get version-specific docs:
+
+\`\`\`
+# If context7 available (check skills_list or task context)
+# Use it for library docs
+
+# If pdf-brain available
+pdf-brain_search(query="<library> <version> <topic>", limit=5)
+
+# If fetch tool available
+fetch(url="https://docs.example.com/v2.0/...")
+
+# If repo-crawl available for OSS libraries
+repo-crawl_readme(repo="owner/repo")
+repo-crawl_file(repo="owner/repo", path="docs/...")
+\`\`\`
+
+### Step 6: Store Full Findings in Semantic Memory
+
+**Store detailed findings for future agents:**
+
+\`\`\`
+semantic-memory_store(
+  information="Researched <library> v<version>. Key findings: <detailed notes with examples, gotchas, patterns>",
+  metadata="<library>, <version>, <topic>, research"
+)
+\`\`\`
+
+**Include:**
+- Library/framework versions discovered
+- Key API patterns
+- Breaking changes from previous versions
+- Common gotchas
+- Relevant examples
+
+### Step 7: Broadcast Condensed Summary via Swarm Mail
+
+**Send concise summary to coordinator:**
+
+\`\`\`
+swarmmail_send(
+  to=["coordinator"],
+  subject="Research Complete: <topic>",
+  body="<3-5 bullet points with key takeaways>",
+  thread_id="<epic-id>"
+)
+\`\`\`
+
+### Step 8: Return Structured Summary
+
+**Output format for shared_context:**
+
+\`\`\`json
+{
+  "researched": "<topic>",
+  "tools_discovered": ["skill-1", "skill-2", "mcp-server-1"],
+  "versions": {
+    "library-1": "1.2.3",
+    "library-2": "4.5.6"
+  },
+  "key_findings": [
+    "Finding 1 with actionable insight",
+    "Finding 2 with actionable insight",
+    "Finding 3 with actionable insight"
+  ],
+  "relevant_skills": ["skill-to-use-1", "skill-to-use-2"],
+  "stored_in_memory": true
+}
+\`\`\`
+
+## Tool Discovery Patterns
+
+### Skills Discovery
+
+\`\`\`
+skills_list()
+# Returns: Available skills from global, project, bundled sources
+
+# Load relevant skill for research domain
+skills_use(name="<skill>", context="Researching <topic>")
+\`\`\`
+
+### MCP Server Detection
+
+**No direct listing tool.** Infer from:
+- Task context (coordinator may mention available tools)
+- Trial: Try calling a tool and catch error if not available
+- Read OpenCode config if accessible
+
+### CLI Tool Detection
+
+\`\`\`
+# Check if tool is installed
+bash("which <tool>", description="Check if <tool> is available")
+
+# Examples:
+bash("which cass", description="Check CASS availability")
+bash("which ubs", description="Check UBS availability")
+bash("ollama --version", description="Check Ollama availability")
+\`\`\`
+
+## Context Efficiency Rules (MANDATORY)
+
+**NEVER dump raw documentation.** Always summarize.
+
+| ❌ Bad (Context Bomb) | ✅ Good (Condensed) |
+|---------------------|-------------------|
+| Paste entire API reference | "Library uses hooks API. Key hooks: useQuery, useMutation. Breaking change in v2: callbacks removed." |
+| Copy full changelog | "v2.0 breaking changes: renamed auth() → authenticate(), dropped IE11 support" |
+| Include all examples | "Common pattern: async/await with error boundaries (stored full example in semantic-memory)" |
+
+**Storage Strategy:**
+- **Semantic Memory**: Full details, examples, code snippets
+- **Swarm Mail**: 3-5 bullet points only
+- **Return Value**: Structured JSON summary
+
+## When to Use This Agent
+
+**DO spawn researcher when:**
+- Task requires understanding current tech stack versions
+- Need to fetch library/framework documentation
+- Discovering project conventions from config files
+- Researching best practices for unfamiliar domain
+
+**DON'T spawn researcher when:**
+- Information is already in semantic memory (query first!)
+- Task doesn't need external docs
+- Time-sensitive work (research adds latency)
+
+## Example Research Tasks
+
+**"Research Next.js 16 caching APIs"**
+
+1. Read package.json → extract Next.js version
+2. Use context7 or fetch to get Next.js 16 cache docs
+3. Store findings: unstable_cache, revalidatePath, cache patterns
+4. Broadcast: "Next.js 16 uses native fetch caching + unstable_cache for functions"
+5. Return structured summary with key APIs
+
+**"Discover available testing tools"**
+
+1. Check skills_list for testing-patterns skill
+2. Check which jest/vitest/bun (bash tool)
+3. Read package.json devDependencies
+4. Store findings: test runner, assertion library, coverage tool
+5. Broadcast: "Project uses Bun test with happy-dom"
+6. Return tool inventory
+
+Begin by executing Step 1 (swarmmail_init).
+`;
+
 // ============================================================================
 // Commands
 // ============================================================================
@@ -1533,6 +1768,7 @@ async function setup() {
   const swarmAgentDir = join(agentDir, "swarm");
   const plannerAgentPath = join(swarmAgentDir, "planner.md");
   const workerAgentPath = join(swarmAgentDir, "worker.md");
+  const researcherAgentPath = join(swarmAgentDir, "researcher.md");
   // Legacy flat paths (for detection/cleanup)
   const legacyPlannerPath = join(agentDir, "swarm-planner.md");
   const legacyWorkerPath = join(agentDir, "swarm-worker.md");
@@ -1542,13 +1778,14 @@ async function setup() {
     commandPath,
     plannerAgentPath,
     workerAgentPath,
+    researcherAgentPath,
     legacyPlannerPath,
     legacyWorkerPath,
   ].filter((f) => existsSync(f));
 
   if (existingFiles.length > 0) {
     p.log.success("Swarm is already configured!");
-    p.log.message(dim("  Found " + existingFiles.length + "/4 config files"));
+    p.log.message(dim("  Found " + existingFiles.length + "/5 config files"));
 
     const action = await p.select({
       message: "What would you like to do?",
@@ -2015,11 +2252,12 @@ async function setup() {
   stats[writeFileWithStatus(pluginPath, getPluginWrapper(), "Plugin")]++;
   stats[writeFileWithStatus(commandPath, SWARM_COMMAND, "Command")]++;
 
-  // Write nested agent files (swarm/planner.md, swarm/worker.md)
+  // Write nested agent files (swarm/planner.md, swarm/worker.md, swarm/researcher.md)
   // This is the format used by Task(subagent_type="swarm/worker")
   p.log.step("Writing agent configuration...");
   stats[writeFileWithStatus(plannerAgentPath, getPlannerAgent(coordinatorModel as string), "Planner agent")]++;
   stats[writeFileWithStatus(workerAgentPath, getWorkerAgent(workerModel as string), "Worker agent")]++;
+  stats[writeFileWithStatus(researcherAgentPath, getResearcherAgent(workerModel as string), "Researcher agent")]++;
 
   // Clean up legacy flat agent files if they exist
   if (existsSync(legacyPlannerPath) || existsSync(legacyWorkerPath)) {
@@ -2320,8 +2558,10 @@ function config() {
   const configDir = join(homedir(), ".config", "opencode");
   const pluginPath = join(configDir, "plugin", "swarm.ts");
   const commandPath = join(configDir, "command", "swarm.md");
-  const plannerAgentPath = join(configDir, "agent", "swarm-planner.md");
-  const workerAgentPath = join(configDir, "agent", "swarm-worker.md");
+  const swarmAgentDir = join(configDir, "agent", "swarm");
+  const plannerAgentPath = join(swarmAgentDir, "planner.md");
+  const workerAgentPath = join(swarmAgentDir, "worker.md");
+  const researcherAgentPath = join(swarmAgentDir, "researcher.md");
   const globalSkillsPath = join(configDir, "skills");
 
   console.log(yellow(BANNER));
@@ -2333,8 +2573,9 @@ function config() {
   const files = [
     { path: pluginPath, desc: "Plugin loader", emoji: "🔌" },
     { path: commandPath, desc: "/swarm command prompt", emoji: "📜" },
-    { path: plannerAgentPath, desc: "@swarm-planner agent", emoji: "🤖" },
-    { path: workerAgentPath, desc: "@swarm-worker agent", emoji: "🐝" },
+    { path: plannerAgentPath, desc: "@swarm/planner agent", emoji: "🤖" },
+    { path: workerAgentPath, desc: "@swarm/worker agent", emoji: "🐝" },
+    { path: researcherAgentPath, desc: "@swarm/researcher agent", emoji: "🔬" },
   ];
 
   for (const { path, desc, emoji } of files) {
@@ -2473,6 +2714,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 log       View swarm logs with filtering
   swarm update    Update to latest version
   swarm version   Show version and banner
   swarm tool      Execute a tool (for plugin wrapper)
@@ -2483,17 +2725,27 @@ ${cyan("Tool Execution:")}
   swarm tool <name>                    Execute tool with no args
   swarm tool <name> --json '<args>'    Execute tool with JSON args
 
+${cyan("Log Viewing:")}
+  swarm log                            Tail recent logs (last 50 lines)
+  swarm log <module>                   Filter by module (e.g., compaction)
+  swarm log --level <level>            Filter by level (trace, debug, info, warn, error, fatal)
+  swarm log --since <duration>         Time filter (30s, 5m, 2h, 1d)
+  swarm log --json                     Raw JSON output for jq
+  swarm log --limit <n>                Limit output to n lines (default: 50)
+
 ${cyan("Usage in OpenCode:")}
   /swarm "Add user authentication with OAuth"
-  @swarm-planner "Decompose this into parallel tasks"
-  @swarm-worker "Execute this specific subtask"
+  @swarm/planner "Decompose this into parallel tasks"
+  @swarm/worker "Execute this specific subtask"
+  @swarm/researcher "Research Next.js caching APIs"
 
 ${cyan("Customization:")}
   Edit the generated files to customize behavior:
-  ${dim("~/.config/opencode/command/swarm.md")}       - /swarm command prompt
-  ${dim("~/.config/opencode/agent/swarm-planner.md")}  - @swarm-planner (coordinator)
-  ${dim("~/.config/opencode/agent/swarm-worker.md")}   - @swarm-worker (fast executor)
-  ${dim("~/.config/opencode/plugin/swarm.ts")}        - Plugin loader
+  ${dim("~/.config/opencode/command/swarm.md")}           - /swarm command prompt
+  ${dim("~/.config/opencode/agent/swarm/planner.md")}     - @swarm/planner (coordinator)
+  ${dim("~/.config/opencode/agent/swarm/worker.md")}      - @swarm/worker (task executor)
+  ${dim("~/.config/opencode/agent/swarm/researcher.md")}  - @swarm/researcher (read-only research)
+  ${dim("~/.config/opencode/plugin/swarm.ts")}           - Plugin loader
 
 ${dim("Docs: https://github.com/joelhooks/opencode-swarm-plugin")}
 `);
@@ -2810,7 +3062,7 @@ async function migrate() {
     // Show results
     const showStat = (label: string, stat: { migrated: number; skipped: number; failed: number }) => {
       if (stat.migrated > 0 || stat.skipped > 0 || stat.failed > 0) {
-        const parts = [];
+        const parts: string[] = [];
         if (stat.migrated > 0) parts.push(green(`${stat.migrated} migrated`));
         if (stat.skipped > 0) parts.push(dim(`${stat.skipped} skipped`));
         if (stat.failed > 0) parts.push(`\x1b[31m${stat.failed} failed\x1b[0m`);
@@ -2838,6 +3090,207 @@ async function migrate() {
   }
 }
 
+// ============================================================================
+// Log Command - View swarm logs with filtering
+// ============================================================================
+
+interface LogLine {
+  level: number;
+  time: string;
+  module: string;
+  msg: string;
+}
+
+function parseLogLine(line: string): LogLine | null {
+  try {
+    const parsed = JSON.parse(line);
+    if (typeof parsed.level === "number" && parsed.time && parsed.msg) {
+      return {
+        level: parsed.level,
+        time: parsed.time,
+        module: parsed.module || "unknown",
+        msg: parsed.msg,
+      };
+    }
+  } catch {
+    // Invalid JSON
+  }
+  return null;
+}
+
+function levelToName(level: number): string {
+  if (level >= 60) return "FATAL";
+  if (level >= 50) return "ERROR";
+  if (level >= 40) return "WARN ";
+  if (level >= 30) return "INFO ";
+  if (level >= 20) return "DEBUG";
+  return "TRACE";
+}
+
+function levelToColor(level: number): (s: string) => string {
+  if (level >= 50) return (s: string) => `\x1b[31m${s}\x1b[0m`; // red
+  if (level >= 40) return (s: string) => `\x1b[33m${s}\x1b[0m`; // yellow
+  if (level >= 30) return green; // green
+  return dim; // dim for debug/trace
+}
+
+function levelNameToNumber(name: string): number {
+  const lower = name.toLowerCase();
+  if (lower === "fatal") return 60;
+  if (lower === "error") return 50;
+  if (lower === "warn") return 40;
+  if (lower === "info") return 30;
+  if (lower === "debug") return 20;
+  if (lower === "trace") return 10;
+  return 30; // default to info
+}
+
+function parseDuration(duration: string): number | null {
+  const match = duration.match(/^(\d+)([smhd])$/);
+  if (!match) return null;
+  
+  const [, num, unit] = match;
+  const value = parseInt(num, 10);
+  
+  const multipliers: Record<string, number> = {
+    s: 1000,
+    m: 60 * 1000,
+    h: 60 * 60 * 1000,
+    d: 24 * 60 * 60 * 1000,
+  };
+  
+  return value * multipliers[unit];
+}
+
+function formatLogLine(log: LogLine, useColor = true): string {
+  const timestamp = new Date(log.time).toLocaleTimeString();
+  const levelName = levelToName(log.level);
+  const module = log.module.padEnd(12);
+  const levelStr = useColor ? levelToColor(log.level)(levelName) : levelName;
+  
+  return `${timestamp} ${levelStr} ${module} ${log.msg}`;
+}
+
+function readLogFiles(dir: string): string[] {
+  if (!existsSync(dir)) return [];
+  
+  const allFiles = readdirSync(dir);
+  const logFiles = allFiles
+    .filter((f: string) => /\.\d+log$/.test(f))
+    .sort()
+    .map((f: string) => join(dir, f));
+  
+  const lines: string[] = [];
+  for (const file of logFiles) {
+    try {
+      const content = readFileSync(file, "utf-8");
+      const fileLines = content.split("\n").filter((line: string) => line.trim());
+      lines.push(...fileLines);
+    } catch {
+      // Skip unreadable files
+    }
+  }
+  
+  return lines;
+}
+
+async function logs() {
+  const args = process.argv.slice(3);
+  
+  // Parse arguments
+  let moduleFilter: string | null = null;
+  let levelFilter: number | null = null;
+  let sinceMs: number | null = null;
+  let jsonOutput = false;
+  let limit = 50;
+  
+  for (let i = 0; i < args.length; i++) {
+    const arg = args[i];
+    
+    if (arg === "--level" && i + 1 < args.length) {
+      levelFilter = levelNameToNumber(args[++i]);
+    } else if (arg === "--since" && i + 1 < args.length) {
+      const duration = parseDuration(args[++i]);
+      if (duration === null) {
+        p.log.error(`Invalid duration format: ${args[i]}`);
+        p.log.message(dim("  Use format: 30s, 5m, 2h, 1d"));
+        process.exit(1);
+      }
+      sinceMs = duration;
+    } else if (arg === "--json") {
+      jsonOutput = true;
+    } else if (arg === "--limit" && i + 1 < args.length) {
+      limit = parseInt(args[++i], 10);
+      if (isNaN(limit) || limit <= 0) {
+        p.log.error(`Invalid limit: ${args[i]}`);
+        process.exit(1);
+      }
+    } else if (!arg.startsWith("--")) {
+      // Positional arg = module filter
+      moduleFilter = arg;
+    }
+  }
+  
+  // Read logs from ~/.config/swarm-tools/logs/
+  const logsDir = join(homedir(), ".config", "swarm-tools", "logs");
+  
+  if (!existsSync(logsDir)) {
+    if (!jsonOutput) {
+      p.log.warn("No logs directory found");
+      p.log.message(dim(`  Expected: ${logsDir}`));
+    } else {
+      console.log(JSON.stringify({ logs: [] }));
+    }
+    return;
+  }
+  
+  const rawLines = readLogFiles(logsDir);
+  
+  // Parse and filter
+  let logs: LogLine[] = rawLines
+    .map(parseLogLine)
+    .filter((log): log is LogLine => log !== null);
+  
+  // Apply filters
+  if (moduleFilter) {
+    logs = logs.filter((log) => log.module === moduleFilter);
+  }
+  
+  if (levelFilter !== null) {
+    logs = logs.filter((log) => log.level >= levelFilter);
+  }
+  
+  if (sinceMs !== null) {
+    const cutoffTime = Date.now() - sinceMs;
+    logs = logs.filter((log) => new Date(log.time).getTime() >= cutoffTime);
+  }
+  
+  // Apply limit (keep most recent)
+  logs = logs.slice(-limit);
+  
+  // Output
+  if (jsonOutput) {
+    console.log(JSON.stringify({ logs }, null, 2));
+  } else {
+    if (logs.length === 0) {
+      p.log.warn("No logs found matching filters");
+      return;
+    }
+    
+    console.log(yellow(BANNER));
+    console.log(dim(`  Logs (${logs.length} entries)`));
+    if (moduleFilter) console.log(dim(`  Module: ${moduleFilter}`));
+    if (levelFilter !== null) console.log(dim(`  Level: >=${levelToName(levelFilter)}`));
+    if (sinceMs !== null) console.log(dim(`  Since: last ${args[args.indexOf("--since") + 1]}`));
+    console.log();
+    
+    for (const log of logs) {
+      console.log(formatLogLine(log));
+    }
+    console.log();
+  }
+}
+
 // ============================================================================
 // Database Info Command
 // ============================================================================
@@ -2981,6 +3434,10 @@ switch (command) {
   case "db":
     await db();
     break;
+  case "log":
+  case "logs":
+    await logs();
+    break;
   case "version":
   case "--version":
   case "-v":

package/dist/compaction-hook.d.ts

@@ -67,7 +67,7 @@ export declare const SWARM_DETECTION_FALLBACK = "## \uD83D\uDC1D Swarm Detection
  * });
  * ```
  */
-export declare function createCompactionHook(): (_input: {
+export declare function createCompactionHook(): (input: {
     sessionID: string;
 }, output: {
     context: string[];

package/dist/compaction-hook.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"compaction-hook.d.ts","sourceRoot":"","sources":["../src/compaction-hook.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AASH;;;;;;;;;GASG;AACH,eAAO,MAAM,wBAAwB,k9DAwDpC,CAAC;AAEF;;;;;GAKG;AACH,eAAO,MAAM,wBAAwB,0nCAiCpC,CAAC;AAoIF;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,wBAAgB,oBAAoB,KAEhC,QAAQ;IAAE,SAAS,EAAE,MAAM,CAAA;CAAE,EAC7B,QAAQ;IAAE,OAAO,EAAE,MAAM,EAAE,CAAA;CAAE,KAC5B,OAAO,CAAC,IAAI,CAAC,CAcjB"}
+{"version":3,"file":"compaction-hook.d.ts","sourceRoot":"","sources":["../src/compaction-hook.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AA+BH;;;;;;;;;GASG;AACH,eAAO,MAAM,wBAAwB,k9DAwDpC,CAAC;AAEF;;;;;GAKG;AACH,eAAO,MAAM,wBAAwB,0nCAiCpC,CAAC;AAuMF;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,wBAAgB,oBAAoB,KAEhC,OAAO;IAAE,SAAS,EAAE,MAAM,CAAA;CAAE,EAC5B,QAAQ;IAAE,OAAO,EAAE,MAAM,EAAE,CAAA;CAAE,KAC5B,OAAO,CAAC,IAAI,CAAC,CAmFjB"}