opencode-swarm-plugin 0.32.0 → 0.34.0

package/src/logger.ts

@@ -0,0 +1,135 @@
+/**
+ * Logger infrastructure using Pino with daily rotation
+ *
+ * Features:
+ * - Daily log rotation via pino-roll (numeric format: swarm.1log, swarm.2log, etc.)
+ * - 14-day retention (14 files max in addition to current file)
+ * - Module-specific child loggers with separate log files
+ * - Pretty mode for development (SWARM_LOG_PRETTY=1 env var)
+ * - Logs to ~/.config/swarm-tools/logs/ by default
+ *
+ * Note: pino-roll uses numeric rotation (e.g., swarm.1log, swarm.2log) not date-based names.
+ * Files rotate daily based on frequency='daily', with a maximum of 14 retained files.
+ */
+
+import { mkdirSync, existsSync } from "node:fs";
+import { join } from "node:path";
+import { homedir } from "node:os";
+import type { Logger } from "pino";
+import pino from "pino";
+
+const DEFAULT_LOG_DIR = join(homedir(), ".config", "swarm-tools", "logs");
+
+/**
+ * Creates the log directory if it doesn't exist
+ */
+function ensureLogDir(logDir: string): void {
+  if (!existsSync(logDir)) {
+    mkdirSync(logDir, { recursive: true });
+  }
+}
+
+/**
+ * Creates a Pino transport with file rotation
+ *
+ * @param filename - Log file base name (e.g., "swarm" becomes swarm.1log, swarm.2log, etc.)
+ * @param logDir - Directory to store logs
+ */
+function createTransport(
+  filename: string,
+  logDir: string,
+): pino.TransportTargetOptions {
+  const isPretty = process.env.SWARM_LOG_PRETTY === "1";
+
+  if (isPretty) {
+    // Pretty mode - output to console with pino-pretty
+    return {
+      target: "pino-pretty",
+      options: {
+        colorize: true,
+        translateTime: "HH:MM:ss",
+        ignore: "pid,hostname",
+      },
+    };
+  }
+
+  // Production mode - file rotation with pino-roll
+  // pino-roll format: {file}.{number}{extension}
+  // So "swarm" becomes "swarm.1log", "swarm.2log", etc.
+  return {
+    target: "pino-roll",
+    options: {
+      file: join(logDir, filename),
+      frequency: "daily",
+      extension: "log",
+      limit: { count: 14 },
+      mkdir: true,
+    },
+  };
+}
+
+const loggerCache = new Map<string, Logger>();
+
+/**
+ * Gets or creates the main logger instance
+ *
+ * @param logDir - Optional log directory (defaults to ~/.config/swarm-tools/logs)
+ * @returns Pino logger instance
+ */
+export function getLogger(logDir: string = DEFAULT_LOG_DIR): Logger {
+  const cacheKey = `swarm:${logDir}`;
+
+  if (loggerCache.has(cacheKey)) {
+    return loggerCache.get(cacheKey)!;
+  }
+
+  ensureLogDir(logDir);
+
+  const logger = pino(
+    {
+      level: process.env.LOG_LEVEL || "info",
+      timestamp: pino.stdTimeFunctions.isoTime,
+    },
+    pino.transport(createTransport("swarm", logDir)),
+  );
+
+  loggerCache.set(cacheKey, logger);
+  return logger;
+}
+
+/**
+ * Creates a child logger for a specific module with its own log file
+ *
+ * @param module - Module name (e.g., "compaction", "cli")
+ * @param logDir - Optional log directory (defaults to ~/.config/swarm-tools/logs)
+ * @returns Child logger instance
+ */
+export function createChildLogger(
+  module: string,
+  logDir: string = DEFAULT_LOG_DIR,
+): Logger {
+  const cacheKey = `${module}:${logDir}`;
+
+  if (loggerCache.has(cacheKey)) {
+    return loggerCache.get(cacheKey)!;
+  }
+
+  ensureLogDir(logDir);
+
+  const childLogger = pino(
+    {
+      level: process.env.LOG_LEVEL || "info",
+      timestamp: pino.stdTimeFunctions.isoTime,
+    },
+    pino.transport(createTransport(module, logDir)),
+  );
+
+  const logger = childLogger.child({ module });
+  loggerCache.set(cacheKey, logger);
+  return logger;
+}
+
+/**
+ * Default logger instance for immediate use
+ */
+export const logger = getLogger();

package/src/observability-tools.test.ts

@@ -0,0 +1,346 @@
+/**
+ * Observability Tools Tests
+ *
+ * TDD: Write tests first, then implement the tools.
+ */
+
+import { describe, test, expect, beforeAll, afterAll } from "bun:test";
+import {
+	observabilityTools,
+	type SwarmAnalyticsArgs,
+	type SwarmQueryArgs,
+	type SwarmDiagnoseArgs,
+	type SwarmInsightsArgs,
+} from "./observability-tools";
+import type { ToolContext } from "@opencode-ai/plugin";
+import {
+	closeSwarmMailLibSQL,
+	createInMemorySwarmMailLibSQL,
+	initSwarmAgent,
+	reserveSwarmFiles,
+	sendSwarmMessage,
+	type SwarmMailAdapter,
+} from "swarm-mail";
+
+describe("observability-tools", () => {
+	let swarmMail: SwarmMailAdapter;
+	const projectPath = "/test/project";
+	const mockContext: ToolContext = { sessionID: "test-session" };
+
+	beforeAll(async () => {
+		// Create in-memory database with test data
+		swarmMail = await createInMemorySwarmMailLibSQL(projectPath);
+
+		// Populate with test events using high-level API
+		const agentName = "TestAgent";
+
+		// Register agent
+		await initSwarmAgent({
+			projectPath,
+			agentName,
+			taskDescription: "test-task",
+		});
+
+		// Reserve and release files (for lock contention analytics)
+		await reserveSwarmFiles({
+			projectPath,
+			agentName,
+			paths: ["src/test.ts"],
+			reason: "test-reason",
+		});
+
+		// Send a message (for message latency analytics)
+		await sendSwarmMessage({
+			projectPath,
+			fromAgent: agentName,
+			toAgents: ["Agent2"],
+			subject: "test-subject",
+			body: "test-body",
+		});
+
+		// Note: subtask outcomes are recorded via a different API
+		// For now, we'll test with the events we have
+		// The important thing is that the tools can execute queries
+	});
+
+	afterAll(async () => {
+		await closeSwarmMailLibSQL(projectPath);
+	});
+
+	describe("swarm_analytics", () => {
+		const tool = observabilityTools.swarm_analytics;
+
+		test("is defined with correct schema", () => {
+			expect(tool).toBeDefined();
+			expect(tool.description).toBeTruthy();
+			expect(tool.args).toBeDefined();
+		});
+
+		test("returns failed-decompositions data", async () => {
+			const args: SwarmAnalyticsArgs = {
+				query: "failed-decompositions",
+			};
+
+			const result = await tool.execute(args, mockContext);
+			expect(result).toBeTruthy();
+
+			const parsed = JSON.parse(result);
+			expect(parsed).toHaveProperty("results");
+			expect(Array.isArray(parsed.results)).toBe(true);
+			// Empty data is fine - we're testing tool execution
+		});
+
+		test("returns strategy-success-rates data", async () => {
+			const args: SwarmAnalyticsArgs = {
+				query: "strategy-success-rates",
+			};
+
+			const result = await tool.execute(args, mockContext);
+			const parsed = JSON.parse(result);
+			expect(parsed).toHaveProperty("results");
+			expect(Array.isArray(parsed.results)).toBe(true);
+		});
+
+		test("returns agent-activity data", async () => {
+			const args: SwarmAnalyticsArgs = {
+				query: "agent-activity",
+			};
+
+			const result = await tool.execute(args, mockContext);
+			const parsed = JSON.parse(result);
+			expect(parsed).toHaveProperty("results");
+			expect(Array.isArray(parsed.results)).toBe(true);
+			// Should have at least our TestAgent
+			expect(parsed.results.length).toBeGreaterThanOrEqual(1);
+		});
+
+		test("supports summary format", async () => {
+			const args: SwarmAnalyticsArgs = {
+				query: "agent-activity",
+				format: "summary",
+			};
+
+			const result = await tool.execute(args, mockContext);
+			expect(result).toBeTruthy();
+			expect(typeof result).toBe("string");
+			// Summary should be concise (<500 chars)
+			expect(result.length).toBeLessThan(500);
+		});
+
+		test("supports time filtering with since", async () => {
+			const args: SwarmAnalyticsArgs = {
+				query: "agent-activity",
+				since: "24h",
+			};
+
+			const result = await tool.execute(args, mockContext);
+			const parsed = JSON.parse(result);
+			expect(parsed).toHaveProperty("results");
+		});
+
+		test("returns error for invalid query type", async () => {
+			const args = {
+				query: "invalid-query",
+			};
+
+			const result = await tool.execute(args as any, mockContext);
+			const parsed = JSON.parse(result);
+			expect(parsed).toHaveProperty("error");
+		});
+	});
+
+	describe("swarm_query", () => {
+		const tool = observabilityTools.swarm_query;
+
+		test("is defined with correct schema", () => {
+			expect(tool).toBeDefined();
+			expect(tool.description).toBeTruthy();
+			expect(tool.args).toBeDefined();
+		});
+
+		test("executes raw SQL queries", async () => {
+			const args: SwarmQueryArgs = {
+				sql: "SELECT type, COUNT(*) as count FROM events GROUP BY type",
+			};
+
+			const result = await tool.execute(args, mockContext);
+			expect(result).toBeTruthy();
+
+			const parsed = JSON.parse(result);
+			// May have errors in test environment - that's ok
+			if (!parsed.error) {
+				// Should have count and results even if empty
+				expect(parsed).toHaveProperty("count");
+				expect(parsed).toHaveProperty("results");
+				expect(Array.isArray(parsed.results)).toBe(true);
+			}
+		});
+
+		test("limits results to max 50 rows", async () => {
+			const args: SwarmQueryArgs = {
+				sql: "SELECT * FROM events LIMIT 100", // Try to fetch 100
+			};
+
+			const result = await tool.execute(args, mockContext);
+			const parsed = JSON.parse(result);
+			// Should be capped at 50 (or less if there's less data)
+			// May return error if database issues - that's ok for this test
+			if (parsed.error) {
+				expect(parsed).toHaveProperty("error");
+			} else {
+				expect(parsed).toHaveProperty("results");
+				expect(parsed.results.length).toBeLessThanOrEqual(50);
+			}
+		});
+
+		test("supports table format", async () => {
+			const args: SwarmQueryArgs = {
+				sql: "SELECT type FROM events LIMIT 3",
+				format: "table",
+			};
+
+			const result = await tool.execute(args, mockContext);
+			expect(typeof result).toBe("string");
+			// Table format returns string (even if "No results" for empty data)
+			expect(result.length).toBeGreaterThan(0);
+		});
+
+		test("returns error for invalid SQL", async () => {
+			const args: SwarmQueryArgs = {
+				sql: "SELECT * FROM nonexistent_table",
+			};
+
+			const result = await tool.execute(args, mockContext);
+			const parsed = JSON.parse(result);
+			expect(parsed).toHaveProperty("error");
+		});
+	});
+
+	describe("swarm_diagnose", () => {
+		const tool = observabilityTools.swarm_diagnose;
+
+		test("is defined with correct schema", () => {
+			expect(tool).toBeDefined();
+			expect(tool.description).toBeTruthy();
+			expect(tool.args).toBeDefined();
+		});
+
+		test("diagnoses issues for a specific epic", async () => {
+			const args: SwarmDiagnoseArgs = {
+				epic_id: "epic-123",
+				include: ["blockers", "errors"],
+			};
+
+			const result = await tool.execute(args, mockContext);
+			expect(result).toBeTruthy();
+
+			const parsed = JSON.parse(result);
+			expect(parsed).toHaveProperty("epic_id");
+			expect(parsed).toHaveProperty("diagnosis");
+		});
+
+		test("returns structured diagnosis with suggestions", async () => {
+			const args: SwarmDiagnoseArgs = {
+				bead_id: "task-1",
+			};
+
+			const result = await tool.execute(args, mockContext);
+			const parsed = JSON.parse(result);
+			expect(parsed).toHaveProperty("diagnosis");
+			expect(Array.isArray(parsed.diagnosis)).toBe(true);
+		});
+
+		test("includes timeline when requested", async () => {
+			const args: SwarmDiagnoseArgs = {
+				bead_id: "task-1",
+				include: ["timeline"],
+			};
+
+			const result = await tool.execute(args, mockContext);
+			const parsed = JSON.parse(result);
+			expect(parsed).toHaveProperty("timeline");
+		});
+	});
+
+	describe("swarm_insights", () => {
+		const tool = observabilityTools.swarm_insights;
+
+		test("is defined with correct schema", () => {
+			expect(tool).toBeDefined();
+			expect(tool.description).toBeTruthy();
+			expect(tool.args).toBeDefined();
+		});
+
+		test("generates insights for recent activity", async () => {
+			const args: SwarmInsightsArgs = {
+				scope: "recent",
+				metrics: ["success_rate", "avg_duration"],
+			};
+
+			const result = await tool.execute(args, mockContext);
+			expect(result).toBeTruthy();
+
+			const parsed = JSON.parse(result);
+			expect(parsed).toHaveProperty("insights");
+			expect(Array.isArray(parsed.insights)).toBe(true);
+		});
+
+		test("generates insights for specific epic", async () => {
+			const args: SwarmInsightsArgs = {
+				scope: "epic",
+				epic_id: "epic-123",
+				metrics: ["conflict_rate", "retry_rate"],
+			};
+
+			const result = await tool.execute(args, mockContext);
+			const parsed = JSON.parse(result);
+			expect(parsed).toHaveProperty("epic_id", "epic-123");
+			expect(parsed).toHaveProperty("insights");
+		});
+
+		test("returns error when epic_id missing for epic scope", async () => {
+			const args: SwarmInsightsArgs = {
+				scope: "epic",
+				metrics: ["success_rate"],
+				// Missing epic_id
+			};
+
+			const result = await tool.execute(args, mockContext);
+			const parsed = JSON.parse(result);
+			expect(parsed).toHaveProperty("error");
+		});
+	});
+
+	describe("integration with swarm-mail analytics", () => {
+		test("all query types are supported", async () => {
+			const queryTypes = [
+				"failed-decompositions",
+				"strategy-success-rates",
+				"lock-contention",
+				"agent-activity",
+				"message-latency",
+				"scope-violations",
+				"task-duration",
+				"checkpoint-frequency",
+				"recovery-success",
+				"human-feedback",
+			];
+
+			for (const queryType of queryTypes) {
+				const tool = observabilityTools.swarm_analytics;
+				const args: SwarmAnalyticsArgs = {
+					query: queryType as SwarmAnalyticsArgs["query"],
+				};
+
+				const result = await tool.execute(args, mockContext);
+				const parsed = JSON.parse(result);
+
+				// Should return results property (even if empty array)
+				// May have errors in test environment - that's ok
+				if (!parsed.error) {
+					expect(parsed).toHaveProperty("results");
+				}
+			}
+		});
+	});
+});