opencode-swarm 4.4.0 → 4.5.0

package/README.md

@@ -1,9 +1,9 @@
 <p align="center">
-  <img src="https://img.shields.io/badge/version-4.3.1-blue" alt="Version">
+  <img src="https://img.shields.io/badge/version-4.5.0-blue" alt="Version">
   <img src="https://img.shields.io/badge/license-MIT-green" alt="License">
   <img src="https://img.shields.io/badge/opencode-plugin-purple" alt="OpenCode Plugin">
   <img src="https://img.shields.io/badge/agents-8-orange" alt="Agents">
-  <img src="https://img.shields.io/badge/tests-483-brightgreen" alt="Tests">
+  <img src="https://img.shields.io/badge/tests-622-brightgreen" alt="Tests">
 </p>
 
 <h1 align="center">🐝 OpenCode Swarm</h1>
@@ -313,37 +313,47 @@ Each architect automatically delegates to its own swarm's agents.
 ## Installation
 
 ```bash
-# Add to opencode.json
-{
-  "plugin": ["opencode-swarm"]
-}
-
-# Or install via CLI
+# Install via CLI (recommended)
 bunx opencode-swarm install
 ```
 
+### Uninstall
+
+```bash
+# Remove from opencode.json
+bunx opencode-swarm uninstall
+
+# Remove from opencode.json + clean up config files
+bunx opencode-swarm uninstall --clean
+```
+
 ---
 
-## What's New in v4.3.0
+## What's New
 
-### 🔧 Hooks Pipeline
-- **`safeHook()`** — Crash-safe wrapper for all hooks. Errors are caught and logged, never crash the plugin.
-- **`composeHandlers()`** — Compose multiple handlers for the same hook type (Plugin API allows only one handler per type).
+### v4.5.0 — Tech Debt + New Commands
+- **Lint cleanup** — Replaced string concatenation with template literals, documented `as any` casts with biome-ignore comments.
+- **Code deduplication** — Extracted `stripSwarmPrefix()` utility to eliminate 3 duplicate prefix-stripping blocks.
+- **`/swarm diagnose`** — Health check for `.swarm/` files, plan structure, and plugin configuration.
+- **`/swarm export`** — Export plan.md and context.md as portable JSON.
+- **`/swarm reset --confirm`** — Clear swarm state files with safety confirmation.
 
-### 📊 Context Pruning
-- **Token budget tracking** — Estimates context window usage and injects warnings at 70% and 90% thresholds.
-- **Enhanced session compaction** — Guides OpenCode's built-in compaction with plan.md phases and context.md decisions.
-- **System prompt enhancement** — Injects current phase, task, and key decisions to keep agents focused post-compaction.
+### v4.4.0 — DX & Quality
+- **CLI `uninstall` command** — Remove plugin with optional `--clean` flag.
+- **Custom error classes** — `SwarmError` hierarchy with actionable `guidance` messages.
+- **`/swarm history`** — View completed phases from plan.md.
+- **`/swarm config`** — View current resolved plugin configuration.
 
-### ⚡ Slash Commands
-- **`/swarm status`** — Current phase, progress, and agent count.
-- **`/swarm plan [N]`** — View full plan or a specific phase.
-- **`/swarm agents`** — List all registered agents with models and permissions.
+### v4.3.2 — Security Hardening
+- **Path validation** — `validateSwarmPath()` prevents directory traversal in `.swarm/` file operations.
+- **Fetch hardening** — 10s timeout, 5MB limit, retry logic for gitingest tool.
+- **Config limits** — Deep merge depth limit (10), config file size limit (100KB).
 
-### 🤖 Agent Awareness
-- **Activity tracking** — Tool usage tracked per agent via `tool.execute.before/after` hooks. Activity summary flushed to context.md every 20 events.
-- **Delegation tracking** — Active agent per session tracked via `chat.message` hook. Optional delegation chain logging.
-- **Cross-agent context** — System enhancer injects relevant context from other agents' activity into system prompts.
+### v4.3.0 — Hooks & Agent Awareness
+- **Hooks pipeline** — `safeHook()` crash-safe wrapper, `composeHandlers()` for multi-handler composition.
+- **Context pruning** — Token budget tracking with 70%/90% threshold warnings.
+- **Slash commands** — `/swarm status`, `/swarm plan`, `/swarm agents`.
+- **Agent awareness** — Activity tracking, delegation tracking, cross-agent context injection.
 
 All features are opt-in via configuration. See [Installation Guide](docs/installation.md) for config options.
 
@@ -380,6 +390,21 @@ All features are opt-in via configuration. See [Installation Guide](docs/install
 
 ---
 
+## Slash Commands
+
+| Command | Description |
+|---------|-------------|
+| `/swarm status` | Current phase, task progress, and agent count |
+| `/swarm plan [N]` | View full plan or filter by phase number |
+| `/swarm agents` | List all registered agents with models and permissions |
+| `/swarm history` | View completed phases with status icons |
+| `/swarm config` | View current resolved plugin configuration |
+| `/swarm diagnose` | Health check for .swarm/ files and config |
+| `/swarm export` | Export plan and context as portable JSON |
+| `/swarm reset --confirm` | Clear swarm state files (with safety gate) |
+
+---
+
 ## Configuration
 
 Create `~/.config/opencode/opencode-swarm.json`:
@@ -448,7 +473,22 @@ bun test
 bun test tests/unit/config/schema.test.ts
 ```
 
-447 unit tests across 21 files covering config, tools, agents, hooks, commands, and state. Uses Bun's built-in test runner — zero additional test dependencies.
+622 unit tests across 29 files covering config, tools, agents, hooks, commands, and state. Uses Bun's built-in test runner — zero additional test dependencies.
+
+## Troubleshooting
+
+### Plugin not loading
+1. Verify `opencode-swarm` is listed in your `opencode.json` plugins array
+2. Run `bunx opencode-swarm install` to auto-configure
+3. Run `/swarm diagnose` to check health status
+
+### Commands not working
+- Ensure you're using `/swarm <command>`, not `/swarm/<command>`
+- Run `/swarm` with no arguments to see available commands
+
+### Resuming a project
+- Swarm automatically detects `.swarm/plan.md` and resumes where you left off
+- If you get unexpected behavior, run `/swarm export` to backup, then `/swarm reset --confirm` to start fresh
 
 ---
 

package/dist/agents/index.d.ts

@@ -2,6 +2,12 @@ import type { AgentConfig as SDKAgentConfig } from '@opencode-ai/sdk';
 import { type PluginConfig } from '../config';
 import { type AgentDefinition } from './architect';
 export type { AgentDefinition } from './architect';
+/**
+ * Strip the swarm prefix from an agent name to get the base name.
+ * e.g., "local_coder" with prefix "local" → "coder"
+ * Returns the name unchanged if no prefix matches.
+ */
+export declare function stripSwarmPrefix(agentName: string, swarmPrefix?: string): string;
 /**
  * Create all agent definitions with configuration applied
  */

package/dist/commands/diagnose.d.ts

@@ -0,0 +1,5 @@
+/**
+ * Handles the /swarm diagnose command.
+ * Performs health checks on swarm state files and configuration.
+ */
+export declare function handleDiagnoseCommand(directory: string, _args: string[]): Promise<string>;

package/dist/commands/export.d.ts

@@ -0,0 +1,5 @@
+/**
+ * Handles the /swarm export command.
+ * Exports plan.md and context.md as a portable JSON object.
+ */
+export declare function handleExportCommand(directory: string, _args: string[]): Promise<string>;

package/dist/commands/index.d.ts

@@ -1,8 +1,11 @@
 import type { AgentDefinition } from '../agents';
 export { handleAgentsCommand } from './agents';
 export { handleConfigCommand } from './config';
+export { handleDiagnoseCommand } from './diagnose';
+export { handleExportCommand } from './export';
 export { handleHistoryCommand } from './history';
 export { handlePlanCommand } from './plan';
+export { handleResetCommand } from './reset';
 export { handleStatusCommand } from './status';
 /**
  * Creates a command.execute.before handler for /swarm commands.

package/dist/commands/reset.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Handles the /swarm reset command.
+ * Clears plan.md and context.md from .swarm/ directory.
+ * Requires --confirm flag as a safety gate.
+ */
+export declare function handleResetCommand(directory: string, args: string[]): Promise<string>;

package/dist/index.js

@@ -14246,28 +14246,28 @@ ${customAppendPrompt}`;
 }
 
 // src/agents/index.ts
-function getModelForAgent(agentName, swarmAgents, swarmPrefix) {
-  let baseAgentName = agentName;
-  if (swarmPrefix && agentName.startsWith(`${swarmPrefix}_`)) {
-    baseAgentName = agentName.substring(swarmPrefix.length + 1);
+function stripSwarmPrefix(agentName, swarmPrefix) {
+  if (!swarmPrefix || !agentName)
+    return agentName;
+  const prefixWithUnderscore = `${swarmPrefix}_`;
+  if (agentName.startsWith(prefixWithUnderscore)) {
+    return agentName.substring(prefixWithUnderscore.length);
   }
+  return agentName;
+}
+function getModelForAgent(agentName, swarmAgents, swarmPrefix) {
+  const baseAgentName = stripSwarmPrefix(agentName, swarmPrefix);
   const explicit = swarmAgents?.[baseAgentName]?.model;
   if (explicit)
     return explicit;
   return DEFAULT_MODELS[baseAgentName] ?? DEFAULT_MODELS.default;
 }
 function isAgentDisabled(agentName, swarmAgents, swarmPrefix) {
-  let baseAgentName = agentName;
-  if (swarmPrefix && agentName.startsWith(`${swarmPrefix}_`)) {
-    baseAgentName = agentName.substring(swarmPrefix.length + 1);
-  }
+  const baseAgentName = stripSwarmPrefix(agentName, swarmPrefix);
   return swarmAgents?.[baseAgentName]?.disabled === true;
 }
 function getTemperatureOverride(agentName, swarmAgents, swarmPrefix) {
-  let baseAgentName = agentName;
-  if (swarmPrefix && agentName.startsWith(`${swarmPrefix}_`)) {
-    baseAgentName = agentName.substring(swarmPrefix.length + 1);
-  }
+  const baseAgentName = stripSwarmPrefix(agentName, swarmPrefix);
   return swarmAgents?.[baseAgentName]?.temperature;
 }
 function applyOverrides(agent, swarmAgents, swarmPrefix) {
@@ -14534,6 +14534,92 @@ function estimateTokens(text) {
   return Math.ceil(text.length * 0.33);
 }
 
+// src/commands/diagnose.ts
+async function handleDiagnoseCommand(directory, _args) {
+  const checks3 = [];
+  const planContent = await readSwarmFileAsync(directory, "plan.md");
+  const contextContent = await readSwarmFileAsync(directory, "context.md");
+  if (planContent) {
+    const hasPhases = /^## Phase \d+/m.test(planContent);
+    const hasTasks = /^- \[[ x]\]/m.test(planContent);
+    if (hasPhases && hasTasks) {
+      checks3.push({
+        name: "plan.md",
+        status: "\u2705",
+        detail: "Found with valid phase structure"
+      });
+    } else {
+      checks3.push({
+        name: "plan.md",
+        status: "\u274C",
+        detail: "Found but missing phase/task structure"
+      });
+    }
+  } else {
+    checks3.push({ name: "plan.md", status: "\u274C", detail: "Not found" });
+  }
+  if (contextContent) {
+    checks3.push({ name: "context.md", status: "\u2705", detail: "Found" });
+  } else {
+    checks3.push({ name: "context.md", status: "\u274C", detail: "Not found" });
+  }
+  try {
+    const config2 = loadPluginConfig(directory);
+    if (config2) {
+      checks3.push({
+        name: "Plugin config",
+        status: "\u2705",
+        detail: "Valid configuration loaded"
+      });
+    } else {
+      checks3.push({
+        name: "Plugin config",
+        status: "\u2705",
+        detail: "Using defaults (no custom config)"
+      });
+    }
+  } catch {
+    checks3.push({
+      name: "Plugin config",
+      status: "\u274C",
+      detail: "Invalid configuration"
+    });
+  }
+  const passCount = checks3.filter((c) => c.status === "\u2705").length;
+  const totalCount = checks3.length;
+  const allPassed = passCount === totalCount;
+  const lines = [
+    "## Swarm Health Check",
+    "",
+    ...checks3.map((c) => `- ${c.status} **${c.name}**: ${c.detail}`),
+    "",
+    `**Result**: ${allPassed ? "\u2705 All checks passed" : `\u26A0\uFE0F ${passCount}/${totalCount} checks passed`}`
+  ];
+  return lines.join(`
+`);
+}
+
+// src/commands/export.ts
+async function handleExportCommand(directory, _args) {
+  const planContent = await readSwarmFileAsync(directory, "plan.md");
+  const contextContent = await readSwarmFileAsync(directory, "context.md");
+  const exportData = {
+    version: "4.5.0",
+    exported: new Date().toISOString(),
+    plan: planContent,
+    context: contextContent
+  };
+  const lines = [
+    "## Swarm Export",
+    "",
+    "```json",
+    JSON.stringify(exportData, null, 2),
+    "```"
+  ];
+  return lines.join(`
+`);
+}
+
 // src/commands/history.ts
 async function handleHistoryCommand(directory, _args) {
   const planContent = await readSwarmFileAsync(directory, "plan.md");
@@ -14628,6 +14714,47 @@ async function handlePlanCommand(directory, args) {
 `).trim();
 }
 
+// src/commands/reset.ts
+import * as fs2 from "fs";
+async function handleResetCommand(directory, args) {
+  const hasConfirm = args.includes("--confirm");
+  if (!hasConfirm) {
+    return [
+      "## Swarm Reset",
+      "",
+      "\u26A0\uFE0F This will delete plan.md and context.md from .swarm/",
+      "",
+      "**Tip**: Run `/swarm export` first to backup your state.",
+      "",
+      "To confirm, run: `/swarm reset --confirm`"
+    ].join(`
+`);
+  }
+  const filesToReset = ["plan.md", "context.md"];
+  const results = [];
+  for (const filename of filesToReset) {
+    try {
+      const resolvedPath = validateSwarmPath(directory, filename);
+      if (fs2.existsSync(resolvedPath)) {
+        fs2.unlinkSync(resolvedPath);
+        results.push(`- \u2705 Deleted ${filename}`);
+      } else {
+        results.push(`- \u23ED\uFE0F ${filename} not found (skipped)`);
+      }
+    } catch {
+      results.push(`- \u274C Failed to delete ${filename}`);
+    }
+  }
+  return [
+    "## Swarm Reset Complete",
+    "",
+    ...results,
+    "",
+    "Swarm state has been cleared. Start fresh with a new plan."
+  ].join(`
+`);
+}
+
 // src/hooks/extractors.ts
 function extractCurrentPhase(planContent) {
   if (!planContent) {
@@ -14804,7 +14931,10 @@ var HELP_TEXT = [
   "- `/swarm plan [phase]` \u2014 Show plan (optionally filter by phase number)",
   "- `/swarm agents` \u2014 List registered agents",
   "- `/swarm history` \u2014 Show completed phases summary",
-  "- `/swarm config` \u2014 Show current resolved configuration"
+  "- `/swarm config` \u2014 Show current resolved configuration",
+  "- `/swarm diagnose` \u2014 Run health check on swarm state",
+  "- `/swarm export` \u2014 Export plan and context as JSON",
+  "- `/swarm reset --confirm` \u2014 Clear swarm state files"
 ].join(`
 `);
 function createSwarmCommandHandler(directory, agents) {
@@ -14831,6 +14961,15 @@ function createSwarmCommandHandler(directory, agents) {
       case "config":
         text = await handleConfigCommand(directory, args);
         break;
+      case "diagnose":
+        text = await handleDiagnoseCommand(directory, args);
+        break;
+      case "export":
+        text = await handleExportCommand(directory, args);
+        break;
+      case "reset":
+        text = await handleResetCommand(directory, args);
+        break;
       default:
         text = HELP_TEXT;
         break;
@@ -14945,19 +15084,19 @@ function renderActivitySection() {
 function replaceOrAppendSection(content, heading, newSection) {
   const headingIndex = content.indexOf(heading);
   if (headingIndex === -1) {
-    return content.trimEnd() + `
+    return `${content.trimEnd()}
 
-` + newSection + `
+${newSection}
 `;
   }
   const afterHeading = content.substring(headingIndex + heading.length);
   const nextHeadingMatch = afterHeading.match(/\n## /);
   if (nextHeadingMatch && nextHeadingMatch.index !== undefined) {
     const endIndex = headingIndex + heading.length + nextHeadingMatch.index;
-    return content.substring(0, headingIndex) + newSection + `
-` + content.substring(endIndex + 1);
+    return `${content.substring(0, headingIndex)}${newSection}
+${content.substring(endIndex + 1)}`;
   }
-  return content.substring(0, headingIndex) + newSection + `
+  return `${content.substring(0, headingIndex)}${newSection}
 `;
 }
 // src/hooks/compaction-customizer.ts
@@ -15205,7 +15344,7 @@ ${activitySection}`;
       break;
   }
   if (contextSummary.length > maxChars) {
-    return contextSummary.substring(0, maxChars - 3) + "...";
+    return `${contextSummary.substring(0, maxChars - 3)}...`;
   }
   return contextSummary;
 }
@@ -27710,7 +27849,7 @@ Use these as DOMAIN values when delegating to @sme.`;
   }
 });
 // src/tools/file-extractor.ts
-import * as fs2 from "fs";
+import * as fs3 from "fs";
 import * as path4 from "path";
 var EXT_MAP = {
   python: ".py",
@@ -27773,8 +27912,8 @@ var extract_code_blocks = tool({
   execute: async (args) => {
     const { content, output_dir, prefix } = args;
     const targetDir = output_dir || process.cwd();
-    if (!fs2.existsSync(targetDir)) {
-      fs2.mkdirSync(targetDir, { recursive: true });
+    if (!fs3.existsSync(targetDir)) {
+      fs3.mkdirSync(targetDir, { recursive: true });
     }
     const pattern = /```(\w*)\n([\s\S]*?)```/g;
     const matches = [...content.matchAll(pattern)];
@@ -27793,12 +27932,12 @@ var extract_code_blocks = tool({
       const base = path4.basename(filepath, path4.extname(filepath));
       const ext = path4.extname(filepath);
       let counter = 1;
-      while (fs2.existsSync(filepath)) {
+      while (fs3.existsSync(filepath)) {
         filepath = path4.join(targetDir, `${base}_${counter}${ext}`);
         counter++;
       }
       try {
-        fs2.writeFileSync(filepath, code.trim(), "utf-8");
+        fs3.writeFileSync(filepath, code.trim(), "utf-8");
         savedFiles.push(filepath);
       } catch (error93) {
         errors5.push(`Failed to save ${filename}: ${error93 instanceof Error ? error93.message : String(error93)}`);

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "opencode-swarm",
-	"version": "4.4.0",
+	"version": "4.5.0",
 	"description": "Architect-centric agentic swarm plugin for OpenCode - hub-and-spoke orchestration with SME consultation, code generation, and QA review",
 	"main": "dist/index.js",
 	"types": "dist/index.d.ts",