@katyella/legio 0.1.0

package/src/watchdog/triage.test.ts

@@ -0,0 +1,162 @@
+/**
+ * Tests for Tier 1 AI-assisted triage.
+ * classifyResponse and buildTriagePrompt are pure functions — tested directly.
+ * triageAgent uses real filesystem (temp dirs). Claude spawn is expected to
+ * fail in test environments, exercising the fallback-to-extend path.
+ * spawnClaude is NOT mocked — we rely on it failing naturally in tests.
+ */
+
+import { mkdir, mkdtemp, rm, writeFile } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { afterEach, beforeEach, describe, expect, test } from "vitest";
+import { buildTriagePrompt, classifyResponse, triageAgent } from "./triage.ts";
+
+describe("classifyResponse", () => {
+	test("returns 'retry' when response contains 'retry'", () => {
+		const result = classifyResponse("The operation should retry.");
+		expect(result).toBe("retry");
+	});
+
+	test("returns 'retry' when response contains 'recoverable'", () => {
+		const result = classifyResponse("This error is recoverable.");
+		expect(result).toBe("retry");
+	});
+
+	test("returns 'terminate' when response contains 'terminate'", () => {
+		const result = classifyResponse("You should terminate the agent.");
+		expect(result).toBe("terminate");
+	});
+
+	test("returns 'terminate' when response contains 'fatal'", () => {
+		const result = classifyResponse("This is a fatal error.");
+		expect(result).toBe("terminate");
+	});
+
+	test("returns 'terminate' when response contains 'failed'", () => {
+		const result = classifyResponse("The operation has failed.");
+		expect(result).toBe("terminate");
+	});
+
+	test("handles mixed case (e.g., 'RETRY', 'Fatal')", () => {
+		expect(classifyResponse("RETRY this operation")).toBe("retry");
+		expect(classifyResponse("Fatal error occurred")).toBe("terminate");
+		expect(classifyResponse("RecOverAble issue")).toBe("retry");
+	});
+
+	test("returns 'extend' when response contains none of the keywords", () => {
+		const result = classifyResponse("The agent is processing data.");
+		expect(result).toBe("extend");
+	});
+
+	test("returns 'extend' for empty string", () => {
+		const result = classifyResponse("");
+		expect(result).toBe("extend");
+	});
+
+	test("first match wins when response has multiple keywords", () => {
+		// 'retry' is checked before 'terminate'
+		const result = classifyResponse("retry this but it may terminate later");
+		expect(result).toBe("retry");
+	});
+});
+
+describe("buildTriagePrompt", () => {
+	test("contains agent name in output", () => {
+		const prompt = buildTriagePrompt("test-agent", "2026-02-13T10:00:00Z", "log content");
+		expect(prompt).toContain("test-agent");
+	});
+
+	test("contains lastActivity timestamp in output", () => {
+		const timestamp = "2026-02-13T10:00:00Z";
+		const prompt = buildTriagePrompt("test-agent", timestamp, "log content");
+		expect(prompt).toContain(timestamp);
+	});
+
+	test("contains log content wrapped in code fences", () => {
+		const logContent = "Error: something went wrong\nat line 42";
+		const prompt = buildTriagePrompt("test-agent", "2026-02-13T10:00:00Z", logContent);
+		expect(prompt).toContain("```");
+		expect(prompt).toContain(logContent);
+		expect(prompt.split("```").length).toBeGreaterThanOrEqual(3); // Opening and closing fences
+	});
+
+	test("contains classification instructions (retry/terminate/extend)", () => {
+		const prompt = buildTriagePrompt("test-agent", "2026-02-13T10:00:00Z", "log content");
+		expect(prompt).toContain("retry");
+		expect(prompt).toContain("terminate");
+		expect(prompt).toContain("extend");
+	});
+});
+
+describe("triageAgent", () => {
+	let tempRoot: string;
+
+	beforeEach(async () => {
+		tempRoot = await mkdtemp(join(tmpdir(), "triage-test-"));
+	});
+
+	afterEach(async () => {
+		await rm(tempRoot, { recursive: true, force: true });
+	});
+
+	test("returns 'extend' when no logs directory exists", async () => {
+		const result = await triageAgent({
+			agentName: "test-agent",
+			root: tempRoot,
+			lastActivity: "2026-02-13T10:00:00Z",
+		});
+		expect(result).toBe("extend");
+	});
+
+	test("returns 'extend' when logs directory exists but is empty", async () => {
+		const logsDir = join(tempRoot, ".legio", "logs", "test-agent");
+		await mkdir(logsDir, { recursive: true });
+
+		const result = await triageAgent({
+			agentName: "test-agent",
+			root: tempRoot,
+			lastActivity: "2026-02-13T10:00:00Z",
+		});
+		expect(result).toBe("extend");
+	});
+
+	test("returns 'extend' when logs directory has session dir but no session.log", async () => {
+		const logsDir = join(tempRoot, ".legio", "logs", "test-agent", "2026-02-13T10-00-00");
+		await mkdir(logsDir, { recursive: true });
+		await writeFile(join(logsDir, ".gitkeep"), "", "utf-8");
+
+		const result = await triageAgent({
+			agentName: "test-agent",
+			root: tempRoot,
+			lastActivity: "2026-02-13T10:00:00Z",
+		});
+		expect(result).toBe("extend");
+	});
+
+	test("returns 'extend' when session.log exists but claude binary fails", async () => {
+		const timestamp = "2026-02-13T10-00-00";
+		const sessionLogDir = join(tempRoot, ".legio", "logs", "test-agent", timestamp);
+		const sessionLogPath = join(sessionLogDir, "session.log");
+
+		await mkdir(sessionLogDir, { recursive: true });
+
+		// Create session.log with some content
+		await writeFile(
+			sessionLogPath,
+			"Agent started\nProcessing data\nError: something went wrong\n",
+			"utf-8",
+		);
+
+		// triageAgent will try to spawn claude which should fail or be killed by timeout.
+		// Short timeout ensures the test doesn't hang even if the claude binary
+		// exists on the system (e.g., inside a Claude Code session).
+		const result = await triageAgent({
+			agentName: "test-agent",
+			root: tempRoot,
+			lastActivity: "2026-02-13T10:00:00Z",
+			timeoutMs: 500,
+		});
+		expect(result).toBe("extend");
+	});
+});

package/src/watchdog/triage.ts

@@ -0,0 +1,193 @@
+/**
+ * Tier 1 AI-assisted failure classification for stalled agents.
+ *
+ * When an agent is detected as stalled, triage reads recent log entries and
+ * uses Claude to classify the situation as recoverable, fatal, or long-running.
+ * Falls back to "extend" if Claude is unavailable.
+ */
+
+import { spawn } from "node:child_process";
+import { readdir, readFile } from "node:fs/promises";
+import { join } from "node:path";
+import { AgentError } from "../errors.ts";
+
+/**
+ * Triage a stalled agent by analyzing its recent log output with Claude.
+ *
+ * Steps:
+ * 1. Find the most recent session log directory for the agent
+ * 2. Read the last 50 lines of session.log
+ * 3. Ask Claude to classify the situation
+ * 4. Parse the response to determine action
+ *
+ * @param options.agentName - Name of the agent to triage
+ * @param options.root - Project root directory (contains .legio/)
+ * @param options.lastActivity - ISO timestamp of the agent's last recorded activity
+ * @returns "retry" if recoverable, "terminate" if fatal, "extend" if likely long-running
+ */
+export async function triageAgent(options: {
+	agentName: string;
+	root: string;
+	lastActivity: string;
+	/** Timeout in ms for the Claude subprocess. Defaults to 30_000 (30s). */
+	timeoutMs?: number;
+}): Promise<"retry" | "terminate" | "extend"> {
+	const { agentName, root, lastActivity, timeoutMs } = options;
+	const logsDir = join(root, ".legio", "logs", agentName);
+
+	let logContent: string;
+	try {
+		logContent = await readRecentLog(logsDir);
+	} catch {
+		// No logs available — assume long-running operation
+		return "extend";
+	}
+
+	const prompt = buildTriagePrompt(agentName, lastActivity, logContent);
+
+	try {
+		const response = await spawnClaude(prompt, timeoutMs);
+		return classifyResponse(response);
+	} catch {
+		// Claude not available — default to extend (safe fallback)
+		return "extend";
+	}
+}
+
+/**
+ * Read the last 50 lines of the most recent session.log for an agent.
+ *
+ * @param logsDir - Path to the agent's logs directory (e.g., .legio/logs/{agent}/)
+ * @returns The last 50 lines of the session log as a string
+ * @throws AgentError if no log directories or session.log are found
+ */
+async function readRecentLog(logsDir: string): Promise<string> {
+	let entries: string[];
+	try {
+		entries = await readdir(logsDir);
+	} catch {
+		throw new AgentError(`No log directory found at ${logsDir}`);
+	}
+
+	if (entries.length === 0) {
+		throw new AgentError(`No session directories in ${logsDir}`);
+	}
+
+	// Session directories are named with timestamps — sort descending to get most recent
+	const sorted = entries.sort().reverse();
+	const mostRecent = sorted[0];
+	if (mostRecent === undefined) {
+		throw new AgentError(`No session directories in ${logsDir}`);
+	}
+
+	const logPath = join(logsDir, mostRecent, "session.log");
+	let content: string;
+	try {
+		content = await readFile(logPath, "utf-8");
+	} catch {
+		throw new AgentError(`No session.log found at ${logPath}`);
+	}
+
+	const lines = content.split("\n");
+
+	// Take the last 50 non-empty lines
+	const tail = lines.slice(-50).join("\n");
+	return tail;
+}
+
+/**
+ * Build the triage prompt for Claude analysis.
+ */
+export function buildTriagePrompt(
+	agentName: string,
+	lastActivity: string,
+	logContent: string,
+): string {
+	return [
+		"Analyze this agent log and classify the situation.",
+		`Agent: ${agentName}`,
+		`Last activity: ${lastActivity}`,
+		"",
+		"Respond with exactly one word: 'retry' if the error is recoverable,",
+		"'terminate' if the error is fatal or the agent has failed,",
+		"or 'extend' if this looks like a long-running operation.",
+		"",
+		"Log content:",
+		"```",
+		logContent,
+		"```",
+	].join("\n");
+}
+
+/** Default timeout for Claude subprocess: 30 seconds */
+const DEFAULT_TRIAGE_TIMEOUT_MS = 30_000;
+
+/**
+ * Spawn Claude in non-interactive mode to analyze the log.
+ *
+ * @param prompt - The analysis prompt
+ * @param timeoutMs - Timeout in ms for the subprocess (default 30s)
+ * @returns Claude's response text
+ * @throws Error if claude is not installed, the process fails, or the timeout is reached
+ */
+async function spawnClaude(prompt: string, timeoutMs?: number): Promise<string> {
+	const timeout = timeoutMs ?? DEFAULT_TRIAGE_TIMEOUT_MS;
+
+	return new Promise((resolve, reject) => {
+		const proc = spawn("claude", ["--print", "-p", prompt], {
+			stdio: ["ignore", "pipe", "pipe"],
+		});
+
+		if (proc.stdout === null || proc.stderr === null) {
+			reject(new AgentError("spawn failed to create stdio pipes"));
+			return;
+		}
+
+		const timer = globalThis.setTimeout(() => {
+			proc.kill();
+		}, timeout);
+
+		const stdoutChunks: Buffer[] = [];
+		const stderrChunks: Buffer[] = [];
+
+		proc.stdout.on("data", (data: Buffer) => stdoutChunks.push(data));
+		proc.stderr.on("data", (data: Buffer) => stderrChunks.push(data));
+
+		proc.on("close", (code) => {
+			clearTimeout(timer);
+			const stdout = Buffer.concat(stdoutChunks).toString().trim();
+			if (code !== 0) {
+				const stderr = Buffer.concat(stderrChunks).toString().trim();
+				reject(new AgentError(`Claude triage failed (exit ${code}): ${stderr}`));
+				return;
+			}
+			resolve(stdout);
+		});
+
+		proc.on("error", (err) => {
+			clearTimeout(timer);
+			reject(err);
+		});
+	});
+}
+
+/**
+ * Classify Claude's response into a triage action.
+ *
+ * @param response - Claude's raw response text
+ * @returns "retry" | "terminate" | "extend"
+ */
+export function classifyResponse(response: string): "retry" | "terminate" | "extend" {
+	const lower = response.toLowerCase();
+
+	if (lower.includes("retry") || lower.includes("recoverable")) {
+		return "retry";
+	}
+
+	if (lower.includes("terminate") || lower.includes("fatal") || lower.includes("failed")) {
+		return "terminate";
+	}
+
+	// Default: assume long-running operation
+	return "extend";
+}