opencode-swarm-plugin 0.3.0 → 0.5.0

package/src/swarm.integration.test.ts

@@ -16,6 +16,8 @@ import {
   swarm_complete,
   swarm_subtask_prompt,
   swarm_evaluation_prompt,
+  formatSubtaskPromptV2,
+  SUBTASK_PROMPT_V2,
 } from "./swarm";
 import { mcpCall, setState, clearState, AGENT_MAIL_URL } from "./agent-mail";
 
@@ -952,3 +954,116 @@ describe("Graceful Degradation", () => {
     expect(result).toContain("Report progress");
   });
 });
+
+// ============================================================================
+// Coordinator-Centric Swarm Tools (V2)
+// ============================================================================
+
+describe("Swarm Prompt V2 (with Agent Mail/Beads)", () => {
+  describe("formatSubtaskPromptV2", () => {
+    it("generates correct prompt with all fields", () => {
+      const result = formatSubtaskPromptV2({
+        bead_id: "bd-123.1",
+        epic_id: "bd-123",
+        subtask_title: "Add OAuth provider",
+        subtask_description: "Configure Google OAuth in the auth config",
+        files: ["src/auth/google.ts", "src/auth/config.ts"],
+        shared_context: "We are using NextAuth.js v5",
+      });
+
+      // Check title is included
+      expect(result).toContain("Add OAuth provider");
+
+      // Check description is included
+      expect(result).toContain("Configure Google OAuth in the auth config");
+
+      // Check files are formatted as list
+      expect(result).toContain("- `src/auth/google.ts`");
+      expect(result).toContain("- `src/auth/config.ts`");
+
+      // Check shared context is included
+      expect(result).toContain("We are using NextAuth.js v5");
+
+      // Check bead/epic IDs are substituted
+      expect(result).toContain("bd-123.1");
+      expect(result).toContain("bd-123");
+    });
+
+    it("handles missing optional fields", () => {
+      const result = formatSubtaskPromptV2({
+        bead_id: "bd-456.1",
+        epic_id: "bd-456",
+        subtask_title: "Simple task",
+        subtask_description: "",
+        files: [],
+      });
+
+      // Check title is included
+      expect(result).toContain("Simple task");
+
+      // Check fallback for empty description
+      expect(result).toContain("(see title)");
+
+      // Check fallback for empty files
+      expect(result).toContain("(no specific files - use judgment)");
+
+      // Check fallback for missing context
+      expect(result).toContain("(none)");
+    });
+
+    it("handles files with special characters", () => {
+      const result = formatSubtaskPromptV2({
+        bead_id: "bd-789.1",
+        epic_id: "bd-789",
+        subtask_title: "Handle paths",
+        subtask_description: "Test file paths",
+        files: [
+          "src/components/[slug]/page.tsx",
+          "src/api/users/[id]/route.ts",
+        ],
+      });
+
+      expect(result).toContain("- `src/components/[slug]/page.tsx`");
+      expect(result).toContain("- `src/api/users/[id]/route.ts`");
+    });
+  });
+
+  describe("SUBTASK_PROMPT_V2", () => {
+    it("contains expected sections", () => {
+      // Check all main sections are present in the template
+      expect(SUBTASK_PROMPT_V2).toContain("## Task");
+      expect(SUBTASK_PROMPT_V2).toContain("{subtask_title}");
+      expect(SUBTASK_PROMPT_V2).toContain("{subtask_description}");
+
+      expect(SUBTASK_PROMPT_V2).toContain("## Files");
+      expect(SUBTASK_PROMPT_V2).toContain("{file_list}");
+
+      expect(SUBTASK_PROMPT_V2).toContain("## Context");
+      expect(SUBTASK_PROMPT_V2).toContain("{shared_context}");
+
+      expect(SUBTASK_PROMPT_V2).toContain("## Workflow");
+    });
+
+    it("DOES contain Agent Mail instructions", () => {
+      // V2 prompt tells agents to USE Agent Mail
+      expect(SUBTASK_PROMPT_V2).toContain("Agent Mail");
+      expect(SUBTASK_PROMPT_V2).toContain("agentmail_send");
+      expect(SUBTASK_PROMPT_V2).toContain("thread_id");
+    });
+
+    it("DOES contain beads instructions", () => {
+      // V2 prompt tells agents to USE beads
+      expect(SUBTASK_PROMPT_V2).toContain("{bead_id}");
+      expect(SUBTASK_PROMPT_V2).toContain("{epic_id}");
+      expect(SUBTASK_PROMPT_V2).toContain("beads_update");
+      expect(SUBTASK_PROMPT_V2).toContain("beads_create");
+      expect(SUBTASK_PROMPT_V2).toContain("swarm_complete");
+    });
+
+    it("instructs agents to communicate", () => {
+      expect(SUBTASK_PROMPT_V2).toContain("Never work silently");
+      expect(SUBTASK_PROMPT_V2).toContain("Report progress");
+      expect(SUBTASK_PROMPT_V2).toContain("coordinator");
+    });
+  });
+});

package/src/swarm.ts

@@ -359,6 +359,87 @@ Before writing code:
 
 Begin work on your subtask now.`;
 
+/**
+ * Streamlined subtask prompt (V2) - still uses Agent Mail and beads
+ *
+ * This is a cleaner version of SUBTASK_PROMPT that's easier to parse.
+ * Agents MUST use Agent Mail for communication and beads for tracking.
+ */
+export const SUBTASK_PROMPT_V2 = `You are a swarm agent working on: **{subtask_title}**
+
+## Identity
+- **Bead ID**: {bead_id}
+- **Epic ID**: {epic_id}
+
+## Task
+{subtask_description}
+
+## Files (exclusive reservation)
+{file_list}
+
+Only modify these files. Need others? Message the coordinator.
+
+## Context
+{shared_context}
+
+## MANDATORY: Use These Tools
+
+### Agent Mail - communicate with the swarm
+\`\`\`typescript
+// Report progress, ask questions, announce blockers
+agentmail_send({
+  to: ["coordinator"],
+  subject: "Progress update",
+  body: "What you did or need",
+  thread_id: "{epic_id}"
+})
+\`\`\`
+
+### Beads - track your work
+- **Blocked?** \`beads_update({ id: "{bead_id}", status: "blocked" })\`
+- **Found bug?** \`beads_create({ title: "Bug description", type: "bug" })\`
+- **Done?** \`swarm_complete({ bead_id: "{bead_id}", summary: "What you did", files_touched: [...] })\`
+
+## Workflow
+
+1. **Read** the files first
+2. **Plan** your approach (message coordinator if complex)
+3. **Implement** the changes
+4. **Verify** (typecheck, tests)
+5. **Report** progress via Agent Mail
+6. **Complete** with swarm_complete when done
+
+**Never work silently.** Communicate progress and blockers immediately.
+
+Begin now.`;
+
+/**
+ * Format the V2 subtask prompt for a specific agent
+ */
+export function formatSubtaskPromptV2(params: {
+  bead_id: string;
+  epic_id: string;
+  subtask_title: string;
+  subtask_description: string;
+  files: string[];
+  shared_context?: string;
+}): string {
+  const fileList =
+    params.files.length > 0
+      ? params.files.map((f) => `- \`${f}\``).join("\n")
+      : "(no specific files - use judgment)";
+
+  return SUBTASK_PROMPT_V2.replace(/{bead_id}/g, params.bead_id)
+    .replace(/{epic_id}/g, params.epic_id)
+    .replace("{subtask_title}", params.subtask_title)
+    .replace(
+      "{subtask_description}",
+      params.subtask_description || "(see title)",
+    )
+    .replace("{file_list}", fileList)
+    .replace("{shared_context}", params.shared_context || "(none)");
+}
+
 /**
  * Prompt for self-evaluation before completing a subtask.
  *
@@ -1418,6 +1499,199 @@ export const swarm_subtask_prompt = tool({
   },
 });
 
+/**
+ * Prepare a subtask for spawning with Task tool (V2 prompt)
+ *
+ * Generates a streamlined prompt that tells agents to USE Agent Mail and beads.
+ * Returns JSON that can be directly used with Task tool.
+ */
+export const swarm_spawn_subtask = tool({
+  description:
+    "Prepare a subtask for spawning. Returns prompt with Agent Mail/beads instructions.",
+  args: {
+    bead_id: tool.schema.string().describe("Subtask bead ID"),
+    epic_id: tool.schema.string().describe("Parent epic bead ID"),
+    subtask_title: tool.schema.string().describe("Subtask title"),
+    subtask_description: tool.schema
+      .string()
+      .optional()
+      .describe("Detailed subtask instructions"),
+    files: tool.schema
+      .array(tool.schema.string())
+      .describe("Files assigned to this subtask"),
+    shared_context: tool.schema
+      .string()
+      .optional()
+      .describe("Context shared across all agents"),
+  },
+  async execute(args) {
+    const prompt = formatSubtaskPromptV2({
+      bead_id: args.bead_id,
+      epic_id: args.epic_id,
+      subtask_title: args.subtask_title,
+      subtask_description: args.subtask_description || "",
+      files: args.files,
+      shared_context: args.shared_context,
+    });
+
+    return JSON.stringify(
+      {
+        prompt,
+        bead_id: args.bead_id,
+        epic_id: args.epic_id,
+        files: args.files,
+      },
+      null,
+      2,
+    );
+  },
+});
+
+/**
+ * Schema for task agent result
+ */
+const TaskResultSchema = z.object({
+  success: z.boolean(),
+  summary: z.string(),
+  files_modified: z.array(z.string()).optional().default([]),
+  files_created: z.array(z.string()).optional().default([]),
+  issues_found: z.array(z.string()).optional().default([]),
+  tests_passed: z.boolean().optional(),
+  notes: z.string().optional(),
+  blocker: z.string().optional(),
+  suggestions: z.array(z.string()).optional(),
+});
+
+type TaskResult = z.infer<typeof TaskResultSchema>;
+
+/**
+ * Handle subtask completion from a Task agent
+ *
+ * This tool is for coordinators to process the result after a Task subagent
+ * returns. It parses the JSON result, closes the bead on success, and
+ * creates new beads for any issues discovered.
+ *
+ * @example
+ * // Task agent returns JSON:
+ * // { "success": true, "summary": "Added auth", "files_modified": ["src/auth.ts"], "issues_found": ["Missing tests"] }
+ * //
+ * // Coordinator calls:
+ * swarm_complete_subtask(bead_id="bd-123.1", task_result=<agent_response>)
+ */
+export const swarm_complete_subtask = tool({
+  description:
+    "Handle subtask completion after Task agent returns. Parses result JSON, closes bead on success, creates new beads for issues found.",
+  args: {
+    bead_id: z.string().describe("Subtask bead ID to close"),
+    task_result: z
+      .string()
+      .describe("JSON result from the Task agent (TaskResult schema)"),
+    files_touched: z
+      .array(z.string())
+      .optional()
+      .describe(
+        "Override files touched (uses task_result.files_modified if not provided)",
+      ),
+  },
+  async execute(args) {
+    // Parse the task result JSON
+    let result: TaskResult;
+    try {
+      const parsed = JSON.parse(args.task_result);
+      result = TaskResultSchema.parse(parsed);
+    } catch (error) {
+      // Handle parse errors gracefully
+      const errorMessage =
+        error instanceof SyntaxError
+          ? `Invalid JSON: ${error.message}`
+          : error instanceof z.ZodError
+            ? `Schema validation failed: ${error.issues.map((i) => i.message).join(", ")}`
+            : String(error);
+
+      return JSON.stringify(
+        {
+          success: false,
+          error: "Failed to parse task result",
+          details: errorMessage,
+          hint: "Task agent should return JSON matching TaskResult schema: { success, summary, files_modified?, issues_found?, ... }",
+        },
+        null,
+        2,
+      );
+    }
+
+    const filesTouched = args.files_touched ?? [
+      ...result.files_modified,
+      ...result.files_created,
+    ];
+    const issuesCreated: Array<{ title: string; id?: string }> = [];
+
+    // If task failed, don't close the bead - return info for coordinator to handle
+    if (!result.success) {
+      return JSON.stringify(
+        {
+          success: false,
+          bead_id: args.bead_id,
+          task_failed: true,
+          summary: result.summary,
+          blocker: result.blocker,
+          suggestions: result.suggestions,
+          files_touched: filesTouched,
+          action_needed:
+            "Task failed - review blocker and decide whether to retry or close as failed",
+        },
+        null,
+        2,
+      );
+    }
+
+    // Task succeeded - close the bead
+    const closeReason = result.summary.slice(0, 200); // Truncate for safety
+    await Bun.$`bd close ${args.bead_id} -r "${closeReason}"`.quiet().nothrow();
+
+    // Create new beads for each issue found
+    if (result.issues_found.length > 0) {
+      for (const issue of result.issues_found) {
+        const issueTitle = issue.slice(0, 100); // Truncate long titles
+        const createResult = await Bun.$`bd create "${issueTitle}" -t bug`
+          .quiet()
+          .nothrow();
+
+        if (createResult.exitCode === 0) {
+          // Try to parse the bead ID from output
+          const output = createResult.stdout.toString();
+          const idMatch = output.match(/bd-[a-z0-9]+/);
+          issuesCreated.push({
+            title: issueTitle,
+            id: idMatch?.[0],
+          });
+        } else {
+          issuesCreated.push({
+            title: issueTitle,
+            id: undefined, // Failed to create
+          });
+        }
+      }
+    }
+
+    return JSON.stringify(
+      {
+        success: true,
+        bead_id: args.bead_id,
+        bead_closed: true,
+        summary: result.summary,
+        files_touched: filesTouched,
+        tests_passed: result.tests_passed,
+        notes: result.notes,
+        issues_created: issuesCreated.length > 0 ? issuesCreated : undefined,
+        issues_count: issuesCreated.length,
+      },
+      null,
+      2,
+    );
+  },
+});
+
 /**
  * Generate self-evaluation prompt
  */
@@ -1560,5 +1834,7 @@ export const swarmTools = {
   swarm_complete: swarm_complete,
   swarm_record_outcome: swarm_record_outcome,
   swarm_subtask_prompt: swarm_subtask_prompt,
+  swarm_spawn_subtask: swarm_spawn_subtask,
+  swarm_complete_subtask: swarm_complete_subtask,
   swarm_evaluation_prompt: swarm_evaluation_prompt,
 };