pi-crew 0.4.0 → 0.5.0

package/CHANGELOG.md

@@ -1,5 +1,54 @@
 # Changelog
 
+## [0.5.0] — Understand-Anything Patterns & New Features (2026-05-26)
+
+### New Features: P0-P6 from Understand-Anything Research
+
+#### P0: Auto-Setup .crew Directory
+- `ensureCrewDirectory()` creates full directory structure on first run
+- `gitignore-manager.ts` auto-updates `.gitignore` with `.crew/` entries
+- Creates: `state/runs`, `state/subagents`, `artifacts`, `cache`, `graphs`, `audit`
+- README.md explains `.crew` directory purpose
+
+#### P1: BM25 Agent/Team Search
+- `BM25Search` class with configurable k1/b parameters
+- `searchAgents(query)` — ranked agent search by name/description/skills
+- `searchTeams(query)` — ranked team search by name/description/roles
+
+#### P2: Team Onboarding Generator
+- `buildTeamOnboarding()` generates markdown from run history
+- Shows: past runs, stats, usage examples, available teams
+- `loadRunSummaries()` helper for run history loading
+
+#### P3: Task Explain Context
+- `handleExplain(runId, taskId)` — full run or individual task explanation
+- `buildTaskExplainContext()` — causal chain, layers, files produced
+- `formatTaskExplain()` — markdown output with why/what/connections
+
+#### P4: Unified Run Graph
+- `buildRunGraph()` — consolidates manifest + tasks into single graph
+- `saveRunGraph()` / `loadRunGraph()` — persist to `.crew/graphs/`
+- `listRunGraphs()` — enumerate archived graphs
+
+#### P5: Run Result Caching
+- `computeRunCacheKey()` — SHA-256 hash of goal+team+workflow
+- `getCachedRun()` / `saveRunToCache()` — TTL-based cache (default 1h)
+- `clearCache()` / `getCacheStats()` — cache management
+
+#### P6: Agent Checkpointing
+- `FileCheckpointStore` — checkpoints in `.crew/state/runs/<runId>/checkpoints/`
+- `saveCheckpoint()` / `loadCheckpoint()` / `clearCheckpoint()`
+- `hasCheckpoint()` / `listCheckpoints()` for recovery
+
+### Tests
+- 56 new unit tests (all passing)
+- Total: 1796 unit tests + 45 integration tests passing
+
+### Bug Fixes
+- Worktree test teardown: clean `.crew/` before git checks for clean repository
+
+---
+
 ## [0.4.0] — 9arm-skills Enforcement Patterns & Integration Tests (2026-05-26)
 
 ### Features

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-crew",
-  "version": "0.4.0",
+  "version": "0.5.0",
   "description": "Pi extension for coordinated AI teams, workflows, worktrees, and async task orchestration",
   "author": "baphuongna",
   "license": "MIT",

package/src/extension/team-onboard.ts

@@ -0,0 +1,176 @@
+import * as fs from "node:fs";
+import * as path from "node:path";
+import { projectCrewRoot } from "../utils/paths.ts";
+import { allTeams, discoverTeams } from "../teams/discover-teams.ts";
+import type { TeamRunManifest } from "../state/types.ts";
+
+export interface OnboardingOptions {
+  team?: string;
+  limit?: number;
+  cwd?: string;
+}
+
+interface RunSummary {
+  runId: string;
+  status: string;
+  goal: string;
+  team: string;
+  createdAt: string;
+  completedAt?: string;
+  taskCount: number;
+}
+
+/**
+ * Load run summaries from the state directory.
+ */
+function loadRunSummaries(cwd: string, options: OnboardingOptions = {}): RunSummary[] {
+  const crewRoot = projectCrewRoot(cwd);
+  const runsRoot = path.join(crewRoot, "state", "runs");
+
+  if (!fs.existsSync(runsRoot)) return [];
+
+  const limit = options.limit ?? 5;
+  const teamFilter = options.team;
+
+  const entries = fs.readdirSync(runsRoot)
+    .filter((e) => {
+      try {
+        return fs.statSync(path.join(runsRoot, e)).isDirectory();
+      } catch {
+        return false;
+      }
+    })
+    .sort()
+    .reverse()
+    .slice(0, 100);
+
+  const summaries: RunSummary[] = [];
+
+  for (const runId of entries) {
+    if (summaries.length >= limit) break;
+
+    const manifestPath = path.join(runsRoot, runId, "manifest.json");
+    if (!fs.existsSync(manifestPath)) continue;
+
+    try {
+      const raw = JSON.parse(fs.readFileSync(manifestPath, "utf-8")) as TeamRunManifest & { completedAt?: string };
+
+      if (teamFilter && raw.team !== teamFilter) continue;
+
+      summaries.push({
+        runId,
+        status: raw.status,
+        goal: raw.goal ?? "",
+        team: raw.team,
+        createdAt: raw.createdAt,
+        completedAt: raw.completedAt ?? raw.updatedAt,
+        taskCount: (raw as Record<string, unknown>).tasks != null
+          ? ((raw as Record<string, unknown>).tasks as unknown[]).length
+          : 0,
+      });
+    } catch {
+      continue;
+    }
+  }
+
+  return summaries;
+}
+
+/**
+ * Format duration in minutes.
+ */
+function formatDuration(createdAt: string, completedAt?: string): string {
+  const start = new Date(createdAt).getTime();
+  const end = completedAt ? new Date(completedAt).getTime() : Date.now();
+  const minutes = Math.round((end - start) / 1000 / 60);
+  if (minutes < 1) return "<1m";
+  if (minutes >= 60) return `${Math.round(minutes / 60)}h`;
+  return `${minutes}m`;
+}
+
+/**
+ * Build markdown onboarding guide for a team.
+ */
+export function buildTeamOnboarding(team: string, cwd: string, options: OnboardingOptions = {}): string {
+  const runs = loadRunSummaries(cwd, { ...options, team });
+
+  const lines: string[] = [];
+
+  // Header
+  lines.push(`# Team: ${team}`);
+  lines.push("");
+  lines.push(`> Multi-agent ${team} team for pi-crew.`);
+  lines.push("");
+
+  // Overview stats
+  const completed = runs.filter((r) => r.status === "completed");
+  const failed = runs.filter((r) => r.status === "failed" || r.status === "cancelled");
+
+  let avgDuration = 0;
+  if (completed.length > 0) {
+    const totalMs = completed.reduce((sum, r) => {
+      const start = new Date(r.createdAt).getTime();
+      const end = r.completedAt ? new Date(r.completedAt).getTime() : Date.now();
+      return sum + (end - start);
+    }, 0);
+    avgDuration = totalMs / completed.length / 1000 / 60;
+  }
+
+  lines.push("## Overview");
+  lines.push("");
+  lines.push(`| Metric | Value |`);
+  lines.push(`|--------|-------|`);
+  lines.push(`| Total runs | ${runs.length} |`);
+  lines.push(`| Completed | ${completed.length} |`);
+  lines.push(`| Failed/Cancelled | ${failed.length} |`);
+  if (avgDuration > 0) {
+    lines.push(`| Avg duration | ${avgDuration.toFixed(1)} min |`);
+  }
+  lines.push("");
+
+  // Past runs table
+  if (runs.length > 0) {
+    lines.push("## Past Runs");
+    lines.push("");
+    lines.push("| Run | Goal | Duration | Status |");
+    lines.push("|-----|------|----------|--------|");
+
+    for (const run of runs) {
+      const duration = formatDuration(run.createdAt, run.completedAt);
+      const goalPreview = run.goal ? run.goal.slice(0, 40) : "N/A";
+      const statusIcon = run.status === "completed" ? "✅" : run.status === "failed" ? "❌" : "⚠️";
+      lines.push(`| \`${run.runId.slice(-8)}\` | ${goalPreview}${run.goal.length > 40 ? "..." : ""} | ${duration} | ${statusIcon} ${run.status} |`);
+    }
+    lines.push("");
+  }
+
+  // How to run
+  lines.push("## How to Run");
+  lines.push("");
+  lines.push("```bash");
+  lines.push(`team action='run' team='${team}' goal="<your goal>"`);
+  lines.push("```");
+  lines.push("");
+  lines.push("See `team action='help'` for more options.");
+  lines.push("");
+
+  // Teams
+  lines.push("## Available Teams");
+  lines.push("");
+  try {
+    const discovery = discoverTeams(cwd);
+    const teams = allTeams(discovery);
+    for (const t of teams) {
+      lines.push(`- \`${t.name}\` — ${t.description ?? "No description"}`);
+    }
+  } catch {
+    lines.push("- *(team discovery unavailable)*");
+  }
+  lines.push("");
+
+  // Footer
+  lines.push("---");
+  lines.push("*Generated by pi-crew. For up-to-date info, check recent run history.*");
+
+  return lines.join("\n");
+}

package/src/extension/team-tool/explain.ts

@@ -0,0 +1,268 @@
+import * as fs from "node:fs";
+import * as path from "node:path";
+import { toolResult } from "../tool-result.ts";
+import { loadRunManifestById } from "../../state/state-store.ts";
+import type { TeamRunManifest, TeamTaskState } from "../../state/types.ts";
+
+/**
+ * Local wrapper matching the planned `result` API used by handleExplain.
+ */
+function result(text: string, details: Record<string, unknown>, isError: boolean): { isError: boolean; text: string } {
+  return { isError, text };
+}
+
+export interface TaskExplainContext {
+  taskId: string;
+  role: string;
+  status: string;
+  phase?: string;
+  why: string;
+  what: string;
+  filesTouched: string[];
+  connectedTasks: Array<{ taskId: string; status: string; relation: string }>;
+  layer: string;
+  complexity: "simple" | "moderate" | "complex";
+  usage?: { inputTokens?: number; outputTokens?: number };
+  duration?: number;
+}
+
+/**
+ * Build explain context for a specific task in a run.
+ */
+export function buildTaskExplainContext(
+  manifest: TeamRunManifest,
+  tasks: TeamTaskState[],
+  taskId: string,
+): TaskExplainContext {
+  const task = tasks.find((t) => t.id === taskId);
+  if (!task) {
+    throw new Error(`Task ${taskId} not found in run ${manifest.runId}`);
+  }
+
+  const dependsOn = task.dependsOn ?? [];
+  const dependents = tasks.filter((t) => (t.dependsOn ?? []).includes(taskId));
+
+  // Layer from phase
+  const layerMap: Record<string, string> = {
+    explore: "exploration",
+    plan: "planning",
+    assess: "assessment",
+    execute: "execution",
+    verify: "verification",
+    analyze: "analysis",
+    write: "documentation",
+    "": "unknown",
+  };
+  const layer = layerMap[task.adaptive?.phase ?? ""] ?? "unknown";
+
+  // Why it exists
+  let why = `Part of ${manifest.team ?? "unknown"} team workflow.`;
+  if (dependsOn.length > 0) {
+    const depTasks = dependsOn.map((d) => {
+      const dep = tasks.find((t) => t.id === d);
+      return dep ? `\`${d}\` (${dep.status})` : `\`${d}\``;
+    }).join(", ");
+    why += ` Depends on ${depTasks}.`;
+  }
+  if (dependents.length > 0) {
+    why += ` ${dependents.length} task(s) depend on this.`;
+  }
+
+  // What it did
+  let what = `Ran agent: ${task.role}`;
+  if (task.model) {
+    what += ` (${task.model})`;
+  }
+  if (task.usage) {
+    const inputTokens = task.usage.input ?? 0;
+    const outputTokens = task.usage.output ?? 0;
+    what += `. Usage: input=${inputTokens}, output=${outputTokens}`;
+  }
+  if (task.status === "failed") {
+    what += `. Status: FAILED`;
+    if (task.error) {
+      what += ` — ${task.error}`;
+    }
+  }
+
+  // Files from artifacts
+  const artifactsPath = manifest.artifactsRoot;
+  const filesTouched: string[] = [];
+  if (fs.existsSync(artifactsPath)) {
+    try {
+      const entries = fs.readdirSync(artifactsPath);
+      for (const entry of entries) {
+        const fullPath = path.join(artifactsPath, entry);
+        try {
+          if (fs.statSync(fullPath).isFile()) {
+            filesTouched.push(entry);
+          }
+        } catch { /* ignore */ }
+      }
+    } catch { /* ignore */ }
+  }
+
+  // Duration
+  let duration: number | undefined;
+  if (task.startedAt && task.finishedAt) {
+    duration = (new Date(task.finishedAt).getTime() - new Date(task.startedAt).getTime()) / 1000;
+  }
+
+  // Complexity
+  const complexity = tasks.length <= 3 ? "simple" : tasks.length <= 8 ? "moderate" : "complex";
+
+  return {
+    taskId,
+    role: task.role,
+    status: task.status,
+    phase: task.adaptive?.phase,
+    why,
+    what,
+    filesTouched,
+    connectedTasks: [
+      ...dependsOn.map((d) => {
+        const dep = tasks.find((t) => t.id === d);
+        return {
+          taskId: d,
+          status: dep?.status ?? "unknown",
+          relation: "depends on",
+        };
+      }),
+      ...dependents.map((d) => ({
+        taskId: d.id,
+        status: d.status,
+        relation: "depended on by",
+      })),
+    ],
+    layer,
+    complexity,
+    usage: task.usage ? { inputTokens: task.usage.input, outputTokens: task.usage.output } : undefined,
+    duration,
+  };
+}
+
+/**
+ * Format task explain context as markdown.
+ */
+export function formatTaskExplain(ctx: TaskExplainContext): string {
+  const lines: string[] = [];
+
+  lines.push(`# Task: ${ctx.taskId} (${ctx.role})`);
+  lines.push("");
+  lines.push(`| | |`);
+  lines.push(`|---|---|`);
+  lines.push(`| **Status** | ${ctx.status} |`);
+  if (ctx.phase) lines.push(`| **Phase** | ${ctx.phase} |`);
+  lines.push(`| **Layer** | ${ctx.layer} |`);
+  lines.push(`| **Complexity** | ${ctx.complexity} |`);
+
+  if (ctx.duration) {
+    const minutes = Math.round(ctx.duration / 60);
+    lines.push(`| **Duration** | ${minutes} min |`);
+  }
+
+  if (ctx.usage) {
+    const input = ctx.usage.inputTokens ?? 0;
+    const output = ctx.usage.outputTokens ?? 0;
+    lines.push(`| **Usage** | ↑${input} ↓${output} tokens |`);
+  }
+
+  lines.push("");
+  lines.push(`## Why it exists`);
+  lines.push("");
+  lines.push(ctx.why);
+  lines.push("");
+  lines.push(`## What it did`);
+  lines.push("");
+  lines.push(ctx.what);
+  lines.push("");
+
+  if (ctx.filesTouched.length > 0) {
+    lines.push("## Files produced");
+    lines.push("");
+    for (const file of ctx.filesTouched) {
+      lines.push(`- \`${file}\``);
+    }
+    lines.push("");
+  }
+
+  if (ctx.connectedTasks.length > 0) {
+    lines.push("## Connected tasks");
+    lines.push("");
+    for (const conn of ctx.connectedTasks) {
+      lines.push(`- ${conn.relation} \`${conn.taskId}\` (${conn.status})`);
+    }
+    lines.push("");
+  }
+
+  return lines.join("\n");
+}
+
+/**
+ * Handle team action='explain'.
+ */
+export function handleExplain(params: {
+  runId?: string;
+  taskId?: string;
+  cwd?: string;
+}, cwd: string): { isError: boolean; text: string } {
+  if (!params.runId) {
+    return result("explain requires runId", { action: "explain", status: "error" }, true);
+  }
+
+  const loaded = loadRunManifestById(cwd, params.runId);
+  if (!loaded) {
+    return result(`Run '${params.runId}' not found.`, { action: "explain", status: "error" }, true);
+  }
+
+  const { manifest, tasks } = loaded;
+
+  if (params.taskId) {
+    try {
+      const ctx = buildTaskExplainContext(manifest, tasks, params.taskId);
+      const output = formatTaskExplain(ctx);
+      return result(output, { action: "explain", runId: params.runId }, false);
+    } catch (err) {
+      return result(`Task '${params.taskId}' not found: ${err instanceof Error ? err.message : String(err)}`, { action: "explain", status: "error" }, true);
+    }
+  }
+
+  // Explain entire run
+  const lines: string[] = [];
+  lines.push(`# Run: ${params.runId}`);
+  lines.push("");
+  lines.push(`| | |`);
+  lines.push(`|---|---|`);
+
+  const start = new Date(manifest.createdAt).getTime();
+  const end = manifest.updatedAt ? new Date(manifest.updatedAt).getTime() : Date.now();
+  const duration = Math.round((end - start) / 1000 / 60);
+
+  lines.push(`| **Team** | ${manifest.team} |`);
+  lines.push(`| **Workflow** | ${manifest.workflow ?? "default"} |`);
+  lines.push(`| **Status** | ${manifest.status} |`);
+  lines.push(`| **Duration** | ${duration} min |`);
+  lines.push(`| **Tasks** | ${tasks.length} |`);
+  lines.push("");
+
+  lines.push("## Tasks");
+  lines.push("");
+  lines.push("| Task | Role | Status | Layer |");
+  lines.push("|------|------|--------|-------|");
+
+  for (const task of tasks) {
+    const layerMap: Record<string, string> = {
+      explore: "exploration", plan: "planning", assess: "assessment",
+      execute: "execution", verify: "verification", analyze: "analysis", write: "documentation",
+    };
+    const layer = layerMap[task.adaptive?.phase ?? ""] ?? "unknown";
+    const statusIcon = task.status === "completed" ? "✅" : task.status === "failed" ? "❌" : "⏳";
+    lines.push(`| \`${task.id}\` | ${task.role} | ${statusIcon} ${task.status} | ${layer} |`);
+  }
+  lines.push("");
+
+  lines.push("---");
+  lines.push(`*Use \`team action='explain' runId=${params.runId} taskId=<taskId>\` for task detail.*`);
+
+  return result(lines.join("\n"), { action: "explain", runId: params.runId }, false);
+}

package/src/extension/team-tool/run.ts

@@ -1,4 +1,5 @@
 import { allAgents, discoverAgents } from "../../agents/discover-agents.ts";
+import { ensureCrewDirectory } from "../../state/crew-init.ts";
 import { allTeams, discoverTeams } from "../../teams/discover-teams.ts";
 import { allWorkflows, discoverWorkflows } from "../../workflows/discover-workflows.ts";
 import { loadConfig } from "../../config/config.ts";
@@ -74,6 +75,9 @@ export async function handleRun(params: TeamToolParamsValue, ctx: TeamContext):
 	if (!goal) return result("Run requires goal or task.", { action: "run", status: "error" }, true);
 	const intentPrefix = goal.length > 60 ? `${goal.slice(0, 57)}...` : goal;
 
+	// P0: Ensure .crew directory structure exists before creating any manifests.
+	await ensureCrewDirectory(ctx.cwd);
+
 	const teams = allTeams(discoverTeams(ctx.cwd));
 	const workflows = allWorkflows(discoverWorkflows(ctx.cwd));
 	const agents = allAgents(discoverAgents(ctx.cwd));