opencode-swarm-plugin 0.12.19 → 0.12.22

package/src/agent-mail.ts

@@ -27,6 +27,35 @@ const AGENT_MAIL_URL = "http://127.0.0.1:8765";
 const DEFAULT_TTL_SECONDS = 3600; // 1 hour
 const MAX_INBOX_LIMIT = 5; // HARD CAP - never exceed this
 
+/**
+ * Default project directory for Agent Mail operations
+ *
+ * This is set by the plugin init to the actual working directory (from OpenCode).
+ * Without this, tools might use the plugin's directory instead of the project's.
+ *
+ * Set this via setAgentMailProjectDirectory() before using tools.
+ */
+let agentMailProjectDirectory: string | null = null;
+
+/**
+ * Set the default project directory for Agent Mail operations
+ *
+ * Called during plugin initialization with the actual project directory.
+ * This ensures agentmail_init uses the correct project path by default.
+ */
+export function setAgentMailProjectDirectory(directory: string): void {
+  agentMailProjectDirectory = directory;
+}
+
+/**
+ * Get the default project directory
+ *
+ * Returns the configured directory, or falls back to cwd if not set.
+ */
+export function getAgentMailProjectDirectory(): string {
+  return agentMailProjectDirectory || process.cwd();
+}
+
 // Retry configuration
 const RETRY_CONFIG = {
   maxRetries: parseInt(process.env.OPENCODE_AGENT_MAIL_MAX_RETRIES || "3"),
@@ -541,6 +570,39 @@ function isRetryableError(error: unknown): boolean {
   return false;
 }
 
+/**
+ * Check if an error indicates the project was not found
+ *
+ * This happens when Agent Mail server restarts and loses project registrations.
+ * The fix is to re-register the project and retry the operation.
+ */
+export function isProjectNotFoundError(error: unknown): boolean {
+  if (error instanceof Error) {
+    const message = error.message.toLowerCase();
+    return (
+      message.includes("project") &&
+      (message.includes("not found") || message.includes("does not exist"))
+    );
+  }
+  return false;
+}
+
+/**
+ * Check if an error indicates the agent was not found
+ *
+ * Similar to project not found - server restart loses agent registrations.
+ */
+export function isAgentNotFoundError(error: unknown): boolean {
+  if (error instanceof Error) {
+    const message = error.message.toLowerCase();
+    return (
+      message.includes("agent") &&
+      (message.includes("not found") || message.includes("does not exist"))
+    );
+  }
+  return false;
+}
+
 // ============================================================================
 // MCP Client
 // ============================================================================
@@ -823,6 +885,153 @@ export async function mcpCall<T>(
   throw lastError || new Error("Unknown error in mcpCall");
 }
 
+/**
+ * Re-register a project with Agent Mail server
+ *
+ * Called when we detect "Project not found" error, indicating server restart.
+ * This is a lightweight operation that just ensures the project exists.
+ */
+async function reRegisterProject(projectKey: string): Promise<boolean> {
+  try {
+    console.warn(
+      `[agent-mail] Re-registering project "${projectKey}" after server restart...`,
+    );
+    await mcpCall<ProjectInfo>("ensure_project", {
+      human_key: projectKey,
+    });
+    console.warn(
+      `[agent-mail] Project "${projectKey}" re-registered successfully`,
+    );
+    return true;
+  } catch (error) {
+    console.error(
+      `[agent-mail] Failed to re-register project "${projectKey}":`,
+      error,
+    );
+    return false;
+  }
+}
+
+/**
+ * Re-register an agent with Agent Mail server
+ *
+ * Called when we detect "Agent not found" error, indicating server restart.
+ */
+async function reRegisterAgent(
+  projectKey: string,
+  agentName: string,
+  taskDescription?: string,
+): Promise<boolean> {
+  try {
+    console.warn(
+      `[agent-mail] Re-registering agent "${agentName}" for project "${projectKey}"...`,
+    );
+    await mcpCall<AgentInfo>("register_agent", {
+      project_key: projectKey,
+      program: "opencode",
+      model: "claude-opus-4",
+      name: agentName,
+      task_description: taskDescription || "Re-registered after server restart",
+    });
+    console.warn(
+      `[agent-mail] Agent "${agentName}" re-registered successfully`,
+    );
+    return true;
+  } catch (error) {
+    console.error(
+      `[agent-mail] Failed to re-register agent "${agentName}":`,
+      error,
+    );
+    return false;
+  }
+}
+
+/**
+ * MCP call with automatic project/agent re-registration on "not found" errors
+ *
+ * This is the self-healing wrapper that handles Agent Mail server restarts.
+ * When the server restarts, it loses all project and agent registrations.
+ * This wrapper detects those errors and automatically re-registers before retrying.
+ *
+ * Use this instead of raw mcpCall when you have project_key and agent_name context.
+ *
+ * @param toolName - The MCP tool to call
+ * @param args - Arguments including project_key and optionally agent_name
+ * @param options - Optional configuration for re-registration
+ * @returns The result of the MCP call
+ */
+export async function mcpCallWithAutoInit<T>(
+  toolName: string,
+  args: Record<string, unknown> & { project_key: string; agent_name?: string },
+  options?: {
+    /** Task description for agent re-registration */
+    taskDescription?: string;
+    /** Max re-registration attempts (default: 1) */
+    maxReregistrationAttempts?: number;
+  },
+): Promise<T> {
+  const maxAttempts = options?.maxReregistrationAttempts ?? 1;
+  let reregistrationAttempts = 0;
+
+  while (true) {
+    try {
+      return await mcpCall<T>(toolName, args);
+    } catch (error) {
+      // Check if this is a recoverable "not found" error
+      const isProjectError = isProjectNotFoundError(error);
+      const isAgentError = isAgentNotFoundError(error);
+
+      if (!isProjectError && !isAgentError) {
+        // Not a recoverable error, rethrow
+        throw error;
+      }
+
+      // Check if we've exhausted re-registration attempts
+      if (reregistrationAttempts >= maxAttempts) {
+        console.error(
+          `[agent-mail] Exhausted ${maxAttempts} re-registration attempt(s) for ${toolName}`,
+        );
+        throw error;
+      }
+
+      reregistrationAttempts++;
+      console.warn(
+        `[agent-mail] Detected "${isProjectError ? "project" : "agent"} not found" for ${toolName}, ` +
+          `attempting re-registration (attempt ${reregistrationAttempts}/${maxAttempts})...`,
+      );
+
+      // Re-register project first (always needed)
+      const projectOk = await reRegisterProject(args.project_key);
+      if (!projectOk) {
+        throw error; // Can't recover without project
+      }
+
+      // Re-register agent if we have one and it was an agent error
+      // (or if the original call needs an agent)
+      if (args.agent_name && (isAgentError || toolName !== "ensure_project")) {
+        const agentOk = await reRegisterAgent(
+          args.project_key,
+          args.agent_name,
+          options?.taskDescription,
+        );
+        if (!agentOk) {
+          // Agent re-registration failed, but project is OK
+          // Some operations might still work, so continue
+          console.warn(
+            `[agent-mail] Agent re-registration failed, but continuing with retry...`,
+          );
+        }
+      }
+
+      // Retry the original call
+      console.warn(
+        `[agent-mail] Retrying ${toolName} after re-registration...`,
+      );
+      // Loop continues to retry
+    }
+  }
+}
+
 /**
  * Get Agent Mail state for a session, or throw if not initialized
  *
@@ -897,7 +1106,10 @@ export const agentmail_init = tool({
   args: {
     project_path: tool.schema
       .string()
-      .describe("Absolute path to the project/repo"),
+      .optional()
+      .describe(
+        "Absolute path to the project/repo (defaults to current working directory)",
+      ),
     agent_name: tool.schema
       .string()
       .optional()
@@ -908,6 +1120,10 @@ export const agentmail_init = tool({
       .describe("Description of current task"),
   },
   async execute(args, ctx) {
+    // Use provided path or fall back to configured project directory
+    // This prevents using the plugin's directory when working in a different project
+    const projectPath = args.project_path || getAgentMailProjectDirectory();
+
     // Check if Agent Mail is available
     const available = await checkAgentMailAvailable();
     if (!available) {
@@ -933,12 +1149,12 @@ export const agentmail_init = tool({
       try {
         // 1. Ensure project exists
         const project = await mcpCall<ProjectInfo>("ensure_project", {
-          human_key: args.project_path,
+          human_key: projectPath,
         });
 
         // 2. Register agent
         const agent = await mcpCall<AgentInfo>("register_agent", {
-          project_key: args.project_path,
+          project_key: projectPath,
           program: "opencode",
           model: "claude-opus-4",
           name: args.agent_name, // undefined = auto-generate
@@ -947,7 +1163,7 @@ export const agentmail_init = tool({
 
         // 3. Store state using sessionID
         const state: AgentMailState = {
-          projectKey: args.project_path,
+          projectKey: projectPath,
           agentName: agent.name,
           reservations: [],
           startedAt: new Date().toISOString(),
@@ -1490,4 +1706,6 @@ export {
   restartServer,
   RETRY_CONFIG,
   RECOVERY_CONFIG,
+  // Note: isProjectNotFoundError, isAgentNotFoundError, mcpCallWithAutoInit
+  // are exported at their definitions
 };

package/src/beads.ts

@@ -159,6 +159,11 @@ function buildCreateCommand(args: BeadCreateArgs): string[] {
     parts.push("--parent", args.parent_id);
   }
 
+  // Custom ID for human-readable bead names (e.g., 'phase-0', 'phase-1.e2e-test')
+  if (args.id) {
+    parts.push("--id", args.id);
+  }
+
   parts.push("--json");
   return parts;
 }
@@ -288,12 +293,22 @@ export const beads_create_epic = tool({
       .string()
       .optional()
       .describe("Epic description"),
+    epic_id: tool.schema
+      .string()
+      .optional()
+      .describe("Custom ID for the epic (e.g., 'phase-0')"),
     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(),
+          id_suffix: tool.schema
+            .string()
+            .optional()
+            .describe(
+              "Custom ID suffix (e.g., 'e2e-test' becomes 'phase-0.e2e-test')",
+            ),
         }),
       )
       .describe("Subtasks to create under the epic"),
@@ -309,6 +324,7 @@ export const beads_create_epic = tool({
         type: "epic",
         priority: 1,
         description: validated.epic_description,
+        id: validated.epic_id,
       });
 
       const epicResult = await runBdCommand(epicCmd.slice(1)); // Remove 'bd' prefix
@@ -326,11 +342,19 @@ export const beads_create_epic = tool({
 
       // 2. Create subtasks
       for (const subtask of validated.subtasks) {
+        // Build subtask ID: if epic has custom ID and subtask has suffix, combine them
+        // e.g., epic_id='phase-0', id_suffix='e2e-test' → 'phase-0.e2e-test'
+        let subtaskId: string | undefined;
+        if (validated.epic_id && subtask.id_suffix) {
+          subtaskId = `${validated.epic_id}.${subtask.id_suffix}`;
+        }
+
         const subtaskCmd = buildCreateCommand({
           title: subtask.title,
           type: "task",
           priority: subtask.priority ?? 2,
           parent_id: epic.id,
+          id: subtaskId,
         });
 
         const subtaskResult = await runBdCommand(subtaskCmd.slice(1)); // Remove 'bd' prefix
@@ -717,11 +741,61 @@ export const beads_sync = tool({
 
     // 5. Pull if requested (with rebase to avoid merge commits)
     if (autoPull) {
+      // Check for unstaged changes that would block pull --rebase
+      const dirtyCheckResult = await runGitCommand([
+        "status",
+        "--porcelain",
+        "--untracked-files=no",
+      ]);
+      const hasDirtyFiles = dirtyCheckResult.stdout.trim() !== "";
+      let didStash = false;
+
+      // Stash dirty files before pull (self-healing for "unstaged changes" error)
+      if (hasDirtyFiles) {
+        console.warn(
+          "[beads] Detected unstaged changes, stashing before pull...",
+        );
+        const stashResult = await runGitCommand([
+          "stash",
+          "push",
+          "-m",
+          "beads_sync: auto-stash before pull",
+          "--include-untracked",
+        ]);
+        if (stashResult.exitCode === 0) {
+          didStash = true;
+          console.warn("[beads] Changes stashed successfully");
+        } else {
+          // Stash failed - try pull anyway, it might work
+          console.warn(
+            `[beads] Stash failed (${stashResult.stderr}), attempting pull anyway...`,
+          );
+        }
+      }
+
       const pullResult = await withTimeout(
         runGitCommand(["pull", "--rebase"]),
         TIMEOUT_MS,
         "git pull --rebase",
       );
+
+      // Restore stashed changes regardless of pull result
+      if (didStash) {
+        console.warn("[beads] Restoring stashed changes...");
+        const unstashResult = await runGitCommand(["stash", "pop"]);
+        if (unstashResult.exitCode !== 0) {
+          // Unstash failed - this is bad, user needs to know
+          console.error(
+            `[beads] WARNING: Failed to restore stashed changes: ${unstashResult.stderr}`,
+          );
+          console.error(
+            "[beads] Your changes are in 'git stash list' - run 'git stash pop' manually",
+          );
+        } else {
+          console.warn("[beads] Stashed changes restored");
+        }
+      }
+
       if (pullResult.exitCode !== 0) {
         throw new BeadError(
           `Failed to pull: ${pullResult.stderr}`,

package/src/index.ts

@@ -25,12 +25,14 @@ import type { Plugin, PluginInput, Hooks } from "@opencode-ai/plugin";
 import { beadsTools, setBeadsWorkingDirectory } from "./beads";
 import {
   agentMailTools,
+  setAgentMailProjectDirectory,
   type AgentMailState,
   AGENT_MAIL_URL,
 } from "./agent-mail";
 import { structuredTools } from "./structured";
 import { swarmTools } from "./swarm";
 import { repoCrawlTools } from "./repo-crawl";
+import { skillsTools, setSkillsProjectDirectory } from "./skills";
 
 /**
  * OpenCode Swarm Plugin
@@ -41,6 +43,7 @@ import { repoCrawlTools } from "./repo-crawl";
  * - structured:* - Structured output parsing and validation
  * - swarm:* - Swarm orchestration and task decomposition
  * - repo-crawl:* - GitHub API tools for repository research
+ * - skills:* - Agent skills discovery, activation, and execution
  *
  * @param input - Plugin context from OpenCode
  * @returns Plugin hooks including tools, events, and tool execution hooks
@@ -54,6 +57,15 @@ export const SwarmPlugin: Plugin = async (
   // This ensures bd runs in the project directory, not ~/.config/opencode
   setBeadsWorkingDirectory(directory);
 
+  // Set the project directory for skills discovery
+  // Skills are discovered from .opencode/skills/, .claude/skills/, or skills/
+  setSkillsProjectDirectory(directory);
+
+  // Set the project directory for Agent Mail
+  // This ensures agentmail_init uses the correct project path by default
+  // (prevents using plugin directory when working in a different project)
+  setAgentMailProjectDirectory(directory);
+
   /** Track active sessions for cleanup */
   let activeAgentMailState: AgentMailState | null = null;
 
@@ -116,6 +128,7 @@ export const SwarmPlugin: Plugin = async (
       ...structuredTools,
       ...swarmTools,
       ...repoCrawlTools,
+      ...skillsTools,
     },
 
     /**
@@ -239,6 +252,11 @@ export {
   AgentMailNotInitializedError,
   FileReservationConflictError,
   createAgentMailError,
+  setAgentMailProjectDirectory,
+  getAgentMailProjectDirectory,
+  mcpCallWithAutoInit,
+  isProjectNotFoundError,
+  isAgentNotFoundError,
   type AgentMailState,
 } from "./agent-mail";
 
@@ -305,6 +323,7 @@ export const allTools = {
   ...structuredTools,
   ...swarmTools,
   ...repoCrawlTools,
+  ...skillsTools,
 } as const;
 
 /**
@@ -387,3 +406,33 @@ export {
  * - Graceful rate limit handling
  */
 export { repoCrawlTools, RepoCrawlError } from "./repo-crawl";
+
+/**
+ * Re-export skills module
+ *
+ * Implements Anthropic's Agent Skills specification for OpenCode.
+ *
+ * Includes:
+ * - skillsTools - All skills tools (list, use, execute, read)
+ * - discoverSkills, getSkill, listSkills - Discovery functions
+ * - parseFrontmatter - YAML frontmatter parser
+ * - getSkillsContextForSwarm - Swarm integration helper
+ * - findRelevantSkills - Task-based skill matching
+ *
+ * Types:
+ * - Skill, SkillMetadata, SkillRef - Skill data types
+ */
+export {
+  skillsTools,
+  discoverSkills,
+  getSkill,
+  listSkills,
+  parseFrontmatter,
+  setSkillsProjectDirectory,
+  invalidateSkillsCache,
+  getSkillsContextForSwarm,
+  findRelevantSkills,
+  type Skill,
+  type SkillMetadata,
+  type SkillRef,
+} from "./skills";

package/src/schemas/bead.ts

@@ -38,11 +38,13 @@ export type BeadDependency = z.infer<typeof BeadDependencySchema>;
  * ID format:
  * - Standard: `{project}-{hash}` (e.g., `opencode-swarm-plugin-1i8`)
  * - Subtask: `{project}-{hash}.{index}` (e.g., `opencode-swarm-plugin-1i8.1`)
+ * - Custom: `{project}-{custom-id}` (e.g., `migrate-egghead-phase-0`)
+ * - Custom subtask: `{project}-{custom-id}.{suffix}` (e.g., `migrate-egghead-phase-0.e2e-test`)
  */
 export const BeadSchema = z.object({
   id: z
     .string()
-    .regex(/^[a-z0-9]+(-[a-z0-9]+)+(\.\d+)?$/, "Invalid bead ID format"),
+    .regex(/^[a-z0-9]+(-[a-z0-9]+)+(\.[\w-]+)?$/, "Invalid bead ID format"),
   title: z.string().min(1, "Title required"),
   description: z.string().optional().default(""),
   status: BeadStatusSchema.default("open"),
@@ -64,6 +66,12 @@ export const BeadCreateArgsSchema = z.object({
   priority: z.number().int().min(0).max(3).default(2),
   description: z.string().optional(),
   parent_id: z.string().optional(),
+  /**
+   * Custom ID for human-readable bead names.
+   * MUST include project prefix (e.g., 'migrate-egghead-phase-0', not just 'phase-0').
+   * For subtasks, use dot notation: 'migrate-egghead-phase-0.e2e-test'
+   */
+  id: z.string().optional(),
 });
 export type BeadCreateArgs = z.infer<typeof BeadCreateArgsSchema>;
 
@@ -125,12 +133,24 @@ export type BeadTree = z.infer<typeof BeadTreeSchema>;
 export const EpicCreateArgsSchema = z.object({
   epic_title: z.string().min(1),
   epic_description: z.string().optional(),
+  /**
+   * Custom ID for the epic. MUST include project prefix.
+   * Example: 'migrate-egghead-phase-0' (not just 'phase-0')
+   * If not provided, bd generates a random ID.
+   */
+  epic_id: z.string().optional(),
   subtasks: z
     .array(
       z.object({
         title: z.string().min(1),
         priority: z.number().int().min(0).max(3).default(2),
         files: z.array(z.string()).optional().default([]),
+        /**
+         * Custom ID suffix for subtask. Combined with epic_id using dot notation.
+         * Example: epic_id='migrate-egghead-phase-0', id_suffix='e2e-test'
+         *          → subtask ID: 'migrate-egghead-phase-0.e2e-test'
+         */
+        id_suffix: z.string().optional(),
       }),
     )
     .min(1),