opencode-swarm-plugin 0.39.1 → 0.42.0

package/src/hive.ts

@@ -741,30 +741,65 @@ export const hive_create_epic = tool({
       };
 
       // Emit DecompositionGeneratedEvent for learning system
-      if (args.project_key) {
-        try {
-          const event = createEvent("decomposition_generated", {
-            project_key: args.project_key,
+      // Always emit using projectKey (from getHiveWorkingDirectory), not args.project_key
+      // This fixes the bug where events weren't emitted when callers didn't pass project_key
+      const effectiveProjectKey = args.project_key || projectKey;
+      try {
+        const event = createEvent("decomposition_generated", {
+          project_key: effectiveProjectKey,
+          epic_id: epic.id,
+          task: args.task || validated.epic_title,
+          context: validated.epic_description,
+          strategy: args.strategy || "feature-based",
+          epic_title: validated.epic_title,
+          subtasks: validated.subtasks.map((st) => ({
+            title: st.title,
+            files: st.files || [],
+            priority: st.priority,
+          })),
+          recovery_context: args.recovery_context,
+        });
+        await appendEvent(event, effectiveProjectKey);
+      } catch (error) {
+        // Non-fatal - log and continue
+        console.warn(
+          "[hive_create_epic] Failed to emit DecompositionGeneratedEvent:",
+          error,
+        );
+      }
+
+      // Capture decomposition_complete event for eval scoring
+      try {
+        const { captureCoordinatorEvent } = await import("./eval-capture.js");
+        
+        // Build files_per_subtask map (indexed by subtask index)
+        const filesPerSubtask: Record<number, string[]> = {};
+        validated.subtasks.forEach((subtask, index) => {
+          if (subtask.files && subtask.files.length > 0) {
+            filesPerSubtask[index] = subtask.files;
+          }
+        });
+
+          captureCoordinatorEvent({
+            session_id: ctx.sessionID || "unknown",
             epic_id: epic.id,
-            task: args.task || validated.epic_title,
-            context: validated.epic_description,
-            strategy: args.strategy || "feature-based",
-            epic_title: validated.epic_title,
-            subtasks: validated.subtasks.map((st) => ({
-              title: st.title,
-              files: st.files || [],
-              priority: st.priority,
-            })),
-            recovery_context: args.recovery_context,
+            timestamp: new Date().toISOString(),
+            event_type: "DECISION",
+            decision_type: "decomposition_complete",
+            payload: {
+              subtask_count: validated.subtasks.length,
+              strategy_used: args.strategy || "feature-based",
+              files_per_subtask: filesPerSubtask,
+              epic_title: validated.epic_title,
+              task: args.task,
+            },
           });
-          await appendEvent(event, args.project_key);
-        } catch (error) {
-          // Non-fatal - log and continue
-          console.warn(
-            "[hive_create_epic] Failed to emit DecompositionGeneratedEvent:",
-            error,
-          );
-        }
+      } catch (error) {
+        // Non-fatal - log and continue
+        console.warn(
+          "[hive_create_epic] Failed to capture decomposition_complete event:",
+          error,
+        );
       }
 
       // Sync cells to JSONL so spawned workers can see them immediately

package/src/index.ts

@@ -49,6 +49,7 @@ import { mandateTools } from "./mandates";
 import { memoryTools } from "./memory-tools";
 import { observabilityTools } from "./observability-tools";
 import { researchTools } from "./swarm-research";
+import { evalTools } from "./eval-runner";
 import {
   guardrailOutput,
   DEFAULT_GUARDRAIL_CONFIG,
@@ -175,6 +176,7 @@ const SwarmPlugin: Plugin = async (
       ...memoryTools,
       ...observabilityTools,
       ...researchTools,
+      ...evalTools,
     },
 
     /**
@@ -729,6 +731,8 @@ export {
  * Includes:
  * - SWARM_COMPACTION_CONTEXT - Prompt text for swarm state preservation
  * - createCompactionHook - Factory function for the compaction hook
+ * - scanSessionMessages - Scan session for swarm state
+ * - ScannedSwarmState - Scanned state interface
  *
  * Usage:
  * ```typescript
@@ -739,7 +743,56 @@ export {
  * };
  * ```
  */
-export { SWARM_COMPACTION_CONTEXT, createCompactionHook } from "./compaction-hook";
+export { 
+  SWARM_COMPACTION_CONTEXT, 
+  createCompactionHook,
+  scanSessionMessages,
+  type ScannedSwarmState,
+} from "./compaction-hook";
+
+/**
+ * Re-export compaction-observability module
+ *
+ * Includes:
+ * - CompactionPhase - Enum of compaction phases
+ * - createMetricsCollector - Create a metrics collector
+ * - recordPhaseStart, recordPhaseComplete - Phase timing
+ * - recordPatternExtracted, recordPatternSkipped - Pattern tracking
+ * - getMetricsSummary - Get metrics summary
+ *
+ * Types:
+ * - CompactionMetrics - Mutable metrics collector
+ * - CompactionMetricsSummary - Read-only summary snapshot
+ *
+ * Features:
+ * - Phase timing breakdown (START, GATHER, DETECT, INJECT, COMPLETE)
+ * - Pattern extraction tracking with reasons
+ * - Success rate calculation
+ * - Debug mode for verbose details
+ * - JSON serializable for persistence
+ *
+ * Usage:
+ * ```typescript
+ * import { createMetricsCollector, CompactionPhase, recordPhaseStart } from "opencode-swarm-plugin";
+ *
+ * const metrics = createMetricsCollector({ session_id: "abc123" });
+ * recordPhaseStart(metrics, CompactionPhase.DETECT);
+ * // ... work ...
+ * recordPhaseComplete(metrics, CompactionPhase.DETECT);
+ * const summary = getMetricsSummary(metrics);
+ * ```
+ */
+export {
+  CompactionPhase,
+  createMetricsCollector,
+  recordPhaseStart,
+  recordPhaseComplete,
+  recordPatternExtracted,
+  recordPatternSkipped,
+  getMetricsSummary,
+  type CompactionMetrics,
+  type CompactionMetricsSummary,
+} from "./compaction-observability";
 
 /**
  * Re-export memory module

package/src/memory-tools.test.ts

@@ -24,6 +24,7 @@ describe("memory tools integration", () => {
 		expect(toolNames).toContain("semantic-memory_list");
 		expect(toolNames).toContain("semantic-memory_stats");
 		expect(toolNames).toContain("semantic-memory_check");
+		expect(toolNames).toContain("semantic-memory_upsert");
 	});
 
 	test("tools have execute functions", () => {
@@ -108,4 +109,87 @@ describe("memory tools integration", () => {
 			expect(typeof parsed.ollama).toBe("boolean");
 		});
 	});
+
+	describe("semantic-memory_upsert", () => {
+		test("returns valid ADD operation result", async () => {
+			const tool = memoryTools["semantic-memory_upsert"];
+			const result = await tool.execute(
+				{
+					information: "Test memory for plugin tool",
+					tags: "test,plugin",
+				},
+				{ sessionID: "test-session" } as any,
+			);
+
+			const parsed = JSON.parse(result);
+			
+			expect(parsed.operation).toBe("ADD");
+			expect(parsed.reason).toBeDefined();
+			expect(parsed.memoryId).toBeDefined();
+			expect(parsed.memoryId).toMatch(/^mem_/);
+		});
+
+		test("includes autoTags when enabled", async () => {
+			const tool = memoryTools["semantic-memory_upsert"];
+			const result = await tool.execute(
+				{
+					information: "TypeScript is a typed superset of JavaScript",
+					autoTag: true,
+				},
+				{ sessionID: "test-session" } as any,
+			);
+
+			const parsed = JSON.parse(result);
+			
+			expect(parsed.autoTags).toBeDefined();
+			expect(parsed.autoTags.tags).toBeInstanceOf(Array);
+			expect(parsed.autoTags.keywords).toBeInstanceOf(Array);
+			expect(parsed.autoTags.category).toBe("general");
+		});
+
+		test("includes linksCreated when autoLink enabled", async () => {
+			const tool = memoryTools["semantic-memory_upsert"];
+			const result = await tool.execute(
+				{
+					information: "React hooks enable functional components to use state",
+					autoLink: true,
+				},
+				{ sessionID: "test-session" } as any,
+			);
+
+			const parsed = JSON.parse(result);
+			
+			expect(parsed.linksCreated).toBeDefined();
+			expect(typeof parsed.linksCreated).toBe("number");
+		});
+
+		test("includes entitiesExtracted when extractEntities enabled", async () => {
+			const tool = memoryTools["semantic-memory_upsert"];
+			const result = await tool.execute(
+				{
+					information: "Next.js 15 was released by Vercel in October 2024",
+					extractEntities: true,
+				},
+				{ sessionID: "test-session" } as any,
+			);
+
+			const parsed = JSON.parse(result);
+			
+			expect(parsed.entitiesExtracted).toBeDefined();
+			expect(typeof parsed.entitiesExtracted).toBe("number");
+		});
+
+		test("throws error when information is missing", async () => {
+			const tool = memoryTools["semantic-memory_upsert"];
+			
+			await expect(async () => {
+				await tool.execute(
+					{
+						tags: "test",
+					} as any,
+					{ sessionID: "test-session" } as any,
+				);
+			}).toThrow("information is required");
+		});
+	});
 });

package/src/memory-tools.ts

@@ -27,6 +27,9 @@ import {
 	type StatsResult,
 	type HealthResult,
 	type OperationResult,
+	type UpsertArgs,
+	type UpsertResult,
+	type AutoTags,
 } from "./memory";
 
 // Re-export types for external use
@@ -41,7 +44,10 @@ export type {
 	StatsResult,
 	HealthResult,
 	OperationResult,
-};
+	UpsertArgs,
+	UpsertResult,
+	AutoTags,
+} from "./memory";
 
 // ============================================================================
 // Types
@@ -65,7 +71,7 @@ let cachedProjectPath: string | null = null;
  * @param projectPath - Project path (uses CWD if not provided)
  * @returns Memory adapter instance
  */
-async function getMemoryAdapter(
+export async function getMemoryAdapter(
 	projectPath?: string,
 ): Promise<MemoryAdapter> {
 	const path = projectPath || process.cwd();
@@ -106,7 +112,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. Confidence affects decay rate: high confidence (1.0) = 135 day half-life, low confidence (0.0) = 45 day half-life.",
+		"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. Supports auto-tagging, auto-linking, and entity extraction via LLM.",
 	args: {
 		information: tool.schema
 			.string()
@@ -127,6 +133,18 @@ export const semantic_memory_store = tool({
 			.number()
 			.optional()
 			.describe("Confidence level (0.0-1.0) affecting decay rate. Higher = slower decay. Default 0.7"),
+		autoTag: tool.schema
+			.boolean()
+			.optional()
+			.describe("Auto-generate tags using LLM. Default false"),
+		autoLink: tool.schema
+			.boolean()
+			.optional()
+			.describe("Auto-link to related memories. Default false"),
+		extractEntities: tool.schema
+			.boolean()
+			.optional()
+			.describe("Extract entities (people, places, technologies). Default false"),
 	},
 	async execute(args, ctx: ToolContext) {
 		const adapter = await getMemoryAdapter();
@@ -258,6 +276,52 @@ export const semantic_memory_check = tool({
 	},
 });
 
+/**
+ * Smart upsert - ADD, UPDATE, DELETE, or NOOP based on existing memories
+ */
+export const semantic_memory_upsert = tool({
+	description:
+		"Smart memory storage that decides whether to ADD, UPDATE, DELETE, or skip (NOOP) based on existing memories. Uses LLM to detect duplicates, refinements, and contradictions. Auto-generates tags, links, and entities when enabled.",
+	args: {
+		information: tool.schema
+			.string()
+			.describe("The information to store (required)"),
+		collection: tool.schema
+			.string()
+			.optional()
+			.describe("Collection name (defaults to 'default')"),
+		tags: tool.schema
+			.string()
+			.optional()
+			.describe("Comma-separated tags (e.g., 'auth,tokens,oauth')"),
+		metadata: tool.schema
+			.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"),
+		autoTag: tool.schema
+			.boolean()
+			.optional()
+			.describe("Auto-generate tags using LLM. Default true"),
+		autoLink: tool.schema
+			.boolean()
+			.optional()
+			.describe("Auto-link to related memories. Default true"),
+		extractEntities: tool.schema
+			.boolean()
+			.optional()
+			.describe("Extract entities (people, places, technologies). Default false"),
+	},
+	async execute(args, ctx: ToolContext) {
+		const adapter = await getMemoryAdapter();
+		const result = await adapter.upsert(args);
+		return JSON.stringify(result, null, 2);
+	},
+});
+
 // ============================================================================
 // Tool Registry
 // ============================================================================
@@ -276,4 +340,5 @@ export const memoryTools = {
 	"semantic-memory_list": semantic_memory_list,
 	"semantic-memory_stats": semantic_memory_stats,
 	"semantic-memory_check": semantic_memory_check,
+	"semantic-memory_upsert": semantic_memory_upsert,
 } as const;

package/src/memory.test.ts

@@ -45,7 +45,7 @@ describe("memory adapter", () => {
 			});
 
 			expect(result.id).toBeDefined();
-			expect(result.id).toMatch(/^mem_/);
+			expect(result.id).toMatch(/^mem-/); // Real swarm-mail adapter uses 'mem-' prefix
 			expect(result.message).toContain("Stored memory");
 		});
 
@@ -55,7 +55,7 @@ describe("memory adapter", () => {
 				collection: "project-alpha",
 			});
 
-			expect(result.id).toMatch(/^mem_/);
+			expect(result.id).toMatch(/^mem-/); // Real swarm-mail adapter uses 'mem-' prefix
 			expect(result.message).toContain("collection: project-alpha");
 		});
 	});

package/src/memory.ts

@@ -39,6 +39,8 @@ import {
 	legacyDatabaseExists,
 	migrateLegacyMemories,
 	toSwarmDb,
+	createMemoryAdapter as createSwarmMailAdapter,
+	type MemoryConfig,
 } from "swarm-mail";
 
 // ============================================================================
@@ -71,6 +73,12 @@ export interface StoreArgs {
 	readonly metadata?: string;
 	/** Confidence level (0.0-1.0) affecting decay rate. Higher = slower decay. Default 0.7 */
 	readonly confidence?: number;
+	/** Auto-generate tags using LLM. Default false */
+	readonly autoTag?: boolean;
+	/** Auto-link to related memories. Default false */
+	readonly autoLink?: boolean;
+	/** Extract entities (people, places, technologies). Default false */
+	readonly extractEntities?: boolean;
 }
 
 /** Arguments for find operation */
@@ -129,6 +137,39 @@ export interface OperationResult {
 	readonly message?: string;
 }
 
+/** Arguments for upsert operation */
+export interface UpsertArgs {
+	readonly information: string;
+	readonly collection?: string;
+	readonly tags?: string;
+	readonly metadata?: string;
+	readonly confidence?: number;
+	/** Auto-generate tags using LLM. Default true */
+	readonly autoTag?: boolean;
+	/** Auto-link to related memories. Default true */
+	readonly autoLink?: boolean;
+	/** Extract entities (people, places, technologies). Default false */
+	readonly extractEntities?: boolean;
+}
+
+/** Auto-generated tags result */
+export interface AutoTags {
+	readonly tags: string[];
+	readonly keywords: string[];
+	readonly category: string;
+}
+
+/** Result from upsert operation */
+export interface UpsertResult {
+	readonly operation: "ADD" | "UPDATE" | "DELETE" | "NOOP";
+	readonly reason: string;
+	readonly memoryId?: string;
+	readonly affectedMemoryIds?: string[];
+	readonly autoTags?: AutoTags;
+	readonly linksCreated?: number;
+	readonly entitiesExtracted?: number;
+}
+
 // ============================================================================
 // Auto-Migration Logic
 // ============================================================================
@@ -206,6 +247,7 @@ export interface MemoryAdapter {
 	readonly list: (args: ListArgs) => Promise<Memory[]>;
 	readonly stats: () => Promise<StatsResult>;
 	readonly checkHealth: () => Promise<HealthResult>;
+	readonly upsert: (args: UpsertArgs) => Promise<UpsertResult>;
 }
 
 /**
@@ -236,10 +278,24 @@ export async function createMemoryAdapter(
 		await maybeAutoMigrate(db);
 	}
 
-	// Convert DatabaseAdapter to SwarmDb (Drizzle client) for createMemoryStore
+	// Convert DatabaseAdapter to SwarmDb (Drizzle client) for real swarm-mail adapter
 	const drizzleDb = toSwarmDb(db);
-	const store = createMemoryStore(drizzleDb);
 	const config = getDefaultConfig();
+	
+	// Create real swarm-mail adapter with Wave 1-3 features
+	const realAdapter = createSwarmMailAdapter(drizzleDb, config);
+	
+	// DEBUG: Check if upsert exists
+	if (!realAdapter || typeof realAdapter.upsert !== 'function') {
+		console.warn('[memory] realAdapter.upsert is not available:', {
+			hasAdapter: !!realAdapter,
+			upsertType: typeof realAdapter?.upsert,
+			methods: realAdapter ? Object.keys(realAdapter) : []
+		});
+	}
+	
+	// For backward compatibility, keep legacy adapter for methods not yet in real adapter
+	const store = createMemoryStore(drizzleDb);
 	const ollamaLayer = makeOllamaLive(config);
 
 	/**
@@ -272,59 +328,39 @@ export async function createMemoryAdapter(
 
 	return {
 		/**
-		 * Store a memory with embedding
+		 * Store a memory with embedding and optional auto-features
+		 * 
+		 * Delegates to real swarm-mail adapter which supports:
+		 * - autoTag: LLM-powered tag generation
+		 * - autoLink: Semantic linking to related memories
+		 * - extractEntities: Entity extraction and knowledge graph building
 		 */
 		async store(args: StoreArgs): Promise<StoreResult> {
-			const id = generateId();
-			const tags = parseTags(args.tags);
-			const collection = args.collection ?? "default";
-
-			// Parse metadata if provided
-			let metadata: Record<string, unknown> = {};
-			if (args.metadata) {
-				try {
-					metadata = JSON.parse(args.metadata);
-				} catch {
-					metadata = { raw: args.metadata };
-				}
-			}
-
-			// Add tags to metadata
-			if (tags.length > 0) {
-				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
-			const program = Effect.gen(function* () {
-				const ollama = yield* Ollama;
-				return yield* ollama.embed(args.information);
+			// Delegate to real swarm-mail adapter
+			const result = await realAdapter.store(args.information, {
+				collection: args.collection,
+				tags: args.tags,
+				metadata: args.metadata,
+				confidence: args.confidence,
+				autoTag: args.autoTag,
+				autoLink: args.autoLink,
+				extractEntities: args.extractEntities,
 			});
 
-			const embedding = await Effect.runPromise(
-				program.pipe(Effect.provide(ollamaLayer)),
-			);
-
-			// Store memory
-			await store.store(memory, embedding);
+			// Build user-facing message
+			let message = `Stored memory ${result.id} in collection: ${args.collection ?? "default"}`;
+			
+			if (result.autoTags) {
+				message += `\nAuto-tags: ${result.autoTags.tags.join(", ")}`;
+			}
+			
+			if (result.links && result.links.length > 0) {
+				message += `\nLinked to ${result.links.length} related memor${result.links.length === 1 ? "y" : "ies"}`;
+			}
 
 			return {
-				id,
-				message: `Stored memory ${id} in collection: ${collection}`,
+				id: result.id,
+				message,
 			};
 		},
 
@@ -450,5 +486,42 @@ export async function createMemoryAdapter(
 				};
 			}
 		},
+
+		/**
+		 * Smart upsert - uses LLM to decide ADD, UPDATE, DELETE, or NOOP
+		 *
+		 * Delegates to real swarm-mail adapter with Mem0 pattern:
+		 * - Finds semantically similar memories
+		 * - LLM analyzes and decides operation
+		 * - Executes with graceful degradation on LLM failures
+		 */
+		async upsert(args: UpsertArgs): Promise<UpsertResult> {
+			// Validate required fields
+			if (!args.information) {
+				throw new Error("information is required for upsert");
+			}
+
+			// Delegate to real swarm-mail adapter with useSmartOps enabled
+			const result = await realAdapter.upsert(args.information, {
+				collection: args.collection,
+				tags: args.tags,
+				metadata: args.metadata,
+				confidence: args.confidence,
+				useSmartOps: true, // Enable LLM-powered decision making
+				autoTag: args.autoTag,
+				autoLink: args.autoLink,
+				extractEntities: args.extractEntities,
+			});
+
+			// Map real adapter result to plugin UpsertResult format
+			return {
+				operation: result.operation,
+				reason: result.reason,
+				memoryId: result.id,
+				affectedMemoryIds: [result.id],
+				// Note: Real adapter doesn't return autoTags/links from upsert yet
+				// Those are only on store(). This is consistent with current behavior.
+			};
+		},
 	};
 }

package/src/observability-tools.test.ts

@@ -343,4 +343,17 @@ describe("observability-tools", () => {
 			}
 		});
 	});
+
+	describe("CLI Stats Helpers", () => {
+		// These helpers will be exported for use in bin/swarm.ts
+		// They format analytics data for beautiful CLI output
+
+		describe("formatSwarmStatsBox", () => {
+			test("formats stats in a beautiful box", () => {
+				// This will be implemented in observability-tools.ts
+				// Just defining the test structure for now
+				expect(true).toBe(true);
+			});
+		});
+	});
 });