pi-crew 0.3.9 → 0.5.0

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

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