opencode-swarm-plugin 0.20.0 → 0.21.0

package/src/swarm-orchestrate.ts

@@ -37,6 +37,9 @@ import {
   releaseSwarmFiles,
   sendSwarmMessage,
 } from "./streams/swarm-mail";
+import { getAgent } from "./streams/projections";
+import { createEvent } from "./streams/events";
+import { appendEvent } from "./streams/store";
 import {
   addStrike,
   clearStrikes,
@@ -836,7 +839,74 @@ export const swarm_progress = tool({
       importance: args.status === "blocked" ? "high" : "normal",
     });
 
-    return `Progress reported: ${args.status}${args.progress_percent !== undefined ? ` (${args.progress_percent}%)` : ""}`;
+    // Auto-checkpoint at milestone progress (25%, 50%, 75%)
+    let checkpointCreated = false;
+    if (
+      args.progress_percent !== undefined &&
+      args.files_touched &&
+      args.files_touched.length > 0
+    ) {
+      const milestones = [25, 50, 75];
+      if (milestones.includes(args.progress_percent)) {
+        try {
+          // Create checkpoint event directly (non-fatal if it fails)
+          const checkpoint = {
+            epic_id: epicId,
+            bead_id: args.bead_id,
+            strategy: "file-based" as const,
+            files: args.files_touched,
+            dependencies: [] as string[],
+            directives: {},
+            recovery: {
+              last_checkpoint: Date.now(),
+              files_modified: args.files_touched,
+              progress_percent: args.progress_percent,
+              last_message: args.message,
+            },
+          };
+
+          const event = createEvent("swarm_checkpointed", {
+            project_key: args.project_key,
+            ...checkpoint,
+          });
+          await appendEvent(event, args.project_key);
+
+          // Update swarm_contexts table
+          const { getDatabase } = await import("./streams/index");
+          const db = await getDatabase(args.project_key);
+          const now = Date.now();
+          await db.query(
+            `INSERT INTO swarm_contexts (id, epic_id, bead_id, strategy, files, dependencies, directives, recovery, created_at, updated_at)
+             VALUES ($1, $2, $3, $4, $5, $6, $7, $8, $9, $10)
+             ON CONFLICT (id) DO UPDATE SET
+               files = EXCLUDED.files,
+               recovery = EXCLUDED.recovery,
+               updated_at = EXCLUDED.updated_at`,
+            [
+              args.bead_id,
+              epicId,
+              args.bead_id,
+              checkpoint.strategy,
+              JSON.stringify(checkpoint.files),
+              JSON.stringify(checkpoint.dependencies),
+              JSON.stringify(checkpoint.directives),
+              JSON.stringify(checkpoint.recovery),
+              now,
+              now,
+            ],
+          );
+          checkpointCreated = true;
+        } catch (error) {
+          // Non-fatal - log and continue
+          console.warn(
+            `[swarm_progress] Auto-checkpoint failed at ${args.progress_percent}%:`,
+            error,
+          );
+        }
+      }
+    }
+
+    return `Progress reported: ${args.status}${args.progress_percent !== undefined ? ` (${args.progress_percent}%)` : ""}${checkpointCreated ? " [checkpoint created]" : ""}`;
   },
 });
 
@@ -966,8 +1036,64 @@ export const swarm_complete = tool({
       .describe(
         "Skip ALL verification (UBS, typecheck, tests). Use sparingly! (default: false)",
       ),
+    planned_files: tool.schema
+      .array(tool.schema.string())
+      .optional()
+      .describe("Files that were originally planned to be modified"),
+    start_time: tool.schema
+      .number()
+      .optional()
+      .describe("Task start timestamp (Unix ms) for duration calculation"),
+    error_count: tool.schema
+      .number()
+      .optional()
+      .describe("Number of errors encountered during task"),
+    retry_count: tool.schema
+      .number()
+      .optional()
+      .describe("Number of retry attempts during task"),
   },
   async execute(args) {
+    // Verify agent is registered in swarm-mail
+    // This catches agents who skipped swarmmail_init
+    const projectKey = args.project_key.replace(/\//g, "-").replace(/\\/g, "-");
+    let agentRegistered = false;
+    let registrationWarning = "";
+
+    try {
+      const agent = await getAgent(
+        projectKey,
+        args.agent_name,
+        args.project_key,
+      );
+      agentRegistered = agent !== null;
+
+      if (!agentRegistered) {
+        registrationWarning = `⚠️  WARNING: Agent '${args.agent_name}' was NOT registered in swarm-mail for project '${projectKey}'.
+
+This usually means you skipped the MANDATORY swarmmail_init step.
+
+**Impact:**
+- Your work was not tracked in the coordination system
+- File reservations may not have been managed
+- Other agents couldn't coordinate with you
+- Learning/eval data may be incomplete
+
+**Next time:** Run swarmmail_init(project_path="${args.project_key}", task_description="<task>") FIRST, before any other work.
+
+Continuing with completion, but this should be fixed for future subtasks.`;
+
+        console.warn(`[swarm_complete] ${registrationWarning}`);
+      }
+    } catch (error) {
+      // Non-fatal - agent might be using legacy workflow
+      console.warn(
+        `[swarm_complete] Could not verify agent registration:`,
+        error,
+      );
+      registrationWarning = `ℹ️  Could not verify swarm-mail registration (database may not be available). Consider running swarmmail_init next time.`;
+    }
+
     // Run Verification Gate unless explicitly skipped
     let verificationResult: VerificationGateResult | null = null;
 
@@ -1086,6 +1212,34 @@ export const swarm_complete = tool({
       );
     }
 
+    // Emit SubtaskOutcomeEvent for learning system
+    try {
+      const epicId = args.bead_id.includes(".")
+        ? args.bead_id.split(".")[0]
+        : args.bead_id;
+
+      const durationMs = args.start_time ? Date.now() - args.start_time : 0;
+
+      const event = createEvent("subtask_outcome", {
+        project_key: args.project_key,
+        epic_id: epicId,
+        bead_id: args.bead_id,
+        planned_files: args.planned_files || [],
+        actual_files: args.files_touched || [],
+        duration_ms: durationMs,
+        error_count: args.error_count || 0,
+        retry_count: args.retry_count || 0,
+        success: true,
+      });
+      await appendEvent(event, args.project_key);
+    } catch (error) {
+      // Non-fatal - log and continue
+      console.warn(
+        "[swarm_complete] Failed to emit SubtaskOutcomeEvent:",
+        error,
+      );
+    }
+
     // Release file reservations for this agent using embedded swarm-mail
     try {
       await releaseSwarmFiles({
@@ -1140,6 +1294,10 @@ export const swarm_complete = tool({
       closed: true,
       reservations_released: true,
       message_sent: true,
+      agent_registration: {
+        verified: agentRegistered,
+        warning: registrationWarning || undefined,
+      },
       verification_gate: verificationResult
         ? {
             passed: true,
@@ -1647,6 +1805,275 @@ export const swarm_check_strikes = tool({
   },
 });
 
+/**
+ * Swarm context shape stored in swarm_contexts table
+ */
+interface SwarmBeadContext {
+  id: string;
+  epic_id: string;
+  bead_id: string;
+  strategy: "file-based" | "feature-based" | "risk-based";
+  files: string[];
+  dependencies: string[];
+  directives: {
+    shared_context?: string;
+    skills_to_load?: string[];
+    coordinator_notes?: string;
+  };
+  recovery: {
+    last_checkpoint: number;
+    files_modified: string[];
+    progress_percent: number;
+    last_message?: string;
+    error_context?: string;
+  };
+  created_at: number;
+  updated_at: number;
+}
+
+/**
+ * Checkpoint swarm context for recovery
+ *
+ * Records the current state of a subtask to enable recovery after crashes,
+ * context overflows, or agent restarts. Non-fatal errors - logs warnings
+ * and continues if checkpoint fails.
+ *
+ * Integration:
+ * - Called automatically by swarm_progress at milestone thresholds (25%, 50%, 75%)
+ * - Can be called manually by agents at critical points
+ * - Emits SwarmCheckpointedEvent for audit trail
+ * - Updates swarm_contexts table for fast recovery queries
+ */
+export const swarm_checkpoint = tool({
+  description:
+    "Checkpoint swarm context for recovery. Records current state for crash recovery. Non-fatal errors.",
+  args: {
+    project_key: tool.schema.string().describe("Project path"),
+    agent_name: tool.schema.string().describe("Agent name"),
+    bead_id: tool.schema.string().describe("Subtask bead ID"),
+    epic_id: tool.schema.string().describe("Epic bead ID"),
+    files_modified: tool.schema
+      .array(tool.schema.string())
+      .describe("Files modified so far"),
+    progress_percent: tool.schema
+      .number()
+      .min(0)
+      .max(100)
+      .describe("Current progress"),
+    directives: tool.schema
+      .object({
+        shared_context: tool.schema.string().optional(),
+        skills_to_load: tool.schema.array(tool.schema.string()).optional(),
+        coordinator_notes: tool.schema.string().optional(),
+      })
+      .optional()
+      .describe("Coordinator directives for this subtask"),
+    error_context: tool.schema
+      .string()
+      .optional()
+      .describe("Error context if checkpoint is during error handling"),
+  },
+  async execute(args) {
+    try {
+      // Build checkpoint data
+      const checkpoint: Omit<
+        SwarmBeadContext,
+        "id" | "created_at" | "updated_at"
+      > = {
+        epic_id: args.epic_id,
+        bead_id: args.bead_id,
+        strategy: "file-based", // TODO: Extract from decomposition metadata
+        files: args.files_modified,
+        dependencies: [], // TODO: Extract from bead metadata
+        directives: args.directives || {},
+        recovery: {
+          last_checkpoint: Date.now(),
+          files_modified: args.files_modified,
+          progress_percent: args.progress_percent,
+          error_context: args.error_context,
+        },
+      };
+
+      // Emit checkpoint event
+      const event = createEvent("swarm_checkpointed", {
+        project_key: args.project_key,
+        epic_id: args.epic_id,
+        bead_id: args.bead_id,
+        strategy: checkpoint.strategy,
+        files: checkpoint.files,
+        dependencies: checkpoint.dependencies,
+        directives: checkpoint.directives,
+        recovery: checkpoint.recovery,
+      });
+
+      await appendEvent(event, args.project_key);
+
+      // Update swarm_contexts table for fast recovery
+      const { getDatabase } = await import("./streams/index");
+      const db = await getDatabase(args.project_key);
+
+      const now = Date.now();
+      await db.query(
+        `INSERT INTO swarm_contexts (id, epic_id, bead_id, strategy, files, dependencies, directives, recovery, created_at, updated_at)
+         VALUES ($1, $2, $3, $4, $5, $6, $7, $8, $9, $10)
+         ON CONFLICT (id) DO UPDATE SET
+           files = EXCLUDED.files,
+           recovery = EXCLUDED.recovery,
+           updated_at = EXCLUDED.updated_at`,
+        [
+          args.bead_id, // Use bead_id as unique ID
+          args.epic_id,
+          args.bead_id,
+          checkpoint.strategy,
+          JSON.stringify(checkpoint.files),
+          JSON.stringify(checkpoint.dependencies),
+          JSON.stringify(checkpoint.directives),
+          JSON.stringify(checkpoint.recovery),
+          now,
+          now,
+        ],
+      );
+
+      return JSON.stringify(
+        {
+          success: true,
+          checkpoint_timestamp: now,
+          summary: `Checkpoint saved for ${args.bead_id} at ${args.progress_percent}%`,
+          bead_id: args.bead_id,
+          epic_id: args.epic_id,
+          files_tracked: args.files_modified.length,
+        },
+        null,
+        2,
+      );
+    } catch (error) {
+      // Non-fatal - log warning and continue
+      console.warn(
+        `[swarm_checkpoint] Failed to checkpoint ${args.bead_id}:`,
+        error,
+      );
+      return JSON.stringify(
+        {
+          success: false,
+          warning: "Checkpoint failed but continuing",
+          error: error instanceof Error ? error.message : String(error),
+          bead_id: args.bead_id,
+          note: "This is non-fatal. Work can continue without checkpoint.",
+        },
+        null,
+        2,
+      );
+    }
+  },
+});
+
+/**
+ * Recover swarm context from last checkpoint
+ *
+ * Queries swarm_contexts table for the most recent checkpoint of an epic.
+ * Returns the full context including files, progress, and recovery state.
+ * Emits SwarmRecoveredEvent for audit trail.
+ *
+ * Graceful fallback: Returns { found: false } if no checkpoint exists.
+ */
+export const swarm_recover = tool({
+  description:
+    "Recover swarm context from last checkpoint. Returns context or null if not found.",
+  args: {
+    project_key: tool.schema.string().describe("Project path"),
+    epic_id: tool.schema.string().describe("Epic bead ID to recover"),
+  },
+  async execute(args) {
+    try {
+      const { getDatabase } = await import("./streams/index");
+      const db = await getDatabase(args.project_key);
+
+      // Query most recent checkpoint for this epic
+      const result = await db.query<{
+        id: string;
+        epic_id: string;
+        bead_id: string;
+        strategy: string;
+        files: string;
+        dependencies: string;
+        directives: string;
+        recovery: string;
+        created_at: number;
+        updated_at: number;
+      }>(
+        `SELECT * FROM swarm_contexts 
+         WHERE epic_id = $1 
+         ORDER BY updated_at DESC 
+         LIMIT 1`,
+        [args.epic_id],
+      );
+
+      if (result.rows.length === 0) {
+        return JSON.stringify(
+          {
+            found: false,
+            message: `No checkpoint found for epic ${args.epic_id}`,
+            epic_id: args.epic_id,
+          },
+          null,
+          2,
+        );
+      }
+
+      const row = result.rows[0];
+      const context: SwarmBeadContext = {
+        id: row.id,
+        epic_id: row.epic_id,
+        bead_id: row.bead_id,
+        strategy: row.strategy as SwarmBeadContext["strategy"],
+        files: JSON.parse(row.files),
+        dependencies: JSON.parse(row.dependencies),
+        directives: JSON.parse(row.directives),
+        recovery: JSON.parse(row.recovery),
+        created_at: row.created_at,
+        updated_at: row.updated_at,
+      };
+
+      // Emit recovery event
+      const event = createEvent("swarm_recovered", {
+        project_key: args.project_key,
+        epic_id: args.epic_id,
+        bead_id: context.bead_id,
+        recovered_from_checkpoint: context.recovery.last_checkpoint,
+      });
+
+      await appendEvent(event, args.project_key);
+
+      return JSON.stringify(
+        {
+          found: true,
+          context,
+          summary: `Recovered checkpoint from ${new Date(context.updated_at).toISOString()}`,
+          age_seconds: Math.round((Date.now() - context.updated_at) / 1000),
+        },
+        null,
+        2,
+      );
+    } catch (error) {
+      // Graceful fallback
+      console.warn(
+        `[swarm_recover] Failed to recover context for ${args.epic_id}:`,
+        error,
+      );
+      return JSON.stringify(
+        {
+          found: false,
+          error: error instanceof Error ? error.message : String(error),
+          message: `Recovery failed for epic ${args.epic_id}`,
+          epic_id: args.epic_id,
+        },
+        null,
+        2,
+      );
+    }
+  },
+});
+
 /**
  * Learn from completed work and optionally create a skill
  *
@@ -1865,5 +2292,7 @@ export const orchestrateTools = {
   swarm_get_error_context,
   swarm_resolve_error,
   swarm_check_strikes,
+  swarm_checkpoint,
+  swarm_recover,
   swarm_learn,
 };

package/src/swarm-prompts.ts

@@ -273,20 +273,29 @@ Only modify these files. Need others? Message the coordinator.
 
 {error_context}
 
-## [MANDATORY: SWARM MAIL]
+## [MANDATORY: SWARM MAIL INITIALIZATION]
 
-**YOU MUST USE SWARM MAIL FOR ALL COORDINATION.** This is non-negotiable.
+**CRITICAL: YOU MUST INITIALIZE SWARM MAIL BEFORE DOING ANY WORK.**
 
-### Initialize FIRST (before any work)
-\`\`\`
-swarmmail_init(project_path="$PWD", task_description="{subtask_title}")
-\`\`\`
+This is your FIRST step - before reading files, before planning, before ANY other action.
 
-### Reserve Files (if not already reserved by coordinator)
+### Step 1: Initialize (REQUIRED - DO THIS FIRST)
 \`\`\`
-swarmmail_reserve(paths=[...files...], reason="{bead_id}: {subtask_title}")
+swarmmail_init(project_path="{project_path}", task_description="{bead_id}: {subtask_title}")
 \`\`\`
 
+**This registers you with the coordination system and enables:**
+- File reservation tracking
+- Inter-agent communication
+- Progress monitoring
+- Conflict detection
+
+**If you skip this step, your work will not be tracked and swarm_complete will fail.**
+
+## [SWARM MAIL USAGE]
+
+After initialization, use Swarm Mail for coordination:
+
 ### Check Inbox Regularly
 \`\`\`
 swarmmail_inbox()  # Check for coordinator messages
@@ -340,14 +349,17 @@ As you work, note reusable patterns, best practices, or domain insights:
 - Skills make swarms smarter over time
 
 ## [WORKFLOW]
-1. **swarmmail_init** - Initialize session FIRST
+1. **swarmmail_init** - Initialize session (MANDATORY FIRST STEP)
 2. Read assigned files
 3. Implement changes
 4. **swarmmail_send** - Report progress to coordinator
 5. Verify (typecheck)
 6. **swarm_complete** - Mark done, release reservations
 
-**CRITICAL: Never work silently. Send progress updates via swarmmail_send every significant milestone.**
+**CRITICAL REQUIREMENTS:**
+- Step 1 (swarmmail_init) is NON-NEGOTIABLE - do it before anything else
+- Never work silently - send progress updates via swarmmail_send every significant milestone
+- If you complete without initializing, swarm_complete will detect this and warn/fail
 
 Begin now.`;
 
@@ -409,6 +421,12 @@ export function formatSubtaskPromptV2(params: {
   shared_context?: string;
   compressed_context?: string;
   error_context?: string;
+  project_path?: string;
+  recovery_context?: {
+    shared_context?: string;
+    skills_to_load?: string[];
+    coordinator_notes?: string;
+  };
 }): string {
   const fileList =
     params.files.length > 0
@@ -421,8 +439,40 @@ export function formatSubtaskPromptV2(params: {
 
   const errorSection = params.error_context ? params.error_context : "";
 
+  // Build recovery context section
+  let recoverySection = "";
+  if (params.recovery_context) {
+    const sections: string[] = [];
+
+    if (params.recovery_context.shared_context) {
+      sections.push(
+        `### Recovery Context\n${params.recovery_context.shared_context}`,
+      );
+    }
+
+    if (
+      params.recovery_context.skills_to_load &&
+      params.recovery_context.skills_to_load.length > 0
+    ) {
+      sections.push(
+        `### Skills to Load\nBefore starting work, load these skills for specialized guidance:\n${params.recovery_context.skills_to_load.map((s) => `- skills_use(name="${s}")`).join("\n")}`,
+      );
+    }
+
+    if (params.recovery_context.coordinator_notes) {
+      sections.push(
+        `### Coordinator Notes\n${params.recovery_context.coordinator_notes}`,
+      );
+    }
+
+    if (sections.length > 0) {
+      recoverySection = `\n## [RECOVERY CONTEXT]\n\n${sections.join("\n\n")}`;
+    }
+  }
+
   return SUBTASK_PROMPT_V2.replace(/{bead_id}/g, params.bead_id)
     .replace(/{epic_id}/g, params.epic_id)
+    .replace(/{project_path}/g, params.project_path || "$PWD")
     .replace("{subtask_title}", params.subtask_title)
     .replace(
       "{subtask_description}",
@@ -431,7 +481,7 @@ export function formatSubtaskPromptV2(params: {
     .replace("{file_list}", fileList)
     .replace("{shared_context}", params.shared_context || "(none)")
     .replace("{compressed_context}", compressedSection)
-    .replace("{error_context}", errorSection);
+    .replace("{error_context}", errorSection + recoverySection);
 }
 
 /**
@@ -497,6 +547,10 @@ export const swarm_subtask_prompt = tool({
       .string()
       .optional()
       .describe("Context shared across all agents"),
+    project_path: tool.schema
+      .string()
+      .optional()
+      .describe("Absolute project path for swarmmail_init"),
   },
   async execute(args) {
     const prompt = formatSubtaskPrompt({
@@ -521,7 +575,7 @@ export const swarm_subtask_prompt = tool({
  */
 export const swarm_spawn_subtask = tool({
   description:
-    "Prepare a subtask for spawning. Returns prompt with Agent Mail/beads instructions.",
+    "Prepare a subtask for spawning. Returns prompt with Agent Mail/beads instructions. IMPORTANT: Pass project_path for swarmmail_init.",
   args: {
     bead_id: tool.schema.string().describe("Subtask bead ID"),
     epic_id: tool.schema.string().describe("Parent epic bead ID"),
@@ -537,6 +591,20 @@ export const swarm_spawn_subtask = tool({
       .string()
       .optional()
       .describe("Context shared across all agents"),
+    project_path: tool.schema
+      .string()
+      .optional()
+      .describe(
+        "Absolute project path for swarmmail_init (REQUIRED for tracking)",
+      ),
+    recovery_context: tool.schema
+      .object({
+        shared_context: tool.schema.string().optional(),
+        skills_to_load: tool.schema.array(tool.schema.string()).optional(),
+        coordinator_notes: tool.schema.string().optional(),
+      })
+      .optional()
+      .describe("Recovery context from checkpoint compaction"),
   },
   async execute(args) {
     const prompt = formatSubtaskPromptV2({
@@ -546,6 +614,8 @@ export const swarm_spawn_subtask = tool({
       subtask_description: args.subtask_description || "",
       files: args.files,
       shared_context: args.shared_context,
+      project_path: args.project_path,
+      recovery_context: args.recovery_context,
     });
 
     return JSON.stringify(
@@ -554,6 +624,8 @@ export const swarm_spawn_subtask = tool({
         bead_id: args.bead_id,
         epic_id: args.epic_id,
         files: args.files,
+        project_path: args.project_path,
+        recovery_context: args.recovery_context,
       },
       null,
       2,