@ag-eco/agentplate-cli 0.13.0

package/src/events/tailer.ts

@@ -0,0 +1,332 @@
+/**
+ * Background NDJSON event tailer for headless agent stdout logs.
+ *
+ * Headless agents (e.g. Sapling) write NDJSON events to a stdout.log file
+ * in .agentplate/logs/{agentName}/{timestamp}/stdout.log. After ap sling exits,
+ * nobody reads this stream — so ap status, ap dashboard, and ap feed cannot
+ * show live progress for headless agents.
+ *
+ * This module provides startEventTailer(), which polls the log file on a
+ * configurable interval, parses new NDJSON lines, and writes them into events.db
+ * via EventStore. The watchdog daemon starts a tailer for each headless agent
+ * session and stops it when the session completes or terminates.
+ */
+
+import { readdir } from "node:fs/promises";
+import { join } from "node:path";
+import { createSessionStore, type SessionStore } from "../sessions/store.ts";
+import type { EventStore, EventType } from "../types.ts";
+import { createEventStore } from "./store.ts";
+
+/**
+ * Handle to a running event tailer.
+ * Call stop() to halt polling and close the database connection.
+ */
+export interface TailerHandle {
+	/** Agent name being tailed. */
+	readonly agentName: string;
+	/** Absolute path to the stdout.log file being tailed. */
+	readonly logPath: string;
+	/** Stop polling and release all resources. */
+	stop(): void;
+}
+
+/** Map NDJSON event type strings to EventStore EventType. */
+function mapEventType(type: string): EventType {
+	switch (type) {
+		case "tool_start":
+			return "tool_start";
+		case "tool_end":
+			return "tool_end";
+		case "session_start":
+			return "session_start";
+		case "session_end":
+			return "session_end";
+		case "turn_start":
+			return "turn_start";
+		case "turn_end":
+			return "turn_end";
+		case "progress":
+			return "progress";
+		case "result":
+			return "result";
+		case "error":
+			return "error";
+		default:
+			return "custom";
+	}
+}
+
+/** Options for startEventTailer. */
+export interface TailerOptions {
+	/** Absolute path to the stdout.log file to tail. */
+	stdoutLogPath: string;
+	/** Agent name for event attribution in events.db. */
+	agentName: string;
+	/** Run ID to associate events with, or null. */
+	runId: string | null;
+	/** Absolute path to events.db. The tailer opens its own connection. */
+	eventsDbPath: string;
+	/**
+	 * Absolute path to sessions.db. When present and not equal to ":memory:",
+	 * the tailer opens a dedicated SessionStore to persist the runtime-provided
+	 * session_id (e.g. Claude stream-json `session_id`). Omit (or set to
+	 * ":memory:") for tailers that should not write to SessionStore.
+	 */
+	sessionsDbPath?: string;
+	/** Poll interval in milliseconds (default: 500). */
+	pollIntervalMs?: number;
+	/** DI: injected EventStore for testing (overrides eventsDbPath). */
+	_eventStore?: EventStore;
+	/** DI: injected SessionStore for testing (overrides sessionsDbPath). */
+	_sessionStore?: SessionStore;
+	/**
+	 * DI: invoked exactly once per tailer when an observed session_id differs
+	 * from the prior claudeSessionId stored in SessionStore. Receives the agent
+	 * name, the prior (requested) id, and the newly observed id. Production
+	 * code logs a warning to stderr instead.
+	 */
+	_onResumeMismatch?: (agentName: string, requested: string, observed: string) => void;
+}
+
+/**
+ * Start a background event tailer for a headless agent's stdout.log.
+ *
+ * Polls the log file on a configurable interval, reads new bytes since the
+ * last poll using file.size as a byte cursor, parses NDJSON lines, and writes
+ * normalized events to events.db. Maintains its own SQLite connection so it
+ * can outlive the daemon tick that created it.
+ *
+ * All errors (file not found, parse failures, DB write failures) are swallowed
+ * silently — the tailer must never crash the watchdog daemon.
+ *
+ * @param opts - Tailer configuration (log path, agent, run, db path)
+ * @returns TailerHandle with stop() to halt polling and close resources
+ */
+export function startEventTailer(opts: TailerOptions): TailerHandle {
+	const { stdoutLogPath, agentName, runId, eventsDbPath, pollIntervalMs = 500 } = opts;
+
+	// Open a dedicated EventStore for this tailer's lifetime (not tick-scoped).
+	// Injected _eventStore is used for testing without an actual DB file.
+	let eventStore: EventStore | null = opts._eventStore ?? null;
+	let ownedEventStore = false;
+	if (!eventStore) {
+		try {
+			eventStore = createEventStore(eventsDbPath);
+			ownedEventStore = true;
+		} catch {
+			// EventStore creation failed — return a no-op handle immediately.
+			// Scheduling a poll loop that silently discards every event would
+			// burn CPU and file descriptors for zero benefit.
+			return {
+				agentName,
+				logPath: stdoutLogPath,
+				stop() {},
+			};
+		}
+	}
+
+	// Open a dedicated SessionStore for this tailer's lifetime when a real
+	// sessionsDbPath is provided. Tailers that omit sessionsDbPath (or pass
+	// ":memory:") skip session_id persistence entirely — backward compat for
+	// callers that don't yet route through the watchdog wiring.
+	let sessionStore: SessionStore | null = opts._sessionStore ?? null;
+	let ownedSessionStore = false;
+	if (!sessionStore && opts.sessionsDbPath && opts.sessionsDbPath !== ":memory:") {
+		try {
+			sessionStore = createSessionStore(opts.sessionsDbPath);
+			ownedSessionStore = true;
+		} catch {
+			// SessionStore failure is non-fatal — events still flow.
+			sessionStore = null;
+		}
+	}
+
+	// Single-fire guard for session_id pinning. Mirrors claude.ts:312
+	// `sessionIdPinned` so that updateClaudeSessionId is called at most once
+	// per tailer lifetime, even if many system events stream by.
+	let sessionIdPinned = false;
+	const onResumeMismatch = opts._onResumeMismatch;
+
+	let stopped = false;
+	let byteOffset = 0;
+	let timer: ReturnType<typeof setTimeout> | null = null;
+
+	const poll = async (): Promise<void> => {
+		if (stopped) return;
+
+		try {
+			const file = Bun.file(stdoutLogPath);
+			const size = file.size;
+
+			if (size > byteOffset) {
+				// Read only new bytes since last poll — avoids re-processing old lines.
+				const newContent = await file.slice(byteOffset, size).text();
+				byteOffset = size;
+
+				const lines = newContent.split("\n");
+				for (const line of lines) {
+					const trimmed = line.trim();
+					if (!trimmed) continue;
+
+					let event: Record<string, unknown>;
+					try {
+						event = JSON.parse(trimmed) as Record<string, unknown>;
+					} catch {
+						// Skip malformed lines — partial writes or debug output.
+						continue;
+					}
+
+					const type = typeof event.type === "string" ? event.type : "custom";
+					const eventType = mapEventType(type);
+					const level = type === "error" ? "error" : "info";
+
+					// Extract tool name from various field names runtimes may use.
+					let toolName: string | null = null;
+					if (typeof event.tool === "string") {
+						toolName = event.tool;
+					} else if (typeof event.tool_name === "string") {
+						toolName = event.tool_name;
+					} else if (typeof event.toolName === "string") {
+						toolName = event.toolName;
+					}
+
+					const toolDurationMs = typeof event.duration_ms === "number" ? event.duration_ms : null;
+
+					// Extract session_id from stream-json system events (e.g. Claude Code
+					// emits `{type:"system", subtype:"init", session_id:"sess-..."}` on
+					// every spawn — including --resume spawns, which assign a fresh id).
+					// The "result" event also carries session_id; treat both as authoritative.
+					// Single-fire per tailer lifetime so we don't churn writes.
+					if (!sessionIdPinned && sessionStore !== null) {
+						const sid =
+							typeof event.session_id === "string" && event.session_id.length > 0
+								? event.session_id
+								: null;
+						if (sid !== null && (type === "system" || type === "result")) {
+							sessionIdPinned = true;
+							let prior: string | null = null;
+							try {
+								prior = sessionStore.getByName(agentName)?.claudeSessionId ?? null;
+							} catch {
+								prior = null;
+							}
+							try {
+								sessionStore.updateClaudeSessionId(agentName, sid);
+							} catch {
+								// Non-fatal: SessionStore write failure must not break tailing.
+							}
+							// Resume mismatch: requested != observed. The observed id wins
+							// (claude assigns fresh ids on --resume), but operators need to
+							// know — log a warning, and call DI hook for tests.
+							if (prior !== null && prior !== sid) {
+								if (onResumeMismatch) {
+									try {
+										onResumeMismatch(agentName, prior, sid);
+									} catch {
+										// DI hook errors must not crash the tailer.
+									}
+								} else {
+									process.stderr.write(
+										`[tailer] resume mismatch for ${agentName}: requested=${prior} observed=${sid}\n`,
+									);
+								}
+							}
+						}
+					}
+
+					try {
+						eventStore?.insert({
+							runId,
+							agentName,
+							sessionId: null,
+							eventType,
+							toolName,
+							toolArgs: null,
+							toolDurationMs,
+							level,
+							data: JSON.stringify(event),
+						});
+					} catch {
+						// DB write failure is non-fatal.
+					}
+				}
+			}
+		} catch {
+			// File read failure is non-fatal — agent may not have started writing yet.
+		}
+
+		if (!stopped) {
+			timer = setTimeout(poll, pollIntervalMs);
+		}
+	};
+
+	// Schedule first poll.
+	timer = setTimeout(poll, pollIntervalMs);
+
+	return {
+		agentName,
+		logPath: stdoutLogPath,
+		stop() {
+			stopped = true;
+			if (timer !== null) {
+				clearTimeout(timer);
+				timer = null;
+			}
+			// Close only the EventStore this tailer owns (not the injected one).
+			if (ownedEventStore && eventStore) {
+				try {
+					eventStore.close();
+				} catch {
+					// Non-fatal.
+				}
+				eventStore = null;
+			}
+			// Close only the SessionStore this tailer owns.
+			if (ownedSessionStore && sessionStore) {
+				try {
+					sessionStore.close();
+				} catch {
+					// Non-fatal.
+				}
+				sessionStore = null;
+			}
+		},
+	};
+}
+
+/**
+ * Discover the most recent stdout.log path for a headless agent.
+ *
+ * Scans .agentplate/logs/{agentName}/ for timestamped session directories and
+ * returns the stdout.log path from the lexicographically last directory.
+ * Directories use ISO timestamps with `-` replacing `.` and `:`, which sort
+ * correctly in lexicographic order (e.g. 2026-03-05T14-52-26-089Z).
+ *
+ * Returns null if no log directory exists or no stdout.log is found.
+ *
+ * @param agentplateDir - Absolute path to .agentplate/
+ * @param agentName - Agent name to look up (matches .agentplate/logs/{agentName}/)
+ */
+export async function findLatestStdoutLog(
+	agentplateDir: string,
+	agentName: string,
+): Promise<string | null> {
+	const agentLogsDir = join(agentplateDir, "logs", agentName);
+	try {
+		const entries = await readdir(agentLogsDir);
+		if (entries.length === 0) return null;
+
+		// Lexicographic sort: ISO timestamps sort correctly without parsing.
+		const sorted = entries.sort();
+		const latest = sorted[sorted.length - 1];
+		if (!latest) return null;
+
+		const logPath = join(agentLogsDir, latest, "stdout.log");
+		const file = Bun.file(logPath);
+		if (await file.exists()) return logPath;
+		return null;
+	} catch {
+		return null;
+	}
+}

package/src/events/tool-filter.test.ts

@@ -0,0 +1,330 @@
+import { describe, expect, test } from "bun:test";
+import { filterToolArgs } from "./tool-filter.ts";
+
+describe("filterToolArgs", () => {
+	describe("Bash", () => {
+		test("keeps command and description, drops timeout/run_in_background/dangerouslyDisableSandbox", () => {
+			const result = filterToolArgs("Bash", {
+				command: "bun test",
+				description: "Run tests",
+				timeout: 60000,
+				run_in_background: true,
+				dangerouslyDisableSandbox: false,
+			});
+			expect(result.args).toEqual({
+				command: "bun test",
+				description: "Run tests",
+			});
+			expect(result.args).not.toHaveProperty("timeout");
+			expect(result.args).not.toHaveProperty("run_in_background");
+			expect(result.args).not.toHaveProperty("dangerouslyDisableSandbox");
+		});
+
+		test("summary shows first 80 chars of command", () => {
+			const result = filterToolArgs("Bash", { command: "bun test" });
+			expect(result.summary).toBe("bash: bun test");
+		});
+
+		test("summary truncates long commands at 80 chars", () => {
+			const longCmd = "a".repeat(120);
+			const result = filterToolArgs("Bash", { command: longCmd });
+			expect(result.summary).toBe(`bash: ${"a".repeat(80)}...`);
+		});
+
+		test("handles missing command gracefully", () => {
+			const result = filterToolArgs("Bash", {});
+			expect(result.args).toEqual({});
+			expect(result.summary).toBe("bash: ");
+		});
+	});
+
+	describe("Read", () => {
+		test("keeps file_path, offset, limit", () => {
+			const result = filterToolArgs("Read", {
+				file_path: "/src/index.ts",
+				offset: 10,
+				limit: 50,
+			});
+			expect(result.args).toEqual({
+				file_path: "/src/index.ts",
+				offset: 10,
+				limit: 50,
+			});
+		});
+
+		test("summary with offset and limit shows line range", () => {
+			const result = filterToolArgs("Read", {
+				file_path: "/src/index.ts",
+				offset: 10,
+				limit: 50,
+			});
+			expect(result.summary).toBe("read: /src/index.ts (lines 10-60)");
+		});
+
+		test("summary with only offset shows from line", () => {
+			const result = filterToolArgs("Read", {
+				file_path: "/src/index.ts",
+				offset: 10,
+			});
+			expect(result.summary).toBe("read: /src/index.ts (from line 10)");
+		});
+
+		test("summary with only limit shows first N lines", () => {
+			const result = filterToolArgs("Read", {
+				file_path: "/src/index.ts",
+				limit: 50,
+			});
+			expect(result.summary).toBe("read: /src/index.ts (first 50 lines)");
+		});
+
+		test("summary without offset or limit shows just path", () => {
+			const result = filterToolArgs("Read", {
+				file_path: "/src/index.ts",
+			});
+			expect(result.summary).toBe("read: /src/index.ts");
+		});
+
+		test("handles missing file_path", () => {
+			const result = filterToolArgs("Read", {});
+			expect(result.summary).toBe("read: ");
+		});
+	});
+
+	describe("Write", () => {
+		test("keeps file_path, drops content", () => {
+			const result = filterToolArgs("Write", {
+				file_path: "/src/index.ts",
+				content: "const x = 1;\nconst y = 2;\n// lots of content...",
+			});
+			expect(result.args).toEqual({ file_path: "/src/index.ts" });
+			expect(result.args).not.toHaveProperty("content");
+		});
+
+		test("summary shows file path", () => {
+			const result = filterToolArgs("Write", {
+				file_path: "/src/index.ts",
+				content: "stuff",
+			});
+			expect(result.summary).toBe("write: /src/index.ts");
+		});
+
+		test("handles missing file_path", () => {
+			const result = filterToolArgs("Write", { content: "data" });
+			expect(result.args).toEqual({});
+			expect(result.summary).toBe("write: ");
+		});
+	});
+
+	describe("Edit", () => {
+		test("keeps file_path, drops old_string and new_string", () => {
+			const result = filterToolArgs("Edit", {
+				file_path: "/src/config.ts",
+				old_string: "const x = 1;",
+				new_string: "const x = 2;",
+			});
+			expect(result.args).toEqual({ file_path: "/src/config.ts" });
+			expect(result.args).not.toHaveProperty("old_string");
+			expect(result.args).not.toHaveProperty("new_string");
+		});
+
+		test("summary shows file path", () => {
+			const result = filterToolArgs("Edit", {
+				file_path: "/src/config.ts",
+				old_string: "a",
+				new_string: "b",
+			});
+			expect(result.summary).toBe("edit: /src/config.ts");
+		});
+	});
+
+	describe("Glob", () => {
+		test("keeps pattern and path", () => {
+			const result = filterToolArgs("Glob", {
+				pattern: "**/*.ts",
+				path: "/src",
+			});
+			expect(result.args).toEqual({ pattern: "**/*.ts", path: "/src" });
+		});
+
+		test("summary with path shows pattern in path", () => {
+			const result = filterToolArgs("Glob", {
+				pattern: "**/*.ts",
+				path: "/src",
+			});
+			expect(result.summary).toBe("glob: **/*.ts in /src");
+		});
+
+		test("summary without path shows only pattern", () => {
+			const result = filterToolArgs("Glob", { pattern: "**/*.ts" });
+			expect(result.summary).toBe("glob: **/*.ts");
+		});
+	});
+
+	describe("Grep", () => {
+		test("keeps pattern, path, glob, output_mode", () => {
+			const result = filterToolArgs("Grep", {
+				pattern: "function\\s+\\w+",
+				path: "/src",
+				glob: "*.ts",
+				output_mode: "content",
+				"-A": 3,
+				"-B": 2,
+			});
+			expect(result.args).toEqual({
+				pattern: "function\\s+\\w+",
+				path: "/src",
+				glob: "*.ts",
+				output_mode: "content",
+			});
+			expect(result.args).not.toHaveProperty("-A");
+			expect(result.args).not.toHaveProperty("-B");
+		});
+
+		test("summary with path shows pattern in path", () => {
+			const result = filterToolArgs("Grep", {
+				pattern: "TODO",
+				path: "/src",
+			});
+			expect(result.summary).toBe('grep: "TODO" in /src');
+		});
+
+		test("summary without path shows only pattern", () => {
+			const result = filterToolArgs("Grep", { pattern: "TODO" });
+			expect(result.summary).toBe('grep: "TODO"');
+		});
+	});
+
+	describe("WebFetch", () => {
+		test("keeps url, drops prompt", () => {
+			const result = filterToolArgs("WebFetch", {
+				url: "https://example.com/page",
+				prompt: "Extract the main content from this page",
+			});
+			expect(result.args).toEqual({ url: "https://example.com/page" });
+			expect(result.args).not.toHaveProperty("prompt");
+		});
+
+		test("summary shows url", () => {
+			const result = filterToolArgs("WebFetch", {
+				url: "https://example.com",
+			});
+			expect(result.summary).toBe("fetch: https://example.com");
+		});
+	});
+
+	describe("WebSearch", () => {
+		test("keeps query, drops domain filters", () => {
+			const result = filterToolArgs("WebSearch", {
+				query: "TypeScript strict mode",
+				allowed_domains: ["developer.mozilla.org"],
+				blocked_domains: ["w3schools.com"],
+			});
+			expect(result.args).toEqual({ query: "TypeScript strict mode" });
+			expect(result.args).not.toHaveProperty("allowed_domains");
+			expect(result.args).not.toHaveProperty("blocked_domains");
+		});
+
+		test("summary shows query", () => {
+			const result = filterToolArgs("WebSearch", {
+				query: "bun test runner",
+			});
+			expect(result.summary).toBe("search: bun test runner");
+		});
+	});
+
+	describe("Task", () => {
+		test("keeps description and subagent_type", () => {
+			const result = filterToolArgs("Task", {
+				description: "Analyze the codebase structure",
+				subagent_type: "research",
+				prompt: "Look at all the files and determine...",
+			});
+			expect(result.args).toEqual({
+				description: "Analyze the codebase structure",
+				subagent_type: "research",
+			});
+			expect(result.args).not.toHaveProperty("prompt");
+		});
+
+		test("summary with subagent_type shows description and type", () => {
+			const result = filterToolArgs("Task", {
+				description: "Find all config files",
+				subagent_type: "research",
+			});
+			expect(result.summary).toBe("task: Find all config files (research)");
+		});
+
+		test("summary without subagent_type shows only description", () => {
+			const result = filterToolArgs("Task", {
+				description: "Find all config files",
+			});
+			expect(result.summary).toBe("task: Find all config files");
+		});
+	});
+
+	describe("unknown tools", () => {
+		test("returns empty args and tool name as summary", () => {
+			const result = filterToolArgs("SomeUnknownTool", {
+				foo: "bar",
+				baz: 42,
+			});
+			expect(result.args).toEqual({});
+			expect(result.summary).toBe("SomeUnknownTool");
+		});
+
+		test("handles empty input for unknown tool", () => {
+			const result = filterToolArgs("Mystery", {});
+			expect(result.args).toEqual({});
+			expect(result.summary).toBe("Mystery");
+		});
+	});
+
+	describe("edge cases", () => {
+		test("handles empty input object for known tool", () => {
+			const result = filterToolArgs("Bash", {});
+			expect(result.args).toEqual({});
+			expect(result.summary).toBe("bash: ");
+		});
+
+		test("handles null values in input", () => {
+			const result = filterToolArgs("Read", {
+				file_path: null as unknown as string,
+				offset: null as unknown as number,
+			});
+			// null is not undefined, so file_path will be picked but summary treats it as non-string
+			expect(result.args).toHaveProperty("file_path");
+			expect(result.summary).toBe("read: ");
+		});
+
+		test("handles undefined values in input", () => {
+			const result = filterToolArgs("Read", {
+				file_path: undefined as unknown as string,
+			});
+			// undefined values should not appear in filtered args
+			expect(result.args).not.toHaveProperty("file_path");
+			expect(result.summary).toBe("read: ");
+		});
+
+		test("handles numeric values where strings expected", () => {
+			const result = filterToolArgs("Bash", {
+				command: 42 as unknown as string,
+			});
+			// Value is kept in args as-is, but summary treats non-strings as empty
+			expect(result.args).toEqual({ command: 42 });
+			expect(result.summary).toBe("bash: ");
+		});
+
+		test("preserves exact 80-char command without truncation", () => {
+			const cmd = "x".repeat(80);
+			const result = filterToolArgs("Bash", { command: cmd });
+			expect(result.summary).toBe(`bash: ${cmd}`);
+			expect(result.summary).not.toContain("...");
+		});
+
+		test("truncates 81-char command", () => {
+			const cmd = "y".repeat(81);
+			const result = filterToolArgs("Bash", { command: cmd });
+			expect(result.summary).toBe(`bash: ${"y".repeat(80)}...`);
+		});
+	});
+});