@os-eco/overstory-cli 0.6.11 → 0.7.2

package/src/metrics/store.test.ts

@@ -399,6 +399,52 @@ describe("getSessionsByRun", () => {
 	});
 });
 
+// === countSessions ===
+
+describe("countSessions", () => {
+	test("returns 0 for empty database", () => {
+		expect(store.countSessions()).toBe(0);
+	});
+
+	test("returns total count of sessions", () => {
+		store.recordSession(makeSession({ agentName: "a1", taskId: "t1" }));
+		store.recordSession(makeSession({ agentName: "a2", taskId: "t2" }));
+		store.recordSession(makeSession({ agentName: "a3", taskId: "t3" }));
+
+		expect(store.countSessions()).toBe(3);
+	});
+
+	test("returns accurate count beyond getRecentSessions default limit", () => {
+		// Insert 25 sessions (more than the default limit of 20)
+		for (let i = 0; i < 25; i++) {
+			store.recordSession(
+				makeSession({
+					agentName: `agent-${i}`,
+					taskId: `task-${i}`,
+					startedAt: new Date(Date.now() + i * 1000).toISOString(),
+				}),
+			);
+		}
+
+		// getRecentSessions is capped at 20 by default
+		expect(store.getRecentSessions().length).toBe(20);
+		// countSessions returns the true total without a cap
+		expect(store.countSessions()).toBe(25);
+	});
+
+	test("count updates after purge", () => {
+		store.recordSession(makeSession({ agentName: "a1", taskId: "t1" }));
+		store.recordSession(makeSession({ agentName: "a2", taskId: "t2" }));
+		expect(store.countSessions()).toBe(2);
+
+		store.purge({ agent: "a1" });
+		expect(store.countSessions()).toBe(1);
+
+		store.purge({ all: true });
+		expect(store.countSessions()).toBe(0);
+	});
+});
+
 // === purge ===
 
 describe("purge", () => {

package/src/metrics/store.ts

@@ -14,6 +14,8 @@ export interface MetricsStore {
 	getSessionsByAgent(agentName: string): SessionMetrics[];
 	getSessionsByRun(runId: string): SessionMetrics[];
 	getAverageDuration(capability?: string): number;
+	/** Count the total number of sessions in the database (no limit cap). */
+	countSessions(): number;
 	/** Delete metrics matching the given criteria. Returns the number of rows deleted. */
 	purge(options: { all?: boolean; agent?: string }): number;
 	/** Record a token usage snapshot for a running agent. */
@@ -252,6 +254,10 @@ export function createMetricsStore(dbPath: string): MetricsStore {
 		SELECT AVG(duration_ms) AS avg_duration FROM sessions WHERE completed_at IS NOT NULL
 	`);
 
+	const countSessionsStmt = db.prepare<{ cnt: number }, Record<string, never>>(`
+		SELECT COUNT(*) as cnt FROM sessions
+	`);
+
 	const avgDurationByCapStmt = db.prepare<
 		{ avg_duration: number | null },
 		{ $capability: string }
@@ -345,6 +351,11 @@ export function createMetricsStore(dbPath: string): MetricsStore {
 			return row?.avg_duration ?? 0;
 		},
 
+		countSessions(): number {
+			const row = countSessionsStmt.get({});
+			return row?.cnt ?? 0;
+		},
+
 		purge(options: { all?: boolean; agent?: string }): number {
 			if (options.all) {
 				const countRow = db

package/src/mulch/client.test.ts

@@ -451,6 +451,26 @@ describe("createMulchClient", () => {
 			const result = await client.search("test", { file: "src/config.ts", sortByScore: true });
 			expect(typeof result).toBe("string");
 		});
+
+		test.skipIf(!hasMulch)("roundtrip: record via API then search and find it", async () => {
+			await initMulch();
+			const addProc = Bun.spawn(["ml", "add", "roundtrip"], {
+				cwd: tempDir,
+				stdout: "pipe",
+				stderr: "pipe",
+			});
+			await addProc.exited;
+
+			const client = createMulchClient(tempDir);
+			await client.record("roundtrip", {
+				type: "convention",
+				description: "unique-roundtrip-marker-xyz",
+			});
+
+			const result = await client.search("unique-roundtrip-marker-xyz");
+			expect(typeof result).toBe("string");
+			expect(result).toContain("unique-roundtrip-marker-xyz");
+		});
 	});
 
 	describe("diff", () => {

package/src/mulch/client.ts

@@ -2,7 +2,11 @@
  * Mulch CLI client.
  *
  * Wraps the `mulch` command-line tool for structured expertise operations.
- * Uses Bun.spawn — zero runtime dependencies.
+ * record(), search(), and query() use the @os-eco/mulch-cli programmatic API
+ * via a variable-based dynamic import so tsc cannot statically resolve the
+ * module (avoiding type errors in mulch's raw .ts source files).
+ * Remaining methods (prime, status, diff, learn, prune, doctor, ready, compact)
+ * remain as Bun.spawn CLI wrappers.
  */
 
 import { AgentError } from "../errors.ts";
@@ -87,6 +91,149 @@ export interface MulchClient {
 	): Promise<MulchCompactResult>;
 }
 
+/**
+ * Local type matching @os-eco/mulch-cli ExpertiseRecord.
+ * Defined locally to avoid tsc following into mulch's raw .ts source
+ * (which conflicts with our noUncheckedIndexedAccess setting).
+ */
+type MulchClassification = "foundational" | "tactical" | "observational";
+
+interface MulchEvidence {
+	commit?: string;
+	date?: string;
+	issue?: string;
+	file?: string;
+	bead?: string;
+}
+
+interface MulchOutcome {
+	status: "success" | "failure" | "partial";
+	duration?: number;
+	test_results?: string;
+	agent?: string;
+	notes?: string;
+	recorded_at?: string;
+}
+
+type MulchExpertiseRecord =
+	| {
+			type: "convention";
+			content: string;
+			classification: MulchClassification;
+			recorded_at: string;
+			id?: string;
+			tags?: string[];
+			evidence?: MulchEvidence;
+			outcomes?: MulchOutcome[];
+			relates_to?: string[];
+			supersedes?: string[];
+	  }
+	| {
+			type: "pattern";
+			name: string;
+			description: string;
+			files?: string[];
+			classification: MulchClassification;
+			recorded_at: string;
+			id?: string;
+			tags?: string[];
+			evidence?: MulchEvidence;
+			outcomes?: MulchOutcome[];
+			relates_to?: string[];
+			supersedes?: string[];
+	  }
+	| {
+			type: "failure";
+			description: string;
+			resolution: string;
+			classification: MulchClassification;
+			recorded_at: string;
+			id?: string;
+			tags?: string[];
+			evidence?: MulchEvidence;
+			outcomes?: MulchOutcome[];
+			relates_to?: string[];
+			supersedes?: string[];
+	  }
+	| {
+			type: "decision";
+			title: string;
+			rationale: string;
+			classification: MulchClassification;
+			recorded_at: string;
+			id?: string;
+			tags?: string[];
+			evidence?: MulchEvidence;
+			outcomes?: MulchOutcome[];
+			relates_to?: string[];
+			supersedes?: string[];
+	  }
+	| {
+			type: "reference";
+			name: string;
+			description: string;
+			files?: string[];
+			classification: MulchClassification;
+			recorded_at: string;
+			id?: string;
+			tags?: string[];
+			evidence?: MulchEvidence;
+			outcomes?: MulchOutcome[];
+			relates_to?: string[];
+			supersedes?: string[];
+	  }
+	| {
+			type: "guide";
+			name: string;
+			description: string;
+			classification: MulchClassification;
+			recorded_at: string;
+			id?: string;
+			tags?: string[];
+			evidence?: MulchEvidence;
+			outcomes?: MulchOutcome[];
+			relates_to?: string[];
+			supersedes?: string[];
+	  };
+
+/**
+ * Interface for mulch programmatic API functions.
+ * Uses a dynamic import with a variable specifier so tsc cannot statically
+ * resolve the module (avoiding type errors in mulch's raw .ts source files).
+ */
+interface MulchProgrammaticApi {
+	recordExpertise(
+		domain: string,
+		record: MulchExpertiseRecord,
+		options?: { force?: boolean; cwd?: string },
+	): Promise<{ action: "created" | "updated" | "skipped"; record: MulchExpertiseRecord }>;
+	searchExpertise(
+		query: string,
+		options?: {
+			domain?: string;
+			type?: string;
+			tag?: string;
+			classification?: string;
+			file?: string;
+			cwd?: string;
+		},
+	): Promise<Array<{ domain: string; records: MulchExpertiseRecord[] }>>;
+	queryDomain(
+		domain: string,
+		options?: { type?: string; classification?: string; file?: string; cwd?: string },
+	): Promise<MulchExpertiseRecord[]>;
+}
+
+const MULCH_PKG = "@os-eco/mulch-cli";
+let _mulchApi: MulchProgrammaticApi | undefined;
+
+async function loadMulchApi(): Promise<MulchProgrammaticApi> {
+	if (!_mulchApi) {
+		_mulchApi = (await import(MULCH_PKG)) as MulchProgrammaticApi;
+	}
+	return _mulchApi;
+}
+
 /**
  * Run a shell command and capture its output.
  */
@@ -105,6 +252,127 @@ async function runCommand(
 	return { stdout, stderr, exitCode };
 }
 
+/**
+ * Build an ExpertiseRecord from record() options.
+ *
+ * CRITICAL MAPPING: --description maps to record.content for convention records,
+ * but to record.description for all other types.
+ */
+function buildExpertiseRecord(options: {
+	type: string;
+	name?: string;
+	description?: string;
+	title?: string;
+	rationale?: string;
+	tags?: string[];
+	classification?: string;
+	evidenceBead?: string;
+	outcomeStatus?: "success" | "failure";
+	outcomeDuration?: number;
+	outcomeTestResults?: string;
+	outcomeAgent?: string;
+}): MulchExpertiseRecord {
+	const base = {
+		classification: (options.classification ?? "tactical") as
+			| "foundational"
+			| "tactical"
+			| "observational",
+		recorded_at: new Date().toISOString(),
+		tags: options.tags,
+		evidence: options.evidenceBead ? { bead: options.evidenceBead } : undefined,
+		outcomes: options.outcomeStatus
+			? [
+					{
+						status: options.outcomeStatus as "success" | "failure" | "partial",
+						duration: options.outcomeDuration,
+						test_results: options.outcomeTestResults,
+						agent: options.outcomeAgent,
+						recorded_at: new Date().toISOString(),
+					},
+				]
+			: undefined,
+	};
+
+	switch (options.type) {
+		case "convention":
+			return { ...base, type: "convention", content: options.description ?? "" };
+		case "pattern":
+			return {
+				...base,
+				type: "pattern",
+				name: options.name ?? "",
+				description: options.description ?? "",
+			};
+		case "failure":
+			return {
+				...base,
+				type: "failure",
+				description: options.description ?? "",
+				resolution: "",
+			};
+		case "decision":
+			return {
+				...base,
+				type: "decision",
+				title: options.title ?? "",
+				rationale: options.rationale ?? "",
+			};
+		case "reference":
+			return {
+				...base,
+				type: "reference",
+				name: options.name ?? "",
+				description: options.description ?? "",
+			};
+		case "guide":
+			return {
+				...base,
+				type: "guide",
+				name: options.name ?? "",
+				description: options.description ?? "",
+			};
+		default:
+			return {
+				...base,
+				type: "convention",
+				content: options.description ?? "",
+			} as MulchExpertiseRecord;
+	}
+}
+
+/**
+ * Format search/query results as a plain string for callers that expect string output.
+ * Preserves behavior for parseConflictPatterns regex in resolver.ts.
+ */
+function formatSearchResults(
+	results: Array<{ domain: string; records: MulchExpertiseRecord[] }>,
+): string {
+	const lines: string[] = [];
+	for (const result of results) {
+		for (const record of result.records) {
+			lines.push(formatRecordText(record));
+		}
+	}
+	return lines.join("\n");
+}
+
+function formatRecordText(record: MulchExpertiseRecord): string {
+	switch (record.type) {
+		case "convention":
+			return record.content;
+		case "pattern":
+			return record.description;
+		case "failure":
+			return record.description;
+		case "decision":
+			return `${record.title}: ${record.rationale}`;
+		case "reference":
+			return record.description;
+		case "guide":
+			return record.description;
+	}
+}
+
 /**
  * Create a MulchClient bound to the given working directory.
  *
@@ -158,61 +426,60 @@ export function createMulchClient(cwd: string): MulchClient {
 		},
 
 		async record(domain, options) {
-			const args = ["record", domain, "--type", options.type];
-			if (options.name) {
-				args.push("--name", options.name);
-			}
-			if (options.description) {
-				args.push("--description", options.description);
-			}
-			if (options.title) {
-				args.push("--title", options.title);
-			}
-			if (options.rationale) {
-				args.push("--rationale", options.rationale);
-			}
-			if (options.tags && options.tags.length > 0) {
-				args.push("--tags", options.tags.join(","));
-			}
-			if (options.classification) {
-				args.push("--classification", options.classification);
-			}
+			// stdin mode: no programmatic API equivalent, fall back to CLI
 			if (options.stdin) {
+				const args = ["record", domain, "--type", options.type];
+				if (options.description) args.push("--description", options.description);
 				args.push("--stdin");
+				await runMulch(args, `record ${domain}`);
+				return;
 			}
-			if (options.evidenceBead) {
-				args.push("--evidence-bead", options.evidenceBead);
-			}
-			if (options.outcomeStatus) {
-				args.push("--outcome-status", options.outcomeStatus);
-			}
-			if (options.outcomeDuration !== undefined) {
-				args.push("--outcome-duration", String(options.outcomeDuration));
-			}
-			if (options.outcomeTestResults) {
-				args.push("--outcome-test-results", options.outcomeTestResults);
-			}
-			if (options.outcomeAgent) {
-				args.push("--outcome-agent", options.outcomeAgent);
+
+			const expertiseRecord = buildExpertiseRecord(options);
+			const api = await loadMulchApi();
+			try {
+				await api.recordExpertise(domain, expertiseRecord, { cwd });
+			} catch (error) {
+				if (error instanceof Error && error.message.includes("not found in config")) {
+					// Auto-create domain (matching mulch CLI 0.6.1+ behavior)
+					await runMulch(["add", domain], `add ${domain}`);
+					await api.recordExpertise(domain, expertiseRecord, { cwd });
+				} else {
+					throw new AgentError(
+						`mulch record ${domain} failed: ${error instanceof Error ? error.message : String(error)}`,
+					);
+				}
 			}
-			await runMulch(args, `record ${domain}`);
 		},
 
 		async query(domain) {
-			const args = ["query"];
-			if (domain) {
-				args.push(domain);
+			if (!domain) {
+				throw new AgentError("mulch query failed (exit 1): domain argument required");
+			}
+			try {
+				const api = await loadMulchApi();
+				const records = await api.queryDomain(domain, { cwd });
+				return formatSearchResults([{ domain, records }]);
+			} catch (error) {
+				throw new AgentError(
+					`mulch query failed: ${error instanceof Error ? error.message : String(error)}`,
+				);
 			}
-			const { stdout } = await runMulch(args, "query");
-			return stdout;
 		},
 
 		async search(query, options) {
-			const args = ["search", query];
-			if (options?.file) args.push("--file", options.file);
-			if (options?.sortByScore) args.push("--sort-by-score");
-			const { stdout } = await runMulch(args, "search");
-			return stdout;
+			try {
+				const api = await loadMulchApi();
+				const results = await api.searchExpertise(query, {
+					file: options?.file,
+					cwd,
+				});
+				return formatSearchResults(results);
+			} catch (error) {
+				throw new AgentError(
+					`mulch search failed: ${error instanceof Error ? error.message : String(error)}`,
+				);
+			}
 		},
 
 		async diff(options) {