pi-crew 0.9.5 → 0.9.7

package/src/ui/dwf-phase-display.ts

@@ -0,0 +1,151 @@
+/**
+ * DWF phase display — pure functions for extracting DWF phase state from the
+ * run's recent event window and rendering phase markers (▶/✓/⏸) in the
+ * progress pane.
+ *
+ * round-15 (P1-4). These functions are side-effect free and perform no I/O;
+ * they derive phase state entirely from the `recentEvents` slice already
+ * tailed by `run-snapshot-cache.ts`. Non-DWF runs (no `dwf.phase_*` events)
+ * yield `null`, so the progress pane stays unchanged for them.
+ */
+import type { TeamEvent } from "../state/event-log.ts";
+
+// ---------------------------------------------------------------------------
+// Types
+// ---------------------------------------------------------------------------
+
+export type DwfPhaseStatus = "running" | "completed" | "pending";
+
+export interface DwfPhaseEntry {
+	/** Phase title as passed to `ctx.phase(title)`. */
+	name: string;
+	/** Derived lifecycle status for display. */
+	status: DwfPhaseStatus;
+}
+
+export interface DwfPhaseState {
+	/** Ordered list of phases seen in the event window (first-seen order). */
+	phases: DwfPhaseEntry[];
+	/** Name of the currently running phase, or null if all are completed. */
+	currentPhase: string | null;
+}
+
+export interface RenderDwfPhaseOptions {
+	/** When true, render ASCII fallback markers instead of Unicode glyphs. */
+	ascii?: boolean;
+}
+
+// ---------------------------------------------------------------------------
+// Markers
+// ---------------------------------------------------------------------------
+
+// Unicode markers — consistent with the ▸/● glyphs already used in the dashboard.
+const MARKER_RUNNING = "▶";
+const MARKER_COMPLETED = "✓";
+const MARKER_PENDING = "⏸";
+
+// ASCII fallbacks for terminals that mis-render the Unicode glyphs above.
+const MARKER_RUNNING_ASCII = "[>]";
+const MARKER_COMPLETED_ASCII = "[v]";
+const MARKER_PENDING_ASCII = "[ ]";
+
+const DWF_PHASE_HEADER = "  ── DWF Phases ──";
+
+function markerFor(status: DwfPhaseStatus, ascii: boolean): string {
+	if (ascii) {
+		if (status === "running") return MARKER_RUNNING_ASCII;
+		if (status === "completed") return MARKER_COMPLETED_ASCII;
+		return MARKER_PENDING_ASCII;
+	}
+	if (status === "running") return MARKER_RUNNING;
+	if (status === "completed") return MARKER_COMPLETED;
+	return MARKER_PENDING;
+}
+
+// ---------------------------------------------------------------------------
+// Extraction
+// ---------------------------------------------------------------------------
+
+function phaseNameFrom(event: TeamEvent): string | undefined {
+	const phase = event.data?.phase;
+	return typeof phase === "string" && phase.length > 0 ? phase : undefined;
+}
+
+/**
+ * Derive DWF phase state from a (chronological) event window.
+ *
+ * Returns `null` when the window contains no `dwf.phase_started` /
+ * `dwf.phase_completed` events — i.e. a non-DWF run — so callers can short
+ * circuit phase rendering entirely.
+ *
+ * Because the window is bounded, the oldest phase events may have scrolled
+ * off. A phase whose `dwf.phase_started` scrolled off but whose
+ * `dwf.phase_completed` is still visible is still tracked (as completed). A
+ * phase that started but whose completion scrolled off and which is not the
+ * current phase is shown as `pending` (indeterminate).
+ */
+export function extractDwfPhaseState(events: TeamEvent[]): DwfPhaseState | null {
+	const order: string[] = [];
+	const seen = new Set<string>();
+	const completed = new Set<string>();
+	let currentPhase: string | null = null;
+
+	const remember = (phase: string): void => {
+		if (!seen.has(phase)) {
+			seen.add(phase);
+			order.push(phase);
+		}
+	};
+
+	for (const event of events) {
+		if (event.type === "dwf.phase_started") {
+			const phase = phaseNameFrom(event);
+			if (phase === undefined) continue;
+			remember(phase);
+			// The most recent phase_started marks the running phase.
+			currentPhase = phase;
+		} else if (event.type === "dwf.phase_completed") {
+			const phase = phaseNameFrom(event);
+			if (phase === undefined) continue;
+			remember(phase);
+			completed.add(phase);
+			// If the phase just closed was the running one, it is no longer running.
+			if (phase === currentPhase) {
+				currentPhase = null;
+			}
+		}
+	}
+
+	if (order.length === 0) return null;
+
+	const phases: DwfPhaseEntry[] = order.map((name) => {
+		if (name === currentPhase) return { name, status: "running" as const };
+		if (completed.has(name)) return { name, status: "completed" as const };
+		return { name, status: "pending" as const };
+	});
+
+	return { phases, currentPhase };
+}
+
+// ---------------------------------------------------------------------------
+// Rendering
+// ---------------------------------------------------------------------------
+
+/**
+ * Render phase marker lines for the progress pane.
+ *
+ * - One line per phase: `  ▶ Phase: Scan`, `  ✓ Phase: Scan`, `  ⏸ Phase: Review`.
+ * - A grouping header is emitted only when more than one phase is present.
+ * - When `options.ascii` is true, ASCII fallback markers are used.
+ *
+ * Always returns a non-empty array (the caller guarantees a non-null state).
+ */
+export function renderDwfPhaseLines(state: DwfPhaseState, options?: RenderDwfPhaseOptions): string[] {
+	const ascii = options?.ascii === true;
+	const lines: string[] = [];
+	if (state.phases.length > 1) lines.push(DWF_PHASE_HEADER);
+	for (const entry of state.phases) {
+		lines.push(`  ${markerFor(entry.status, ascii)} Phase: ${entry.name}`);
+	}
+	return lines;
+}

package/src/ui/run-snapshot-cache.ts

@@ -10,6 +10,7 @@ import { loadRunManifestById, loadRunManifestByIdAsync } from "../state/state-st
 import type { TeamRunManifest, TeamTaskState } from "../state/types.ts";
 import type { RunSnapshotCache as RunSnapshotCacheBase, RunUiGroupJoin, RunUiMailbox, RunUiProgress, RunUiSnapshot, RunUiUsage } from "./snapshot-types.ts";
 import { runEventBus } from "./run-event-bus.ts";
+import { extractDwfPhaseState } from "./dwf-phase-display.ts";
 import { sequencePath } from "../state/event-log.ts";
 
 export interface RunSnapshotCache extends RunSnapshotCacheBase {
@@ -566,6 +567,7 @@ function signatureFor(input: Omit<RunUiSnapshot, "signature" | "fetchedAt" | "sl
 		groupJoins: input.groupJoins,
 		events: input.recentEvents.map((event) => [event.metadata?.seq, event.time, event.type, event.taskId, event.message, event.data?.reason]),
 		cancellationReason: input.cancellationReason,
+		dwfPhaseState: input.dwfPhaseState,
 		output: input.recentOutputLines,
 		stamps,
 	}));
@@ -684,6 +686,7 @@ export function createRunSnapshotCache(cwd: string, options: RunSnapshotCacheOpt
 			mailbox,
 			groupJoins,
 			cancellationReason: cancellationReasonFromEvents(recentEvents),
+			dwfPhaseState: extractDwfPhaseState(recentEvents),
 			recentEvents,
 			recentOutputLines: recentOutputLines(loaded.manifest, agents, recentOutputLimit),
 		};
@@ -730,6 +733,7 @@ export function createRunSnapshotCache(cwd: string, options: RunSnapshotCacheOpt
 			mailbox,
 			groupJoins,
 			cancellationReason: cancellationReasonFromEvents(recentEvents),
+			dwfPhaseState: extractDwfPhaseState(recentEvents),
 			recentEvents,
 			recentOutputLines: recentOutput,
 		};

package/src/ui/snapshot-types.ts

@@ -1,6 +1,7 @@
 import type { CrewAgentRecord } from "../runtime/crew-agent-runtime.ts";
 import type { TeamEvent } from "../state/event-log.ts";
 import type { TeamRunManifest, TeamTaskState } from "../state/types.ts";
+import type { DwfPhaseState } from "./dwf-phase-display.ts";
 
 export interface RunUiProgress {
 	total: number;
@@ -73,6 +74,8 @@ export interface RunUiSnapshot {
 	groupJoins?: RunUiGroupJoin[];
 	/** Structured cancellation reason from run.cancelled event data, when available. */
 	cancellationReason?: string;
+	/** DWF phase state derived from `recentEvents`. Null/absent for non-DWF runs. */
+	dwfPhaseState?: DwfPhaseState | null;
 	recentEvents: TeamEvent[];
 	recentOutputLines: string[];
 }

package/src/workflows/workflow-config.ts

@@ -45,6 +45,9 @@ export interface WorkflowConfig {
 	runtime?: "static" | "dynamic";
 	/** For runtime:"dynamic" — relative/absolute path to the .dwf.ts script. Unused for static. */
 	dynamicScript?: string;
+	/** For runtime:"dynamic" — per-workflow token budget. When set, ctx.agent() auto-rejects with
+	 *  ok:false once exhausted. Accumulated from each agent run's reported usage. */
+	maxTokenBudget?: number;
 }
 
 /** A dynamic workflow (runtime === "dynamic"). steps is empty — the script is the source of truth. */

package/src/worktree/worktree-manager.ts

@@ -1,4 +1,5 @@
 import { execFileSync, spawnSync } from "node:child_process";
+import { randomBytes } from "node:crypto";
 import * as fs from "node:fs";
 import * as path from "node:path";
 import { WINDOWS_ESSENTIAL_ENV_VARS } from "../utils/env-allowlist.ts";
@@ -7,6 +8,7 @@ import { projectCrewRoot } from "../utils/paths.ts";
 import { DEFAULT_PATHS } from "../config/defaults.ts";
 import { logInternalError } from "../utils/internal-error.ts";
 import { sanitizeEnvSecrets } from "../utils/env-filter.ts";
+import { writeArtifact } from "../state/artifact-store.ts";
 import type { TeamRunManifest, TeamTaskState } from "../state/types.ts";
 
 export interface PreparedTaskWorkspace {
@@ -460,3 +462,95 @@ export function captureWorktreeDiff(worktreePath: string): string {
 		return `Failed to capture worktree diff: ${message}`;
 	}
 }
+
+/**
+ * round-17 P2-4: Create an isolated git worktree for a single DWF agent call.
+ *
+ * Lightweight — does NOT require a TeamTaskState and does NOT depend on
+ * `manifest.workspaceMode === "worktree"` (DWF manifests use `single`). It
+ * reuses the same internal helpers as `prepareTaskWorkspace` (git, findGitRoot,
+ * assertCleanLeader, pruneStaleWorktrees, sanitizeBranchPart,
+ * linkNodeModulesIfPresent) but with a minimal, task-free signature.
+ *
+ * Returns `undefined` when worktree creation is unavailable (no git repo, dirty
+ * leader, git error) so the caller (`ctx.agent`) can fall back gracefully.
+ */
+export function prepareAgentWorktree(
+	manifest: TeamRunManifest,
+	agentId: string,
+): PreparedTaskWorkspace | undefined {
+	try {
+		const repoRoot = findGitRoot(manifest.cwd);
+		const loadedConfig = loadConfig(manifest.cwd);
+		if (loadedConfig.config.requireCleanWorktreeLeader !== false) assertCleanLeader(repoRoot);
+		const sanitizedRunId = manifest.runId.replace(/[^a-zA-Z0-9._-]/g, "-").replace(/^-+|-+$/g, "") || "run";
+		const worktreeRoot = path.join(projectCrewRoot(manifest.cwd), DEFAULT_PATHS.state.worktreesSubdir, sanitizedRunId);
+		fs.mkdirSync(worktreeRoot, { recursive: true });
+		const sanitizedAgentId = sanitizeBranchPart(agentId);
+		const worktreePath = path.join(worktreeRoot, sanitizedAgentId);
+		const branch = `pi-crew/${sanitizedRunId}/${sanitizedAgentId}`;
+		pruneStaleWorktrees(repoRoot);
+		git(repoRoot, ["worktree", "add", "-b", branch, worktreePath, "HEAD"]);
+		const nodeModulesLinked = loadedConfig.config.worktree?.linkNodeModules === true
+			? linkNodeModulesIfPresent(repoRoot, worktreePath)
+			: false;
+		return { cwd: worktreePath, worktreePath, branch, nodeModulesLinked };
+	} catch {
+		// Graceful fallback: no git repo, dirty leader, or git error → run normally.
+		return undefined;
+	}
+}
+
+/**
+ * round-17 P2-4: Remove a DWF agent worktree after the agent completes.
+ *
+ * Captures the worktree diff as an artifact before removal (best-effort), then
+ * removes the worktree, deletes the ephemeral branch, and prunes stale refs.
+ * NEVER throws — cleanup failures are logged via `logInternalError` so a
+ * worktree/branch leak never crashes a workflow.
+ */
+export function cleanupAgentWorktree(manifest: TeamRunManifest, worktreePath: string, branch?: string): void {
+	// Capture diff as artifact (best-effort).
+	try {
+		const diff = captureWorktreeDiff(worktreePath);
+		if (diff.trim() && !diff.startsWith("Failed to capture worktree diff")) {
+			writeArtifact(manifest.artifactsRoot, {
+				kind: "diff",
+				relativePath: `wf/worktree-diff-${Date.now()}-${randomBytes(2).toString("hex")}.diff`,
+				content: diff,
+				producer: "dynamic-workflow",
+			});
+		}
+	} catch (error) {
+		logInternalError("worktree.agent-cleanup.diff", error, `worktreePath=${worktreePath}`);
+	}
+	// Remove worktree (best-effort). Try git first, then fall back to fs.rm.
+	try {
+		const repoRoot = findGitRoot(manifest.cwd);
+		git(repoRoot, ["worktree", "remove", "--force", worktreePath]);
+	} catch (error) {
+		logInternalError("worktree.agent-cleanup.remove", error, `worktreePath=${worktreePath}`);
+		try {
+			fs.rmSync(worktreePath, { recursive: true, force: true });
+		} catch (rmError) {
+			logInternalError("worktree.agent-cleanup.rm", rmError, `worktreePath=${worktreePath}`);
+		}
+	}
+	// Delete the ephemeral agent branch (best-effort) to avoid accumulation across
+	// many agent calls. The diff is already captured above; the branch holds no value.
+	if (branch) {
+		try {
+			const repoRoot = findGitRoot(manifest.cwd);
+			git(repoRoot, ["branch", "-D", branch]);
+		} catch (error) {
+			logInternalError("worktree.agent-cleanup.branch", error, `branch=${branch}`);
+		}
+	}
+	// Prune stale worktree refs (best-effort).
+	try {
+		const repoRoot = findGitRoot(manifest.cwd);
+		git(repoRoot, ["worktree", "prune"]);
+	} catch (error) {
+		logInternalError("worktree.agent-cleanup.prune", error, `worktreePath=${worktreePath}`);
+	}
+}

package/types/dwf.d.ts

@@ -0,0 +1,187 @@
+/**
+ * Authoring types for pi-crew dynamic workflow scripts (`.dwf.ts`).
+ *
+ * Round-14 P1-1: gives TS users IDE IntelliSense for the `ctx` object passed to a
+ * workflow script's `export default async function(ctx) { ... }`.
+ *
+ * pi-crew passes `ctx` as a parameter (NOT as ambient globals), so the types here are
+ * named exports. Import them in your workflow script:
+ *
+ * ```ts
+ * import type { WorkflowCtx } from "pi-crew/workflow";
+ *
+ * export default async function run(ctx: WorkflowCtx): Promise<void> {
+ *   ctx.log("starting");
+ *   const res = await ctx.agent({ role: "explorer", prompt: "look around" });
+ *   ctx.setResult(res.artifactPath ?? "");
+ * }
+ * ```
+ *
+ * Alternatively, add a triple-slash reference so the package's type map is loaded:
+ *
+ * ```ts
+ * /// <reference types="pi-crew/workflow" />
+ * import type { WorkflowCtx } from "pi-crew/workflow";
+ * ```
+ *
+ * These interfaces mirror the runtime types in `src/runtime/dynamic-workflow-context.ts`.
+ * They are authoring-only (no runtime values); the real implementations live in the runner.
+ *
+ * ## Resume & Checkpoint (round-18 P2-3)
+ *
+ * The runner persists a checkpoint after every `ctx.agent()` call so that a crash
+ * (timeout, OOM, agent error) between calls does not lose all progress. When you run
+ * `team action='resume' runId='X'`, the runner re-executes the script from the top
+ * but **hydrates** `ctx.vars`, `ctx.budget.spent()`, the phase list, and the log
+ * buffer from the last checkpoint.
+ *
+ * Because the script re-runs from the top, write it **defensively** — check
+ * `ctx.vars` to skip already-completed work:
+ *
+ * ```ts
+ * export default async function run(ctx) {
+ *   // Defensive resume: skip the scan phase if it already ran.
+ *   if (ctx.vars.lastPhase !== "scan") {
+ *     const res = await ctx.agent({ role: "explorer", prompt: "scan" });
+ *     ctx.vars.lastPhase = "scan";   // checkpointed after this call
+ *   }
+ *   // ... continue with analyze, using ctx.vars from the prior run
+ * }
+ * ```
+ *
+ * On a clean completion the checkpoint is deleted, so a re-run with the same runId
+ * starts fresh. A missing or corrupt checkpoint is treated as a fresh run.
+ */
+
+export interface AgentCallOpts {
+	prompt: string;
+	/** Role name (resolved via 4-tier chain) OR explicit agent name. */
+	role?: string;
+	/** Explicit agent name — bypasses team-role lookup. */
+	agent?: string;
+	description?: string;
+	model?: string;
+	skill?: string[] | false;
+	maxTurns?: number;
+	graceTurns?: number;
+	/** Dependency artifact paths injected into the agent prompt. */
+	inputs?: string[];
+	/** Disable ALL tools for this call (pure-judgment / verdict steps). */
+	disableTools?: boolean;
+	/** Override the resolved agent's system prompt. */
+	systemPrompt?: string;
+	/** Round-13: optional TypeBox schema. When set, output is validated; mismatch yields ok:false. */
+	schema?: { readonly [key: string]: unknown };
+	/** round-17 P2-4: spawn this agent in an isolated git worktree. Useful when
+	 *  parallel agents modify files concurrently (avoids conflicts). The worktree
+	 *  is created from HEAD, the agent runs there, and on completion the diff is
+	 *  captured as an artifact before cleanup. Default false. If worktree creation
+	 *  fails (no git repo, dirty leader), the agent runs in the normal cwd with a
+	 *  warning. Backward compatible — omitting it is identical to `false`. */
+	worktree?: boolean;
+}
+
+export interface AgentResult {
+	ok: boolean;
+	text: string;
+	structured?: unknown;
+	usage?: { input?: number; output?: number; cost?: number; turns?: number };
+	runId?: string;
+	taskId?: string;
+	artifactPath?: string;
+	error?: string;
+	durationMs?: number;
+}
+
+/** Round-14 P1-2: per-workflow token budget. */
+export interface WorkflowBudget {
+	/** Configured budget, or null when unbounded. */
+	total: number | null;
+	/** Tokens consumed so far (accumulated from each ctx.agent() run's usage). */
+	spent(): number;
+	/** Tokens remaining; Infinity when total is null. */
+	remaining(): number;
+}
+
+export interface ReviewResult {
+	outcome: "accept" | "reject" | "changes_requested";
+	feedback: string;
+}
+
+/** Options for ctx.mail(). */
+export interface MailOpts {
+	kind?: string;
+	taskId?: string;
+	replyTo?: string;
+	replyDeadline?: number;
+}
+
+/** Options for ctx.review(). */
+export interface ReviewOpts {
+	content?: string;
+	artifactPath?: string;
+	disableTools?: boolean;
+}
+
+/** Options for ctx.retry(). */
+export interface RetryOpts {
+	feedback?: string;
+}
+
+/**
+ * The capability-locked context object passed to a `.dwf.ts` script's
+ * `export default async function(ctx)`. Exposes ONLY the documented methods —
+ * no raw manifest/process/require leaks.
+ *
+ * NOTE: v1 has NO vm sandbox; the script CAN reach process/require directly.
+ * The frozen ctx is a contract surface, not a security boundary. `.dwf.ts`
+ * scripts are postinstall-equivalent trust.
+ */
+export interface WorkflowCtx {
+	cwd: string;
+	runId: string;
+	goal?: string;
+	/** Script-local persistent variables.
+	 *
+	 *  On resume (round-18 P2-3), these are hydrated from the last checkpoint so a
+	 *  re-run continues where it left off. Write defensive scripts that inspect
+	 *  `ctx.vars` to skip work already done in a prior (crashed) run. */
+	vars: Record<string, unknown>;
+	/** Abort signal (cancel/stop). */
+	signal: AbortSignal;
+	/** Concurrency semaphore (bounded by ctx concurrency). */
+	semaphore: import("../src/runtime/semaphore").Semaphore;
+
+	/** Spawn one agent, await result. Concurrency enforced by ctx.semaphore. */
+	agent(opts: AgentCallOpts): Promise<AgentResult>;
+	/** Bounded fan-out preserving order. */
+	fanOut<T>(items: T[], limit: number, fn: (item: T, i: number) => Promise<AgentResult>): Promise<AgentResult[]>;
+	/** Pipeline: sequential per-item stages, parallel across items (bounded by ctx.semaphore).
+	 *  Failed stage → null for that item (logged); other items continue. round-16 (P2-1). */
+	pipeline<TItem, TResult = unknown>(
+		items: TItem[],
+		...stages: Array<(previous: TResult, original: TItem, index: number) => Promise<TResult> | TResult>
+	): Promise<(TResult | null)[]>;
+	/** Run a reviewer agent over an artifact; parse {outcome, feedback}. */
+	review(taskId: string, reviewerRole?: string, opts?: ReviewOpts): Promise<ReviewResult>;
+	/** Re-run a task with feedback (wraps executeWithRetry). */
+	retry(taskId: string, opts?: RetryOpts): Promise<AgentResult>;
+	/** Send a mailbox message to another agent/leader. Returns the message id. */
+	mail(to: string, body: string, opts?: MailOpts): string;
+	/** Block until N mailbox replies arrive or deadline. */
+	gatherReplies(messageIds: string[], deadlineMs: number): Promise<unknown[]>;
+	/** Render a built-in plan template (full-implementation / standard-review). */
+	renderTemplate(name: string, vars: Record<string, string>): unknown;
+	/** Mark the final result. ONLY this artifact reaches the main context. */
+	setResult(artifactPath: string, meta?: Record<string, unknown>): void;
+	/** Round-12: mark the start of a named workflow phase (emits dwf.phase_started/_completed). Idempotent on the same title. */
+	phase(title: string): void;
+	/** Round-14 P1-3: append a workflow-level log line (emits a dwf.log event). */
+	log(message: unknown): void;
+	/** Round-14 P1-2: per-workflow token budget; ctx.agent() auto-rejects when exhausted. */
+	budget: WorkflowBudget;
+	/** Round-14 P1-5: typed workflow arguments (sourced from manifest.args). Defaults to {}. */
+	args<T = unknown>(): T;
+}
+
+export {};