pi-crew 0.4.0 → 0.5.0

package/src/runtime/checkpoint.ts

@@ -0,0 +1,232 @@
+import * as fs from "node:fs";
+import * as path from "node:path";
+
+export interface Checkpoint {
+  runId: string;
+  taskId: string;
+  step: number;
+  context: string;
+  progress: string;
+  savedAt: number;
+  agentId: string;
+  agentModel?: string;
+}
+
+export interface CheckpointStore {
+  save(checkpoint: Checkpoint): void;
+  load(runId: string, taskId: string): Checkpoint | null;
+  delete(runId: string, taskId: string): void;
+  list(runId: string): Checkpoint[];
+  hasCheckpoint(runId: string, taskId: string): boolean;
+}
+
+interface CheckpointEntry {
+  checkpoints: Record<string, Checkpoint>;
+}
+
+/**
+ * File-based checkpoint store.
+ * Saves checkpoints as JSON files in .crew/state/runs/<runId>/checkpoints/
+ */
+export class FileCheckpointStore implements CheckpointStore {
+  private readonly stateRoot: string;
+
+  constructor(stateRoot: string) {
+    this.stateRoot = stateRoot;
+  }
+
+  private checkpointDir(): string {
+    return path.join(this.stateRoot, "checkpoints");
+  }
+
+  private checkpointPath(taskId: string): string {
+    return path.join(this.checkpointDir(), `${taskId}.json`);
+  }
+
+  private ensureDir(): void {
+    const dir = this.checkpointDir();
+    if (!fs.existsSync(dir)) {
+      fs.mkdirSync(dir, { recursive: true });
+    }
+  }
+
+  save(checkpoint: Checkpoint): void {
+    this.ensureDir();
+    const p = this.checkpointPath(checkpoint.taskId);
+    fs.writeFileSync(p, JSON.stringify(checkpoint, null, 2), "utf-8");
+  }
+
+  load(runId: string, taskId: string): Checkpoint | null {
+    const p = this.checkpointPath(taskId);
+    if (!fs.existsSync(p)) return null;
+
+    try {
+      const data = JSON.parse(fs.readFileSync(p, "utf-8")) as Checkpoint;
+      // Verify it's for the correct run
+      if (data.runId !== runId) return null;
+      return data;
+    } catch {
+      return null;
+    }
+  }
+
+  delete(runId: string, taskId: string): void {
+    const p = this.checkpointPath(taskId);
+    if (fs.existsSync(p)) {
+      try {
+        const data = JSON.parse(fs.readFileSync(p, "utf-8")) as Checkpoint;
+        if (data.runId === runId) {
+          fs.unlinkSync(p);
+        }
+      } catch {
+        // File existed but couldn't read — delete it anyway
+        try {
+          fs.unlinkSync(p);
+        } catch { /* ignore */ }
+      }
+    }
+  }
+
+  list(runId: string): Checkpoint[] {
+    const dir = this.checkpointDir();
+    if (!fs.existsSync(dir)) return [];
+
+    return fs.readdirSync(dir)
+      .filter((f) => f.endsWith(".json"))
+      .map((f) => {
+        try {
+          return JSON.parse(fs.readFileSync(path.join(dir, f), "utf-8")) as Checkpoint;
+        } catch {
+          return null;
+        }
+      })
+      .filter((c): c is Checkpoint => c !== null && c.runId === runId);
+  }
+
+  hasCheckpoint(runId: string, taskId: string): boolean {
+    return this.load(runId, taskId) !== null;
+  }
+}
+
+const _stores = new Map<string, FileCheckpointStore>();
+
+/**
+ * Get checkpoint store for a run's state root.
+ */
+export function getCheckpointStore(stateRoot: string): CheckpointStore {
+  if (!_stores.has(stateRoot)) {
+    _stores.set(stateRoot, new FileCheckpointStore(stateRoot));
+  }
+  return _stores.get(stateRoot)!;
+}
+
+/**
+ * Clear all checkpoint stores (for testing).
+ */
+export function clearCheckpointStores(): void {
+  _stores.clear();
+}
+
+/**
+ * Save a checkpoint during agent execution.
+ */
+export function saveCheckpoint(
+  runId: string,
+  taskId: string,
+  step: number,
+  context: string,
+  progress: string,
+  agentId: string,
+  agentModel?: string,
+): void {
+  const checkpoint: Checkpoint = {
+    runId,
+    taskId,
+    step,
+    context,
+    progress,
+    savedAt: Date.now(),
+    agentId,
+    agentModel,
+  };
+
+  // State root is parent of checkpoints dir
+  const stateRoot = path.join(process.cwd(), ".crew/state/runs", runId);
+  const store = getCheckpointStore(stateRoot);
+  store.save(checkpoint);
+}
+
+/**
+ * Load a checkpoint for resuming.
+ */
+export function loadCheckpoint(runId: string, taskId: string): Checkpoint | null {
+  const stateRoot = path.join(process.cwd(), ".crew/state/runs", runId);
+  const store = getCheckpointStore(stateRoot);
+  return store.load(runId, taskId);
+}
+
+/**
+ * Delete a checkpoint after successful completion.
+ */
+export function clearCheckpoint(runId: string, taskId: string): void {
+  const stateRoot = path.join(process.cwd(), ".crew/state/runs", runId);
+  const store = getCheckpointStore(stateRoot);
+  store.delete(runId, taskId);
+}
+
+/**
+ * Check if a checkpoint exists for a task.
+ */
+export function hasCheckpoint(runId: string, taskId: string): boolean {
+  const stateRoot = path.join(process.cwd(), ".crew/state/runs", runId);
+  const store = getCheckpointStore(stateRoot);
+  return store.hasCheckpoint(runId, taskId);
+}
+
+/**
+ * List all checkpoints for a run.
+ */
+export function listCheckpoints(runId: string): Checkpoint[] {
+  const stateRoot = path.join(process.cwd(), ".crew/state/runs", runId);
+  const store = getCheckpointStore(stateRoot);
+  return store.list(runId);
+}
+
+/**
+ * Format a checkpoint for display.
+ */
+export function formatCheckpoint(checkpoint: Checkpoint): string {
+  return [
+    `## Checkpoint: ${checkpoint.taskId}`,
+    "",
+    `**Agent:** ${checkpoint.agentId}`,
+    checkpoint.agentModel ? `**Model:** ${checkpoint.agentModel}` : "",
+    "",
+    `**Progress:** ${checkpoint.progress}`,
+    "",
+    `**Step:** ${checkpoint.step}`,
+    `**Saved:** ${new Date(checkpoint.savedAt).toISOString()}`,
+    "",
+    `**Context:** ${checkpoint.context.slice(0, 300)}${checkpoint.context.length > 300 ? "..." : ""}`,
+  ].filter(Boolean).join("\n");
+}
+
+/**
+ * Format all checkpoints for a run.
+ */
+export function formatAllCheckpoints(runId: string): string {
+  const checkpoints = listCheckpoints(runId);
+  if (checkpoints.length === 0) {
+    return `No checkpoints found for run ${runId}`;
+  }
+
+  return [
+    `# Checkpoints: ${runId}`,
+    "",
+    ...checkpoints.map((cp, i) =>
+      `${i + 1}. **${cp.taskId}** — ${cp.progress} (${new Date(cp.savedAt).toLocaleString()})`,
+    ),
+    "",
+    `Use \`team action='resume' runId=${runId} taskId=<taskId>\` to resume.`,
+  ].join("\n");
+}

package/src/state/crew-init.ts

@@ -0,0 +1,121 @@
+/**
+ * Auto-initialize .crew directory structure and .gitignore entries.
+ * Called on first team run in a workspace to ensure all required
+ * directories and files exist.
+ */
+import * as fs from "node:fs";
+import * as path from "node:path";
+import { projectCrewRoot } from "../utils/paths.ts";
+import { updateGitignore } from "./gitignore-manager.ts";
+
+/** README content for the .crew directory. */
+const CREW_README = `# .crew — pi-crew Runtime Directory
+
+This directory contains pi-crew runtime state and artifacts.
+
+## What's Here
+
+| Directory | Purpose | Commit? |
+|-----------|---------|---------|
+| \`state/runs/\` | Run manifests, tasks, events | No |
+| \`state/subagents/\` | Subagent state | No |
+| \`artifacts/\` | Run outputs (test files, docs, etc.) | Optional |
+| \`cache/\` | Cached run results (fingerprint-based) | No |
+| \`graphs/\` | Archived run graphs | Optional |
+| \`audit/\` | Security event logs | No |
+
+## Cleanup
+
+To prune old runs:
+\`\`\`bash
+team action='prune' keep=5
+\`\`\`
+
+To clear cache:
+\`\`\`bash
+team action='cache' action='clear'
+\`\`\`
+`;
+
+/**
+ * Ensure the .crew directory structure exists with all required subdirectories,
+ * placeholder files, README, and .gitignore entries.
+ *
+ * Uses `projectCrewRoot()` to resolve the correct root (`.crew/` or `.pi/teams/`
+ * for legacy projects). Idempotent — safe to call multiple times.
+ */
+export async function ensureCrewDirectory(cwd: string): Promise<void> {
+	const crewRoot = projectCrewRoot(cwd);
+
+	// 1. Create directory structure
+	const dirs = [
+		crewRoot,
+		path.join(crewRoot, "state", "runs"),
+		path.join(crewRoot, "state", "subagents"),
+		path.join(crewRoot, "artifacts"),
+		path.join(crewRoot, "cache"),
+		path.join(crewRoot, "graphs"),
+		path.join(crewRoot, "audit"),
+	];
+
+	for (const dir of dirs) {
+		if (!fs.existsSync(dir)) {
+			fs.mkdirSync(dir, { recursive: true });
+		}
+	}
+
+	// 2. Create .gitkeep placeholders in directories that should be tracked
+	const placeholders = [
+		path.join(crewRoot, "artifacts", ".gitkeep"),
+		path.join(crewRoot, "cache", ".gitkeep"),
+		path.join(crewRoot, "graphs", ".gitkeep"),
+		path.join(crewRoot, "audit", ".gitkeep"),
+	];
+
+	for (const placeholder of placeholders) {
+		if (!fs.existsSync(placeholder)) {
+			fs.writeFileSync(placeholder, "", "utf-8");
+		}
+	}
+
+	// 3. Write README.md (always overwrite to keep it current)
+	fs.writeFileSync(path.join(crewRoot, "README.md"), CREW_README, "utf-8");
+
+	// 4. Update .gitignore — resolve project root to place .gitignore correctly
+	// Find the repo root to place .gitignore at the project root (not inside .crew)
+	const repoRoot = findRepoRootForGitignore(cwd);
+	if (repoRoot) {
+		const gitignorePath = path.join(repoRoot, ".gitignore");
+		await updateGitignore(gitignorePath);
+	}
+}
+
+/**
+ * Find the appropriate project root for placing the .gitignore.
+ * Walks up from cwd to find a directory with project markers.
+ */
+function findRepoRootForGitignore(cwd: string): string | undefined {
+	// Use the same project root markers as paths.ts
+	const dirMarkers = [".git", ".pi", ".crew", ".hg", ".svn"];
+	const fileMarkers = [
+		"package.json",
+		"pyproject.toml",
+		"Cargo.toml",
+		"go.mod",
+	];
+	const root = path.parse(cwd).root;
+	let current = path.resolve(cwd);
+	while (current !== root) {
+		for (const marker of dirMarkers) {
+			if (fs.existsSync(path.join(current, marker))) return current;
+		}
+		for (const marker of fileMarkers) {
+			if (fs.existsSync(path.join(current, marker))) return current;
+		}
+		const parent = path.dirname(current);
+		if (parent === current) break;
+		current = parent;
+	}
+	// No project root found — don't create .gitignore
+	return undefined;
+}

package/src/state/gitignore-manager.ts

@@ -0,0 +1,51 @@
+/**
+ * Manage .gitignore entries for the .crew directory.
+ * Only adds entries if not already present; preserves existing content.
+ */
+import * as fs from "node:fs";
+
+/**
+ * Entries to add to .gitignore for .crew directory management.
+ *
+ * - `/.crew/` and `/.crew` ignore the core state directory.
+ * - Exceptions allow optional commit of artifacts/ and graphs/ (including their .gitkeep).
+ */
+const CREW_GITIGNORE_ENTRIES = [
+	"/.crew/",
+	"/.crew",
+	"!.crew/artifacts/",
+	"!.crew/graphs/",
+	"!.crew/artifacts/.gitkeep",
+	"!.crew/graphs/.gitkeep",
+];
+
+/**
+ * Update .gitignore with .crew entries. Creates the file if it doesn't exist.
+ * Preserves all existing content.
+ */
+export async function updateGitignore(gitignorePath: string): Promise<void> {
+	if (!fs.existsSync(gitignorePath)) {
+		fs.writeFileSync(
+			gitignorePath,
+			CREW_GITIGNORE_ENTRIES.join("\n") + "\n",
+			"utf-8",
+		);
+		return;
+	}
+
+	const current = fs.readFileSync(gitignorePath, "utf-8");
+	const existingLines = new Set(
+		current.split("\n").map((line) => line.trim()),
+	);
+
+	let appended = "";
+	for (const entry of CREW_GITIGNORE_ENTRIES) {
+		if (!existingLines.has(entry)) {
+			appended += `\n${entry}`;
+		}
+	}
+
+	if (appended) {
+		fs.writeFileSync(gitignorePath, current + appended, "utf-8");
+	}
+}

package/src/state/run-cache.ts

@@ -0,0 +1,176 @@
+import * as fs from "node:fs";
+import * as path from "node:path";
+import * as crypto from "node:crypto";
+import { projectCrewRoot } from "../utils/paths.ts";
+import type { TeamTaskState } from "./types.ts";
+
+const DEFAULT_CACHE_TTL_MS = 60 * 60 * 1000; // 1 hour
+
+export interface CacheEntry {
+  key: string;
+  runId: string;
+  status: string;
+  tasks: TeamTaskState[];
+  cachedAt: number;
+  expiresAt: number;
+  goal: string;
+  team: string;
+}
+
+interface CacheIndex {
+  [cacheKey: string]: string;
+}
+
+/**
+ * Compute a cache key from run parameters.
+ * Uses SHA-256 hash of normalized goal + team + workflow.
+ */
+export function computeRunCacheKey(goal: string, team: string, workflow: string, _cwd: string): string {
+  const normalized = goal.trim().toLowerCase().replace(/\s+/g, " ");
+  return crypto.createHash("sha256")
+    .update(normalized)
+    .update(team)
+    .update(workflow)
+    .digest("hex")
+    .slice(0, 16);
+}
+
+/**
+ * Get the cache directory path.
+ */
+function cacheDir(cwd: string): string {
+  return path.join(projectCrewRoot(cwd), "cache");
+}
+
+/**
+ * Get cached run result if exists and valid.
+ * Returns null if cache miss or expired.
+ */
+export function getCachedRun(cwd: string, cacheKey: string): CacheEntry | null {
+  const dir = cacheDir(cwd);
+  const indexPath = path.join(dir, "index.json");
+
+  if (!fs.existsSync(indexPath)) return null;
+
+  try {
+    const index = JSON.parse(fs.readFileSync(indexPath, "utf-8")) as CacheIndex;
+    const entryPath = index[cacheKey];
+
+    if (!entryPath || !fs.existsSync(entryPath)) return null;
+
+    const entry = JSON.parse(fs.readFileSync(entryPath, "utf-8")) as CacheEntry;
+
+    if (Date.now() > entry.expiresAt) {
+      // Remove expired entry
+      try {
+        fs.unlinkSync(entryPath);
+      } catch { /* ignore */ }
+      delete index[cacheKey];
+      fs.writeFileSync(indexPath, JSON.stringify(index), "utf-8");
+      return null;
+    }
+
+    return entry;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Save run result to cache.
+ */
+export function saveRunToCache(
+  cwd: string,
+  cacheKey: string,
+  runId: string,
+  status: string,
+  tasks: TeamTaskState[],
+  goal: string,
+  team: string,
+  ttlMs: number = DEFAULT_CACHE_TTL_MS,
+): void {
+  const dir = cacheDir(cwd);
+
+  if (!fs.existsSync(dir)) {
+    fs.mkdirSync(dir, { recursive: true });
+  }
+
+  const entry: CacheEntry = {
+    key: cacheKey,
+    runId,
+    status,
+    tasks,
+    cachedAt: Date.now(),
+    expiresAt: Date.now() + ttlMs,
+    goal,
+    team,
+  };
+
+  const entryPath = path.join(dir, `${cacheKey}.json`);
+  fs.writeFileSync(entryPath, JSON.stringify(entry), "utf-8");
+
+  // Update index
+  const indexPath = path.join(dir, "index.json");
+  const index: CacheIndex = fs.existsSync(indexPath)
+    ? JSON.parse(fs.readFileSync(indexPath, "utf-8"))
+    : {};
+
+  index[cacheKey] = entryPath;
+  fs.writeFileSync(indexPath, JSON.stringify(index), "utf-8");
+}
+
+/**
+ * Clear all cache entries.
+ */
+export function clearCache(cwd: string): void {
+  const dir = cacheDir(cwd);
+  if (!fs.existsSync(dir)) return;
+
+  const indexPath = path.join(dir, "index.json");
+  if (fs.existsSync(indexPath)) {
+    try {
+      const index = JSON.parse(fs.readFileSync(indexPath, "utf-8")) as CacheIndex;
+      for (const entryPath of Object.values(index)) {
+        try {
+          fs.unlinkSync(entryPath);
+        } catch { /* ignore */ }
+      }
+      fs.unlinkSync(indexPath);
+    } catch { /* ignore */ }
+  }
+
+  // Remove entry files not in index
+  const entries = fs.readdirSync(dir).filter((f) => f.endsWith(".json"));
+  for (const entry of entries) {
+    try {
+      fs.unlinkSync(path.join(dir, entry));
+    } catch { /* ignore */ }
+  }
+}
+
+/**
+ * Get cache stats.
+ */
+export function getCacheStats(cwd: string): { entries: number; sizeBytes: number } {
+  const dir = cacheDir(cwd);
+  if (!fs.existsSync(dir)) return { entries: 0, sizeBytes: 0 };
+
+  let sizeBytes = 0;
+  let entries = 0;
+  const indexPath = path.join(dir, "index.json");
+
+  if (fs.existsSync(indexPath)) {
+    try {
+      const index = JSON.parse(fs.readFileSync(indexPath, "utf-8")) as CacheIndex;
+      entries = Object.keys(index).length;
+      for (const entryPath of Object.values(index)) {
+        try {
+          const stat = fs.statSync(entryPath);
+          sizeBytes += stat.size;
+        } catch { /* ignore */ }
+      }
+    } catch { /* ignore */ }
+  }
+
+  return { entries, sizeBytes };
+}