pi-crew 0.5.1 → 0.5.2

package/src/state/instinct-store.ts

@@ -0,0 +1,249 @@
+import * as fs from "node:fs";
+import * as path from "node:path";
+import { randomUUID } from "node:crypto";
+
+/**
+ * Represents a learned instinct that guides agent behavior.
+ * Instincts can be project-scoped or global.
+ */
+export interface Instinct {
+	/** Unique identifier for this instinct */
+	id: string;
+	/** What triggers this instinct */
+	trigger: string;
+	/** What action to take when triggered */
+	action: string;
+	/** Confidence level: 0.3 (low), 0.6 (medium), 0.9 (high) */
+	confidence: 0.3 | 0.6 | 0.9;
+	/** Whether this instinct applies to a project or globally */
+	scope: "project" | "global";
+	/** Project identifier (undefined for global instincts) */
+	projectId?: string;
+	/** ISO timestamp of when this instinct was created */
+	createdAt: string;
+	/** Examples/evidence supporting this instinct */
+	evidence: string[];
+}
+
+/** Input type for creating a new instinct (excludes auto-generated fields) */
+export type NewInstinct = Omit<Instinct, "id" | "createdAt">;
+
+const INSTINCT_FILE = "instincts.jsonl";
+
+/**
+ * InstinctStore manages persistence of learned instincts using JSONL files.
+ * - Project instincts: `.crew/instincts/projects/{projectId}/instincts.jsonl`
+ * - Global instincts: `.crew/instincts/global/instincts.jsonl`
+ */
+export class InstinctStore {
+	private readonly crewRoot: string;
+
+	constructor(crewRoot: string) {
+		this.crewRoot = crewRoot;
+	}
+
+	/**
+	 * Get the file path for project instincts
+	 */
+	private getProjectInstinctPath(projectId: string): string {
+		return path.join(this.crewRoot, "instincts", "projects", projectId, INSTINCT_FILE);
+	}
+
+	/**
+	 * Get the file path for global instincts
+	 */
+	private getGlobalInstinctPath(): string {
+		return path.join(this.crewRoot, "instincts", "global", INSTINCT_FILE);
+	}
+
+	/**
+	 * Ensure a directory exists, creating it recursively if needed
+	 */
+	private ensureDir(dirPath: string): void {
+		fs.mkdirSync(dirPath, { recursive: true });
+	}
+
+	/**
+	 * Parse a JSONL file and return all instincts
+	 */
+	private readInstinctsFromFile(filePath: string): Instinct[] {
+		if (!fs.existsSync(filePath)) {
+			return [];
+		}
+		try {
+			const content = fs.readFileSync(filePath, "utf-8");
+			const lines = content.split("\n").filter((line) => line.trim() !== "");
+			return lines.map((line) => JSON.parse(line) as Instinct);
+		} catch {
+			// If file is corrupted, return empty array
+			return [];
+		}
+	}
+
+	/**
+	 * Append a single instinct to a JSONL file
+	 */
+	private appendInstinctToFile(filePath: string, instinct: Instinct): void {
+		const dir = path.dirname(filePath);
+		this.ensureDir(dir);
+		fs.appendFileSync(filePath, `${JSON.stringify(instinct)}\n`, "utf-8");
+	}
+
+	/**
+	 * Rewrite a JSONL file with the given instincts
+	 */
+	private rewriteFile(filePath: string, instincts: Instinct[]): void {
+		const dir = path.dirname(filePath);
+		this.ensureDir(dir);
+		const content = instincts.map((i) => JSON.stringify(i)).join("\n") + "\n";
+		fs.writeFileSync(filePath, content, "utf-8");
+	}
+
+	/**
+	 * Save a new instinct with auto-generated id and timestamp.
+	 * Direct scope is determined by the instinct's scope field.
+	 *
+	 * @param instinct - The instinct to save (without id and createdAt)
+	 * @returns The saved instinct with generated id and createdAt
+	 */
+	saveInstinct(instinct: NewInstinct): Instinct {
+		const savedInstinct: Instinct = {
+			...instinct,
+			id: randomUUID(),
+			createdAt: new Date().toISOString(),
+		};
+
+		if (savedInstinct.scope === "global") {
+			savedInstinct.projectId = undefined;
+			this.appendInstinctToFile(this.getGlobalInstinctPath(), savedInstinct);
+		} else {
+			if (!savedInstinct.projectId) {
+				throw new Error("Project-scoped instinct requires a projectId");
+			}
+			this.appendInstinctToFile(this.getProjectInstinctPath(savedInstinct.projectId), savedInstinct);
+		}
+
+		return savedInstinct;
+	}
+
+	/**
+	 * Get all instincts, optionally filtered by scope.
+	 *
+	 * @param scope - Optional filter: 'project' or 'global'
+	 * @returns Array of instincts matching the filter
+	 */
+	getInstincts(scope?: "project" | "global"): Instinct[] {
+		const results: Instinct[] = [];
+
+		if (!scope || scope === "project") {
+			const projectsDir = path.join(this.crewRoot, "instincts", "projects");
+			if (fs.existsSync(projectsDir)) {
+				for (const projectId of fs.readdirSync(projectsDir, { withFileTypes: true }).filter((e) => e.isDirectory()).map((e) => e.name)) {
+					const filePath = path.join(projectsDir, projectId, INSTINCT_FILE);
+					results.push(...this.readInstinctsFromFile(filePath));
+				}
+			}
+		}
+
+		if (!scope || scope === "global") {
+			results.push(...this.readInstinctsFromFile(this.getGlobalInstinctPath()));
+		}
+
+		return results;
+	}
+
+	/**
+	 * Get all instincts for a specific project.
+	 * Includes both project-scoped instincts and global instincts.
+	 *
+	 * @param projectId - The project identifier
+	 * @returns Array of instincts for the project
+	 */
+	getProjectInstincts(projectId: string): Instinct[] {
+		const projectInstincts = this.readInstinctsFromFile(this.getProjectInstinctPath(projectId));
+		const globalInstincts = this.readInstinctsFromFile(this.getGlobalInstinctPath());
+		return [...projectInstincts, ...globalInstincts];
+	}
+
+	/**
+	 * Promote a project-scoped instinct to global scope.
+	 * Creates a copy in global instincts and removes from project.
+	 *
+	 * @param instinctId - The instinct id to promote
+	 * @returns The promoted instinct, or null if not found
+	 */
+	promoteInstinct(instinctId: string): Instinct | null {
+		// Search in all project instinct files
+		const projectsDir = path.join(this.crewRoot, "instincts", "projects");
+		if (fs.existsSync(projectsDir)) {
+			for (const projectId of fs.readdirSync(projectsDir, { withFileTypes: true }).filter((e) => e.isDirectory()).map((e) => e.name)) {
+				const filePath = path.join(projectsDir, projectId, INSTINCT_FILE);
+				const instincts = this.readInstinctsFromFile(filePath);
+				const index = instincts.findIndex((i) => i.id === instinctId);
+
+				if (index !== -1) {
+					const instinct = instincts[index];
+
+					// Create promoted version (global)
+					const promotedInstinct: Instinct = {
+						...instinct,
+						id: randomUUID(), // New id for promoted instinct
+						scope: "global",
+						projectId: undefined,
+						createdAt: new Date().toISOString(),
+					};
+
+					// Add to global instincts
+					this.appendInstinctToFile(this.getGlobalInstinctPath(), promotedInstinct);
+
+					// Remove from project instincts
+					const updatedInstincts = instincts.filter((i) => i.id !== instinctId);
+					this.rewriteFile(filePath, updatedInstincts);
+
+					return promotedInstinct;
+				}
+			}
+		}
+
+		return null;
+	}
+
+	/**
+	 * Delete an instinct by id.
+	 *
+	 * @param instinctId - The instinct id to delete
+	 * @returns true if deleted, false if not found
+	 */
+	deleteInstinct(instinctId: string): boolean {
+		// Search in global instincts first
+		const globalPath = this.getGlobalInstinctPath();
+		let instincts = this.readInstinctsFromFile(globalPath);
+		let index = instincts.findIndex((i) => i.id === instinctId);
+
+		if (index !== -1) {
+			const updatedInstincts = instincts.filter((i) => i.id !== instinctId);
+			this.rewriteFile(globalPath, updatedInstincts);
+			return true;
+		}
+
+		// Search in project instincts
+		const projectsDir = path.join(this.crewRoot, "instincts", "projects");
+		if (fs.existsSync(projectsDir)) {
+			for (const projectId of fs.readdirSync(projectsDir, { withFileTypes: true }).filter((e) => e.isDirectory()).map((e) => e.name)) {
+				const filePath = path.join(projectsDir, projectId, INSTINCT_FILE);
+				instincts = this.readInstinctsFromFile(filePath);
+				index = instincts.findIndex((i) => i.id === instinctId);
+
+				if (index !== -1) {
+					const updatedInstincts = instincts.filter((i) => i.id !== instinctId);
+					this.rewriteFile(filePath, updatedInstincts);
+					return true;
+				}
+			}
+		}
+
+		return false;
+	}
+}
+
+export { getGlobalStorageDir, getProjectStorageDir } from "../utils/project-detector.ts";

package/src/state/run-metrics.ts

@@ -0,0 +1,135 @@
+import * as fs from "node:fs";
+import * as path from "node:path";
+import { loadRunManifestById } from "./state-store.ts";
+import { projectCrewRoot, userCrewRoot } from "../utils/paths.ts";
+import { atomicWriteJson, readJsonFile } from "./atomic-write.ts";
+import { DEFAULT_PATHS } from "../config/defaults.ts";
+
+/**
+ * Run metrics snapshot captured after a run completes (or on demand).
+ */
+export interface RunMetrics {
+	runId: string;
+	timestamp: string;
+	taskCount: number;
+	completedCount: number;
+	failedCount: number;
+	totalTokens: number;
+	totalCost: number;
+	durationMs: number;
+	consistencyScore: number;
+}
+
+/** Number of recent metric files to scan when building a summary. */
+const MAX_METRIC_FILES_TO_SCAN = 500;
+
+function metricsDir(cwd: string): string {
+	const repoRoot = projectCrewRoot(cwd);
+	return path.join(repoRoot, "state", "metrics");
+}
+
+function metricsFilePath(cwd: string, runId: string): string {
+	return path.join(metricsDir(cwd), `${runId}.json`);
+}
+
+/**
+ * Collect metrics for a run by reading its manifest, tasks, and event log.
+ * Returns undefined if the run cannot be loaded.
+ */
+export function collectRunMetrics(cwd: string, runId: string): RunMetrics | undefined {
+	const result = loadRunManifestById(cwd, runId);
+	if (!result) return undefined;
+
+	const { manifest, tasks } = result;
+	const now = new Date().toISOString();
+
+	// Aggregate token/cost from all tasks that have usage data.
+	let totalTokens = 0;
+	let totalCost = 0;
+	for (const task of tasks) {
+		if (task.usage) {
+			totalTokens += (task.usage.input ?? 0) + (task.usage.output ?? 0);
+			totalCost += task.usage.cost ?? 0;
+		}
+	}
+
+	// Count completed vs failed tasks.
+	let completedCount = 0;
+	let failedCount = 0;
+	for (const task of tasks) {
+		if (task.status === "completed") completedCount++;
+		else if (task.status === "failed") failedCount++;
+	}
+
+	// Duration: from run createdAt to updatedAt (manifest timestamps), or 0 if unavailable.
+	const createdAt = new Date(manifest.createdAt).getTime();
+	const updatedAt = new Date(manifest.updatedAt).getTime();
+	const durationMs = isNaN(createdAt) || isNaN(updatedAt) ? 0 : Math.max(0, updatedAt - createdAt);
+
+	// Consistency score: proportion of tasks that completed successfully among all non-skipped tasks.
+	const nonSkippedTasks = tasks.filter((t) => t.status !== "skipped");
+	const consistencyScore = nonSkippedTasks.length > 0 ? completedCount / nonSkippedTasks.length : 1.0;
+
+	return {
+		runId,
+		timestamp: now,
+		taskCount: tasks.length,
+		completedCount,
+		failedCount,
+		totalTokens,
+		totalCost,
+		durationMs,
+		consistencyScore: Math.round(consistencyScore * 1000) / 1000, // 3 decimal places
+	};
+}
+
+/**
+ * Persist a metrics snapshot to .crew/state/metrics/<runId>.json.
+ * Uses atomicWriteJson to ensure safe writes.
+ */
+export function saveRunMetrics(cwd: string, metrics: RunMetrics): void {
+	const dir = metricsDir(cwd);
+	fs.mkdirSync(dir, { recursive: true });
+	atomicWriteJson(metricsFilePath(cwd, metrics.runId), metrics);
+}
+
+/**
+ * Load a previously saved metrics snapshot.
+ * Returns undefined if the file does not exist or cannot be parsed.
+ */
+export function loadRunMetrics(cwd: string, runId: string): RunMetrics | undefined {
+	return readJsonFile<RunMetrics>(metricsFilePath(cwd, runId));
+}
+
+/**
+ * List recent metrics files up to `limit` entries (newest first).
+ * Returns an array of { runId, timestamp, taskCount, completedCount, failedCount, totalTokens, totalCost, durationMs, consistencyScore }.
+ * Gracefully skips files that cannot be read or parsed.
+ */
+export function getRunMetricsSummary(cwd: string, limit = 25): RunMetrics[] {
+	const dir = metricsDir(cwd);
+	let entries: fs.Dirent[] = [];
+	try {
+		entries = fs.readdirSync(dir, { withFileTypes: true });
+	} catch {
+		return [];
+	}
+
+	const metrics: RunMetrics[] = [];
+	for (const entry of entries) {
+		if (!entry.isFile() || !entry.name.endsWith(".json")) continue;
+		const runId = entry.name.replace(/\.json$/, "");
+		const m = loadRunMetrics(cwd, runId);
+		if (m) metrics.push(m);
+		if (metrics.length >= MAX_METRIC_FILES_TO_SCAN) break;
+	}
+
+	// Sort newest first (by timestamp, then runId as tiebreaker).
+	metrics.sort((a, b) => {
+		const diff = new Date(b.timestamp).getTime() - new Date(a.timestamp).getTime();
+		if (diff !== 0) return diff;
+		return b.runId.localeCompare(a.runId);
+	});
+
+	return metrics.slice(0, limit);
+}