opencode-swarm-plugin 0.1.0

package/src/index.ts

@@ -0,0 +1,267 @@
+/**
+ * OpenCode Swarm Plugin
+ *
+ * A type-safe plugin for multi-agent coordination with beads issue tracking
+ * and Agent Mail integration. Provides structured tools for swarm operations.
+ *
+ * @module opencode-swarm-plugin
+ *
+ * @example
+ * ```typescript
+ * // In opencode.jsonc
+ * {
+ *   "plugins": ["opencode-swarm-plugin"]
+ * }
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // Programmatic usage
+ * import { beadsTools, agentMailTools } from "opencode-swarm-plugin"
+ * ```
+ */
+import type { Plugin, PluginInput, Hooks } from "@opencode-ai/plugin";
+
+import { beadsTools } from "./beads";
+import {
+  agentMailTools,
+  type AgentMailState,
+  AGENT_MAIL_URL,
+} from "./agent-mail";
+import { structuredTools } from "./structured";
+import { swarmTools } from "./swarm";
+
+/**
+ * OpenCode Swarm Plugin
+ *
+ * Registers all swarm coordination tools:
+ * - beads:* - Type-safe beads issue tracker wrappers
+ * - agent-mail:* - Multi-agent coordination via Agent Mail MCP
+ * - structured:* - Structured output parsing and validation
+ * - swarm:* - Swarm orchestration and task decomposition
+ *
+ * @param input - Plugin context from OpenCode
+ * @returns Plugin hooks including tools, events, and tool execution hooks
+ */
+export const SwarmPlugin: Plugin = async (
+  input: PluginInput,
+): Promise<Hooks> => {
+  const { $ } = input;
+
+  /** Track active sessions for cleanup */
+  let activeAgentMailState: AgentMailState | null = null;
+
+  /**
+   * Release all file reservations for the active agent
+   * Best-effort cleanup - errors are logged but not thrown
+   */
+  async function releaseReservations(): Promise<void> {
+    if (
+      !activeAgentMailState ||
+      activeAgentMailState.reservations.length === 0
+    ) {
+      return;
+    }
+
+    try {
+      const response = await fetch(`${AGENT_MAIL_URL}/mcp/`, {
+        method: "POST",
+        headers: { "Content-Type": "application/json" },
+        body: JSON.stringify({
+          jsonrpc: "2.0",
+          id: crypto.randomUUID(),
+          method: "tools/call",
+          params: {
+            name: "release_file_reservations",
+            arguments: {
+              project_key: activeAgentMailState.projectKey,
+              agent_name: activeAgentMailState.agentName,
+            },
+          },
+        }),
+      });
+
+      if (response.ok) {
+        console.log(
+          `[swarm-plugin] Auto-released ${activeAgentMailState.reservations.length} file reservation(s)`,
+        );
+        activeAgentMailState.reservations = [];
+      }
+    } catch (error) {
+      // Agent Mail might not be running - that's ok
+      console.warn(
+        `[swarm-plugin] Could not auto-release reservations: ${error instanceof Error ? error.message : String(error)}`,
+      );
+    }
+  }
+
+  return {
+    /**
+     * Register all tools from modules
+     *
+     * Tools are namespaced by module:
+     * - beads:create, beads:query, beads:update, etc.
+     * - agent-mail:init, agent-mail:send, agent-mail:reserve, etc.
+     */
+    tool: {
+      ...beadsTools,
+      ...agentMailTools,
+      ...structuredTools,
+      ...swarmTools,
+    },
+
+    /**
+     * Event hook for session lifecycle
+     *
+     * Handles cleanup when session becomes idle:
+     * - Releases any held file reservations
+     */
+    event: async ({ event }) => {
+      // Auto-release reservations on session idle
+      if (event.type === "session.idle") {
+        await releaseReservations();
+      }
+    },
+
+    /**
+     * Hook after tool execution for automatic cleanup
+     *
+     * Auto-releases file reservations after swarm:complete or beads:close
+     * to prevent stale locks when tasks finish.
+     */
+    "tool.execute.after": async (input, output) => {
+      const toolName = input.tool;
+
+      // Track Agent Mail state for cleanup
+      if (toolName === "agentmail_init" && output.output) {
+        try {
+          const result = JSON.parse(output.output);
+          if (result.agent) {
+            activeAgentMailState = {
+              projectKey: result.project?.human_key || "",
+              agentName: result.agent.name,
+              reservations: [],
+              startedAt: new Date().toISOString(),
+            };
+          }
+        } catch {
+          // Parsing failed - ignore
+        }
+      }
+
+      // Track reservations from output
+      if (
+        toolName === "agentmail_reserve" &&
+        output.output &&
+        activeAgentMailState
+      ) {
+        // Extract reservation count from output if present
+        const match = output.output.match(/Reserved (\d+) path/);
+        if (match) {
+          // Track reservation for cleanup
+          activeAgentMailState.reservations.push(Date.now());
+        }
+      }
+
+      // Auto-release after swarm:complete
+      if (toolName === "swarm_complete" && activeAgentMailState) {
+        await releaseReservations();
+        console.log(
+          "[swarm-plugin] Auto-released reservations after swarm:complete",
+        );
+      }
+
+      // Auto-sync beads after closing
+      if (toolName === "beads_close") {
+        // Trigger async sync without blocking - fire and forget
+        void $`bd sync`
+          .quiet()
+          .nothrow()
+          .then(() => {
+            console.log("[swarm-plugin] Auto-synced beads after close");
+          });
+      }
+    },
+  };
+};
+
+/**
+ * Default export for OpenCode plugin loading
+ *
+ * OpenCode loads plugins by their default export, so this allows:
+ * ```json
+ * { "plugins": ["opencode-swarm-plugin"] }
+ * ```
+ */
+export default SwarmPlugin;
+
+// =============================================================================
+// Re-exports for programmatic use
+// =============================================================================
+
+/**
+ * Re-export all schemas for type-safe usage
+ */
+export * from "./schemas";
+
+/**
+ * Re-export beads module
+ *
+ * Includes:
+ * - beadsTools - All bead tool definitions
+ * - Individual tool exports (beads_create, beads_query, etc.)
+ * - BeadError, BeadValidationError - Error classes
+ */
+export * from "./beads";
+
+/**
+ * Re-export agent-mail module
+ *
+ * Includes:
+ * - agentMailTools - All agent mail tool definitions
+ * - AgentMailError, FileReservationConflictError - Error classes
+ * - AgentMailState - Session state type
+ *
+ * NOTE: We selectively export to avoid exporting constants like AGENT_MAIL_URL
+ * which would confuse the plugin loader (it tries to call all exports as functions)
+ */
+export {
+  agentMailTools,
+  AgentMailError,
+  AgentMailNotInitializedError,
+  FileReservationConflictError,
+  type AgentMailState,
+} from "./agent-mail";
+
+/**
+ * Re-export structured module
+ *
+ * Includes:
+ * - structuredTools - Structured output parsing tools
+ * - Utility functions for JSON extraction
+ */
+export {
+  structuredTools,
+  extractJsonFromText,
+  formatZodErrors,
+  getSchemaByName,
+} from "./structured";
+
+/**
+ * Re-export swarm module
+ *
+ * Includes:
+ * - swarmTools - Swarm orchestration tools
+ * - SwarmError, DecompositionError - Error classes
+ * - formatSubtaskPrompt, formatEvaluationPrompt - Prompt helpers
+ *
+ * NOTE: Prompt template strings (DECOMPOSITION_PROMPT, etc.) are NOT exported
+ * to avoid confusing the plugin loader which tries to call all exports as functions
+ */
+export {
+  swarmTools,
+  SwarmError,
+  DecompositionError,
+  formatSubtaskPrompt,
+  formatEvaluationPrompt,
+} from "./swarm";