opencode-swarm-plugin 0.30.6 → 0.31.0

package/src/hive.ts

@@ -19,9 +19,11 @@ import {
   createHiveAdapter,
   FlushManager,
   importFromJSONL,
+  syncMemories,
   type HiveAdapter,
   type Cell as AdapterCell,
   getSwarmMail,
+  resolvePartialId,
 } from "swarm-mail";
 import { existsSync, readFileSync } from "node:fs";
 import { join } from "node:path";
@@ -422,6 +424,78 @@ export async function importJsonlToPGLite(projectPath: string): Promise<{
  */
 const adapterCache = new Map<string, HiveAdapter>();
 
+// ============================================================================
+// Process Exit Hook - Safety Net for Dirty Cells
+// ============================================================================
+
+/**
+ * Track if exit hook is already registered (prevent duplicate registrations)
+ */
+let exitHookRegistered = false;
+
+/**
+ * Track if exit hook is currently running (prevent re-entry)
+ */
+let exitHookRunning = false;
+
+/**
+ * Register process.on('beforeExit') handler to flush dirty cells
+ * This is a safety net - catches any dirty cells that weren't explicitly synced
+ * 
+ * Idempotent - safe to call multiple times (only registers once)
+ */
+function registerExitHook(): void {
+  if (exitHookRegistered) {
+    return; // Already registered
+  }
+  
+  exitHookRegistered = true;
+  
+  process.on('beforeExit', async (code) => {
+    // Prevent re-entry if already flushing
+    if (exitHookRunning) {
+      return;
+    }
+    
+    exitHookRunning = true;
+    
+    try {
+      // Flush all projects that have adapters (and potentially dirty cells)
+      const flushPromises: Promise<void>[] = [];
+      
+      for (const [projectKey, adapter] of adapterCache.entries()) {
+        const flushPromise = (async () => {
+          try {
+            ensureHiveDirectory(projectKey);
+            const flushManager = new FlushManager({
+              adapter,
+              projectKey,
+              outputPath: `${projectKey}/.hive/issues.jsonl`,
+            });
+            await flushManager.flush();
+          } catch (error) {
+            // Non-fatal - log and continue
+            console.warn(
+              `[hive exit hook] Failed to flush ${projectKey}:`,
+              error instanceof Error ? error.message : String(error)
+            );
+          }
+        })();
+        
+        flushPromises.push(flushPromise);
+      }
+      
+      // Wait for all flushes to complete
+      await Promise.all(flushPromises);
+    } finally {
+      exitHookRunning = false;
+    }
+  });
+}
+
+// Register exit hook immediately when module is imported
+registerExitHook();
+
 /**
  * Get or create a HiveAdapter instance for a project
  * Exported for testing - allows tests to verify state directly
@@ -693,6 +767,23 @@ export const hive_create_epic = tool({
         }
       }
 
+      // Sync cells to JSONL so spawned workers can see them immediately
+      try {
+        ensureHiveDirectory(projectKey);
+        const flushManager = new FlushManager({
+          adapter,
+          projectKey,
+          outputPath: `${projectKey}/.hive/issues.jsonl`,
+        });
+        await flushManager.flush();
+      } catch (error) {
+        // Non-fatal - log and continue
+        console.warn(
+          "[hive_create_epic] Failed to sync to JSONL:",
+          error,
+        );
+      }
+
       return JSON.stringify(result, null, 2);
     } catch (error) {
       // Partial failure - rollback via deleteCell
@@ -789,7 +880,7 @@ export const hive_query = tool({
 export const hive_update = tool({
   description: "Update cell status/description",
   args: {
-    id: tool.schema.string().describe("Cell ID"),
+    id: tool.schema.string().describe("Cell ID or partial hash"),
     status: tool.schema
       .enum(["open", "in_progress", "blocked", "closed"])
       .optional()
@@ -808,26 +899,29 @@ export const hive_update = tool({
     const adapter = await getHiveAdapter(projectKey);
 
     try {
+      // Resolve partial ID to full ID
+      const cellId = await resolvePartialId(adapter, projectKey, validated.id) || validated.id;
+      
       let cell: AdapterCell;
 
       // Status changes use changeCellStatus, other fields use updateCell
       if (validated.status) {
         cell = await adapter.changeCellStatus(
           projectKey,
-          validated.id,
+          cellId,
           validated.status,
         );
       }
 
       // Update other fields if provided
       if (validated.description !== undefined || validated.priority !== undefined) {
-        cell = await adapter.updateCell(projectKey, validated.id, {
+        cell = await adapter.updateCell(projectKey, cellId, {
           description: validated.description,
           priority: validated.priority,
         });
       } else if (!validated.status) {
         // No changes requested
-        const existingCell = await adapter.getCell(projectKey, validated.id);
+        const existingCell = await adapter.getCell(projectKey, cellId);
         if (!existingCell) {
           throw new HiveError(
             `Cell not found: ${validated.id}`,
@@ -837,12 +931,27 @@ export const hive_update = tool({
         cell = existingCell;
       }
 
-      await adapter.markDirty(projectKey, validated.id);
+      await adapter.markDirty(projectKey, cellId);
 
       const formatted = formatCellForOutput(cell!);
       return JSON.stringify(formatted, null, 2);
     } catch (error) {
       const message = error instanceof Error ? error.message : String(error);
+      
+      // Provide helpful error messages
+      if (message.includes("Ambiguous hash")) {
+        throw new HiveError(
+          `Ambiguous ID '${validated.id}': multiple cells match. Please provide more characters.`,
+          "hive_update",
+        );
+      }
+      if (message.includes("Bead not found") || message.includes("Cell not found")) {
+        throw new HiveError(
+          `No cell found matching ID '${validated.id}'`,
+          "hive_update",
+        );
+      }
+      
       throw new HiveError(
         `Failed to update cell: ${message}`,
         "hive_update",
@@ -857,7 +966,7 @@ export const hive_update = tool({
 export const hive_close = tool({
   description: "Close a cell with reason",
   args: {
-    id: tool.schema.string().describe("Cell ID"),
+    id: tool.schema.string().describe("Cell ID or partial hash"),
     reason: tool.schema.string().describe("Completion reason"),
   },
   async execute(args, ctx) {
@@ -866,17 +975,35 @@ export const hive_close = tool({
     const adapter = await getHiveAdapter(projectKey);
 
     try {
+      // Resolve partial ID to full ID
+      const cellId = await resolvePartialId(adapter, projectKey, validated.id) || validated.id;
+      
       const cell = await adapter.closeCell(
         projectKey,
-        validated.id,
+        cellId,
         validated.reason,
       );
 
-      await adapter.markDirty(projectKey, validated.id);
+      await adapter.markDirty(projectKey, cellId);
 
       return `Closed ${cell.id}: ${validated.reason}`;
     } catch (error) {
       const message = error instanceof Error ? error.message : String(error);
+      
+      // Provide helpful error messages
+      if (message.includes("Ambiguous hash")) {
+        throw new HiveError(
+          `Ambiguous ID '${validated.id}': multiple cells match. Please provide more characters.`,
+          "hive_close",
+        );
+      }
+      if (message.includes("Bead not found") || message.includes("Cell not found")) {
+        throw new HiveError(
+          `No cell found matching ID '${validated.id}'`,
+          "hive_close",
+        );
+      }
+      
       throw new HiveError(
         `Failed to close cell: ${message}`,
         "hive_close",
@@ -892,24 +1019,42 @@ export const hive_start = tool({
   description:
     "Mark a cell as in-progress (shortcut for update --status in_progress)",
   args: {
-    id: tool.schema.string().describe("Cell ID"),
+    id: tool.schema.string().describe("Cell ID or partial hash"),
   },
   async execute(args, ctx) {
     const projectKey = getHiveWorkingDirectory();
     const adapter = await getHiveAdapter(projectKey);
 
     try {
+      // Resolve partial ID to full ID
+      const cellId = await resolvePartialId(adapter, projectKey, args.id) || args.id;
+      
       const cell = await adapter.changeCellStatus(
         projectKey,
-        args.id,
+        cellId,
         "in_progress",
       );
 
-      await adapter.markDirty(projectKey, args.id);
+      await adapter.markDirty(projectKey, cellId);
 
       return `Started: ${cell.id}`;
     } catch (error) {
       const message = error instanceof Error ? error.message : String(error);
+      
+      // Provide helpful error messages
+      if (message.includes("Ambiguous hash")) {
+        throw new HiveError(
+          `Ambiguous ID '${args.id}': multiple cells match. Please provide more characters.`,
+          "hive_start",
+        );
+      }
+      if (message.includes("Bead not found") || message.includes("Cell not found")) {
+        throw new HiveError(
+          `No cell found matching ID '${args.id}'`,
+          "hive_start",
+        );
+      }
+      
       throw new HiveError(
         `Failed to start cell: ${message}`,
         "hive_start",
@@ -1012,8 +1157,21 @@ export const hive_sync = tool({
       "flush hive",
     );
 
-    if (flushResult.cellsExported === 0) {
-      return "No cells to sync";
+    // 2b. Sync memories to JSONL
+    const swarmMail = await getSwarmMail(projectKey);
+    const db = await swarmMail.getDatabase();
+    const hivePath = join(projectKey, ".hive");
+    let memoriesSynced = 0;
+    try {
+      const memoryResult = await syncMemories(db, hivePath);
+      memoriesSynced = memoryResult.exported;
+    } catch (err) {
+      // Memory sync is optional - don't fail if it errors
+      console.warn("[hive_sync] Memory sync warning:", err);
+    }
+
+    if (flushResult.cellsExported === 0 && memoriesSynced === 0) {
+      return "No cells or memories to sync";
     }
 
     // 3. Check if there are changes to commit

package/src/memory-tools.ts

@@ -104,7 +104,7 @@ export { createMemoryAdapter };
  */
 export const semantic_memory_store = tool({
 	description:
-		"Store a memory with semantic embedding. Memories are searchable by semantic similarity and can be organized into collections.",
+		"Store a memory with semantic embedding. Memories are searchable by semantic similarity and can be organized into collections. Confidence affects decay rate: high confidence (1.0) = 135 day half-life, low confidence (0.0) = 45 day half-life.",
 	args: {
 		information: tool.schema
 			.string()
@@ -121,6 +121,10 @@ export const semantic_memory_store = tool({
 			.string()
 			.optional()
 			.describe("JSON string with additional metadata"),
+		confidence: tool.schema
+			.number()
+			.optional()
+			.describe("Confidence level (0.0-1.0) affecting decay rate. Higher = slower decay. Default 0.7"),
 	},
 	async execute(args, ctx: ToolContext) {
 		const adapter = await getMemoryAdapter();

package/src/memory.ts

@@ -68,6 +68,8 @@ export interface StoreArgs {
 	readonly collection?: string;
 	readonly tags?: string;
 	readonly metadata?: string;
+	/** Confidence level (0.0-1.0) affecting decay rate. Higher = slower decay. Default 0.7 */
+	readonly confidence?: number;
 }
 
 /** Arguments for find operation */
@@ -288,12 +290,19 @@ export async function createMemoryAdapter(
 				metadata.tags = tags;
 			}
 
+			// Clamp confidence to valid range [0.0, 1.0]
+			const clampConfidence = (c: number | undefined): number => {
+				if (c === undefined) return 0.7;
+				return Math.max(0.0, Math.min(1.0, c));
+			};
+
 			const memory: Memory = {
 				id,
 				content: args.information,
 				metadata,
 				collection,
 				createdAt: new Date(),
+				confidence: clampConfidence(args.confidence),
 			};
 
 			// Generate embedding

package/src/swarm-decompose.ts

@@ -52,7 +52,7 @@ Agents MUST update their bead status as they work. No silent progress.
 
 ## Requirements
 
-1. **Break into 2-{max_subtasks} independent subtasks** that can run in parallel
+1. **Break into independent subtasks** that can run in parallel (as many as needed)
 2. **Assign files** - each subtask must specify which files it will modify
 3. **No file overlap** - files cannot appear in multiple subtasks (they get exclusive locks)
 4. **Order by dependency** - if subtask B needs subtask A's output, A must come first in the array
@@ -129,7 +129,7 @@ Agents MUST update their bead status as they work. No silent progress.
 
 ## Requirements
 
-1. **Break into 2-{max_subtasks} independent subtasks** that can run in parallel
+1. **Break into independent subtasks** that can run in parallel (as many as needed)
 2. **Assign files** - each subtask must specify which files it will modify
 3. **No file overlap** - files cannot appear in multiple subtasks (they get exclusive locks)
 4. **Order by dependency** - if subtask B needs subtask A's output, A must come first in the array
@@ -437,10 +437,9 @@ export const swarm_decompose = tool({
     max_subtasks: tool.schema
       .number()
       .int()
-      .min(2)
-      .max(10)
-      .default(5)
-      .describe("Maximum number of subtasks (default: 5)"),
+      .min(1)
+      .optional()
+      .describe("Suggested max subtasks (optional - LLM decides if not specified)"),
     context: tool.schema
       .string()
       .optional()
@@ -453,7 +452,6 @@ export const swarm_decompose = tool({
       .number()
       .int()
       .min(1)
-      .max(10)
       .optional()
       .describe("Max CASS results to include (default: 3)"),
   },
@@ -702,11 +700,9 @@ export const swarm_delegate_planning = tool({
     max_subtasks: tool.schema
       .number()
       .int()
-      .min(2)
-      .max(10)
+      .min(1)
       .optional()
-      .default(5)
-      .describe("Maximum number of subtasks (default: 5)"),
+      .describe("Suggested max subtasks (optional - LLM decides if not specified)"),
     strategy: tool.schema
       .enum(["auto", "file-based", "feature-based", "risk-based"])
       .optional()

package/src/swarm-orchestrate.ts

@@ -72,7 +72,7 @@ import {
   isToolAvailable,
   warnMissingTool,
 } from "./tool-availability";
-import { getHiveAdapter } from "./hive";
+import { getHiveAdapter, hive_sync, setHiveWorkingDirectory, getHiveWorkingDirectory } from "./hive";
 import { listSkills } from "./skills";
 import {
   canUseWorktreeIsolation,
@@ -1570,6 +1570,30 @@ This will be recorded as a negative learning signal.`;
         );
       }
 
+      // Sync cell to .hive/issues.jsonl (auto-sync on complete)
+      // This ensures the worker's completed work persists before process exits
+      let syncSuccess = false;
+      let syncError: string | undefined;
+      try {
+        // Save current working directory and set to project path
+        const previousWorkingDir = getHiveWorkingDirectory();
+        setHiveWorkingDirectory(args.project_key);
+        
+        try {
+          const syncResult = await hive_sync.execute({ auto_pull: false }, _ctx);
+          syncSuccess = !syncResult.includes("error");
+        } finally {
+          // Restore previous working directory
+          setHiveWorkingDirectory(previousWorkingDir);
+        }
+      } catch (error) {
+        // Non-fatal - log warning but don't block completion
+        syncError = error instanceof Error ? error.message : String(error);
+        console.warn(
+          `[swarm_complete] Auto-sync failed (non-fatal): ${syncError}`,
+        );
+      }
+
       // Emit SubtaskOutcomeEvent for learning system
       try {
         const epicId = args.bead_id.includes(".")
@@ -1709,6 +1733,8 @@ This will be recorded as a negative learning signal.`;
         bead_id: args.bead_id,
         closed: true,
         reservations_released: true,
+        synced: syncSuccess,
+        sync_error: syncError,
         message_sent: messageSent,
         message_error: messageError,
         agent_registration: {

package/src/swarm-prompts.test.ts

@@ -113,8 +113,9 @@ describe("SUBTASK_PROMPT_V2", () => {
         new RegExp(`### Step ${lastStepNum}:[\\s\\S]*?(?=## \\[|$)`)
       );
       expect(lastStepMatch).not.toBeNull();
+      if (!lastStepMatch) return;
       
-      const lastStepContent = lastStepMatch![0];
+      const lastStepContent = lastStepMatch[0];
       expect(lastStepContent).toContain("swarm_complete");
       expect(lastStepContent).toMatch(/NOT.*hive_close|DO NOT.*hive_close/i);
     });
@@ -124,16 +125,18 @@ describe("SUBTASK_PROMPT_V2", () => {
     test("lists memory query as non-negotiable", () => {
       const criticalSection = SUBTASK_PROMPT_V2.match(/\[CRITICAL REQUIREMENTS\][\s\S]*?Begin now/);
       expect(criticalSection).not.toBeNull();
+      if (!criticalSection) return;
       
-      expect(criticalSection![0]).toMatch(/semantic-memory_find|memory.*MUST|Step 2.*MUST/i);
+      expect(criticalSection[0]).toMatch(/semantic-memory_find|memory.*MUST|Step 2.*MUST/i);
     });
 
     test("lists consequences of skipping memory steps", () => {
       const criticalSection = SUBTASK_PROMPT_V2.match(/\[CRITICAL REQUIREMENTS\][\s\S]*?Begin now/);
       expect(criticalSection).not.toBeNull();
+      if (!criticalSection) return;
       
       // Should mention consequences for skipping memory
-      expect(criticalSection![0]).toMatch(/repeat|waste|already.solved|mistakes/i);
+      expect(criticalSection[0]).toMatch(/repeat|waste|already.solved|mistakes/i);
     });
   });
 });
@@ -141,8 +144,8 @@ describe("SUBTASK_PROMPT_V2", () => {
 describe("formatSubtaskPromptV2", () => {
   test("substitutes all placeholders correctly", () => {
     const result = formatSubtaskPromptV2({
-      bead_id: "test-bead-123",
-      epic_id: "test-epic-456",
+      bead_id: "test-project-abc123-bead456",
+      epic_id: "test-project-abc123-epic789",
       subtask_title: "Test Subtask",
       subtask_description: "Do the test thing",
       files: ["src/test.ts", "src/test.test.ts"],
@@ -150,8 +153,8 @@ describe("formatSubtaskPromptV2", () => {
       project_path: "/path/to/project",
     });
 
-    expect(result).toContain("test-bead-123");
-    expect(result).toContain("test-epic-456");
+    expect(result).toContain("test-project-abc123-bead456");
+    expect(result).toContain("test-project-abc123-epic789");
     expect(result).toContain("Test Subtask");
     expect(result).toContain("Do the test thing");
     expect(result).toContain("src/test.ts");
@@ -160,8 +163,8 @@ describe("formatSubtaskPromptV2", () => {
 
   test("includes memory query step with MANDATORY emphasis", () => {
     const result = formatSubtaskPromptV2({
-      bead_id: "test-bead",
-      epic_id: "test-epic",
+      bead_id: "test-project-abc123-def456",
+      epic_id: "test-project-abc123-ghi789",
       subtask_title: "Test",
       subtask_description: "",
       files: [],

package/src/swarm-prompts.ts

@@ -46,7 +46,7 @@ Agents MUST update their cell status as they work. No silent progress.
 
 ## Requirements
 
-1. **Break into 2-{max_subtasks} independent subtasks** that can run in parallel
+1. **Break into independent subtasks** that can run in parallel (as many as needed)
 2. **Assign files** - each subtask must specify which files it will modify
 3. **No file overlap** - files cannot appear in multiple subtasks (they get exclusive locks)
 4. **Order by dependency** - if subtask B needs subtask A's output, A must come first in the array
@@ -123,7 +123,7 @@ Agents MUST update their cell status as they work. No silent progress.
 
 ## Requirements
 
-1. **Break into 2-{max_subtasks} independent subtasks** that can run in parallel
+1. **Break into independent subtasks** that can run in parallel (as many as needed)
 2. **Assign files** - each subtask must specify which files it will modify
 3. **No file overlap** - files cannot appear in multiple subtasks (they get exclusive locks)
 4. **Order by dependency** - if subtask B needs subtask A's output, A must come first in the array
@@ -406,21 +406,44 @@ swarm_checkpoint(
 
 **Checkpoints preserve context so you can recover if things go wrong.**
 
-### Step 8: Store Learnings (if you discovered something)
+### Step 8: 💾 STORE YOUR LEARNINGS (if you discovered something)
+
+**If you learned it the hard way, STORE IT so the next agent doesn't have to.**
+
 \`\`\`
 semantic-memory_store(
   information="<what you learned, WHY it matters, how to apply it>",
-  metadata="<tags: domain, tech-stack, pattern-type>"
+  tags="<domain, tech-stack, pattern-type>"
 )
 \`\`\`
 
-**Store:**
-- Tricky bugs you solved (root cause + solution)
-- Project-specific patterns or domain rules
-- Tool/library gotchas and workarounds
-- Failed approaches (anti-patterns to avoid)
+**MANDATORY Storage Triggers - Store when you:**
+- 🐛 **Solved a tricky bug** (>15min debugging) - include root cause + solution
+- 💡 **Discovered a project-specific pattern** - domain rules, business logic quirks
+- ⚠️ **Found a tool/library gotcha** - API quirks, version-specific bugs, workarounds
+- 🚫 **Tried an approach that failed** - anti-patterns to avoid, why it didn't work
+- 🏗️ **Made an architectural decision** - reasoning, alternatives considered, tradeoffs
 
-**Don't store generic knowledge.** Store the WHY, not just the WHAT.
+**What Makes a GOOD Memory:**
+
+✅ **GOOD** (actionable, explains WHY):
+\`\`\`
+"OAuth refresh tokens need 5min buffer before expiry to avoid race conditions.
+Without buffer, token refresh can fail mid-request if expiry happens between
+check and use. Implemented with: if (expiresAt - Date.now() < 300000) refresh()"
+\`\`\`
+
+❌ **BAD** (generic, no context):
+\`\`\`
+"Fixed the auth bug by adding a null check"
+\`\`\`
+
+**What NOT to Store:**
+- Generic knowledge that's in official documentation
+- Implementation details that change frequently
+- Vague descriptions without context ("fixed the thing")
+
+**The WHY matters more than the WHAT.** Future agents need context to apply your learning.
 
 ### Step 9: Complete (REQUIRED - releases reservations)
 \`\`\`
@@ -511,17 +534,20 @@ Other cell operations:
 
 **NON-NEGOTIABLE:**
 1. Step 1 (swarmmail_init) MUST be first - do it before anything else
-2. Step 2 (semantic-memory_find) MUST happen before starting work
+2. 🧠 Step 2 (semantic-memory_find) MUST happen BEFORE starting work - query first, code second
 3. Step 4 (swarmmail_reserve) - YOU reserve files, not coordinator
 4. Step 6 (swarm_progress) - Report at milestones, don't work silently
-5. Step 9 (swarm_complete) - Use this to close, NOT hive_close
+5. 💾 Step 8 (semantic-memory_store) - If you learned something hard, STORE IT
+6. Step 9 (swarm_complete) - Use this to close, NOT hive_close
 
 **If you skip these steps:**
 - Your work won't be tracked (swarm_complete will fail)
-- You'll waste time repeating solved problems (no semantic memory query)
+- 🔄 You'll waste time repeating already-solved problems (no semantic memory query)
 - Edit conflicts with other agents (no file reservation)
 - Lost work if you crash (no checkpoints)
-- Future agents repeat your mistakes (no learnings stored)
+- 🔄 Future agents repeat YOUR mistakes (no learnings stored)
+
+**Memory is the swarm's collective intelligence. Query it. Feed it.**
 
 Begin now.`;
 
@@ -901,10 +927,9 @@ export const swarm_plan_prompt = tool({
     max_subtasks: tool.schema
       .number()
       .int()
-      .min(2)
-      .max(10)
-      .default(5)
-      .describe("Maximum number of subtasks (default: 5)"),
+      .min(1)
+      .optional()
+      .describe("Suggested max subtasks (optional - LLM decides if not specified)"),
     context: tool.schema
       .string()
       .optional()
@@ -917,7 +942,6 @@ export const swarm_plan_prompt = tool({
       .number()
       .int()
       .min(1)
-      .max(10)
       .optional()
       .describe("Max CASS results to include (default: 3)"),
     include_skills: tool.schema