opencode-swarm-plugin 0.11.2 → 0.12.0

package/.beads/issues.jsonl

@@ -678,6 +678,12 @@
 {"id":"opencode-swarm-plugin-fmkz8.1","title":"Step 1","description":"","status":"closed","priority":2,"issue_type":"task","created_at":"2025-12-08T11:12:43.192563-08:00","updated_at":"2025-12-08T11:12:43.285206-08:00","closed_at":"2025-12-08T11:12:43.285206-08:00","dependencies":[{"issue_id":"opencode-swarm-plugin-fmkz8.1","depends_on_id":"opencode-swarm-plugin-fmkz8","type":"parent-child","created_at":"2025-12-08T11:12:43.192901-08:00","created_by":"daemon"}]}
 {"id":"opencode-swarm-plugin-fmkz8.2","title":"Step 2","description":"","status":"closed","priority":2,"issue_type":"task","created_at":"2025-12-08T11:12:43.229469-08:00","updated_at":"2025-12-08T11:12:43.340511-08:00","closed_at":"2025-12-08T11:12:43.340511-08:00","dependencies":[{"issue_id":"opencode-swarm-plugin-fmkz8.2","depends_on_id":"opencode-swarm-plugin-fmkz8","type":"parent-child","created_at":"2025-12-08T11:12:43.229808-08:00","created_by":"daemon"}]}
 {"id":"opencode-swarm-plugin-fmte","title":"Thread link test bead","description":"[thread:test-thread-456]","status":"closed","priority":2,"issue_type":"task","created_at":"2025-12-08T08:14:30.118389-08:00","updated_at":"2025-12-08T08:14:31.757071-08:00","closed_at":"2025-12-08T08:14:31.757071-08:00"}
+{"id":"opencode-swarm-plugin-fn2a3","title":"CLI-based plugin wrapper for OpenCode","description":"Replace broken npm import plugin with thin wrapper that shells out to `swarm tool` CLI. Fixes bun: protocol crash.","status":"closed","priority":1,"issue_type":"epic","created_at":"2025-12-09T12:44:59.286448-08:00","updated_at":"2025-12-09T12:53:22.927803-08:00","closed_at":"2025-12-09T12:53:22.927803-08:00"}
+{"id":"opencode-swarm-plugin-fn2a3.1","title":"Add CLI tool subcommand with JSON interface","description":"","status":"closed","priority":1,"issue_type":"task","created_at":"2025-12-09T12:44:59.380582-08:00","updated_at":"2025-12-09T12:48:28.655484-08:00","closed_at":"2025-12-09T12:48:28.655484-08:00","dependencies":[{"issue_id":"opencode-swarm-plugin-fn2a3.1","depends_on_id":"opencode-swarm-plugin-fn2a3","type":"parent-child","created_at":"2025-12-09T12:44:59.381424-08:00","created_by":"daemon"}]}
+{"id":"opencode-swarm-plugin-fn2a3.2","title":"Add file-based session state for Agent Mail","description":"","status":"closed","priority":1,"issue_type":"task","created_at":"2025-12-09T12:44:59.452126-08:00","updated_at":"2025-12-09T12:50:05.569927-08:00","closed_at":"2025-12-09T12:50:05.569927-08:00","dependencies":[{"issue_id":"opencode-swarm-plugin-fn2a3.2","depends_on_id":"opencode-swarm-plugin-fn2a3","type":"parent-child","created_at":"2025-12-09T12:44:59.452571-08:00","created_by":"daemon"}]}
+{"id":"opencode-swarm-plugin-fn2a3.3","title":"Create plugin wrapper template generator","description":"","status":"closed","priority":1,"issue_type":"task","created_at":"2025-12-09T12:44:59.511026-08:00","updated_at":"2025-12-09T12:52:13.47915-08:00","closed_at":"2025-12-09T12:52:13.47915-08:00","dependencies":[{"issue_id":"opencode-swarm-plugin-fn2a3.3","depends_on_id":"opencode-swarm-plugin-fn2a3","type":"parent-child","created_at":"2025-12-09T12:44:59.511712-08:00","created_by":"daemon"}]}
+{"id":"opencode-swarm-plugin-fn2a3.4","title":"Update setup command to generate new plugin wrapper","description":"","status":"closed","priority":2,"issue_type":"task","created_at":"2025-12-09T12:44:59.559682-08:00","updated_at":"2025-12-09T12:53:13.282356-08:00","closed_at":"2025-12-09T12:53:13.282356-08:00","dependencies":[{"issue_id":"opencode-swarm-plugin-fn2a3.4","depends_on_id":"opencode-swarm-plugin-fn2a3","type":"parent-child","created_at":"2025-12-09T12:44:59.560036-08:00","created_by":"daemon"}]}
+{"id":"opencode-swarm-plugin-fn2a3.5","title":"Export tool registry from source modules","description":"","status":"closed","priority":1,"issue_type":"task","created_at":"2025-12-09T12:44:59.609125-08:00","updated_at":"2025-12-09T12:46:18.092813-08:00","closed_at":"2025-12-09T12:46:18.092813-08:00","dependencies":[{"issue_id":"opencode-swarm-plugin-fn2a3.5","depends_on_id":"opencode-swarm-plugin-fn2a3","type":"parent-child","created_at":"2025-12-09T12:44:59.609492-08:00","created_by":"daemon"}]}
 {"id":"opencode-swarm-plugin-fo9z","title":"Query test bead","description":"","status":"closed","priority":2,"issue_type":"task","created_at":"2025-12-08T07:53:43.635138-08:00","updated_at":"2025-12-08T07:53:46.190181-08:00","closed_at":"2025-12-08T07:53:46.190181-08:00"}
 {"id":"opencode-swarm-plugin-foht","title":"New feature request","description":"","status":"closed","priority":1,"issue_type":"feature","created_at":"2025-12-08T11:11:07.341455-08:00","updated_at":"2025-12-08T11:11:10.086863-08:00","closed_at":"2025-12-08T11:11:10.086863-08:00"}
 {"id":"opencode-swarm-plugin-fomf","title":"Limit test bead 1","description":"","status":"closed","priority":2,"issue_type":"task","created_at":"2025-12-08T11:12:25.714274-08:00","updated_at":"2025-12-08T11:12:28.097683-08:00","closed_at":"2025-12-08T11:12:28.097683-08:00"}

package/README.md

@@ -45,9 +45,9 @@ The setup wizard handles everything:
 │
 ◇  Setting up OpenCode integration...
 │
-◆  Plugin: ~/.config/opencode/plugins/swarm.ts
-◆  Command: ~/.config/opencode/commands/swarm.md
-◆  Agent: ~/.config/opencode/agents/swarm-planner.md
+◆  Plugin: ~/.config/opencode/plugin/swarm.ts
+◆  Command: ~/.config/opencode/command/swarm.md
+◆  Agent: ~/.config/opencode/agent/swarm-planner.md
 │
 └  Setup complete!
 ```
@@ -90,18 +90,18 @@ Run `swarm config` to see your config file paths:
 
 ```
 🔌 Plugin loader
-   ~/.config/opencode/plugins/swarm.ts
+   ~/.config/opencode/plugin/swarm.ts
 
 📜 /swarm command prompt
-   ~/.config/opencode/commands/swarm.md
+   ~/.config/opencode/command/swarm.md
 
 🤖 @swarm-planner agent
-   ~/.config/opencode/agents/swarm-planner.md
+   ~/.config/opencode/agent/swarm-planner.md
 ```
 
 ### /swarm Command
 
-The `/swarm` command is defined in `~/.config/opencode/commands/swarm.md`:
+The `/swarm` command is defined in `~/.config/opencode/command/swarm.md`:
 
 ```markdown
 ---
@@ -138,7 +138,7 @@ Begin decomposition now.
 
 ### @swarm-planner Agent
 
-The `@swarm-planner` agent is defined in `~/.config/opencode/agents/swarm-planner.md`:
+The `@swarm-planner` agent is defined in `~/.config/opencode/agent/swarm-planner.md`:
 
 ````markdown
 ---

package/bin/swarm.ts

@@ -457,9 +457,32 @@ async function checkAllDependencies(): Promise<CheckResult[]> {
 // File Templates
 // ============================================================================
 
-const PLUGIN_WRAPPER = `import { SwarmPlugin } from "opencode-swarm-plugin"
+/**
+ * Get the plugin wrapper template
+ *
+ * Reads from examples/plugin-wrapper-template.ts which contains a self-contained
+ * plugin that shells out to the `swarm` CLI for all tool execution.
+ */
+function getPluginWrapper(): string {
+  const templatePath = join(
+    __dirname,
+    "..",
+    "examples",
+    "plugin-wrapper-template.ts",
+  );
+  try {
+    return readFileSync(templatePath, "utf-8");
+  } catch (error) {
+    // Fallback to minimal wrapper if template not found (shouldn't happen in normal install)
+    console.warn(
+      `[swarm] Could not read plugin template from ${templatePath}, using minimal wrapper`,
+    );
+    return `// Minimal fallback - install opencode-swarm-plugin globally for full functionality
+import { SwarmPlugin } from "opencode-swarm-plugin"
 export default SwarmPlugin
 `;
+  }
+}
 
 const SWARM_COMMAND = `---
 description: Decompose task into parallel subtasks and coordinate agents
@@ -636,13 +659,13 @@ async function setup() {
   // Check if already configured FIRST
   const configDir = join(homedir(), ".config", "opencode");
   const pluginDir = join(configDir, "plugin");
-  const commandsDir = join(configDir, "commands");
-  const agentsDir = join(configDir, "agents");
+  const commandDir = join(configDir, "command");
+  const agentDir = join(configDir, "agent");
 
   const pluginPath = join(pluginDir, "swarm.ts");
-  const commandPath = join(commandsDir, "swarm.md");
-  const plannerAgentPath = join(agentsDir, "swarm-planner.md");
-  const workerAgentPath = join(agentsDir, "swarm-worker.md");
+  const commandPath = join(commandDir, "swarm.md");
+  const plannerAgentPath = join(agentDir, "swarm-planner.md");
+  const workerAgentPath = join(agentDir, "swarm-worker.md");
 
   const existingFiles = [
     pluginPath,
@@ -955,13 +978,13 @@ async function setup() {
   p.log.step("Setting up OpenCode integration...");
 
   // Create directories if needed
-  for (const dir of [pluginDir, commandsDir, agentsDir]) {
+  for (const dir of [pluginDir, commandDir, agentDir]) {
     if (!existsSync(dir)) {
       mkdirSync(dir, { recursive: true });
     }
   }
 
-  writeFileSync(pluginPath, PLUGIN_WRAPPER);
+  writeFileSync(pluginPath, getPluginWrapper());
   p.log.success("Plugin: " + pluginPath);
 
   writeFileSync(commandPath, SWARM_COMMAND);
@@ -1081,9 +1104,9 @@ async function version() {
 function config() {
   const configDir = join(homedir(), ".config", "opencode");
   const pluginPath = join(configDir, "plugin", "swarm.ts");
-  const commandPath = join(configDir, "commands", "swarm.md");
-  const plannerAgentPath = join(configDir, "agents", "swarm-planner.md");
-  const workerAgentPath = join(configDir, "agents", "swarm-worker.md");
+  const commandPath = join(configDir, "command", "swarm.md");
+  const plannerAgentPath = join(configDir, "agent", "swarm-planner.md");
+  const workerAgentPath = join(configDir, "agent", "swarm-worker.md");
 
   console.log(yellow(BANNER));
   console.log(dim("  " + TAGLINE + " v" + VERSION));
@@ -1180,8 +1203,14 @@ ${cyan("Commands:")}
   swarm config    Show paths to generated config files
   swarm update    Update to latest version
   swarm version   Show version and banner
+  swarm tool      Execute a tool (for plugin wrapper)
   swarm help      Show this help
 
+${cyan("Tool Execution:")}
+  swarm tool --list                    List all available tools
+  swarm tool <name>                    Execute tool with no args
+  swarm tool <name> --json '<args>'    Execute tool with JSON args
+
 ${cyan("Usage in OpenCode:")}
   /swarm "Add user authentication with OAuth"
   @swarm-planner "Decompose this into parallel tasks"
@@ -1189,9 +1218,9 @@ ${cyan("Usage in OpenCode:")}
 
 ${cyan("Customization:")}
   Edit the generated files to customize behavior:
-  ${dim("~/.config/opencode/commands/swarm.md")}      - /swarm command prompt
-  ${dim("~/.config/opencode/agents/swarm-planner.md")} - @swarm-planner (coordinator)
-  ${dim("~/.config/opencode/agents/swarm-worker.md")}  - @swarm-worker (fast executor)
+  ${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("Docs: https://github.com/joelhooks/opencode-swarm-plugin")}
@@ -1202,6 +1231,150 @@ ${dim("Docs: https://github.com/joelhooks/opencode-swarm-plugin")}
   if (updateInfo) showUpdateNotification(updateInfo);
 }
 
+// ============================================================================
+// Tool Execution (for plugin wrapper)
+// ============================================================================
+
+/**
+ * Execute a tool by name with JSON args
+ *
+ * This is the bridge between the plugin wrapper and the actual tool implementations.
+ * The plugin wrapper shells out to `swarm tool <name> --json '<args>'` and this
+ * function executes the tool and returns JSON.
+ *
+ * Exit codes:
+ * - 0: Success
+ * - 1: Tool execution error (error details in JSON output)
+ * - 2: Unknown tool name
+ * - 3: Invalid JSON args
+ */
+async function executeTool(toolName: string, argsJson?: string) {
+  // Lazy import to avoid loading all tools on every CLI invocation
+  const { allTools } = await import("../src/index");
+
+  // Validate tool name
+  if (!(toolName in allTools)) {
+    const availableTools = Object.keys(allTools).sort();
+    console.log(
+      JSON.stringify({
+        success: false,
+        error: {
+          code: "UNKNOWN_TOOL",
+          message: `Unknown tool: ${toolName}`,
+          available_tools: availableTools,
+        },
+      }),
+    );
+    process.exit(2);
+  }
+
+  // Parse args
+  let args: Record<string, unknown> = {};
+  if (argsJson) {
+    try {
+      args = JSON.parse(argsJson);
+    } catch (e) {
+      console.log(
+        JSON.stringify({
+          success: false,
+          error: {
+            code: "INVALID_JSON",
+            message: `Invalid JSON args: ${e instanceof Error ? e.message : String(e)}`,
+            raw_input: argsJson.slice(0, 200),
+          },
+        }),
+      );
+      process.exit(3);
+    }
+  }
+
+  // Create mock context for tools that need sessionID
+  // This mimics what OpenCode provides to plugins
+  const mockContext = {
+    sessionID: process.env.OPENCODE_SESSION_ID || `cli-${Date.now()}`,
+    messageID: process.env.OPENCODE_MESSAGE_ID || `msg-${Date.now()}`,
+    agent: process.env.OPENCODE_AGENT || "cli",
+    abort: new AbortController().signal,
+  };
+
+  // Get the tool
+  const toolDef = allTools[toolName as keyof typeof allTools];
+
+  // Execute tool
+  // Note: We cast args to any because the CLI accepts arbitrary JSON
+  // The tool's internal Zod validation will catch type errors
+  try {
+    const result = await toolDef.execute(args as any, mockContext);
+
+    // If result is already valid JSON, try to parse and re-wrap it
+    // Otherwise wrap the string result
+    try {
+      const parsed = JSON.parse(result);
+      // If it's already a success/error response, pass through
+      if (typeof parsed === "object" && "success" in parsed) {
+        console.log(JSON.stringify(parsed));
+      } else {
+        console.log(JSON.stringify({ success: true, data: parsed }));
+      }
+    } catch {
+      // Result is a plain string, wrap it
+      console.log(JSON.stringify({ success: true, data: result }));
+    }
+    process.exit(0);
+  } catch (error) {
+    console.log(
+      JSON.stringify({
+        success: false,
+        error: {
+          code: error instanceof Error ? error.name : "TOOL_ERROR",
+          message: error instanceof Error ? error.message : String(error),
+          details:
+            error instanceof Error && "zodError" in error
+              ? (error as { zodError?: unknown }).zodError
+              : undefined,
+        },
+      }),
+    );
+    process.exit(1);
+  }
+}
+
+/**
+ * List all available tools
+ */
+async function listTools() {
+  const { allTools } = await import("../src/index");
+  const tools = Object.keys(allTools).sort();
+
+  console.log(yellow(BANNER));
+  console.log(dim("  " + TAGLINE + " v" + VERSION));
+  console.log();
+  console.log(cyan("Available tools:") + ` (${tools.length} total)`);
+  console.log();
+
+  // Group by prefix
+  const groups: Record<string, string[]> = {};
+  for (const tool of tools) {
+    const prefix = tool.split("_")[0];
+    if (!groups[prefix]) groups[prefix] = [];
+    groups[prefix].push(tool);
+  }
+
+  for (const [prefix, toolList] of Object.entries(groups)) {
+    console.log(green(`  ${prefix}:`));
+    for (const t of toolList) {
+      console.log(`    ${t}`);
+    }
+    console.log();
+  }
+
+  console.log(dim("Usage: swarm tool <name> [--json '<args>']"));
+  console.log(dim("Example: swarm tool beads_ready"));
+  console.log(
+    dim('Example: swarm tool beads_create --json \'{"title": "Fix bug"}\''),
+  );
+}
+
 // ============================================================================
 // Main
 // ============================================================================
@@ -1224,6 +1397,19 @@ switch (command) {
   case "update":
     await update();
     break;
+  case "tool": {
+    const toolName = process.argv[3];
+    if (!toolName || toolName === "--list" || toolName === "-l") {
+      await listTools();
+    } else {
+      // Look for --json flag
+      const jsonFlagIndex = process.argv.indexOf("--json");
+      const argsJson =
+        jsonFlagIndex !== -1 ? process.argv[jsonFlagIndex + 1] : undefined;
+      await executeTool(toolName, argsJson);
+    }
+    break;
+  }
   case "version":
   case "--version":
   case "-v":

package/dist/index.js

@@ -22590,6 +22590,15 @@ async function getRateLimiter() {
 }
 
 // src/agent-mail.ts
+import {
+  existsSync as existsSync2,
+  mkdirSync as mkdirSync2,
+  readFileSync,
+  writeFileSync,
+  unlinkSync
+} from "fs";
+import { join as join2 } from "path";
+import { tmpdir } from "os";
 var AGENT_MAIL_URL = "http://127.0.0.1:8765";
 var DEFAULT_TTL_SECONDS = 3600;
 var MAX_INBOX_LIMIT = 5;
@@ -22605,6 +22614,34 @@ var RECOVERY_CONFIG = {
   restartCooldownMs: 30000,
   enabled: process.env.OPENCODE_AGENT_MAIL_AUTO_RESTART !== "false"
 };
+var SESSION_STATE_DIR = process.env.SWARM_STATE_DIR || join2(tmpdir(), "swarm-sessions");
+function getSessionStatePath(sessionID) {
+  const safeID = sessionID.replace(/[^a-zA-Z0-9_-]/g, "_");
+  return join2(SESSION_STATE_DIR, `${safeID}.json`);
+}
+function loadSessionState(sessionID) {
+  const path = getSessionStatePath(sessionID);
+  try {
+    if (existsSync2(path)) {
+      const data = readFileSync(path, "utf-8");
+      return JSON.parse(data);
+    }
+  } catch (error45) {
+    console.warn(`[agent-mail] Could not load session state: ${error45}`);
+  }
+  return null;
+}
+function saveSessionState(sessionID, state) {
+  try {
+    if (!existsSync2(SESSION_STATE_DIR)) {
+      mkdirSync2(SESSION_STATE_DIR, { recursive: true });
+    }
+    const path = getSessionStatePath(sessionID);
+    writeFileSync(path, JSON.stringify(state, null, 2));
+  } catch (error45) {
+    console.warn(`[agent-mail] Could not save session state: ${error45}`);
+  }
+}
 var sessionStates = new Map;
 
 class AgentMailError extends Error {
@@ -22908,7 +22945,13 @@ async function mcpCall(toolName, args) {
   throw lastError || new Error("Unknown error in mcpCall");
 }
 function requireState(sessionID) {
-  const state = sessionStates.get(sessionID);
+  let state = sessionStates.get(sessionID);
+  if (!state) {
+    state = loadSessionState(sessionID) ?? undefined;
+    if (state) {
+      sessionStates.set(sessionID, state);
+    }
+  }
   if (!state) {
     throw new AgentMailNotInitializedError;
   }
@@ -22916,6 +22959,7 @@ function requireState(sessionID) {
 }
 function setState(sessionID, state) {
   sessionStates.set(sessionID, state);
+  saveSessionState(sessionID, state);
 }
 var agentmail_init = tool({
   description: "Initialize Agent Mail session (ensure project + register agent)",
@@ -25554,6 +25598,12 @@ var SwarmPlugin = async (input) => {
   };
 };
 var src_default = SwarmPlugin;
+var allTools = {
+  ...beadsTools,
+  ...agentMailTools,
+  ...structuredTools,
+  ...swarmTools
+};
 export {
   withToolFallback,
   warnMissingTool,
@@ -25592,6 +25642,7 @@ export {
   beads_create,
   beads_close,
   beadsTools,
+  allTools,
   agentMailTools,
   WeightedEvaluationSchema,
   WeightedCriterionEvaluationSchema,

package/dist/plugin.js

@@ -22564,6 +22564,15 @@ async function getRateLimiter() {
 }
 
 // src/agent-mail.ts
+import {
+  existsSync as existsSync2,
+  mkdirSync as mkdirSync2,
+  readFileSync,
+  writeFileSync,
+  unlinkSync
+} from "fs";
+import { join as join2 } from "path";
+import { tmpdir } from "os";
 var AGENT_MAIL_URL = "http://127.0.0.1:8765";
 var DEFAULT_TTL_SECONDS = 3600;
 var MAX_INBOX_LIMIT = 5;
@@ -22579,6 +22588,34 @@ var RECOVERY_CONFIG = {
   restartCooldownMs: 30000,
   enabled: process.env.OPENCODE_AGENT_MAIL_AUTO_RESTART !== "false"
 };
+var SESSION_STATE_DIR = process.env.SWARM_STATE_DIR || join2(tmpdir(), "swarm-sessions");
+function getSessionStatePath(sessionID) {
+  const safeID = sessionID.replace(/[^a-zA-Z0-9_-]/g, "_");
+  return join2(SESSION_STATE_DIR, `${safeID}.json`);
+}
+function loadSessionState(sessionID) {
+  const path = getSessionStatePath(sessionID);
+  try {
+    if (existsSync2(path)) {
+      const data = readFileSync(path, "utf-8");
+      return JSON.parse(data);
+    }
+  } catch (error45) {
+    console.warn(`[agent-mail] Could not load session state: ${error45}`);
+  }
+  return null;
+}
+function saveSessionState(sessionID, state) {
+  try {
+    if (!existsSync2(SESSION_STATE_DIR)) {
+      mkdirSync2(SESSION_STATE_DIR, { recursive: true });
+    }
+    const path = getSessionStatePath(sessionID);
+    writeFileSync(path, JSON.stringify(state, null, 2));
+  } catch (error45) {
+    console.warn(`[agent-mail] Could not save session state: ${error45}`);
+  }
+}
 var sessionStates = new Map;
 
 class AgentMailError extends Error {
@@ -22882,7 +22919,13 @@ async function mcpCall(toolName, args) {
   throw lastError || new Error("Unknown error in mcpCall");
 }
 function requireState(sessionID) {
-  const state = sessionStates.get(sessionID);
+  let state = sessionStates.get(sessionID);
+  if (!state) {
+    state = loadSessionState(sessionID) ?? undefined;
+    if (state) {
+      sessionStates.set(sessionID, state);
+    }
+  }
   if (!state) {
     throw new AgentMailNotInitializedError;
   }
@@ -22890,6 +22933,7 @@ function requireState(sessionID) {
 }
 function setState(sessionID, state) {
   sessionStates.set(sessionID, state);
+  saveSessionState(sessionID, state);
 }
 var agentmail_init = tool({
   description: "Initialize Agent Mail session (ensure project + register agent)",
@@ -25203,6 +25247,12 @@ var SwarmPlugin = async (input) => {
     }
   };
 };
+var allTools = {
+  ...beadsTools,
+  ...agentMailTools,
+  ...structuredTools,
+  ...swarmTools
+};
 export {
   SwarmPlugin
 };