opencode-swarm-plugin 0.11.2 → 0.12.0

package/examples/plugin-wrapper-template.ts

@@ -0,0 +1,723 @@
+/**
+ * OpenCode Swarm Plugin Wrapper
+ *
+ * This is a thin wrapper that shells out to the `swarm` CLI for all tool execution.
+ * Generated by: swarm setup
+ *
+ * The plugin only depends on @opencode-ai/plugin (provided by OpenCode).
+ * All tool logic lives in the npm package - this just bridges to it.
+ *
+ * Environment variables:
+ * - OPENCODE_SESSION_ID: Passed to CLI for session state persistence
+ * - OPENCODE_MESSAGE_ID: Passed to CLI for context
+ * - OPENCODE_AGENT: Passed to CLI for context
+ */
+import type { Plugin, PluginInput, Hooks } from "@opencode-ai/plugin";
+import { tool } from "@opencode-ai/plugin";
+import { spawn } from "child_process";
+
+const SWARM_CLI = "swarm";
+
+// =============================================================================
+// CLI Execution Helper
+// =============================================================================
+
+/**
+ * Execute a swarm tool via CLI
+ *
+ * Spawns `swarm tool <name> --json '<args>'` and returns the result.
+ * Passes session context via environment variables.
+ */
+async function execTool(
+  name: string,
+  args: Record<string, unknown>,
+  ctx: { sessionID: string; messageID: string; agent: string },
+): Promise<string> {
+  return new Promise((resolve, reject) => {
+    const hasArgs = Object.keys(args).length > 0;
+    const cliArgs = hasArgs
+      ? ["tool", name, "--json", JSON.stringify(args)]
+      : ["tool", name];
+
+    const proc = spawn(SWARM_CLI, cliArgs, {
+      stdio: ["ignore", "pipe", "pipe"],
+      env: {
+        ...process.env,
+        OPENCODE_SESSION_ID: ctx.sessionID,
+        OPENCODE_MESSAGE_ID: ctx.messageID,
+        OPENCODE_AGENT: ctx.agent,
+      },
+    });
+
+    let stdout = "";
+    let stderr = "";
+
+    proc.stdout.on("data", (data) => {
+      stdout += data;
+    });
+    proc.stderr.on("data", (data) => {
+      stderr += data;
+    });
+
+    proc.on("close", (code) => {
+      if (code === 0) {
+        // Success - return the JSON output
+        try {
+          const result = JSON.parse(stdout);
+          if (result.success && result.data !== undefined) {
+            // Unwrap the data for cleaner tool output
+            resolve(
+              typeof result.data === "string"
+                ? result.data
+                : JSON.stringify(result.data, null, 2),
+            );
+          } else if (!result.success && result.error) {
+            // Tool returned an error in JSON format
+            reject(new Error(result.error.message || "Tool execution failed"));
+          } else {
+            resolve(stdout);
+          }
+        } catch {
+          resolve(stdout);
+        }
+      } else if (code === 2) {
+        reject(new Error(`Unknown tool: ${name}`));
+      } else if (code === 3) {
+        reject(new Error(`Invalid JSON args: ${stderr}`));
+      } else {
+        // Tool returned error
+        try {
+          const result = JSON.parse(stdout);
+          if (!result.success && result.error) {
+            reject(
+              new Error(
+                result.error.message || `Tool failed with code ${code}`,
+              ),
+            );
+          } else {
+            reject(
+              new Error(stderr || stdout || `Tool failed with code ${code}`),
+            );
+          }
+        } catch {
+          reject(
+            new Error(stderr || stdout || `Tool failed with code ${code}`),
+          );
+        }
+      }
+    });
+
+    proc.on("error", (err) => {
+      if ((err as NodeJS.ErrnoException).code === "ENOENT") {
+        reject(
+          new Error(
+            `swarm CLI not found. Install with: npm install -g opencode-swarm-plugin`,
+          ),
+        );
+      } else {
+        reject(err);
+      }
+    });
+  });
+}
+
+// =============================================================================
+// Beads Tools
+// =============================================================================
+
+const beads_create = tool({
+  description: "Create a new bead with type-safe validation",
+  args: {
+    title: tool.schema.string().describe("Bead title"),
+    type: tool.schema
+      .enum(["bug", "feature", "task", "epic", "chore"])
+      .optional()
+      .describe("Issue type (default: task)"),
+    priority: tool.schema
+      .number()
+      .min(0)
+      .max(3)
+      .optional()
+      .describe("Priority 0-3 (default: 2)"),
+    description: tool.schema.string().optional().describe("Bead description"),
+    parent_id: tool.schema
+      .string()
+      .optional()
+      .describe("Parent bead ID for epic children"),
+  },
+  execute: (args, ctx) => execTool("beads_create", args, ctx),
+});
+
+const beads_create_epic = tool({
+  description: "Create epic with subtasks in one atomic operation",
+  args: {
+    epic_title: tool.schema.string().describe("Epic title"),
+    epic_description: tool.schema
+      .string()
+      .optional()
+      .describe("Epic description"),
+    subtasks: tool.schema
+      .array(
+        tool.schema.object({
+          title: tool.schema.string(),
+          priority: tool.schema.number().min(0).max(3).optional(),
+          files: tool.schema.array(tool.schema.string()).optional(),
+        }),
+      )
+      .describe("Subtasks to create under the epic"),
+  },
+  execute: (args, ctx) => execTool("beads_create_epic", args, ctx),
+});
+
+const beads_query = tool({
+  description: "Query beads with filters (replaces bd list, bd ready, bd wip)",
+  args: {
+    status: tool.schema
+      .enum(["open", "in_progress", "blocked", "closed"])
+      .optional()
+      .describe("Filter by status"),
+    type: tool.schema
+      .enum(["bug", "feature", "task", "epic", "chore"])
+      .optional()
+      .describe("Filter by type"),
+    ready: tool.schema
+      .boolean()
+      .optional()
+      .describe("Only show unblocked beads"),
+    limit: tool.schema
+      .number()
+      .optional()
+      .describe("Max results (default: 20)"),
+  },
+  execute: (args, ctx) => execTool("beads_query", args, ctx),
+});
+
+const beads_update = tool({
+  description: "Update bead status/description",
+  args: {
+    id: tool.schema.string().describe("Bead ID"),
+    status: tool.schema
+      .enum(["open", "in_progress", "blocked", "closed"])
+      .optional()
+      .describe("New status"),
+    description: tool.schema.string().optional().describe("New description"),
+    priority: tool.schema
+      .number()
+      .min(0)
+      .max(3)
+      .optional()
+      .describe("New priority"),
+  },
+  execute: (args, ctx) => execTool("beads_update", args, ctx),
+});
+
+const beads_close = tool({
+  description: "Close a bead with reason",
+  args: {
+    id: tool.schema.string().describe("Bead ID"),
+    reason: tool.schema.string().describe("Completion reason"),
+  },
+  execute: (args, ctx) => execTool("beads_close", args, ctx),
+});
+
+const beads_start = tool({
+  description: "Mark a bead as in-progress",
+  args: {
+    id: tool.schema.string().describe("Bead ID"),
+  },
+  execute: (args, ctx) => execTool("beads_start", args, ctx),
+});
+
+const beads_ready = tool({
+  description: "Get the next ready bead (unblocked, highest priority)",
+  args: {},
+  execute: (args, ctx) => execTool("beads_ready", args, ctx),
+});
+
+const beads_sync = tool({
+  description: "Sync beads to git and push (MANDATORY at session end)",
+  args: {
+    auto_pull: tool.schema.boolean().optional().describe("Pull before sync"),
+  },
+  execute: (args, ctx) => execTool("beads_sync", args, ctx),
+});
+
+const beads_link_thread = tool({
+  description: "Add metadata linking bead to Agent Mail thread",
+  args: {
+    bead_id: tool.schema.string().describe("Bead ID"),
+    thread_id: tool.schema.string().describe("Agent Mail thread ID"),
+  },
+  execute: (args, ctx) => execTool("beads_link_thread", args, ctx),
+});
+
+// =============================================================================
+// Agent Mail Tools
+// =============================================================================
+
+const agentmail_init = tool({
+  description: "Initialize Agent Mail session",
+  args: {
+    project_path: tool.schema.string().describe("Absolute path to the project"),
+    agent_name: tool.schema.string().optional().describe("Custom agent name"),
+    task_description: tool.schema
+      .string()
+      .optional()
+      .describe("Task description"),
+  },
+  execute: (args, ctx) => execTool("agentmail_init", args, ctx),
+});
+
+const agentmail_send = tool({
+  description: "Send message to other agents",
+  args: {
+    to: tool.schema
+      .array(tool.schema.string())
+      .describe("Recipient agent names"),
+    subject: tool.schema.string().describe("Message subject"),
+    body: tool.schema.string().describe("Message body"),
+    thread_id: tool.schema
+      .string()
+      .optional()
+      .describe("Thread ID for grouping"),
+    importance: tool.schema
+      .enum(["low", "normal", "high", "urgent"])
+      .optional()
+      .describe("Message importance"),
+    ack_required: tool.schema
+      .boolean()
+      .optional()
+      .describe("Require acknowledgment"),
+  },
+  execute: (args, ctx) => execTool("agentmail_send", args, ctx),
+});
+
+const agentmail_inbox = tool({
+  description: "Fetch inbox (CONTEXT-SAFE: bodies excluded, limit 5)",
+  args: {
+    limit: tool.schema
+      .number()
+      .max(5)
+      .optional()
+      .describe("Max messages (max 5)"),
+    urgent_only: tool.schema
+      .boolean()
+      .optional()
+      .describe("Only urgent messages"),
+    since_ts: tool.schema
+      .string()
+      .optional()
+      .describe("Messages since timestamp"),
+  },
+  execute: (args, ctx) => execTool("agentmail_inbox", args, ctx),
+});
+
+const agentmail_read_message = tool({
+  description: "Fetch ONE message body by ID",
+  args: {
+    message_id: tool.schema.number().describe("Message ID"),
+  },
+  execute: (args, ctx) => execTool("agentmail_read_message", args, ctx),
+});
+
+const agentmail_summarize_thread = tool({
+  description: "Summarize thread (PREFERRED over fetching all messages)",
+  args: {
+    thread_id: tool.schema.string().describe("Thread ID"),
+    include_examples: tool.schema
+      .boolean()
+      .optional()
+      .describe("Include example messages"),
+  },
+  execute: (args, ctx) => execTool("agentmail_summarize_thread", args, ctx),
+});
+
+const agentmail_reserve = tool({
+  description: "Reserve file paths for exclusive editing",
+  args: {
+    paths: tool.schema
+      .array(tool.schema.string())
+      .describe("File paths/patterns"),
+    ttl_seconds: tool.schema.number().optional().describe("Reservation TTL"),
+    exclusive: tool.schema.boolean().optional().describe("Exclusive lock"),
+    reason: tool.schema.string().optional().describe("Reservation reason"),
+  },
+  execute: (args, ctx) => execTool("agentmail_reserve", args, ctx),
+});
+
+const agentmail_release = tool({
+  description: "Release file reservations",
+  args: {
+    paths: tool.schema
+      .array(tool.schema.string())
+      .optional()
+      .describe("Paths to release"),
+    reservation_ids: tool.schema
+      .array(tool.schema.number())
+      .optional()
+      .describe("Reservation IDs"),
+  },
+  execute: (args, ctx) => execTool("agentmail_release", args, ctx),
+});
+
+const agentmail_ack = tool({
+  description: "Acknowledge a message",
+  args: {
+    message_id: tool.schema.number().describe("Message ID"),
+  },
+  execute: (args, ctx) => execTool("agentmail_ack", args, ctx),
+});
+
+const agentmail_search = tool({
+  description: "Search messages by keyword",
+  args: {
+    query: tool.schema.string().describe("Search query"),
+    limit: tool.schema.number().optional().describe("Max results"),
+  },
+  execute: (args, ctx) => execTool("agentmail_search", args, ctx),
+});
+
+const agentmail_health = tool({
+  description: "Check if Agent Mail server is running",
+  args: {},
+  execute: (args, ctx) => execTool("agentmail_health", args, ctx),
+});
+
+// =============================================================================
+// Structured Tools
+// =============================================================================
+
+const structured_extract_json = tool({
+  description: "Extract JSON from markdown/text response",
+  args: {
+    text: tool.schema.string().describe("Text containing JSON"),
+  },
+  execute: (args, ctx) => execTool("structured_extract_json", args, ctx),
+});
+
+const structured_validate = tool({
+  description: "Validate agent response against a schema",
+  args: {
+    response: tool.schema.string().describe("Agent response to validate"),
+    schema_name: tool.schema
+      .enum(["evaluation", "task_decomposition", "bead_tree"])
+      .describe("Schema to validate against"),
+    max_retries: tool.schema
+      .number()
+      .min(1)
+      .max(5)
+      .optional()
+      .describe("Max retries"),
+  },
+  execute: (args, ctx) => execTool("structured_validate", args, ctx),
+});
+
+const structured_parse_evaluation = tool({
+  description: "Parse and validate evaluation response",
+  args: {
+    response: tool.schema.string().describe("Agent response"),
+  },
+  execute: (args, ctx) => execTool("structured_parse_evaluation", args, ctx),
+});
+
+const structured_parse_decomposition = tool({
+  description: "Parse and validate task decomposition response",
+  args: {
+    response: tool.schema.string().describe("Agent response"),
+  },
+  execute: (args, ctx) => execTool("structured_parse_decomposition", args, ctx),
+});
+
+const structured_parse_bead_tree = tool({
+  description: "Parse and validate bead tree response",
+  args: {
+    response: tool.schema.string().describe("Agent response"),
+  },
+  execute: (args, ctx) => execTool("structured_parse_bead_tree", args, ctx),
+});
+
+// =============================================================================
+// Swarm Tools
+// =============================================================================
+
+const swarm_init = tool({
+  description: "Initialize swarm session and check tool availability",
+  args: {
+    project_path: tool.schema.string().optional().describe("Project path"),
+  },
+  execute: (args, ctx) => execTool("swarm_init", args, ctx),
+});
+
+const swarm_select_strategy = tool({
+  description: "Analyze task and recommend decomposition strategy",
+  args: {
+    task: tool.schema.string().min(1).describe("Task to analyze"),
+    codebase_context: tool.schema
+      .string()
+      .optional()
+      .describe("Codebase context"),
+  },
+  execute: (args, ctx) => execTool("swarm_select_strategy", args, ctx),
+});
+
+const swarm_plan_prompt = tool({
+  description: "Generate strategy-specific decomposition prompt",
+  args: {
+    task: tool.schema.string().min(1).describe("Task to decompose"),
+    strategy: tool.schema
+      .enum(["file-based", "feature-based", "risk-based", "auto"])
+      .optional()
+      .describe("Decomposition strategy"),
+    max_subtasks: tool.schema
+      .number()
+      .int()
+      .min(2)
+      .max(10)
+      .optional()
+      .describe("Max subtasks"),
+    context: tool.schema.string().optional().describe("Additional context"),
+    query_cass: tool.schema
+      .boolean()
+      .optional()
+      .describe("Query CASS for similar tasks"),
+    cass_limit: tool.schema
+      .number()
+      .int()
+      .min(1)
+      .max(10)
+      .optional()
+      .describe("CASS limit"),
+  },
+  execute: (args, ctx) => execTool("swarm_plan_prompt", args, ctx),
+});
+
+const swarm_decompose = tool({
+  description: "Generate decomposition prompt for breaking task into subtasks",
+  args: {
+    task: tool.schema.string().min(1).describe("Task to decompose"),
+    max_subtasks: tool.schema
+      .number()
+      .int()
+      .min(2)
+      .max(10)
+      .optional()
+      .describe("Max subtasks"),
+    context: tool.schema.string().optional().describe("Additional context"),
+    query_cass: tool.schema.boolean().optional().describe("Query CASS"),
+    cass_limit: tool.schema
+      .number()
+      .int()
+      .min(1)
+      .max(10)
+      .optional()
+      .describe("CASS limit"),
+  },
+  execute: (args, ctx) => execTool("swarm_decompose", args, ctx),
+});
+
+const swarm_validate_decomposition = tool({
+  description: "Validate a decomposition response against BeadTreeSchema",
+  args: {
+    response: tool.schema.string().describe("Decomposition response"),
+  },
+  execute: (args, ctx) => execTool("swarm_validate_decomposition", args, ctx),
+});
+
+const swarm_status = tool({
+  description: "Get status of a swarm by epic ID",
+  args: {
+    epic_id: tool.schema.string().describe("Epic bead ID"),
+    project_key: tool.schema.string().describe("Project key"),
+  },
+  execute: (args, ctx) => execTool("swarm_status", args, ctx),
+});
+
+const swarm_progress = tool({
+  description: "Report progress on a subtask to coordinator",
+  args: {
+    project_key: tool.schema.string().describe("Project key"),
+    agent_name: tool.schema.string().describe("Agent name"),
+    bead_id: tool.schema.string().describe("Bead ID"),
+    status: tool.schema
+      .enum(["in_progress", "blocked", "completed", "failed"])
+      .describe("Status"),
+    message: tool.schema.string().optional().describe("Progress message"),
+    progress_percent: tool.schema
+      .number()
+      .min(0)
+      .max(100)
+      .optional()
+      .describe("Progress %"),
+    files_touched: tool.schema
+      .array(tool.schema.string())
+      .optional()
+      .describe("Files modified"),
+  },
+  execute: (args, ctx) => execTool("swarm_progress", args, ctx),
+});
+
+const swarm_complete = tool({
+  description:
+    "Mark subtask complete, release reservations, notify coordinator",
+  args: {
+    project_key: tool.schema.string().describe("Project key"),
+    agent_name: tool.schema.string().describe("Agent name"),
+    bead_id: tool.schema.string().describe("Bead ID"),
+    summary: tool.schema.string().describe("Completion summary"),
+    evaluation: tool.schema.string().optional().describe("Self-evaluation"),
+    files_touched: tool.schema
+      .array(tool.schema.string())
+      .optional()
+      .describe("Files modified"),
+    skip_ubs_scan: tool.schema.boolean().optional().describe("Skip UBS scan"),
+  },
+  execute: (args, ctx) => execTool("swarm_complete", args, ctx),
+});
+
+const swarm_record_outcome = tool({
+  description: "Record subtask outcome for implicit feedback scoring",
+  args: {
+    bead_id: tool.schema.string().describe("Bead ID"),
+    duration_ms: tool.schema.number().int().min(0).describe("Duration in ms"),
+    error_count: tool.schema
+      .number()
+      .int()
+      .min(0)
+      .optional()
+      .describe("Error count"),
+    retry_count: tool.schema
+      .number()
+      .int()
+      .min(0)
+      .optional()
+      .describe("Retry count"),
+    success: tool.schema.boolean().describe("Whether task succeeded"),
+    files_touched: tool.schema
+      .array(tool.schema.string())
+      .optional()
+      .describe("Files modified"),
+    criteria: tool.schema
+      .array(tool.schema.string())
+      .optional()
+      .describe("Evaluation criteria"),
+    strategy: tool.schema
+      .enum(["file-based", "feature-based", "risk-based"])
+      .optional()
+      .describe("Strategy used"),
+  },
+  execute: (args, ctx) => execTool("swarm_record_outcome", args, ctx),
+});
+
+const swarm_subtask_prompt = tool({
+  description: "Generate the prompt for a spawned subtask agent",
+  args: {
+    agent_name: tool.schema.string().describe("Agent name"),
+    bead_id: tool.schema.string().describe("Bead ID"),
+    epic_id: tool.schema.string().describe("Epic ID"),
+    subtask_title: tool.schema.string().describe("Subtask title"),
+    subtask_description: tool.schema
+      .string()
+      .optional()
+      .describe("Description"),
+    files: tool.schema.array(tool.schema.string()).describe("Files to work on"),
+    shared_context: tool.schema.string().optional().describe("Shared context"),
+  },
+  execute: (args, ctx) => execTool("swarm_subtask_prompt", args, ctx),
+});
+
+const swarm_spawn_subtask = tool({
+  description: "Prepare a subtask for spawning with Task tool",
+  args: {
+    bead_id: tool.schema.string().describe("Bead ID"),
+    epic_id: tool.schema.string().describe("Epic ID"),
+    subtask_title: tool.schema.string().describe("Subtask title"),
+    subtask_description: tool.schema
+      .string()
+      .optional()
+      .describe("Description"),
+    files: tool.schema.array(tool.schema.string()).describe("Files to work on"),
+    shared_context: tool.schema.string().optional().describe("Shared context"),
+  },
+  execute: (args, ctx) => execTool("swarm_spawn_subtask", args, ctx),
+});
+
+const swarm_complete_subtask = tool({
+  description: "Handle subtask completion after Task agent returns",
+  args: {
+    bead_id: tool.schema.string().describe("Bead ID"),
+    task_result: tool.schema.string().describe("Task result JSON"),
+    files_touched: tool.schema
+      .array(tool.schema.string())
+      .optional()
+      .describe("Files modified"),
+  },
+  execute: (args, ctx) => execTool("swarm_complete_subtask", args, ctx),
+});
+
+const swarm_evaluation_prompt = tool({
+  description: "Generate self-evaluation prompt for a completed subtask",
+  args: {
+    bead_id: tool.schema.string().describe("Bead ID"),
+    subtask_title: tool.schema.string().describe("Subtask title"),
+    files_touched: tool.schema
+      .array(tool.schema.string())
+      .describe("Files modified"),
+  },
+  execute: (args, ctx) => execTool("swarm_evaluation_prompt", args, ctx),
+});
+
+// =============================================================================
+// Plugin Export
+// =============================================================================
+
+export const SwarmPlugin: Plugin = async (
+  _input: PluginInput,
+): Promise<Hooks> => {
+  return {
+    tool: {
+      // Beads
+      beads_create,
+      beads_create_epic,
+      beads_query,
+      beads_update,
+      beads_close,
+      beads_start,
+      beads_ready,
+      beads_sync,
+      beads_link_thread,
+      // Agent Mail
+      agentmail_init,
+      agentmail_send,
+      agentmail_inbox,
+      agentmail_read_message,
+      agentmail_summarize_thread,
+      agentmail_reserve,
+      agentmail_release,
+      agentmail_ack,
+      agentmail_search,
+      agentmail_health,
+      // Structured
+      structured_extract_json,
+      structured_validate,
+      structured_parse_evaluation,
+      structured_parse_decomposition,
+      structured_parse_bead_tree,
+      // Swarm
+      swarm_init,
+      swarm_select_strategy,
+      swarm_plan_prompt,
+      swarm_decompose,
+      swarm_validate_decomposition,
+      swarm_status,
+      swarm_progress,
+      swarm_complete,
+      swarm_record_outcome,
+      swarm_subtask_prompt,
+      swarm_spawn_subtask,
+      swarm_complete_subtask,
+      swarm_evaluation_prompt,
+    },
+  };
+};
+
+export default SwarmPlugin;