opencode-swarm-plugin 0.42.5 → 0.42.6

package/src/index.ts

@@ -515,6 +515,7 @@ export const allTools = {
   ...skillsTools,
   ...mandateTools,
   ...memoryTools,
+  ...observabilityTools,
 } as const;
 
 /**

package/src/schemas/cell.ts

@@ -122,6 +122,7 @@ export const CellQueryArgsSchema = z.object({
   status: CellStatusSchema.optional(),
   type: CellTypeSchema.optional(),
   ready: z.boolean().optional(),
+  parent_id: z.string().optional(),
   limit: z.number().int().positive().default(20),
 });
 export type CellQueryArgs = z.infer<typeof CellQueryArgsSchema>;

package/src/swarm-insights.test.ts

@@ -0,0 +1,214 @@
+/**
+ * Swarm Insights Data Layer Tests
+ *
+ * TDD: Red → Green → Refactor
+ */
+
+import { describe, expect, test, beforeAll, afterAll } from "bun:test";
+import {
+	getStrategyInsights,
+	getFileInsights,
+	getPatternInsights,
+	formatInsightsForPrompt,
+	type StrategyInsight,
+	type FileInsight,
+	type PatternInsight,
+} from "./swarm-insights";
+import { createInMemorySwarmMail, type SwarmMailAdapter } from "swarm-mail";
+
+describe("swarm-insights data layer", () => {
+	let swarmMail: SwarmMailAdapter;
+
+	beforeAll(async () => {
+		swarmMail = await createInMemorySwarmMail("test-insights");
+	});
+
+	afterAll(async () => {
+		await swarmMail.close();
+	});
+
+	describe("getStrategyInsights", () => {
+		test("returns empty array when no data", async () => {
+			const insights = await getStrategyInsights(swarmMail, "test-task");
+			expect(insights).toEqual([]);
+		});
+
+		test("returns strategy success rates from outcomes", async () => {
+			// Seed some outcome events (id is auto-increment, timestamp is integer)
+			const db = await swarmMail.getDatabase();
+			const now = Date.now();
+			await db.query(
+				`INSERT INTO events (type, project_key, timestamp, data) VALUES 
+				('subtask_outcome', 'test', ?, ?),
+				('subtask_outcome', 'test', ?, ?),
+				('subtask_outcome', 'test', ?, ?)`,
+				[
+					now,
+					JSON.stringify({ strategy: "file-based", success: "true" }),
+					now,
+					JSON.stringify({ strategy: "file-based", success: "true" }),
+					now,
+					JSON.stringify({ strategy: "file-based", success: "false" }),
+				],
+			);
+
+			const insights = await getStrategyInsights(swarmMail, "test-task");
+
+			expect(insights.length).toBeGreaterThan(0);
+			const fileBased = insights.find((i) => i.strategy === "file-based");
+			expect(fileBased).toBeDefined();
+			expect(fileBased?.successRate).toBeCloseTo(66.67, 0);
+			expect(fileBased?.totalAttempts).toBe(3);
+		});
+
+		test("includes recommendation based on success rate", async () => {
+			const insights = await getStrategyInsights(swarmMail, "test-task");
+			const fileBased = insights.find((i) => i.strategy === "file-based");
+
+			expect(fileBased?.recommendation).toBeDefined();
+			expect(typeof fileBased?.recommendation).toBe("string");
+		});
+	});
+
+	describe("getFileInsights", () => {
+		test("returns empty array for unknown files", async () => {
+			const insights = await getFileInsights(swarmMail, [
+				"src/unknown-file.ts",
+			]);
+			expect(insights).toEqual([]);
+		});
+
+		test("returns past issues for known files", async () => {
+			// Seed some file-related events (id is auto-increment, timestamp is integer)
+			const db = await swarmMail.getDatabase();
+			const now = Date.now();
+			await db.query(
+				`INSERT INTO events (type, project_key, timestamp, data) VALUES 
+				('subtask_outcome', 'test', ?, ?)`,
+				[
+					now,
+					JSON.stringify({
+						files_touched: ["src/auth.ts"],
+						success: "false",
+						error_count: 2,
+					}),
+				],
+			);
+
+			const insights = await getFileInsights(swarmMail, ["src/auth.ts"]);
+
+			expect(insights.length).toBeGreaterThan(0);
+			const authInsight = insights.find((i) => i.file === "src/auth.ts");
+			expect(authInsight).toBeDefined();
+			expect(authInsight?.failureCount).toBeGreaterThan(0);
+		});
+
+		test("includes gotchas from semantic memory", async () => {
+			// This would query semantic memory for file-specific learnings
+			const insights = await getFileInsights(swarmMail, ["src/auth.ts"]);
+
+			// Even if no gotchas, the structure should be correct
+			const authInsight = insights.find((i) => i.file === "src/auth.ts");
+			expect(authInsight?.gotchas).toBeDefined();
+			expect(Array.isArray(authInsight?.gotchas)).toBe(true);
+		});
+	});
+
+	describe("getPatternInsights", () => {
+		test("returns common failure patterns", async () => {
+			const insights = await getPatternInsights(swarmMail);
+
+			expect(Array.isArray(insights)).toBe(true);
+			// Structure check
+			if (insights.length > 0) {
+				expect(insights[0]).toHaveProperty("pattern");
+				expect(insights[0]).toHaveProperty("frequency");
+				expect(insights[0]).toHaveProperty("recommendation");
+			}
+		});
+
+		test("includes anti-patterns from learning system", async () => {
+			const insights = await getPatternInsights(swarmMail);
+
+			// Should include anti-patterns if any exist
+			expect(Array.isArray(insights)).toBe(true);
+		});
+	});
+
+	describe("formatInsightsForPrompt", () => {
+		test("formats strategy insights concisely", () => {
+			const strategies: StrategyInsight[] = [
+				{
+					strategy: "file-based",
+					successRate: 85,
+					totalAttempts: 20,
+					recommendation: "Preferred for this project",
+				},
+				{
+					strategy: "feature-based",
+					successRate: 60,
+					totalAttempts: 10,
+					recommendation: "Use with caution",
+				},
+			];
+
+			const formatted = formatInsightsForPrompt({ strategies });
+
+			expect(formatted).toContain("file-based");
+			expect(formatted).toContain("85%");
+			expect(formatted.length).toBeLessThan(500); // Context-efficient
+		});
+
+		test("formats file insights concisely", () => {
+			const files: FileInsight[] = [
+				{
+					file: "src/auth.ts",
+					failureCount: 3,
+					lastFailure: "2025-12-25",
+					gotchas: ["Watch for race conditions in token refresh"],
+				},
+			];
+
+			const formatted = formatInsightsForPrompt({ files });
+
+			expect(formatted).toContain("src/auth.ts");
+			expect(formatted).toContain("race conditions");
+			expect(formatted.length).toBeLessThan(300); // Per-file budget
+		});
+
+		test("formats pattern insights concisely", () => {
+			const patterns: PatternInsight[] = [
+				{
+					pattern: "Missing error handling",
+					frequency: 5,
+					recommendation: "Add try/catch around async operations",
+				},
+			];
+
+			const formatted = formatInsightsForPrompt({ patterns });
+
+			expect(formatted).toContain("Missing error handling");
+			expect(formatted).toContain("try/catch");
+		});
+
+		test("respects token budget", () => {
+			// Create many insights
+			const strategies: StrategyInsight[] = Array.from({ length: 10 }, (_, i) => ({
+				strategy: `strategy-${i}`,
+				successRate: 50 + i * 5,
+				totalAttempts: 10,
+				recommendation: `Recommendation for strategy ${i}`,
+			}));
+
+			const formatted = formatInsightsForPrompt({ strategies }, { maxTokens: 200 });
+
+			// Should truncate to fit budget
+			expect(formatted.length).toBeLessThan(1000); // ~200 tokens ≈ 800 chars
+		});
+
+		test("returns empty string when no insights", () => {
+			const formatted = formatInsightsForPrompt({});
+			expect(formatted).toBe("");
+		});
+	});
+});

package/src/swarm-insights.ts

@@ -0,0 +1,346 @@
+/**
+ * Swarm Insights Data Layer
+ *
+ * Aggregates insights from swarm coordination for prompt injection.
+ * Provides concise, context-efficient summaries for coordinators and workers.
+ *
+ * Data sources:
+ * - Event store (subtask_outcome, eval_finalized)
+ * - Semantic memory (file-specific learnings)
+ * - Anti-pattern registry
+ */
+
+import type { SwarmMailAdapter } from "swarm-mail";
+
+// ============================================================================
+// Types
+// ============================================================================
+
+export interface StrategyInsight {
+	strategy: string;
+	successRate: number;
+	totalAttempts: number;
+	recommendation: string;
+}
+
+export interface FileInsight {
+	file: string;
+	failureCount: number;
+	lastFailure: string | null;
+	gotchas: string[];
+}
+
+export interface PatternInsight {
+	pattern: string;
+	frequency: number;
+	recommendation: string;
+}
+
+export interface InsightsBundle {
+	strategies?: StrategyInsight[];
+	files?: FileInsight[];
+	patterns?: PatternInsight[];
+}
+
+export interface FormatOptions {
+	maxTokens?: number;
+}
+
+// ============================================================================
+// Strategy Insights
+// ============================================================================
+
+/**
+ * Get strategy success rates and recommendations for a task.
+ *
+ * Queries the event store for subtask_outcome events and calculates
+ * success rates by strategy. Returns recommendations based on historical data.
+ */
+export async function getStrategyInsights(
+	swarmMail: SwarmMailAdapter,
+	_task: string,
+): Promise<StrategyInsight[]> {
+	const db = await swarmMail.getDatabase();
+
+	const query = `
+		SELECT 
+			json_extract(data, '$.strategy') as strategy,
+			COUNT(*) as total_attempts,
+			SUM(CASE WHEN json_extract(data, '$.success') = 'true' THEN 1 ELSE 0 END) as successes
+		FROM events
+		WHERE type = 'subtask_outcome'
+		AND json_extract(data, '$.strategy') IS NOT NULL
+		GROUP BY json_extract(data, '$.strategy')
+		ORDER BY total_attempts DESC
+	`;
+
+	const result = await db.query(query, []);
+	const rows = result.rows as Array<{
+		strategy: string;
+		total_attempts: number;
+		successes: number;
+	}>;
+
+	return rows.map((row) => {
+		const successRate = (row.successes / row.total_attempts) * 100;
+		return {
+			strategy: row.strategy,
+			successRate: Math.round(successRate * 100) / 100,
+			totalAttempts: row.total_attempts,
+			recommendation: getStrategyRecommendation(row.strategy, successRate),
+		};
+	});
+}
+
+/**
+ * Generate recommendation based on strategy and success rate.
+ */
+function getStrategyRecommendation(strategy: string, successRate: number): string {
+	if (successRate >= 80) {
+		return `${strategy} is performing well (${successRate.toFixed(0)}% success)`;
+	}
+	if (successRate >= 60) {
+		return `${strategy} is moderate - monitor for issues`;
+	}
+	if (successRate >= 40) {
+		return `${strategy} has low success - consider alternatives`;
+	}
+	return `AVOID ${strategy} - high failure rate (${successRate.toFixed(0)}%)`;
+}
+
+// ============================================================================
+// File Insights
+// ============================================================================
+
+/**
+ * Get insights for specific files based on historical outcomes.
+ *
+ * Queries the event store for failures involving these files and
+ * semantic memory for file-specific gotchas.
+ */
+export async function getFileInsights(
+	swarmMail: SwarmMailAdapter,
+	files: string[],
+): Promise<FileInsight[]> {
+	if (files.length === 0) return [];
+
+	const db = await swarmMail.getDatabase();
+	const insights: FileInsight[] = [];
+
+	for (const file of files) {
+		// Query for failures involving this file
+		const query = `
+			SELECT 
+				COUNT(*) as failure_count,
+				MAX(timestamp) as last_failure
+			FROM events
+			WHERE type = 'subtask_outcome'
+			AND json_extract(data, '$.success') = 'false'
+			AND json_extract(data, '$.files_touched') LIKE ?
+		`;
+
+		const result = await db.query(query, [`%${file}%`]);
+		const row = result.rows[0] as {
+			failure_count: number;
+			last_failure: string | null;
+		};
+
+		if (row && row.failure_count > 0) {
+			// Query semantic memory for gotchas (simplified - would use actual memory search)
+			const gotchas = await getFileGotchas(swarmMail, file);
+
+			insights.push({
+				file,
+				failureCount: row.failure_count,
+				lastFailure: row.last_failure,
+				gotchas,
+			});
+		}
+	}
+
+	return insights;
+}
+
+/**
+ * Get gotchas for a file from semantic memory.
+ *
+ * In a full implementation, this would query the semantic memory
+ * for file-specific learnings. For now, returns empty array.
+ */
+async function getFileGotchas(
+	_swarmMail: SwarmMailAdapter,
+	_file: string,
+): Promise<string[]> {
+	// TODO: Query semantic memory for file-specific learnings
+	// const memories = await semanticMemoryFind({ query: `file:${file}`, limit: 3 });
+	// return memories.map(m => m.summary);
+	return [];
+}
+
+// ============================================================================
+// Pattern Insights
+// ============================================================================
+
+/**
+ * Get common failure patterns and anti-patterns.
+ *
+ * Analyzes event store for recurring failure patterns and
+ * queries the anti-pattern registry.
+ */
+export async function getPatternInsights(
+	swarmMail: SwarmMailAdapter,
+): Promise<PatternInsight[]> {
+	const db = await swarmMail.getDatabase();
+	const patterns: PatternInsight[] = [];
+
+	// Query for common error patterns
+	const query = `
+		SELECT 
+			json_extract(data, '$.error_type') as error_type,
+			COUNT(*) as frequency
+		FROM events
+		WHERE type = 'subtask_outcome'
+		AND json_extract(data, '$.success') = 'false'
+		AND json_extract(data, '$.error_type') IS NOT NULL
+		GROUP BY json_extract(data, '$.error_type')
+		HAVING COUNT(*) >= 2
+		ORDER BY frequency DESC
+		LIMIT 5
+	`;
+
+	const result = await db.query(query, []);
+	const rows = result.rows as Array<{
+		error_type: string;
+		frequency: number;
+	}>;
+
+	for (const row of rows) {
+		patterns.push({
+			pattern: row.error_type,
+			frequency: row.frequency,
+			recommendation: getPatternRecommendation(row.error_type),
+		});
+	}
+
+	return patterns;
+}
+
+/**
+ * Generate recommendation for a failure pattern.
+ */
+function getPatternRecommendation(errorType: string): string {
+	// Common patterns and their recommendations
+	const recommendations: Record<string, string> = {
+		type_error: "Add explicit type annotations and null checks",
+		timeout: "Consider breaking into smaller tasks",
+		conflict: "Check file reservations before editing",
+		test_failure: "Run tests incrementally during implementation",
+	};
+
+	return recommendations[errorType] || `Address ${errorType} issues`;
+}
+
+// ============================================================================
+// Prompt Formatting
+// ============================================================================
+
+/**
+ * Format insights bundle for prompt injection.
+ *
+ * Produces a concise, context-efficient summary suitable for
+ * inclusion in coordinator or worker prompts.
+ *
+ * @param bundle - Insights to format
+ * @param options - Formatting options (maxTokens)
+ * @returns Formatted string for prompt injection
+ */
+export function formatInsightsForPrompt(
+	bundle: InsightsBundle,
+	options: FormatOptions = {},
+): string {
+	const { maxTokens = 500 } = options;
+	const sections: string[] = [];
+
+	// Format strategy insights
+	if (bundle.strategies && bundle.strategies.length > 0) {
+		const strategyLines = bundle.strategies
+			.slice(0, 3) // Top 3 strategies
+			.map(
+				(s) =>
+					`- ${s.strategy}: ${s.successRate.toFixed(0)}% success (${s.totalAttempts} attempts)`,
+			);
+		sections.push(`**Strategy Performance:**\n${strategyLines.join("\n")}`);
+	}
+
+	// Format file insights
+	if (bundle.files && bundle.files.length > 0) {
+		const fileLines = bundle.files.slice(0, 5).map((f) => {
+			const gotchaStr =
+				f.gotchas.length > 0 ? ` - ${f.gotchas[0]}` : "";
+			return `- ${f.file}: ${f.failureCount} past failures${gotchaStr}`;
+		});
+		sections.push(`**File-Specific Gotchas:**\n${fileLines.join("\n")}`);
+	}
+
+	// Format pattern insights
+	if (bundle.patterns && bundle.patterns.length > 0) {
+		const patternLines = bundle.patterns
+			.slice(0, 3)
+			.map((p) => `- ${p.pattern} (${p.frequency}x): ${p.recommendation}`);
+		sections.push(`**Common Pitfalls:**\n${patternLines.join("\n")}`);
+	}
+
+	if (sections.length === 0) {
+		return "";
+	}
+
+	let result = sections.join("\n\n");
+
+	// Truncate to fit token budget (rough estimate: 4 chars per token)
+	const maxChars = maxTokens * 4;
+	if (result.length > maxChars) {
+		result = result.slice(0, maxChars - 3) + "...";
+	}
+
+	return result;
+}
+
+// ============================================================================
+// Caching (for future optimization)
+// ============================================================================
+
+// Simple in-memory cache with TTL
+const insightsCache = new Map<
+	string,
+	{ data: InsightsBundle; expires: number }
+>();
+const CACHE_TTL_MS = 5 * 60 * 1000; // 5 minutes
+
+/**
+ * Get cached insights or compute fresh ones.
+ */
+export async function getCachedInsights(
+	_swarmMail: SwarmMailAdapter,
+	cacheKey: string,
+	computeFn: () => Promise<InsightsBundle>,
+): Promise<InsightsBundle> {
+	const cached = insightsCache.get(cacheKey);
+	if (cached && cached.expires > Date.now()) {
+		return cached.data;
+	}
+
+	const data = await computeFn();
+	insightsCache.set(cacheKey, {
+		data,
+		expires: Date.now() + CACHE_TTL_MS,
+	});
+
+	return data;
+}
+
+/**
+ * Clear the insights cache.
+ */
+export function clearInsightsCache(): void {
+	insightsCache.clear();
+}