pi-crew 0.1.51 → 0.2.0

package/src/runtime/supervisor-contact.ts

@@ -1,59 +1,59 @@
-import type { TeamRunManifest } from "../state/types.ts";
-import { appendEvent } from "../state/event-log.ts";
-import { logInternalError } from "../utils/internal-error.ts";
-
-export interface SupervisorContactPayload {
-	runId: string;
-	taskId: string;
-	reason: "decision_needed" | "clarification" | "approval" | "error_escalation" | "custom";
-	message: string;
-	data?: Record<string, unknown>;
-	timestamp: string;
-}
-
-/**
- * Record a supervisor contact event from a child task.
- * This represents a child→parent communication where the child needs
- * a decision, clarification, or approval to continue.
- */
-export function recordSupervisorContact(manifest: TeamRunManifest, payload: Omit<SupervisorContactPayload, "timestamp">): void {
-	const fullPayload: SupervisorContactPayload = {
-		...payload,
-		timestamp: new Date().toISOString(),
-	};
-	try {
-		appendEvent(manifest.eventsPath, {
-			type: "supervisor.contact",
-			runId: manifest.runId,
-			taskId: payload.taskId,
-			data: fullPayload as unknown as Record<string, unknown>,
-		});
-	} catch (error) {
-		logInternalError("supervisor-contact.record", error, `runId=${manifest.runId} taskId=${payload.taskId}`);
-	}
-}
-
-/**
- * Parse a supervisor contact request from child Pi stdout.
- * Detects structured JSON lines with type "supervisor_contact".
- */
-export function parseSupervisorContactFromLine(line: string): Omit<SupervisorContactPayload, "timestamp" | "runId"> | undefined {
-	if (!line.trim()) return undefined;
-	let parsed: unknown;
-	try {
-		parsed = JSON.parse(line);
-	} catch {
-		return undefined;
-	}
-	if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) return undefined;
-	const record = parsed as Record<string, unknown>;
-	if (record.type !== "supervisor_contact" && record.type !== "crew_supervisor_contact") return undefined;
-	return {
-		taskId: typeof record.taskId === "string" ? record.taskId : "",
-		reason: typeof record.reason === "string" && ["decision_needed", "clarification", "approval", "error_escalation", "custom"].includes(record.reason)
-			? record.reason as SupervisorContactPayload["reason"]
-			: "custom",
-		message: typeof record.message === "string" ? record.message : String(record.message ?? ""),
-		data: record.data && typeof record.data === "object" && !Array.isArray(record.data) ? record.data as Record<string, unknown> : undefined,
-	};
-}
+import type { TeamRunManifest } from "../state/types.ts";
+import { appendEvent } from "../state/event-log.ts";
+import { logInternalError } from "../utils/internal-error.ts";
+
+export interface SupervisorContactPayload {
+	runId: string;
+	taskId: string;
+	reason: "decision_needed" | "clarification" | "approval" | "error_escalation" | "custom";
+	message: string;
+	data?: Record<string, unknown>;
+	timestamp: string;
+}
+
+/**
+ * Record a supervisor contact event from a child task.
+ * This represents a child→parent communication where the child needs
+ * a decision, clarification, or approval to continue.
+ */
+export function recordSupervisorContact(manifest: TeamRunManifest, payload: Omit<SupervisorContactPayload, "timestamp">): void {
+	const fullPayload: SupervisorContactPayload = {
+		...payload,
+		timestamp: new Date().toISOString(),
+	};
+	try {
+		appendEvent(manifest.eventsPath, {
+			type: "supervisor.contact",
+			runId: manifest.runId,
+			taskId: payload.taskId,
+			data: fullPayload as unknown as Record<string, unknown>,
+		});
+	} catch (error) {
+		logInternalError("supervisor-contact.record", error, `runId=${manifest.runId} taskId=${payload.taskId}`);
+	}
+}
+
+/**
+ * Parse a supervisor contact request from child Pi stdout.
+ * Detects structured JSON lines with type "supervisor_contact".
+ */
+export function parseSupervisorContactFromLine(line: string): Omit<SupervisorContactPayload, "timestamp" | "runId"> | undefined {
+	if (!line.trim()) return undefined;
+	let parsed: unknown;
+	try {
+		parsed = JSON.parse(line);
+	} catch {
+		return undefined;
+	}
+	if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) return undefined;
+	const record = parsed as Record<string, unknown>;
+	if (record.type !== "supervisor_contact" && record.type !== "crew_supervisor_contact") return undefined;
+	return {
+		taskId: typeof record.taskId === "string" ? record.taskId : "",
+		reason: typeof record.reason === "string" && ["decision_needed", "clarification", "approval", "error_escalation", "custom"].includes(record.reason)
+			? record.reason as SupervisorContactPayload["reason"]
+			: "custom",
+		message: typeof record.message === "string" ? record.message : String(record.message ?? ""),
+		data: record.data && typeof record.data === "object" && !Array.isArray(record.data) ? record.data as Record<string, unknown> : undefined,
+	};
+}

package/src/runtime/task-display.ts

@@ -1,38 +1,38 @@
-import type { TeamTaskState } from "../state/types.ts";
-import type { CrewAgentRecord, CrewRuntimeKind } from "./crew-agent-runtime.ts";
-import { recordFromTask } from "./crew-agent-records.ts";
-import type { TeamRunManifest } from "../state/types.ts";
-
-export function shouldMaterializeAgent(task: TeamTaskState): boolean {
-	return task.status !== "queued" && task.status !== "skipped";
-}
-
-export function recordsForMaterializedTasks(manifest: TeamRunManifest, tasks: TeamTaskState[], runtime: CrewRuntimeKind): CrewAgentRecord[] {
-	return tasks.filter(shouldMaterializeAgent).map((task) => recordFromTask(manifest, task, runtime));
-}
-
-export function taskById(tasks: TeamTaskState[]): Map<string, TeamTaskState> {
-	const map = new Map<string, TeamTaskState>();
-	for (const task of tasks) {
-		map.set(task.id, task);
-		if (task.stepId) map.set(task.stepId, task);
-	}
-	return map;
-}
-
-export function waitingReason(task: TeamTaskState, tasks: TeamTaskState[]): string | undefined {
-	if (task.status !== "queued") return undefined;
-	const byId = taskById(tasks);
-	const waiting = task.dependsOn.map((id) => byId.get(id)?.id ?? id).filter((id) => byId.get(id)?.status !== "completed");
-	if (waiting.length === 0) return "ready";
-	return `waiting for ${waiting.join(", ")}`;
-}
-
-export function formatTaskGraphLines(tasks: TeamTaskState[]): string[] {
-	if (tasks.length === 0) return ["- (none)"];
-	return tasks.map((task) => {
-		const icon = task.status === "completed" ? "✓" : task.status === "running" ? "⠋" : task.status === "failed" ? "✗" : task.status === "cancelled" || task.status === "skipped" ? "■" : "◦";
-		const wait = waitingReason(task, tasks);
-		return `- ${icon} ${task.id} [${task.status}] ${task.role}->${task.agent}${wait && wait !== "ready" ? ` (${wait})` : ""}`;
-	});
-}
+import type { TeamTaskState } from "../state/types.ts";
+import type { CrewAgentRecord, CrewRuntimeKind } from "./crew-agent-runtime.ts";
+import { recordFromTask } from "./crew-agent-records.ts";
+import type { TeamRunManifest } from "../state/types.ts";
+
+export function shouldMaterializeAgent(task: TeamTaskState): boolean {
+	return task.status !== "queued" && task.status !== "skipped";
+}
+
+export function recordsForMaterializedTasks(manifest: TeamRunManifest, tasks: TeamTaskState[], runtime: CrewRuntimeKind): CrewAgentRecord[] {
+	return tasks.filter(shouldMaterializeAgent).map((task) => recordFromTask(manifest, task, runtime));
+}
+
+export function taskById(tasks: TeamTaskState[]): Map<string, TeamTaskState> {
+	const map = new Map<string, TeamTaskState>();
+	for (const task of tasks) {
+		map.set(task.id, task);
+		if (task.stepId) map.set(task.stepId, task);
+	}
+	return map;
+}
+
+export function waitingReason(task: TeamTaskState, tasks: TeamTaskState[]): string | undefined {
+	if (task.status !== "queued") return undefined;
+	const byId = taskById(tasks);
+	const waiting = task.dependsOn.map((id) => byId.get(id)?.id ?? id).filter((id) => byId.get(id)?.status !== "completed");
+	if (waiting.length === 0) return "ready";
+	return `waiting for ${waiting.join(", ")}`;
+}
+
+export function formatTaskGraphLines(tasks: TeamTaskState[]): string[] {
+	if (tasks.length === 0) return ["- (none)"];
+	return tasks.map((task) => {
+		const icon = task.status === "completed" ? "✓" : task.status === "running" ? "⠋" : task.status === "failed" ? "✗" : task.status === "cancelled" || task.status === "skipped" ? "■" : "◦";
+		const wait = waitingReason(task, tasks);
+		return `- ${icon} ${task.id} [${task.status}] ${task.role}->${task.agent}${wait && wait !== "ready" ? ` (${wait})` : ""}`;
+	});
+}

package/src/runtime/task-graph.ts

@@ -0,0 +1,207 @@
+/**
+ * DAG-based task execution order calculator.
+ *
+ * Uses Kahn's algorithm for topological sort and DFS for cycle detection.
+ * Groups tasks into parallel "waves" where all tasks in wave N can run
+ * concurrently and wave N+1 depends on at least one task in wave N.
+ */
+
+/** A lightweight node representation for the execution DAG. */
+export interface TaskNode {
+	id: string;
+	dependsOn: string[];
+	phase?: string;
+}
+
+/** A group of tasks that can all run in parallel. */
+export interface ExecutionWave {
+	index: number;
+	taskIds: string[];
+	label?: string;
+}
+
+/** The full execution plan produced by topological sort. */
+export interface ExecutionPlan {
+	waves: ExecutionWave[];
+	hasCycle: boolean;
+	cycleNodes?: string[];
+}
+
+/**
+ * Build an execution plan from a flat list of task nodes using Kahn's algorithm.
+ *
+ * - Tasks with empty `dependsOn` go into wave 0.
+ * - Each subsequent wave contains tasks whose dependencies are all in earlier waves.
+ * - If all tasks have empty `dependsOn`, they all go into wave 0 (backward compatible).
+ * - If a cycle is detected, `hasCycle` is true and `cycleNodes` lists the involved IDs.
+ */
+export function buildExecutionPlan(tasks: TaskNode[]): ExecutionPlan {
+	if (tasks.length === 0) {
+		return { waves: [], hasCycle: false };
+	}
+
+	const idSet = new Set<string>(tasks.map((t) => t.id));
+	const adjacency = new Map<string, Set<string>>();       // id -> ids that depend on it
+	const inDegree = new Map<string, number>();
+
+	for (const task of tasks) {
+		adjacency.set(task.id, new Set<string>());
+		inDegree.set(task.id, 0);
+	}
+
+	for (const task of tasks) {
+		let degree = 0;
+		for (const dep of task.dependsOn) {
+			if (!idSet.has(dep)) continue; // ignore unknown deps
+			adjacency.get(dep)!.add(task.id);
+			degree++;
+		}
+		inDegree.set(task.id, degree);
+	}
+
+	// Kahn's algorithm with wave grouping
+	const waves: ExecutionWave[] = [];
+	const assigned = new Set<string>();
+	let currentWaveIds = tasks
+		.filter((t) => inDegree.get(t.id) === 0)
+		.map((t) => t.id);
+
+	let waveIndex = 0;
+	while (currentWaveIds.length > 0) {
+		for (const id of currentWaveIds) assigned.add(id);
+
+		const wave = buildWave(tasks, currentWaveIds, waveIndex);
+		waves.push(wave);
+
+		// Decrement in-degrees for dependents
+		const nextWaveCandidates = new Set<string>();
+		for (const id of currentWaveIds) {
+			for (const dependent of adjacency.get(id) ?? []) {
+				const current = inDegree.get(dependent)!;
+				inDegree.set(dependent, current - 1);
+				if (current - 1 === 0) nextWaveCandidates.add(dependent);
+			}
+		}
+
+		currentWaveIds = [...nextWaveCandidates];
+		waveIndex++;
+	}
+
+	// Detect cycle: if not all tasks were assigned, remaining ones form cycles
+	if (assigned.size < tasks.length) {
+		const cycleNodes = tasks
+			.filter((t) => !assigned.has(t.id))
+			.map((t) => t.id);
+		return {
+			waves,
+			hasCycle: true,
+			cycleNodes,
+		};
+	}
+
+	return { waves, hasCycle: false };
+}
+
+/**
+ * Derive the phase label for a wave. If all tasks in the wave share the same
+ * `phase` value, use it as the wave label; otherwise leave it undefined.
+ */
+function buildWave(tasks: TaskNode[], ids: string[], index: number): ExecutionWave {
+	const taskMap = new Map(tasks.map((t) => [t.id, t]));
+	const waveTasks = ids.map((id) => taskMap.get(id)!).filter(Boolean);
+
+	let label: string | undefined;
+	if (waveTasks.length > 0 && waveTasks.every((t) => t.phase !== undefined)) {
+		const phases = new Set(waveTasks.map((t) => t.phase));
+		if (phases.size === 1) label = [...phases][0];
+	}
+
+	return { index, taskIds: ids, label };
+}
+
+/**
+ * Return the IDs of tasks that are ready to run given a set of completed tasks.
+ *
+ * A task is "ready" when all its dependencies are in `completedTaskIds` AND
+ * it has not already been completed itself. Returns tasks from the earliest
+ * wave that still has uncompleted tasks.
+ */
+export function getReadyTasks(plan: ExecutionPlan, completedTaskIds: Set<string>): string[] {
+	if (plan.hasCycle || plan.waves.length === 0) return [];
+
+	const completed = completedTaskIds;
+
+	for (const wave of plan.waves) {
+		// All tasks in prior waves must be completed for this wave to be ready
+		const priorWavesComplete = plan.waves
+			.slice(0, wave.index)
+			.every((w) => w.taskIds.every((id) => completed.has(id)));
+
+		if (!priorWavesComplete) continue;
+
+		// Filter to tasks not already completed
+		const ready = wave.taskIds.filter((id) => !completed.has(id));
+		if (ready.length > 0) return ready;
+	}
+
+	return [];
+}
+
+/**
+ * Detect all cycles in the task graph using DFS.
+ *
+ * Returns an array of cycles, where each cycle is represented as an array of
+ * task IDs forming a path from a node back to itself.
+ */
+export function detectCycles(tasks: TaskNode[]): string[][] {
+	if (tasks.length === 0) return [];
+
+	const idSet = new Set<string>(tasks.map((t) => t.id));
+	const adjacency = new Map<string, string[]>();
+	for (const task of tasks) {
+		adjacency.set(
+			task.id,
+			task.dependsOn.filter((dep) => idSet.has(dep)),
+		);
+	}
+
+	const WHITE = 0;
+	const GRAY = 1;
+	const BLACK = 2;
+
+	const color = new Map<string, number>();
+	for (const task of tasks) color.set(task.id, WHITE);
+
+	const cycles: string[][] = [];
+	const path: string[] = [];
+
+	function dfs(nodeId: string): void {
+		color.set(nodeId, GRAY);
+		path.push(nodeId);
+
+		const deps = adjacency.get(nodeId) ?? [];
+		for (const dep of deps) {
+			const depColor = color.get(dep);
+			if (depColor === GRAY) {
+				// Found a cycle: extract the path from dep to current node
+				const cycleStart = path.indexOf(dep);
+				if (cycleStart >= 0) {
+					cycles.push(path.slice(cycleStart));
+				}
+			} else if (depColor === WHITE) {
+				dfs(dep);
+			}
+		}
+
+		path.pop();
+		color.set(nodeId, BLACK);
+	}
+
+	for (const task of tasks) {
+		if (color.get(task.id) === WHITE) {
+			dfs(task.id);
+		}
+	}
+
+	return cycles;
+}

package/src/runtime/task-quality.ts

@@ -0,0 +1,207 @@
+/**
+ * Task quality scoring — simple additive heuristic for evaluating task
+ * completion quality based on diagnostics, metrics, artifacts, and duration.
+ *
+ * Distilled from pi-autoresearch's quality scoring pattern.
+ */
+import * as fs from "node:fs";
+import * as path from "node:path";
+import type { TeamTaskState } from "../state/types.ts";
+
+/** Letter grade for task quality. */
+export type QualityGrade = "A" | "B" | "C" | "D";
+
+/** Breakdown of individual quality criteria. */
+export interface QualityBreakdown {
+	/** Task has a non-empty diagnostics object. */
+	hasDiagnostics: boolean;
+	/** Task has a non-empty metrics object. */
+	hasMetrics: boolean;
+	/** Task produced files in the artifacts directory. */
+	producedArtifacts: boolean;
+	/** Task has a non-empty result/description. */
+	hasDescription: boolean;
+	/** Task duration is reasonable (> 0 and < 1 hour). */
+	durationReasonable: boolean;
+}
+
+/** Scored quality result for a task. */
+export interface TaskQualityScore {
+	/** Numeric score (0–5). */
+	score: number;
+	/** Individual criterion breakdown. */
+	breakdown: QualityBreakdown;
+	/** Letter grade based on score thresholds. */
+	grade: QualityGrade;
+}
+
+/** One hour in milliseconds. */
+const ONE_HOUR_MS = 3_600_000;
+
+/**
+ * Determine the letter grade for a given numeric score.
+ *
+ * A: 4–5, B: 3, C: 2, D: 0–1
+ */
+function scoreToGrade(score: number): QualityGrade {
+	if (score >= 4) return "A";
+	if (score === 3) return "B";
+	if (score === 2) return "C";
+	return "D";
+}
+
+/**
+ * Check whether the artifacts directory contains files for the given task.
+ *
+ * Looks for a subdirectory named after the task ID, or files containing
+ * the task ID prefix in the artifacts directory.
+ */
+function hasTaskArtifacts(taskId: string, artifactsDir: string): boolean {
+	try {
+		if (!fs.existsSync(artifactsDir)) return false;
+
+		// Check for a task-specific subdirectory
+		const taskDir = path.join(artifactsDir, taskId);
+		if (fs.existsSync(taskDir)) {
+			const stat = fs.statSync(taskDir);
+			if (stat.isDirectory()) {
+				const entries = fs.readdirSync(taskDir);
+				return entries.length > 0;
+			}
+		}
+
+		// Check for files containing the task ID prefix
+		const entries = fs.readdirSync(artifactsDir);
+		const safePrefix = taskId.replace(/[^a-zA-Z0-9_-]/g, "");
+		return entries.some((entry) => entry.includes(safePrefix));
+	} catch {
+		return false;
+	}
+}
+
+/**
+ * Check if a task result string is a non-empty description.
+ *
+ * A result is considered descriptive if any of these sources have non-empty content:
+ * - task.resultArtifact exists with a path
+ * - task.error is a non-empty string (workers often set this with result info)
+ * - task.verification.satisfied is true
+ * - task.diagnostics contains a 'result' string
+ */
+function isResultDescriptive(task: TeamTaskState): boolean {
+	// Check resultArtifact — presence of a result artifact indicates output was produced
+	if (task.resultArtifact?.path) return true;
+
+	// Check error field — workers often put result info here
+	if (typeof task.error === "string" && task.error.trim().length > 0) return true;
+
+	// Check verification — satisfied verification indicates meaningful output
+	if (task.verification?.satisfied) return true;
+
+	// Check diagnostics for an explicit result string
+	if (
+		task.diagnostics &&
+		typeof task.diagnostics === "object" &&
+		typeof task.diagnostics.result === "string" &&
+		(task.diagnostics.result as string).trim().length > 0
+	) return true;
+
+	return false;
+}
+
+/**
+ * Check if the task duration is reasonable (started, finished, > 0, < 1 hour).
+ */
+function isDurationReasonable(task: TeamTaskState): boolean {
+	if (!task.startedAt || !task.finishedAt) return false;
+
+	const started = new Date(task.startedAt).getTime();
+	const finished = new Date(task.finishedAt).getTime();
+
+	if (Number.isNaN(started) || Number.isNaN(finished)) return false;
+
+	const duration = finished - started;
+	return duration > 0 && duration < ONE_HOUR_MS;
+}
+
+/**
+ * Compute the quality score for a completed task.
+ *
+ * Uses simple additive scoring across 5 criteria:
+ * - hasDiagnostics: +1 if task.diagnostics exists and has keys
+ * - hasMetrics: +1 if task.metrics exists and has keys
+ * - producedArtifacts: +1 if artifactsDir has files for this task
+ * - hasDescription: +1 if task has a non-empty result/description
+ * - durationReasonable: +1 if task has both startedAt and finishedAt, duration > 0 and < 1 hour
+ *
+ * @param task - The task state to evaluate
+ * @param artifactsDir - Optional path to the run artifacts directory
+ * @returns TaskQualityScore with numeric score, breakdown, and letter grade
+ */
+export function computeTaskQuality(
+	task: TeamTaskState,
+	artifactsDir?: string,
+): TaskQualityScore {
+	const hasDiagnostics =
+		task.diagnostics !== undefined &&
+		typeof task.diagnostics === "object" &&
+		Object.keys(task.diagnostics).length > 0;
+
+	const hasMetrics =
+		task.metrics !== undefined &&
+		typeof task.metrics === "object" &&
+		Object.keys(task.metrics).length > 0;
+
+	const producedArtifacts =
+		artifactsDir !== undefined && hasTaskArtifacts(task.id, artifactsDir);
+
+	const hasDescription = isResultDescriptive(task);
+
+	const durationReasonable = isDurationReasonable(task);
+
+	const breakdown: QualityBreakdown = {
+		hasDiagnostics,
+		hasMetrics,
+		producedArtifacts,
+		hasDescription,
+		durationReasonable,
+	};
+
+	const score =
+		(hasDiagnostics ? 1 : 0) +
+		(hasMetrics ? 1 : 0) +
+		(producedArtifacts ? 1 : 0) +
+		(hasDescription ? 1 : 0) +
+		(durationReasonable ? 1 : 0);
+
+	return {
+		score,
+		breakdown,
+		grade: scoreToGrade(score),
+	};
+}
+
+/** Human-readable labels for each quality criterion. */
+const CRITERION_LABELS: Record<keyof QualityBreakdown, string> = {
+	hasDiagnostics: "diagnostics",
+	hasMetrics: "metrics",
+	producedArtifacts: "artifacts",
+	hasDescription: "description",
+	durationReasonable: "duration",
+};
+
+/**
+ * Format a quality score as a human-readable one-line string.
+ *
+ * Format: "Quality: B (3/5: diagnostics, metrics, description)"
+ *
+ * @param score - The quality score to format
+ * @returns Formatted string
+ */
+export function formatQualityScore(score: TaskQualityScore): string {
+	const metCriteria = Object.entries(score.breakdown)
+		.filter(([, met]) => met)
+		.map(([key]) => CRITERION_LABELS[key as keyof QualityBreakdown]);
+
+	return `Quality: ${score.grade} (${score.score}/5${metCriteria.length > 0 ? `: ${metCriteria.join(", ")}` : ""})`;
+}