pi-crew 0.1.51 → 0.2.1

package/src/runtime/policy-engine.ts

@@ -1,79 +1,79 @@
-import type { CrewLimitsConfig } from "../config/config.ts";
-import type { PolicyDecision, PolicyDecisionAction, PolicyDecisionReason, TeamRunManifest, TeamTaskState } from "../state/types.ts";
-import { evaluateGreenContract } from "./green-contract.ts";
-import { isWorkerHeartbeatStale } from "./worker-heartbeat.ts";
-
-export interface PolicyEngineInput {
-	manifest: TeamRunManifest;
-	tasks: TeamTaskState[];
-	limits?: CrewLimitsConfig;
-	now?: Date;
-}
-
-function decision(action: PolicyDecisionAction, reason: PolicyDecisionReason, message: string, taskId?: string): PolicyDecision {
-	return {
-		action,
-		reason,
-		message,
-		taskId,
-		createdAt: new Date().toISOString(),
-	};
-}
-
-function taskDepth(task: TeamTaskState, tasksById: Map<string, TeamTaskState>): number {
-	let depth = 0;
-	let current = task.graph?.parentId;
-	const seen = new Set<string>();
-	while (current && !seen.has(current)) {
-		seen.add(current);
-		depth += 1;
-		current = tasksById.get(current)?.graph?.parentId;
-	}
-	return depth;
-}
-
-export function evaluateCrewPolicy(input: PolicyEngineInput): PolicyDecision[] {
-	const decisions: PolicyDecision[] = [];
-	const maxTasksPerRun = Number.isFinite(input.limits?.maxTasksPerRun) ? input.limits!.maxTasksPerRun : undefined;
-	if (maxTasksPerRun !== undefined && input.tasks.length > maxTasksPerRun) {
-		decisions.push(decision("block", "limit_exceeded", `Run has ${input.tasks.length} tasks, exceeding maxTasksPerRun=${maxTasksPerRun}.`));
-	}
-	const runningCount = input.tasks.filter((task) => task.status === "running").length;
-	const maxConcurrentWorkers = Number.isFinite(input.limits?.maxConcurrentWorkers) ? input.limits!.maxConcurrentWorkers : undefined;
-	if (maxConcurrentWorkers !== undefined && runningCount > maxConcurrentWorkers) {
-		decisions.push(decision("block", "limit_exceeded", `Run has ${runningCount} running workers, exceeding maxConcurrentWorkers=${maxConcurrentWorkers}.`));
-	}
-	const tasksById = new Map(input.tasks.map((task) => [task.id, task]));
-
-	for (const task of input.tasks) {
-		if (input.limits?.maxChildrenPerTask !== undefined && (task.graph?.children.length ?? 0) > input.limits.maxChildrenPerTask) {
-			decisions.push(decision("block", "limit_exceeded", `Task has ${task.graph?.children.length ?? 0} children, exceeding maxChildrenPerTask=${input.limits.maxChildrenPerTask}.`, task.id));
-		}
-		if (input.limits?.maxTaskDepth !== undefined && taskDepth(task, tasksById) > input.limits.maxTaskDepth) {
-			decisions.push(decision("block", "limit_exceeded", `Task graph depth exceeds maxTaskDepth=${input.limits.maxTaskDepth}.`, task.id));
-		}
-		if (task.status === "failed") {
-			const retryCount = task.policy?.retryCount ?? 0;
-			const maxRetries = input.limits?.maxRetriesPerTask ?? 0;
-			decisions.push(decision(retryCount < maxRetries ? "retry" : "escalate", "task_failed", task.error ? `Task failed: ${task.error}` : "Task failed.", task.id));
-		}
-		if ((task.status === "running" || task.status === "queued") && task.heartbeat && task.heartbeat.alive !== false && isWorkerHeartbeatStale(task.heartbeat, input.limits?.heartbeatStaleMs ?? 60_000, input.now)) {
-			decisions.push(decision("escalate", "worker_stale", "Worker heartbeat is stale.", task.id));
-		}
-		if (task.taskPacket?.verification) {
-			const outcome = evaluateGreenContract(task.taskPacket.verification, task.verification);
-			if (!outcome.satisfied && task.status === "completed") {
-				decisions.push(decision("block", "green_unsatisfied", `Green contract unsatisfied: required=${outcome.requiredGreenLevel}, observed=${outcome.observedGreenLevel}.`, task.id));
-			}
-		}
-	}
-
-	if (decisions.length === 0 && input.tasks.length > 0 && input.tasks.every((task) => task.status === "completed")) {
-		decisions.push(decision("closeout", "run_complete", "All tasks completed and no policy blockers were found."));
-	}
-	return decisions;
-}
-
-export function summarizePolicyDecisions(decisions: PolicyDecision[]): string[] {
-	return decisions.map((item) => `- ${item.action} (${item.reason})${item.taskId ? ` ${item.taskId}` : ""}: ${item.message}`);
-}
+import type { CrewLimitsConfig } from "../config/config.ts";
+import type { PolicyDecision, PolicyDecisionAction, PolicyDecisionReason, TeamRunManifest, TeamTaskState } from "../state/types.ts";
+import { evaluateGreenContract } from "./green-contract.ts";
+import { isWorkerHeartbeatStale } from "./worker-heartbeat.ts";
+
+export interface PolicyEngineInput {
+	manifest: TeamRunManifest;
+	tasks: TeamTaskState[];
+	limits?: CrewLimitsConfig;
+	now?: Date;
+}
+
+function decision(action: PolicyDecisionAction, reason: PolicyDecisionReason, message: string, taskId?: string): PolicyDecision {
+	return {
+		action,
+		reason,
+		message,
+		taskId,
+		createdAt: new Date().toISOString(),
+	};
+}
+
+function taskDepth(task: TeamTaskState, tasksById: Map<string, TeamTaskState>): number {
+	let depth = 0;
+	let current = task.graph?.parentId;
+	const seen = new Set<string>();
+	while (current && !seen.has(current)) {
+		seen.add(current);
+		depth += 1;
+		current = tasksById.get(current)?.graph?.parentId;
+	}
+	return depth;
+}
+
+export function evaluateCrewPolicy(input: PolicyEngineInput): PolicyDecision[] {
+	const decisions: PolicyDecision[] = [];
+	const maxTasksPerRun = Number.isFinite(input.limits?.maxTasksPerRun) ? input.limits!.maxTasksPerRun : undefined;
+	if (maxTasksPerRun !== undefined && input.tasks.length > maxTasksPerRun) {
+		decisions.push(decision("block", "limit_exceeded", `Run has ${input.tasks.length} tasks, exceeding maxTasksPerRun=${maxTasksPerRun}.`));
+	}
+	const runningCount = input.tasks.filter((task) => task.status === "running").length;
+	const maxConcurrentWorkers = Number.isFinite(input.limits?.maxConcurrentWorkers) ? input.limits!.maxConcurrentWorkers : undefined;
+	if (maxConcurrentWorkers !== undefined && runningCount > maxConcurrentWorkers) {
+		decisions.push(decision("block", "limit_exceeded", `Run has ${runningCount} running workers, exceeding maxConcurrentWorkers=${maxConcurrentWorkers}.`));
+	}
+	const tasksById = new Map(input.tasks.map((task) => [task.id, task]));
+
+	for (const task of input.tasks) {
+		if (input.limits?.maxChildrenPerTask !== undefined && (task.graph?.children.length ?? 0) > input.limits.maxChildrenPerTask) {
+			decisions.push(decision("block", "limit_exceeded", `Task has ${task.graph?.children.length ?? 0} children, exceeding maxChildrenPerTask=${input.limits.maxChildrenPerTask}.`, task.id));
+		}
+		if (input.limits?.maxTaskDepth !== undefined && taskDepth(task, tasksById) > input.limits.maxTaskDepth) {
+			decisions.push(decision("block", "limit_exceeded", `Task graph depth exceeds maxTaskDepth=${input.limits.maxTaskDepth}.`, task.id));
+		}
+		if (task.status === "failed") {
+			const retryCount = task.policy?.retryCount ?? 0;
+			const maxRetries = input.limits?.maxRetriesPerTask ?? 0;
+			decisions.push(decision(retryCount < maxRetries ? "retry" : "escalate", "task_failed", task.error ? `Task failed: ${task.error}` : "Task failed.", task.id));
+		}
+		if ((task.status === "running" || task.status === "queued") && task.heartbeat && task.heartbeat.alive !== false && isWorkerHeartbeatStale(task.heartbeat, input.limits?.heartbeatStaleMs ?? 60_000, input.now)) {
+			decisions.push(decision("escalate", "worker_stale", "Worker heartbeat is stale.", task.id));
+		}
+		if (task.taskPacket?.verification) {
+			const outcome = evaluateGreenContract(task.taskPacket.verification, task.verification);
+			if (!outcome.satisfied && task.status === "completed") {
+				decisions.push(decision("block", "green_unsatisfied", `Green contract unsatisfied: required=${outcome.requiredGreenLevel}, observed=${outcome.observedGreenLevel}.`, task.id));
+			}
+		}
+	}
+
+	if (decisions.length === 0 && input.tasks.length > 0 && input.tasks.every((task) => task.status === "completed")) {
+		decisions.push(decision("closeout", "run_complete", "All tasks completed and no policy blockers were found."));
+	}
+	return decisions;
+}
+
+export function summarizePolicyDecisions(decisions: PolicyDecision[]): string[] {
+	return decisions.map((item) => `- ${item.action} (${item.reason})${item.taskId ? ` ${item.taskId}` : ""}: ${item.message}`);
+}

package/src/runtime/post-checks.ts

@@ -0,0 +1,122 @@
+/**
+ * Post-task backpressure checks — runs a configurable shell script after
+ * task completion to verify workspace health before proceeding.
+ *
+ * Distilled from pi-autoresearch's post-check / backpressure pattern.
+ */
+import { execFileSync } from "node:child_process";
+
+/** Default timeout for post-check scripts (5 minutes). */
+const DEFAULT_TIMEOUT_MS = 300_000;
+
+/** Environment variable name for the post-check script path. */
+const POST_CHECK_SCRIPT_ENV = "PI_CREW_POST_CHECK_SCRIPT";
+
+/**
+ * Configuration for a post-task check.
+ */
+export interface PostCheckConfig {
+	/** Path to the shell script to execute. */
+	scriptPath: string;
+	/** Timeout in milliseconds. Defaults to 300000 (5 minutes). */
+	timeoutMs: number;
+}
+
+/**
+ * Result of running a post-task check.
+ */
+export interface PostCheckResult {
+	/** Whether the check passed (exit code 0). */
+	passed: boolean;
+	/** Combined stdout + stderr from the script. */
+	output: string;
+	/** Wall-clock duration of the check in milliseconds. */
+	durationMs: number;
+	/** Whether the check timed out. */
+	timedOut: boolean;
+}
+
+/**
+ * Resolve the effective post-check script path.
+ * Prefers config.scriptPath; falls back to the PI_CREW_POST_CHECK_SCRIPT env var.
+ */
+function resolveScriptPath(config: PostCheckConfig): string | undefined {
+	if (config.scriptPath && config.scriptPath.length > 0) {
+		return config.scriptPath;
+	}
+	return process.env[POST_CHECK_SCRIPT_ENV];
+}
+
+/**
+ * Run a post-task backpressure check script.
+ *
+ * Executes the configured bash script and returns a structured result.
+ * If no script path is available (neither config nor env var), the check
+ * passes by default with a note.
+ *
+ * **Security note:** The script path is user-configurable (config or env var)
+ * and executed with minimal environment (PATH, HOME, USER, LANG). Only use with trusted script
+ * paths. No path containment validation is performed.
+ *
+ * @param config - Post-check configuration (script path and timeout)
+ * @param cwd - Working directory for script execution
+ * @returns PostCheckResult with pass/fail status, output, and timing
+ */
+export async function runPostCheck(config: PostCheckConfig, cwd: string): Promise<PostCheckResult> {
+	const scriptPath = resolveScriptPath(config);
+	const timeoutMs = config.timeoutMs > 0 ? config.timeoutMs : DEFAULT_TIMEOUT_MS;
+
+	if (!scriptPath) {
+		return {
+			passed: true,
+			output: "No post-check script configured; skipping.",
+			durationMs: 0,
+			timedOut: false,
+		};
+	}
+
+	const startTime = Date.now();
+
+	return new Promise<PostCheckResult>((resolve) => {
+		try {
+			const output = execFileSync("bash", [scriptPath], {
+				cwd,
+				timeout: timeoutMs,
+				encoding: "utf-8",
+				maxBuffer: 10 * 1024 * 1024, // 10 MB
+				env: { PATH: process.env.PATH ?? "/usr/bin:/bin", HOME: process.env.HOME ?? "/tmp", USER: process.env.USER, LANG: process.env.LANG, PI_CREW_POST_CHECK: "1" },
+			});
+
+			const durationMs = Date.now() - startTime;
+			resolve({
+				passed: true,
+				output: output.trim(),
+				durationMs,
+				timedOut: false,
+			});
+		} catch (error: unknown) {
+			const durationMs = Date.now() - startTime;
+
+			// Determine if this was a timeout
+			// execFileSync throws with code 'ETIMEDOUT' or sets killed:true on timeout
+			const isTimedOut =
+				Boolean((error as NodeJS.ErrnoException & { killed?: boolean }).killed) ||
+				(error as NodeJS.ErrnoException).code === "ETIMEDOUT";
+
+			let output = "";
+			if (error instanceof Error) {
+				const execError = error as NodeJS.ErrnoException & { stdout?: string; stderr?: string };
+				output = [execError.stdout ?? "", execError.stderr ?? "", execError.message ?? ""].join("\n").trim();
+			} else {
+				output = String(error);
+			}
+
+			resolve({
+				passed: false,
+				output,
+				durationMs,
+				timedOut: isTimedOut,
+			});
+		}
+	});
+}

package/src/runtime/progress-event-coalescer.ts

@@ -1,43 +1,43 @@
-export interface ProgressEventSummary {
-	eventType: string;
-	currentTool?: string;
-	toolCount?: number;
-	tokens?: number;
-	turns?: number;
-	activityState?: string;
-	lastActivityAt?: string;
-}
-
-export interface ProgressEventCoalesceDecision {
-	shouldAppend: boolean;
-	reason: string;
-}
-
-export interface ProgressEventCoalesceInput {
-	previous?: ProgressEventSummary;
-	next: ProgressEventSummary;
-	nowMs: number;
-	lastAppendMs?: number;
-	minIntervalMs: number;
-	force?: boolean;
-	tokenThreshold?: number;
-}
-
-const DEFAULT_TOKEN_THRESHOLD = 256;
-
-function numericIncrease(previous: number | undefined, next: number | undefined): number {
-	return next !== undefined && previous !== undefined ? next - previous : next !== undefined ? next : 0;
-}
-
-export function shouldAppendProgressEventUpdate(input: ProgressEventCoalesceInput): ProgressEventCoalesceDecision {
-	if (input.force) return { shouldAppend: true, reason: "force" };
-	if (!input.previous) return { shouldAppend: true, reason: "first" };
-	if (input.previous.activityState !== input.next.activityState) return { shouldAppend: true, reason: "activity_changed" };
-	if (input.previous.currentTool !== input.next.currentTool) return { shouldAppend: true, reason: "tool_changed" };
-	if (numericIncrease(input.previous.toolCount, input.next.toolCount) > 0) return { shouldAppend: true, reason: "tool_count_increased" };
-	if (numericIncrease(input.previous.turns, input.next.turns) > 0) return { shouldAppend: true, reason: "turns_increased" };
-	const tokenIncrease = numericIncrease(input.previous.tokens, input.next.tokens);
-	if (tokenIncrease >= (input.tokenThreshold ?? DEFAULT_TOKEN_THRESHOLD)) return { shouldAppend: true, reason: "tokens_increased" };
-	if (input.lastAppendMs === undefined || input.nowMs - input.lastAppendMs >= input.minIntervalMs) return { shouldAppend: true, reason: "interval" };
-	return { shouldAppend: false, reason: "coalesced" };
-}
+export interface ProgressEventSummary {
+	eventType: string;
+	currentTool?: string;
+	toolCount?: number;
+	tokens?: number;
+	turns?: number;
+	activityState?: string;
+	lastActivityAt?: string;
+}
+
+export interface ProgressEventCoalesceDecision {
+	shouldAppend: boolean;
+	reason: string;
+}
+
+export interface ProgressEventCoalesceInput {
+	previous?: ProgressEventSummary;
+	next: ProgressEventSummary;
+	nowMs: number;
+	lastAppendMs?: number;
+	minIntervalMs: number;
+	force?: boolean;
+	tokenThreshold?: number;
+}
+
+const DEFAULT_TOKEN_THRESHOLD = 256;
+
+function numericIncrease(previous: number | undefined, next: number | undefined): number {
+	return next !== undefined && previous !== undefined ? next - previous : next !== undefined ? next : 0;
+}
+
+export function shouldAppendProgressEventUpdate(input: ProgressEventCoalesceInput): ProgressEventCoalesceDecision {
+	if (input.force) return { shouldAppend: true, reason: "force" };
+	if (!input.previous) return { shouldAppend: true, reason: "first" };
+	if (input.previous.activityState !== input.next.activityState) return { shouldAppend: true, reason: "activity_changed" };
+	if (input.previous.currentTool !== input.next.currentTool) return { shouldAppend: true, reason: "tool_changed" };
+	if (numericIncrease(input.previous.toolCount, input.next.toolCount) > 0) return { shouldAppend: true, reason: "tool_count_increased" };
+	if (numericIncrease(input.previous.turns, input.next.turns) > 0) return { shouldAppend: true, reason: "turns_increased" };
+	const tokenIncrease = numericIncrease(input.previous.tokens, input.next.tokens);
+	if (tokenIncrease >= (input.tokenThreshold ?? DEFAULT_TOKEN_THRESHOLD)) return { shouldAppend: true, reason: "tokens_increased" };
+	if (input.lastAppendMs === undefined || input.nowMs - input.lastAppendMs >= input.minIntervalMs) return { shouldAppend: true, reason: "interval" };
+	return { shouldAppend: false, reason: "coalesced" };
+}