pi-crew 0.5.0 → 0.5.2

package/src/state/hook-instinct-bridge.ts

@@ -0,0 +1,90 @@
+/**
+ * Hook-to-instinct bridge - connects crewHooks events to instinct formation.
+ * Auto-initializes when imported.
+ */
+
+import { crewHooks } from "../runtime/crew-hooks.ts";
+
+// Lazy-initialized store and paths
+let storeInstance: import("./instinct-store").InstinctStore | null = null;
+let pathsInstance: typeof import("../utils/paths") | null = null;
+
+async function getStore() {
+	if (!storeInstance) {
+		const { InstinctStore } = await import("./instinct-store");
+		const paths = await import("../utils/paths");
+		storeInstance = new InstinctStore(paths.projectCrewRoot(process.cwd()));
+	}
+	return storeInstance;
+}
+
+async function getPaths() {
+	if (!pathsInstance) {
+		pathsInstance = await import("../utils/paths");
+	}
+	return pathsInstance;
+}
+
+// Subscribe to events
+crewHooks.register("task_completed", async (event) => {
+	try {
+		const store = await getStore();
+		if (event.data?.role) {
+			store.saveInstinct({
+				trigger: `role:${event.data.role}`,
+				action: "prefer",
+				confidence: 0.6,
+				scope: "global",
+				evidence: [`task:${event.taskId} completed`],
+			});
+		}
+	} catch {
+		// Best-effort - don't crash on instinct formation failures
+	}
+});
+
+crewHooks.register("task_failed", async (event) => {
+	try {
+		const store = await getStore();
+		if (event.data?.role) {
+			store.saveInstinct({
+				trigger: `role:${event.data.role}`,
+				action: "avoid",
+				confidence: 0.3,
+				scope: "global",
+				evidence: [`task:${event.taskId} failed`],
+			});
+		}
+	} catch {
+		// Best-effort
+	}
+});
+
+crewHooks.register("run_completed", async (event) => {
+	try {
+		const store = await getStore();
+		if (event.data?.taskCount) {
+			store.saveInstinct({
+				trigger: "run_completed",
+				action: `completed:${event.data.taskCount}tasks`,
+				confidence: 0.6,
+				scope: "global",
+				evidence: [`run:${event.runId}`],
+			});
+		}
+	} catch {
+		// Best-effort
+	}
+});
+
+/**
+ * Get instinct-based recommendations.
+ */
+export async function getInstinctRecommendations() {
+	try {
+		const store = await getStore();
+		return store.getInstincts().filter((i: { confidence: number }) => i.confidence >= 0.6);
+	} catch {
+		return [];
+	}
+}

package/src/state/hook-integrations.ts

@@ -0,0 +1,51 @@
+/**
+ * Hook integrations - subscribes to crewHooks and provides observability.
+ * Auto-initializes when imported.
+ */
+
+import { crewHooks } from "../runtime/crew-hooks.ts";
+
+// Statistics
+let tasksCompleted = 0;
+let tasksFailed = 0;
+let runsCompleted = 0;
+let runsFailed = 0;
+
+// Subscribe to events (fire-and-forget)
+crewHooks.register("task_completed", () => {
+	tasksCompleted++;
+});
+
+crewHooks.register("task_failed", () => {
+	tasksFailed++;
+});
+
+crewHooks.register("run_completed", () => {
+	runsCompleted++;
+});
+
+crewHooks.register("run_failed", () => {
+	runsFailed++;
+});
+
+/**
+ * Get current hook statistics.
+ */
+export function getHookStats(): {
+	tasksCompleted: number;
+	tasksFailed: number;
+	runsCompleted: number;
+	runsFailed: number;
+} {
+	return { tasksCompleted, tasksFailed, runsCompleted, runsFailed };
+}
+
+/**
+ * Reset statistics (useful for testing).
+ */
+export function resetHookStats(): void {
+	tasksCompleted = 0;
+	tasksFailed = 0;
+	runsCompleted = 0;
+	runsFailed = 0;
+}

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-graph.ts

@@ -57,7 +57,6 @@ export function buildRunGraph(
       workflow: manifest.workflow,
       status: manifest.status,
       createdAt: manifest.createdAt,
-      completedAt: (manifest as Record<string, unknown>).completedAt,
     },
   });
   nodeIds.add(`run:${runId}`);
@@ -73,10 +72,7 @@ export function buildRunGraph(
       type: "task",
       name: task.role,
       metadata: {
-        phase: (task as Record<string, unknown>).phase,
         status: task.status,
-        agentModel: (task as Record<string, unknown>).agentModel,
-        usage: (task as Record<string, unknown>).usage,
         startedAt: task.startedAt,
         finishedAt: task.finishedAt,
       },
@@ -99,29 +95,14 @@ export function buildRunGraph(
       });
     }
 
-    // Edge from task to agent (if we have agent model info)
-    const agentModel = (task as Record<string, unknown>).agentModel as string | undefined;
-    if (agentModel) {
-      const agentId = `agent:${agentModel.replace(/[^a-zA-Z0-9-_]/g, "_")}`;
-      if (!nodeIds.has(agentId)) {
-        nodeIds.add(agentId);
-        nodes.push({ id: agentId, type: "agent", name: agentModel });
-      }
-      edges.push({
-        source: agentId,
-        target: taskId,
-        type: "runs",
-        weight: 0.9,
-      });
-    }
   }
 
-  // Group by layer (based on phase)
+  // Group by layer (based on phase or role)
   const layerMap = new Map<string, string[]>();
   for (const task of tasks) {
-    const phase = ((task as Record<string, unknown>).phase as string) ?? "unknown";
-    if (!layerMap.has(phase)) layerMap.set(phase, []);
-    layerMap.get(phase)!.push(`task:${task.id}`);
+    const layerName = task.adaptive?.phase ?? task.role;
+    if (!layerMap.has(layerName)) layerMap.set(layerName, []);
+    layerMap.get(layerName)!.push(`task:${task.id}`);
   }
 
   const layers: RunGraphLayer[] = [...layerMap.entries()].map(([name, nodeIdList]) => ({
@@ -135,7 +116,7 @@ export function buildRunGraph(
     team: manifest.team ?? "unknown",
     workflow: manifest.workflow ?? "unknown",
     createdAt: manifest.createdAt,
-    completedAt: (manifest as Record<string, unknown>).completedAt as string | undefined,
+    completedAt: manifest.updatedAt,
     status: manifest.status,
     nodes,
     edges,

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