opencode-swarm-plugin 0.21.0 → 0.22.0

package/dist/plugin.js

@@ -35359,14 +35359,16 @@ var swarm_complete = tool({
     retry_count: tool.schema.number().optional().describe("Number of retry attempts during task")
   },
   async execute(args) {
-    const projectKey = args.project_key.replace(/\//g, "-").replace(/\\/g, "-");
-    let agentRegistered = false;
-    let registrationWarning = "";
+    const epicId = args.bead_id.includes(".") ? args.bead_id.split(".")[0] : args.bead_id;
     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}'.
+      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.
 
@@ -35379,150 +35381,176 @@ This usually means you skipped the MANDATORY swarmmail_init step.
 **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}`);
+          console.warn(`[swarm_complete] ${registrationWarning}`);
+        }
+      } catch (error45) {
+        console.warn(`[swarm_complete] Could not verify agent registration:`, error45);
+        registrationWarning = `ℹ️  Could not verify swarm-mail registration (database may not be available). Consider running swarmmail_init next time.`;
       }
-    } catch (error45) {
-      console.warn(`[swarm_complete] Could not verify agent registration:`, error45);
-      registrationWarning = `ℹ️  Could not verify swarm-mail registration (database may not be available). Consider running swarmmail_init next time.`;
-    }
-    let verificationResult = null;
-    if (!args.skip_verification && args.files_touched?.length) {
-      verificationResult = await runVerificationGate(args.files_touched, args.skip_ubs_scan ?? false);
-      if (!verificationResult.passed) {
-        return JSON.stringify({
-          success: false,
-          error: "Verification Gate FAILED - fix issues before completing",
-          verification: {
-            passed: false,
-            summary: verificationResult.summary,
-            blockers: verificationResult.blockers,
-            steps: verificationResult.steps.map((s) => ({
-              name: s.name,
-              passed: s.passed,
-              skipped: s.skipped,
-              skipReason: s.skipReason,
-              error: s.error?.slice(0, 200)
-            }))
-          },
-          hint: verificationResult.blockers.length > 0 ? `Fix these issues: ${verificationResult.blockers.map((b, i) => `${i + 1}. ${b}`).join(", ")}. Use skip_verification=true only as last resort.` : "Fix the failing checks and try again. Use skip_verification=true only as last resort.",
-          gate_function: "IDENTIFY → RUN → READ → VERIFY → CLAIM (you are at VERIFY, claim blocked)"
-        }, null, 2);
+      let verificationResult = null;
+      if (!args.skip_verification && args.files_touched?.length) {
+        verificationResult = await runVerificationGate(args.files_touched, args.skip_ubs_scan ?? false);
+        if (!verificationResult.passed) {
+          return JSON.stringify({
+            success: false,
+            error: "Verification Gate FAILED - fix issues before completing",
+            verification: {
+              passed: false,
+              summary: verificationResult.summary,
+              blockers: verificationResult.blockers,
+              steps: verificationResult.steps.map((s) => ({
+                name: s.name,
+                passed: s.passed,
+                skipped: s.skipped,
+                skipReason: s.skipReason,
+                error: s.error?.slice(0, 200)
+              }))
+            },
+            hint: verificationResult.blockers.length > 0 ? `Fix these issues: ${verificationResult.blockers.map((b, i) => `${i + 1}. ${b}`).join(", ")}. Use skip_verification=true only as last resort.` : "Fix the failing checks and try again. Use skip_verification=true only as last resort.",
+            gate_function: "IDENTIFY → RUN → READ → VERIFY → CLAIM (you are at VERIFY, claim blocked)"
+          }, null, 2);
+        }
       }
-    }
-    let ubsResult = null;
-    if (!args.skip_verification && !verificationResult && args.files_touched?.length && !args.skip_ubs_scan) {
-      ubsResult = await runUbsScan(args.files_touched);
-      if (ubsResult && ubsResult.summary.critical > 0) {
-        return JSON.stringify({
-          success: false,
-          error: `UBS found ${ubsResult.summary.critical} critical bug(s) that must be fixed before completing`,
-          ubs_scan: {
-            critical_count: ubsResult.summary.critical,
-            bugs: ubsResult.bugs.filter((b) => b.severity === "critical")
-          },
-          hint: `Fix these critical bugs: ${ubsResult.bugs.filter((b) => b.severity === "critical").map((b) => `${b.file}:${b.line} - ${b.message}`).slice(0, 3).join("; ")}. Try: Run 'ubs scan ${args.files_touched?.join(" ") || "."} --json' for full report, fix reported issues, or use skip_ubs_scan=true to bypass (not recommended).`
-        }, null, 2);
+      let ubsResult = null;
+      if (!args.skip_verification && !verificationResult && args.files_touched?.length && !args.skip_ubs_scan) {
+        ubsResult = await runUbsScan(args.files_touched);
+        if (ubsResult && ubsResult.summary.critical > 0) {
+          return JSON.stringify({
+            success: false,
+            error: `UBS found ${ubsResult.summary.critical} critical bug(s) that must be fixed before completing`,
+            ubs_scan: {
+              critical_count: ubsResult.summary.critical,
+              bugs: ubsResult.bugs.filter((b) => b.severity === "critical")
+            },
+            hint: `Fix these critical bugs: ${ubsResult.bugs.filter((b) => b.severity === "critical").map((b) => `${b.file}:${b.line} - ${b.message}`).slice(0, 3).join("; ")}. Try: Run 'ubs scan ${args.files_touched?.join(" ") || "."} --json' for full report, fix reported issues, or use skip_ubs_scan=true to bypass (not recommended).`
+          }, null, 2);
+        }
+      }
+      let parsedEvaluation;
+      if (args.evaluation) {
+        try {
+          parsedEvaluation = EvaluationSchema.parse(JSON.parse(args.evaluation));
+        } catch (error45) {
+          return JSON.stringify({
+            success: false,
+            error: "Invalid evaluation format",
+            details: error45 instanceof exports_external.ZodError ? error45.issues : String(error45)
+          }, null, 2);
+        }
+        if (!parsedEvaluation.passed) {
+          return JSON.stringify({
+            success: false,
+            error: "Self-evaluation failed",
+            retry_suggestion: parsedEvaluation.retry_suggestion,
+            feedback: parsedEvaluation.overall_feedback
+          }, null, 2);
+        }
+      }
+      const closeResult = await Bun.$`bd close ${args.bead_id} --reason ${args.summary} --json`.quiet().nothrow();
+      if (closeResult.exitCode !== 0) {
+        throw new Error(`Failed to close bead because bd close command failed: ${closeResult.stderr.toString()}. Try: Verify bead exists and is not already closed with 'bd show ${args.bead_id}', check if bead ID is correct with 'beads_query()', or use beads_close tool directly.`);
       }
-    }
-    let parsedEvaluation;
-    if (args.evaluation) {
       try {
-        parsedEvaluation = EvaluationSchema.parse(JSON.parse(args.evaluation));
+        const epicId3 = args.bead_id.includes(".") ? args.bead_id.split(".")[0] : args.bead_id;
+        const durationMs2 = args.start_time ? Date.now() - args.start_time : 0;
+        const event = createEvent("subtask_outcome", {
+          project_key: args.project_key,
+          epic_id: epicId3,
+          bead_id: args.bead_id,
+          planned_files: args.planned_files || [],
+          actual_files: args.files_touched || [],
+          duration_ms: durationMs2,
+          error_count: args.error_count || 0,
+          retry_count: args.retry_count || 0,
+          success: true
+        });
+        await appendEvent(event, args.project_key);
       } catch (error45) {
-        return JSON.stringify({
-          success: false,
-          error: "Invalid evaluation format",
-          details: error45 instanceof exports_external.ZodError ? error45.issues : String(error45)
-        }, null, 2);
+        console.warn("[swarm_complete] Failed to emit SubtaskOutcomeEvent:", error45);
       }
-      if (!parsedEvaluation.passed) {
-        return JSON.stringify({
-          success: false,
-          error: "Self-evaluation failed",
-          retry_suggestion: parsedEvaluation.retry_suggestion,
-          feedback: parsedEvaluation.overall_feedback
-        }, null, 2);
+      let capturedStrategy;
+      const durationMs = args.start_time ? Date.now() - args.start_time : 0;
+      const memoryInfo = formatMemoryStoreOnSuccess(args.bead_id, args.summary, args.files_touched || [], capturedStrategy);
+      let memoryStored = false;
+      let memoryError;
+      try {
+        const memoryAvailable = await isToolAvailable("semantic-memory");
+        if (memoryAvailable) {
+          const storeResult = await Bun.$`semantic-memory store ${memoryInfo.information} --metadata ${memoryInfo.metadata}`.quiet().nothrow();
+          if (storeResult.exitCode === 0) {
+            memoryStored = true;
+            console.log(`[swarm_complete] Stored learning for ${args.bead_id} in semantic-memory`);
+          } else {
+            memoryError = `semantic-memory store failed: ${storeResult.stderr.toString().slice(0, 200)}`;
+            console.warn(`[swarm_complete] ${memoryError}`);
+          }
+        } else {
+          memoryError = "semantic-memory not available - learning stored in-memory only";
+          warnMissingTool("semantic-memory");
+        }
+      } catch (error45) {
+        memoryError = `Failed to store memory: ${error45 instanceof Error ? error45.message : String(error45)}`;
+        console.warn(`[swarm_complete] ${memoryError}`);
+      }
+      try {
+        await releaseSwarmFiles({
+          projectPath: args.project_key,
+          agentName: args.agent_name
+        });
+      } catch (error45) {
+        console.warn(`[swarm] Failed to release file reservations for ${args.agent_name}:`, error45);
       }
-    }
-    const closeResult = await Bun.$`bd close ${args.bead_id} --reason ${args.summary} --json`.quiet().nothrow();
-    if (closeResult.exitCode !== 0) {
-      throw new Error(`Failed to close bead because bd close command failed: ${closeResult.stderr.toString()}. Try: Verify bead exists and is not already closed with 'bd show ${args.bead_id}', check if bead ID is correct with 'beads_query()', or use beads_close tool directly.`);
-    }
-    try {
       const epicId2 = 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: epicId2,
-        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 (error45) {
-      console.warn("[swarm_complete] Failed to emit SubtaskOutcomeEvent:", error45);
-    }
-    try {
-      await releaseSwarmFiles({
+      const completionBody = [
+        `## Subtask Complete: ${args.bead_id}`,
+        "",
+        `**Summary**: ${args.summary}`,
+        "",
+        parsedEvaluation ? `**Self-Evaluation**: ${parsedEvaluation.passed ? "PASSED" : "FAILED"}` : "",
+        parsedEvaluation?.overall_feedback ? `**Feedback**: ${parsedEvaluation.overall_feedback}` : "",
+        "",
+        `**Memory Capture**: ${memoryStored ? "✓ Stored in semantic-memory" : `✗ ${memoryError || "Failed"}`}`
+      ].filter(Boolean).join(`
+`);
+      await sendSwarmMessage({
         projectPath: args.project_key,
-        agentName: args.agent_name
+        fromAgent: args.agent_name,
+        toAgents: [],
+        subject: `Complete: ${args.bead_id}`,
+        body: completionBody,
+        threadId: epicId2,
+        importance: "normal"
       });
-    } catch (error45) {
-      console.warn(`[swarm] Failed to release file reservations for ${args.agent_name}:`, error45);
-    }
-    const epicId = args.bead_id.includes(".") ? args.bead_id.split(".")[0] : args.bead_id;
-    const completionBody = [
-      `## Subtask Complete: ${args.bead_id}`,
-      "",
-      `**Summary**: ${args.summary}`,
-      "",
-      parsedEvaluation ? `**Self-Evaluation**: ${parsedEvaluation.passed ? "PASSED" : "FAILED"}` : "",
-      parsedEvaluation?.overall_feedback ? `**Feedback**: ${parsedEvaluation.overall_feedback}` : ""
-    ].filter(Boolean).join(`
-`);
-    await sendSwarmMessage({
-      projectPath: args.project_key,
-      fromAgent: args.agent_name,
-      toAgents: [],
-      subject: `Complete: ${args.bead_id}`,
-      body: completionBody,
-      threadId: epicId,
-      importance: "normal"
-    });
-    const response = {
-      success: true,
-      bead_id: args.bead_id,
-      closed: true,
-      reservations_released: true,
-      message_sent: true,
-      agent_registration: {
-        verified: agentRegistered,
-        warning: registrationWarning || undefined
-      },
-      verification_gate: verificationResult ? {
-        passed: true,
-        summary: verificationResult.summary,
-        steps: verificationResult.steps.map((s) => ({
-          name: s.name,
-          passed: s.passed,
-          skipped: s.skipped,
-          skipReason: s.skipReason
-        }))
-      } : args.skip_verification ? { skipped: true, reason: "skip_verification=true" } : { skipped: true, reason: "no files_touched provided" },
-      ubs_scan: ubsResult ? {
-        ran: true,
-        bugs_found: ubsResult.summary.total,
-        summary: ubsResult.summary,
-        warnings: ubsResult.bugs.filter((b) => b.severity !== "critical")
-      } : verificationResult ? { ran: true, included_in_verification_gate: true } : {
-        ran: false,
-        reason: args.skip_ubs_scan ? "skipped" : "no files or ubs unavailable"
-      },
-      learning_prompt: `## Reflection
+      const response = {
+        success: true,
+        bead_id: args.bead_id,
+        closed: true,
+        reservations_released: true,
+        message_sent: true,
+        agent_registration: {
+          verified: agentRegistered,
+          warning: registrationWarning || undefined
+        },
+        verification_gate: verificationResult ? {
+          passed: true,
+          summary: verificationResult.summary,
+          steps: verificationResult.steps.map((s) => ({
+            name: s.name,
+            passed: s.passed,
+            skipped: s.skipped,
+            skipReason: s.skipReason
+          }))
+        } : args.skip_verification ? { skipped: true, reason: "skip_verification=true" } : { skipped: true, reason: "no files_touched provided" },
+        ubs_scan: ubsResult ? {
+          ran: true,
+          bugs_found: ubsResult.summary.total,
+          summary: ubsResult.summary,
+          warnings: ubsResult.bugs.filter((b) => b.severity !== "critical")
+        } : verificationResult ? { ran: true, included_in_verification_gate: true } : {
+          ran: false,
+          reason: args.skip_ubs_scan ? "skipped" : "no files or ubs unavailable"
+        },
+        learning_prompt: `## Reflection
 
 Did you learn anything reusable during this subtask? Consider:
 
@@ -35534,9 +35562,81 @@ Did you learn anything reusable during this subtask? Consider:
 If you discovered something valuable, use \`swarm_learn\` or \`skills_create\` to preserve it as a skill for future swarms.
 
 Files touched: ${args.files_touched?.join(", ") || "none recorded"}`,
-      memory_store: formatMemoryStoreOnSuccess(args.bead_id, args.summary, args.files_touched || [])
-    };
-    return JSON.stringify(response, null, 2);
+        memory_capture: {
+          attempted: true,
+          stored: memoryStored,
+          error: memoryError,
+          information: memoryInfo.information,
+          metadata: memoryInfo.metadata,
+          note: memoryStored ? "Learning automatically stored in semantic-memory" : `Failed to store: ${memoryError}. Learning lost unless semantic-memory is available.`
+        }
+      };
+      return JSON.stringify(response, null, 2);
+    } catch (error45) {
+      const errorMessage = error45 instanceof Error ? error45.message : String(error45);
+      const errorStack = error45 instanceof Error ? error45.stack : undefined;
+      let failedStep = "unknown";
+      if (errorMessage.includes("verification")) {
+        failedStep = "Verification Gate (UBS/typecheck/tests)";
+      } else if (errorMessage.includes("UBS") || errorMessage.includes("ubs")) {
+        failedStep = "UBS scan";
+      } else if (errorMessage.includes("evaluation")) {
+        failedStep = "Self-evaluation parsing";
+      } else if (errorMessage.includes("bead") || errorMessage.includes("close")) {
+        failedStep = "Bead close";
+      } else if (errorMessage.includes("memory") || errorMessage.includes("semantic")) {
+        failedStep = "Memory storage (non-fatal)";
+      } else if (errorMessage.includes("reservation") || errorMessage.includes("release")) {
+        failedStep = "File reservation release";
+      } else if (errorMessage.includes("message") || errorMessage.includes("mail")) {
+        failedStep = "Swarm mail notification";
+      }
+      const errorBody = [
+        `## ⚠️ SWARM_COMPLETE FAILED`,
+        "",
+        `**Bead**: ${args.bead_id}`,
+        `**Agent**: ${args.agent_name}`,
+        `**Failed Step**: ${failedStep}`,
+        "",
+        `### Error Message`,
+        "```",
+        errorMessage,
+        "```",
+        "",
+        errorStack ? `### Stack Trace
+\`\`\`
+${errorStack.slice(0, 1000)}
+\`\`\`
+` : "",
+        `### Context`,
+        `- **Summary**: ${args.summary}`,
+        `- **Files touched**: ${args.files_touched?.length ? args.files_touched.join(", ") : "none"}`,
+        `- **Skip UBS**: ${args.skip_ubs_scan ?? false}`,
+        `- **Skip verification**: ${args.skip_verification ?? false}`,
+        "",
+        `### Recovery Actions`,
+        "1. Check error message for specific issue",
+        "2. Review failed step (UBS scan, typecheck, bead close, etc.)",
+        "3. Fix underlying issue or use skip flags if appropriate",
+        "4. Retry swarm_complete after fixing"
+      ].filter(Boolean).join(`
+`);
+      try {
+        await sendSwarmMessage({
+          projectPath: args.project_key,
+          fromAgent: args.agent_name,
+          toAgents: [],
+          subject: `FAILED: swarm_complete for ${args.bead_id}`,
+          body: errorBody,
+          threadId: epicId,
+          importance: "urgent"
+        });
+      } catch (mailError) {
+        console.error(`[swarm_complete] CRITICAL: Failed to notify coordinator of failure for ${args.bead_id}:`, mailError);
+        console.error(`[swarm_complete] Original error:`, error45);
+      }
+      throw error45;
+    }
   }
 });
 var swarm_record_outcome = tool({
@@ -37347,6 +37447,34 @@ class InMemoryMaturityStorage {
   }
 }
 
+// src/storage.ts
+function getCollectionNames() {
+  const base = {
+    feedback: "swarm-feedback",
+    patterns: "swarm-patterns",
+    maturity: "swarm-maturity"
+  };
+  if (process.env.TEST_MEMORY_COLLECTIONS === "true") {
+    return {
+      feedback: `${base.feedback}-test`,
+      patterns: `${base.patterns}-test`,
+      maturity: `${base.maturity}-test`
+    };
+  }
+  return base;
+}
+var DEFAULT_STORAGE_CONFIG = {
+  backend: "semantic-memory",
+  collections: getCollectionNames(),
+  useSemanticSearch: true
+};
+var sessionStats = {
+  storesCount: 0,
+  queriesCount: 0,
+  sessionStart: Date.now(),
+  lastAlertCheck: Date.now()
+};
+
 // src/index.ts
 init_skills();
 var SwarmPlugin = async (input) => {

package/docs/semantic-memory-cli-syntax.md

@@ -0,0 +1,123 @@
+# Semantic Memory CLI Syntax Reference
+
+**CRITICAL: The semantic-memory CLI has specific JSON requirements that will fail silently if violated.**
+
+## Working Syntax
+
+### Store Memory (via Bash)
+
+```bash
+semantic-memory store \
+  --information "Your learning here with full context" \
+  --metadata '{"tags": ["tag1", "tag2", "tag3"]}'
+```
+
+**Key Rules:**
+
+- `--metadata` MUST be valid JSON with single quotes wrapping the object
+- Use `{"tags": [...]}` structure, NOT comma-separated strings
+- Information can be plain text (no quotes needed in bash)
+
+### Store Memory (via MCP tool - PREFERRED)
+
+The MCP tool `semantic-memory_store` has different syntax:
+
+```typescript
+semantic-memory_store(
+  information: "Your learning here",
+  metadata: "tag1, tag2, tag3"  // Comma-separated string, NOT JSON
+)
+```
+
+**Use the MCP tool when available - it handles JSON serialization for you.**
+
+## Common Mistakes
+
+### ❌ WRONG - Comma-separated string in CLI
+
+```bash
+semantic-memory store \
+  --metadata "swarm,edge-case,workaround"
+# Error: Invalid JSON in --metadata
+```
+
+### ❌ WRONG - Double quotes wrapping JSON
+
+```bash
+semantic-memory store \
+  --metadata "{"tags": ["swarm"]}"
+# Error: Shell parsing breaks on nested quotes
+```
+
+### ❌ WRONG - No tags wrapper
+
+```bash
+semantic-memory store \
+  --metadata '["swarm", "edge-case"]'
+# Error: Expected object with "tags" key
+```
+
+### ✅ CORRECT - JSON object with single quotes
+
+```bash
+semantic-memory store \
+  --information "swarm_complete fails when files outside project_key" \
+  --metadata '{"tags": ["swarm", "edge-case", "workaround"]}'
+```
+
+## When to Use Which
+
+| Context                     | Tool                               | Metadata Format                       |
+| --------------------------- | ---------------------------------- | ------------------------------------- |
+| **Inside OpenCode session** | `semantic-memory_store()` MCP tool | `"tag1, tag2, tag3"` (string)         |
+| **Direct CLI / Bash tool**  | `semantic-memory store` command    | `'{"tags": ["tag1", "tag2"]}'` (JSON) |
+| **Scripts / automation**    | CLI command                        | JSON object                           |
+
+## Other Commands
+
+### Find Memories
+
+```bash
+# CLI
+semantic-memory find --query "search terms" --limit 5
+
+# MCP tool (preferred)
+semantic-memory_find(query="search terms", limit=5)
+```
+
+### Validate Memory (reset decay)
+
+```bash
+# CLI
+semantic-memory validate --id "mem-uuid"
+
+# MCP tool (preferred)
+semantic-memory_validate(id="mem-uuid")
+```
+
+### List All
+
+```bash
+# CLI
+semantic-memory list
+
+# MCP tool (preferred)
+semantic-memory_list()
+```
+
+## Pro Tips
+
+1. **Prefer MCP tools in OpenCode sessions** - they handle serialization
+2. **Use CLI for scripts** - more control, but requires JSON knowledge
+3. **Test metadata syntax** - run `semantic-memory list` to verify storage
+4. **Keep tags focused** - 3-5 tags max, use domain/tech/pattern structure
+5. **Include error messages verbatim** - makes search more effective
+
+## Debugging
+
+If storage fails:
+
+1. Check `--metadata` is valid JSON: `echo '{"tags": ["test"]}' | jq`
+2. Verify single quotes wrap the JSON object
+3. Ensure no shell escaping issues with information text
+4. Try MCP tool instead of CLI if in OpenCode session