@os-eco/overstory-cli 0.6.1

package/src/events/store.ts

@@ -0,0 +1,369 @@
+/**
+ * SQLite-backed event store for agent activity observability.
+ *
+ * Tracks tool invocations, session lifecycle, mail events, and errors.
+ * Uses bun:sqlite for zero-dependency, synchronous database access.
+ * WAL mode enables concurrent reads from multiple agent processes.
+ */
+
+import { Database } from "bun:sqlite";
+import type {
+	EventLevel,
+	EventQueryOptions,
+	EventStore,
+	InsertEvent,
+	StoredEvent,
+	ToolStats,
+} from "../types.ts";
+
+/** Row shape as stored in SQLite (snake_case columns). */
+interface EventRow {
+	id: number;
+	run_id: string | null;
+	agent_name: string;
+	session_id: string | null;
+	event_type: string;
+	tool_name: string | null;
+	tool_args: string | null;
+	tool_duration_ms: number | null;
+	level: string;
+	data: string | null;
+	created_at: string;
+}
+
+const CREATE_TABLE = `
+CREATE TABLE IF NOT EXISTS events (
+  id INTEGER PRIMARY KEY AUTOINCREMENT,
+  run_id TEXT,
+  agent_name TEXT NOT NULL,
+  session_id TEXT,
+  event_type TEXT NOT NULL,
+  tool_name TEXT,
+  tool_args TEXT,
+  tool_duration_ms INTEGER,
+  level TEXT NOT NULL DEFAULT 'info' CHECK(level IN ('debug','info','warn','error')),
+  data TEXT,
+  created_at TEXT NOT NULL DEFAULT (strftime('%Y-%m-%dT%H:%M:%f','now'))
+)`;
+
+const CREATE_INDEXES = `
+CREATE INDEX IF NOT EXISTS idx_events_agent_time ON events(agent_name, created_at);
+CREATE INDEX IF NOT EXISTS idx_events_run_time ON events(run_id, created_at);
+CREATE INDEX IF NOT EXISTS idx_events_type_time ON events(event_type, created_at);
+CREATE INDEX IF NOT EXISTS idx_events_tool_agent ON events(tool_name, agent_name);
+CREATE INDEX IF NOT EXISTS idx_events_level_error ON events(level) WHERE level = 'error'`;
+
+/** Convert a database row (snake_case) to a StoredEvent object (camelCase). */
+function rowToEvent(row: EventRow): StoredEvent {
+	return {
+		id: row.id,
+		runId: row.run_id,
+		agentName: row.agent_name,
+		sessionId: row.session_id,
+		eventType: row.event_type as StoredEvent["eventType"],
+		toolName: row.tool_name,
+		toolArgs: row.tool_args,
+		toolDurationMs: row.tool_duration_ms,
+		level: row.level as EventLevel,
+		data: row.data,
+		createdAt: row.created_at,
+	};
+}
+
+/** Build WHERE clause fragments and params from EventQueryOptions. */
+function buildFilterClauses(
+	opts: EventQueryOptions | undefined,
+	existingConditions: string[] = [],
+	existingParams: Record<string, string | number> = {},
+): { whereClause: string; params: Record<string, string | number>; limitClause: string } {
+	const conditions = [...existingConditions];
+	const params = { ...existingParams };
+
+	if (opts?.since !== undefined) {
+		conditions.push("created_at >= $since");
+		params.$since = opts.since;
+	}
+	if (opts?.until !== undefined) {
+		conditions.push("created_at <= $until");
+		params.$until = opts.until;
+	}
+	if (opts?.level !== undefined) {
+		conditions.push("level = $level");
+		params.$level = opts.level;
+	}
+
+	const whereClause = conditions.length > 0 ? `WHERE ${conditions.join(" AND ")}` : "";
+	const limitClause = opts?.limit !== undefined ? `LIMIT ${opts.limit}` : "";
+
+	return { whereClause, params, limitClause };
+}
+
+/**
+ * Create a new EventStore backed by a SQLite database at the given path.
+ *
+ * Initializes the database with WAL mode and a 5-second busy timeout.
+ * Creates the events table and indexes if they do not already exist.
+ */
+export function createEventStore(dbPath: string): EventStore {
+	const db = new Database(dbPath);
+
+	// Configure for concurrent access from multiple agent processes.
+	db.exec("PRAGMA journal_mode = WAL");
+	db.exec("PRAGMA synchronous = NORMAL");
+	db.exec("PRAGMA busy_timeout = 5000");
+
+	// Create schema
+	db.exec(CREATE_TABLE);
+	db.exec(CREATE_INDEXES);
+
+	// Prepare the insert statement
+	const insertStmt = db.prepare<
+		{ id: number },
+		{
+			$run_id: string | null;
+			$agent_name: string;
+			$session_id: string | null;
+			$event_type: string;
+			$tool_name: string | null;
+			$tool_args: string | null;
+			$tool_duration_ms: number | null;
+			$level: string;
+			$data: string | null;
+		}
+	>(`
+		INSERT INTO events
+			(run_id, agent_name, session_id, event_type, tool_name, tool_args, tool_duration_ms, level, data)
+		VALUES
+			($run_id, $agent_name, $session_id, $event_type, $tool_name, $tool_args, $tool_duration_ms, $level, $data)
+		RETURNING id
+	`);
+
+	// Prepare correlateToolEnd: find the most recent tool_start for this agent+tool
+	// that has no corresponding tool_end yet (no tool_duration_ms set).
+	const correlateStmt = db.prepare<
+		{ id: number; created_at: string },
+		{ $agent_name: string; $tool_name: string }
+	>(`
+		SELECT id, created_at FROM events
+		WHERE agent_name = $agent_name
+		  AND tool_name = $tool_name
+		  AND event_type = 'tool_start'
+		  AND tool_duration_ms IS NULL
+		ORDER BY created_at DESC
+		LIMIT 1
+	`);
+
+	const updateDurationStmt = db.prepare<void, { $id: number; $duration_ms: number }>(`
+		UPDATE events SET tool_duration_ms = $duration_ms WHERE id = $id
+	`);
+
+	// Prepare getByAgent
+	const byAgentStmt = db.prepare<EventRow, { $agent_name: string }>(`
+		SELECT * FROM events WHERE agent_name = $agent_name ORDER BY created_at ASC
+	`);
+
+	// Prepare getByRun
+	const byRunStmt = db.prepare<EventRow, { $run_id: string }>(`
+		SELECT * FROM events WHERE run_id = $run_id ORDER BY created_at ASC
+	`);
+
+	return {
+		insert(event: InsertEvent): number {
+			const row = insertStmt.get({
+				$run_id: event.runId,
+				$agent_name: event.agentName,
+				$session_id: event.sessionId,
+				$event_type: event.eventType,
+				$tool_name: event.toolName,
+				$tool_args: event.toolArgs,
+				$tool_duration_ms: event.toolDurationMs,
+				$level: event.level,
+				$data: event.data,
+			});
+			// RETURNING id always returns a row for INSERT; if somehow null, fallback to 0
+			if (!row) {
+				return 0;
+			}
+			return row.id;
+		},
+
+		correlateToolEnd(
+			agentName: string,
+			toolName: string,
+		): { startId: number; durationMs: number } | null {
+			const startRow = correlateStmt.get({
+				$agent_name: agentName,
+				$tool_name: toolName,
+			});
+
+			if (!startRow) {
+				return null;
+			}
+
+			const startTime = new Date(startRow.created_at).getTime();
+			const durationMs = Date.now() - startTime;
+
+			// Mark the start event with the computed duration
+			updateDurationStmt.run({
+				$id: startRow.id,
+				$duration_ms: durationMs,
+			});
+
+			return { startId: startRow.id, durationMs };
+		},
+
+		getByAgent(agentName: string, opts?: EventQueryOptions): StoredEvent[] {
+			if (
+				opts !== undefined &&
+				(opts.since !== undefined ||
+					opts.until !== undefined ||
+					opts.level !== undefined ||
+					opts.limit !== undefined)
+			) {
+				// Use dynamic query with filters
+				const { whereClause, params, limitClause } = buildFilterClauses(
+					opts,
+					["agent_name = $agent_name"],
+					{ $agent_name: agentName },
+				);
+				const query = `SELECT * FROM events ${whereClause} ORDER BY created_at ASC ${limitClause}`;
+				const rows = db.prepare<EventRow, Record<string, string | number>>(query).all(params);
+				return rows.map(rowToEvent);
+			}
+			const rows = byAgentStmt.all({ $agent_name: agentName });
+			return rows.map(rowToEvent);
+		},
+
+		getByRun(runId: string, opts?: EventQueryOptions): StoredEvent[] {
+			if (
+				opts !== undefined &&
+				(opts.since !== undefined ||
+					opts.until !== undefined ||
+					opts.level !== undefined ||
+					opts.limit !== undefined)
+			) {
+				const { whereClause, params, limitClause } = buildFilterClauses(
+					opts,
+					["run_id = $run_id"],
+					{ $run_id: runId },
+				);
+				const query = `SELECT * FROM events ${whereClause} ORDER BY created_at ASC ${limitClause}`;
+				const rows = db.prepare<EventRow, Record<string, string | number>>(query).all(params);
+				return rows.map(rowToEvent);
+			}
+			const rows = byRunStmt.all({ $run_id: runId });
+			return rows.map(rowToEvent);
+		},
+
+		getErrors(opts?: EventQueryOptions): StoredEvent[] {
+			const { whereClause, params, limitClause } = buildFilterClauses(opts, ["level = 'error'"]);
+			const query = `SELECT * FROM events ${whereClause} ORDER BY created_at DESC ${limitClause}`;
+			const rows = db.prepare<EventRow, Record<string, string | number>>(query).all(params);
+			return rows.map(rowToEvent);
+		},
+
+		getTimeline(opts: EventQueryOptions & { since: string }): StoredEvent[] {
+			const { whereClause, params, limitClause } = buildFilterClauses(opts);
+			const query = `SELECT * FROM events ${whereClause} ORDER BY created_at ASC ${limitClause}`;
+			const rows = db.prepare<EventRow, Record<string, string | number>>(query).all(params);
+			return rows.map(rowToEvent);
+		},
+
+		getToolStats(opts?: { agentName?: string; since?: string }): ToolStats[] {
+			const conditions: string[] = ["tool_name IS NOT NULL", "event_type = 'tool_start'"];
+			const params: Record<string, string> = {};
+
+			if (opts?.agentName !== undefined) {
+				conditions.push("agent_name = $agent_name");
+				params.$agent_name = opts.agentName;
+			}
+			if (opts?.since !== undefined) {
+				conditions.push("created_at >= $since");
+				params.$since = opts.since;
+			}
+
+			const whereClause = `WHERE ${conditions.join(" AND ")}`;
+			const query = `
+				SELECT
+					tool_name,
+					COUNT(*) AS count,
+					COALESCE(AVG(tool_duration_ms), 0) AS avg_duration_ms,
+					COALESCE(MAX(tool_duration_ms), 0) AS max_duration_ms
+				FROM events
+				${whereClause}
+				GROUP BY tool_name
+				ORDER BY count DESC
+			`;
+			const rows = db
+				.prepare<
+					{
+						tool_name: string;
+						count: number;
+						avg_duration_ms: number;
+						max_duration_ms: number;
+					},
+					Record<string, string>
+				>(query)
+				.all(params);
+
+			return rows.map((row) => ({
+				toolName: row.tool_name,
+				count: row.count,
+				avgDurationMs: row.avg_duration_ms,
+				maxDurationMs: row.max_duration_ms,
+			}));
+		},
+
+		purge(opts: { all?: boolean; olderThanMs?: number; agentName?: string }): number {
+			if (opts.all) {
+				const countRow = db
+					.prepare<{ cnt: number }, []>("SELECT COUNT(*) as cnt FROM events")
+					.get();
+				const count = countRow?.cnt ?? 0;
+				db.prepare("DELETE FROM events").run();
+				return count;
+			}
+
+			const conditions: string[] = [];
+			const params: Record<string, string> = {};
+
+			if (opts.olderThanMs !== undefined) {
+				const cutoff = new Date(Date.now() - opts.olderThanMs).toISOString();
+				conditions.push("created_at < $cutoff");
+				params.$cutoff = cutoff;
+			}
+
+			if (opts.agentName !== undefined) {
+				conditions.push("agent_name = $agent_name");
+				params.$agent_name = opts.agentName;
+			}
+
+			if (conditions.length === 0) {
+				return 0;
+			}
+
+			const whereClause = conditions.join(" AND ");
+			const countRow = db
+				.prepare<{ cnt: number }, Record<string, string>>(
+					`SELECT COUNT(*) as cnt FROM events WHERE ${whereClause}`,
+				)
+				.get(params);
+			const count = countRow?.cnt ?? 0;
+
+			db.prepare<void, Record<string, string>>(`DELETE FROM events WHERE ${whereClause}`).run(
+				params,
+			);
+
+			return count;
+		},
+
+		close(): void {
+			try {
+				db.exec("PRAGMA wal_checkpoint(PASSIVE)");
+			} catch {
+				// Best effort -- checkpoint failure is non-fatal
+			}
+			db.close();
+		},
+	};
+}

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)}...`);
+		});
+	});
+});