pi-crew 0.1.51 → 0.2.0

package/src/runtime/iteration-hooks.ts

@@ -0,0 +1,262 @@
+/**
+ * Transparent iteration hooks — runs user-supplied before/after task scripts
+ * with structured JSON payload on stdin.
+ *
+ * Distilled from pi-autoresearch's iteration hook pattern.
+ */
+import { spawn } from "node:child_process";
+import * as fs from "node:fs";
+import { DENIED_METRIC_NAMES } from "./metric-parser.ts";
+
+/** Hook execution stage. */
+export type HookStage = "before" | "after";
+
+/** Payload sent to the hook script via stdin as JSON. */
+export interface HookPayload {
+	event: HookStage;
+	cwd: string;
+	taskId: string;
+	runId: string;
+	taskRole: string;
+	lastResult?: {
+		status: string;
+		description: string;
+		diagnostics?: Record<string, unknown>;
+	} | null;
+	session: {
+		teamName: string;
+		workflowName: string;
+		goal: string;
+		completedTasks: number;
+		totalTasks: number;
+	};
+}
+
+/** Result of executing an iteration hook. */
+export interface HookResult {
+	/** Whether the hook script was actually executed. */
+	fired: boolean;
+	/** Captured stdout (truncated to 8KB). */
+	stdout: string;
+	/** Captured stderr. */
+	stderr: string;
+	/** Exit code of the hook process. */
+	exitCode: number | null;
+	/** Whether the hook timed out. */
+	timedOut: boolean;
+	/** Wall-clock duration in milliseconds. */
+	durationMs: number;
+}
+
+/** Maximum stdout capture size in bytes (8 KB). */
+const MAX_STDOUT_BYTES = 8192;
+
+/** Hook execution timeout in milliseconds (30 seconds). */
+const HOOK_TIMEOUT_MS = 30_000;
+
+/**
+ * Create a not-fired result for when the hook script is absent or not executable.
+ */
+function notFiredResult(): HookResult {
+	return {
+		fired: false,
+		stdout: "",
+		stderr: "",
+		exitCode: null,
+		timedOut: false,
+		durationMs: 0,
+	};
+}
+
+/**
+ * Truncate a buffer to the given byte limit, snapping to the last newline
+ * boundary for UTF-8 safety.
+ */
+function truncateToLimit(buf: Buffer, limit: number): Buffer {
+	if (buf.byteLength <= limit) return buf;
+
+	const slice = buf.subarray(0, limit);
+	// Find the last newline within the truncated region
+	const lastNewline = slice.lastIndexOf("\n");
+	if (lastNewline >= 0) {
+		return slice.subarray(0, lastNewline);
+	}
+	// No newline found — return the full slice
+	return slice;
+}
+
+/**
+ * Check if a script path exists and is executable.
+ */
+function isScriptRunnable(scriptPath: string): boolean {
+	try {
+		if (!fs.existsSync(scriptPath)) return false;
+
+		// On Windows, X_OK is unreliable — just check F_OK (file exists).
+		// On Unix, check both F_OK and X_OK.
+		if (process.platform === "win32") {
+			fs.accessSync(scriptPath, fs.constants.F_OK);
+		} else {
+			fs.accessSync(scriptPath, fs.constants.F_OK | fs.constants.X_OK);
+		}
+		return true;
+	} catch {
+		return false;
+	}
+}
+
+/**
+ * Run an iteration hook script with JSON payload on stdin.
+ *
+ * Spawns `bash <script>` with the hook payload as JSON on stdin.
+ * Captures stdout (capped at 8KB) and stderr. Enforces a 30-second timeout.
+ *
+ * **Security note:** The script path is user-configurable and executed with
+ * minimal environment (PATH, HOME, USER, LANG). Only use with trusted script paths from
+ * workspace-owned configuration. No path containment validation is performed.
+ *
+ * @param payload - Structured hook payload
+ * @param hookScriptPath - Absolute or relative path to the hook script
+ * @returns HookResult indicating whether the hook fired and its output
+ */
+export async function runIterationHook(
+	payload: HookPayload,
+	hookScriptPath: string,
+): Promise<HookResult> {
+	if (!isScriptRunnable(hookScriptPath)) {
+		return notFiredResult();
+	}
+
+	const startTime = Date.now();
+	const stdinJson = JSON.stringify(payload);
+	const stdoutChunks: Buffer[] = [];
+	const stderrChunks: Buffer[] = [];
+
+	return new Promise<HookResult>((resolve) => {
+		const child = spawn("bash", [hookScriptPath], {
+			cwd: payload.cwd,
+			env: { PATH: process.env.PATH ?? "/usr/bin:/bin", HOME: process.env.HOME ?? "/tmp", USER: process.env.USER, LANG: process.env.LANG, PI_CREW_HOOK: "1" },
+			stdio: ["pipe", "pipe", "pipe"],
+		});
+
+		let killed = false;
+		const timeout = setTimeout(() => {
+			killed = true;
+			child.kill("SIGKILL");
+		}, HOOK_TIMEOUT_MS);
+
+		child.stdout.on("data", (chunk: Buffer) => {
+			stdoutChunks.push(chunk);
+		});
+
+		child.stderr.on("data", (chunk: Buffer) => {
+			stderrChunks.push(chunk);
+		});
+
+		child.on("close", (code: number | null) => {
+			clearTimeout(timeout);
+			const durationMs = Date.now() - startTime;
+
+			const rawStdout = Buffer.concat(stdoutChunks);
+			const truncatedStdout = truncateToLimit(rawStdout, MAX_STDOUT_BYTES);
+
+			const rawStderr = Buffer.concat(stderrChunks);
+
+			resolve({
+				fired: true,
+				stdout: truncatedStdout.toString("utf-8"),
+				stderr: rawStderr.toString("utf-8"),
+				exitCode: code,
+				timedOut: killed,
+				durationMs,
+			});
+		});
+
+		child.on("error", (err: Error) => {
+			clearTimeout(timeout);
+			const durationMs = Date.now() - startTime;
+			resolve({
+				fired: true,
+				stdout: "",
+				stderr: err.message,
+				exitCode: null,
+				timedOut: false,
+				durationMs,
+			});
+		});
+
+		// Write payload to stdin and close it
+		child.stdin.write(stdinJson, "utf-8");
+		child.stdin.end();
+	});
+}
+
+/**
+ * Derive a steer message from the hook result.
+ *
+ * - Non-zero exit → error steer message
+ * - Timeout → timeout steer message
+ * - Empty stdout → null (no steer)
+ * - Otherwise → trimmed stdout content
+ */
+export function steerMessageFromHook(
+	stage: HookStage,
+	result: HookResult,
+): string | null {
+	if (!result.fired) return null;
+
+	if (result.timedOut) {
+		return `[${stage}-hook] Hook timed out after ${result.durationMs}ms`;
+	}
+
+	if (result.exitCode !== null && result.exitCode !== 0) {
+		const stderrSnippet = result.stderr.trim().slice(0, 200);
+		return `[${stage}-hook] Hook exited with code ${result.exitCode}${stderrSnippet ? `: ${stderrSnippet}` : ""}`;
+	}
+
+	const trimmed = result.stdout.trim();
+	if (trimmed.length === 0) return null;
+
+	// Filter out prototype-polluting metric names from hook output
+	const lines = trimmed.split("\n");
+	const safeLines = lines.filter((line) => {
+		const match = /^CREW_METRIC\s+(\w+)=/.exec(line);
+		if (match) {
+			const name = match[1];
+			return !DENIED_METRIC_NAMES.has(name);
+		}
+		return true;
+	});
+
+	return safeLines.join("\n");
+}
+
+/**
+ * Build a log entry for recording hook execution in events.jsonl.
+ */
+export function hookLogEntry(
+	stage: HookStage,
+	result: HookResult,
+): Record<string, unknown> {
+	const entry: Record<string, unknown> = {
+		type: "iteration-hook",
+		stage,
+		fired: result.fired,
+		durationMs: result.durationMs,
+	};
+
+	if (result.fired) {
+		entry.exitCode = result.exitCode;
+		entry.timedOut = result.timedOut;
+
+		// Include truncated stdout/stderr for diagnostics
+		if (result.stdout.length > 0) {
+			entry.stdoutPreview = result.stdout.slice(0, 512);
+		}
+		if (result.stderr.length > 0) {
+			entry.stderrPreview = result.stderr.slice(0, 512);
+		}
+	}
+
+	return entry;
+}

package/src/runtime/live-agent-control.ts

@@ -1,88 +1,88 @@
-import * as fs from "node:fs";
-import * as path from "node:path";
-import type { TeamRunManifest } from "../state/types.ts";
-import { agentStateFile, ensureAgentStateDir } from "./crew-agent-records.ts";
-
-export type LiveAgentControlOperation = "steer" | "follow-up" | "stop" | "resume";
-
-export interface LiveAgentControlRequest {
-	id: string;
-	runId: string;
-	taskId: string;
-	agentId?: string;
-	operation: LiveAgentControlOperation;
-	message?: string;
-	createdAt: string;
-	processedAt?: string;
-	error?: string;
-}
-
-export interface LiveAgentControlCursor {
-	offset: number;
-}
-
-export function liveAgentControlPath(manifest: TeamRunManifest, taskId: string): string {
-	return path.join(ensureAgentStateDir(manifest, taskId), "live-control.jsonl");
-}
-
-function liveAgentControlFile(manifest: TeamRunManifest, taskId: string): string {
-	return agentStateFile(manifest, taskId, "live-control.jsonl");
-}
-
-function requestId(): string {
-	return `ctrl_${Date.now().toString(36)}_${Math.random().toString(16).slice(2, 10)}`;
-}
-
-export function appendLiveAgentControlRequest(manifest: TeamRunManifest, input: { taskId: string; agentId?: string; operation: LiveAgentControlOperation; message?: string }): LiveAgentControlRequest {
-	const request: LiveAgentControlRequest = {
-		id: requestId(),
-		runId: manifest.runId,
-		taskId: input.taskId,
-		agentId: input.agentId,
-		operation: input.operation,
-		message: input.message,
-		createdAt: new Date().toISOString(),
-	};
-	const filePath = liveAgentControlFile(manifest, input.taskId);
-	fs.appendFileSync(filePath, `${JSON.stringify(request)}\n`, "utf-8");
-	return request;
-}
-
-export function readLiveAgentControlRequests(manifest: TeamRunManifest, taskId: string, cursor: LiveAgentControlCursor = { offset: 0 }): { requests: LiveAgentControlRequest[]; cursor: LiveAgentControlCursor } {
-	let filePath: string;
-	try {
-		filePath = liveAgentControlFile(manifest, taskId);
-	} catch {
-		return { requests: [], cursor };
-	}
-	if (!fs.existsSync(filePath)) return { requests: [], cursor };
-	const text = fs.readFileSync(filePath, "utf-8");
-	const lines = text.split(/\r?\n/).filter(Boolean);
-	const requests = lines.slice(cursor.offset).flatMap((line) => {
-		try {
-			const parsed = JSON.parse(line) as LiveAgentControlRequest;
-			return parsed && parsed.runId === manifest.runId && parsed.taskId === taskId ? [parsed] : [];
-		} catch {
-			return [];
-		}
-	});
-	return { requests, cursor: { offset: lines.length } };
-}
-
-export async function applyLiveAgentControlRequest(input: { request: LiveAgentControlRequest; taskId: string; agentId: string; session: { steer?: (text: string) => Promise<void>; prompt?: (text: string, options?: Record<string, unknown>) => Promise<void>; abort?: () => Promise<void> | void }; seenRequestIds?: Set<string> }): Promise<boolean> {
-	const { request, taskId, agentId, session, seenRequestIds } = input;
-	if (seenRequestIds?.has(request.id)) return false;
-	if (request.agentId && request.agentId !== agentId && request.agentId !== taskId) return false;
-	seenRequestIds?.add(request.id);
-	if (request.operation === "steer") await session.steer?.(request.message ?? "Please report current status and wrap up if possible.");
-	else if (request.operation === "follow-up") await session.prompt?.(request.message ?? "Please continue with the follow-up request.", { source: "api", expandPromptTemplates: false });
-	else if (request.operation === "resume") await session.prompt?.(request.message ?? "Please resume and report final status.", { source: "api", expandPromptTemplates: false });
-	else if (request.operation === "stop") await session.abort?.();
-	return true;
-}
-
-export async function applyLiveAgentControlRequests(input: { manifest: TeamRunManifest; taskId: string; agentId: string; session: { steer?: (text: string) => Promise<void>; prompt?: (text: string, options?: Record<string, unknown>) => Promise<void>; abort?: () => Promise<void> | void }; cursor: LiveAgentControlCursor; seenRequestIds?: Set<string> }): Promise<LiveAgentControlCursor> {
-	const batch = readLiveAgentControlRequests(input.manifest, input.taskId, input.cursor);
-	for (const request of batch.requests) await applyLiveAgentControlRequest({ request, taskId: input.taskId, agentId: input.agentId, session: input.session, seenRequestIds: input.seenRequestIds });
-	return batch.cursor;
-}
+import * as fs from "node:fs";
+import * as path from "node:path";
+import type { TeamRunManifest } from "../state/types.ts";
+import { agentStateFile, ensureAgentStateDir } from "./crew-agent-records.ts";
+
+export type LiveAgentControlOperation = "steer" | "follow-up" | "stop" | "resume";
+
+export interface LiveAgentControlRequest {
+	id: string;
+	runId: string;
+	taskId: string;
+	agentId?: string;
+	operation: LiveAgentControlOperation;
+	message?: string;
+	createdAt: string;
+	processedAt?: string;
+	error?: string;
+}
+
+export interface LiveAgentControlCursor {
+	offset: number;
+}
+
+export function liveAgentControlPath(manifest: TeamRunManifest, taskId: string): string {
+	return path.join(ensureAgentStateDir(manifest, taskId), "live-control.jsonl");
+}
+
+function liveAgentControlFile(manifest: TeamRunManifest, taskId: string): string {
+	return agentStateFile(manifest, taskId, "live-control.jsonl");
+}
+
+function requestId(): string {
+	return `ctrl_${Date.now().toString(36)}_${Math.random().toString(16).slice(2, 10)}`;
+}
+
+export function appendLiveAgentControlRequest(manifest: TeamRunManifest, input: { taskId: string; agentId?: string; operation: LiveAgentControlOperation; message?: string }): LiveAgentControlRequest {
+	const request: LiveAgentControlRequest = {
+		id: requestId(),
+		runId: manifest.runId,
+		taskId: input.taskId,
+		agentId: input.agentId,
+		operation: input.operation,
+		message: input.message,
+		createdAt: new Date().toISOString(),
+	};
+	const filePath = liveAgentControlFile(manifest, input.taskId);
+	fs.appendFileSync(filePath, `${JSON.stringify(request)}\n`, "utf-8");
+	return request;
+}
+
+export function readLiveAgentControlRequests(manifest: TeamRunManifest, taskId: string, cursor: LiveAgentControlCursor = { offset: 0 }): { requests: LiveAgentControlRequest[]; cursor: LiveAgentControlCursor } {
+	let filePath: string;
+	try {
+		filePath = liveAgentControlFile(manifest, taskId);
+	} catch {
+		return { requests: [], cursor };
+	}
+	if (!fs.existsSync(filePath)) return { requests: [], cursor };
+	const text = fs.readFileSync(filePath, "utf-8");
+	const lines = text.split(/\r?\n/).filter(Boolean);
+	const requests = lines.slice(cursor.offset).flatMap((line) => {
+		try {
+			const parsed = JSON.parse(line) as LiveAgentControlRequest;
+			return parsed && parsed.runId === manifest.runId && parsed.taskId === taskId ? [parsed] : [];
+		} catch {
+			return [];
+		}
+	});
+	return { requests, cursor: { offset: lines.length } };
+}
+
+export async function applyLiveAgentControlRequest(input: { request: LiveAgentControlRequest; taskId: string; agentId: string; session: { steer?: (text: string) => Promise<void>; prompt?: (text: string, options?: Record<string, unknown>) => Promise<void>; abort?: () => Promise<void> | void }; seenRequestIds?: Set<string> }): Promise<boolean> {
+	const { request, taskId, agentId, session, seenRequestIds } = input;
+	if (seenRequestIds?.has(request.id)) return false;
+	if (request.agentId && request.agentId !== agentId && request.agentId !== taskId) return false;
+	seenRequestIds?.add(request.id);
+	if (request.operation === "steer") await session.steer?.(request.message ?? "Please report current status and wrap up if possible.");
+	else if (request.operation === "follow-up") await session.prompt?.(request.message ?? "Please continue with the follow-up request.", { source: "api", expandPromptTemplates: false });
+	else if (request.operation === "resume") await session.prompt?.(request.message ?? "Please resume and report final status.", { source: "api", expandPromptTemplates: false });
+	else if (request.operation === "stop") await session.abort?.();
+	return true;
+}
+
+export async function applyLiveAgentControlRequests(input: { manifest: TeamRunManifest; taskId: string; agentId: string; session: { steer?: (text: string) => Promise<void>; prompt?: (text: string, options?: Record<string, unknown>) => Promise<void>; abort?: () => Promise<void> | void }; cursor: LiveAgentControlCursor; seenRequestIds?: Set<string> }): Promise<LiveAgentControlCursor> {
+	const batch = readLiveAgentControlRequests(input.manifest, input.taskId, input.cursor);
+	for (const request of batch.requests) await applyLiveAgentControlRequest({ request, taskId: input.taskId, agentId: input.agentId, session: input.session, seenRequestIds: input.seenRequestIds });
+	return batch.cursor;
+}

package/src/runtime/live-control-realtime.ts

@@ -1,36 +1,36 @@
-import type { LiveAgentControlRequest } from "./live-agent-control.ts";
-
-export interface LiveControlRealtimeMessage {
-	type: "live-control";
-	version: 1;
-	request: LiveAgentControlRequest;
-}
-
-type Listener = (request: LiveAgentControlRequest) => void | Promise<void>;
-
-const listeners = new Set<Listener>();
-
-export function publishLiveControlRealtime(request: LiveAgentControlRequest): void {
-	for (const listener of [...listeners]) void listener(request);
-}
-
-export function subscribeLiveControlRealtime(listener: Listener): () => void {
-	listeners.add(listener);
-	return () => listeners.delete(listener);
-}
-
-export function liveControlRealtimeMessage(request: LiveAgentControlRequest): LiveControlRealtimeMessage {
-	return { type: "live-control", version: 1, request };
-}
-
-export function parseLiveControlRealtimeMessage(raw: unknown): LiveAgentControlRequest | undefined {
-	if (!raw || typeof raw !== "object" || Array.isArray(raw)) return undefined;
-	const message = raw as { type?: unknown; version?: unknown; request?: unknown };
-	if (message.type !== "live-control" || message.version !== 1 || !message.request || typeof message.request !== "object" || Array.isArray(message.request)) return undefined;
-	const request = message.request as Partial<LiveAgentControlRequest>;
-	return typeof request.id === "string" && typeof request.runId === "string" && typeof request.taskId === "string" && (request.operation === "steer" || request.operation === "follow-up" || request.operation === "stop" || request.operation === "resume") && typeof request.createdAt === "string" ? request as LiveAgentControlRequest : undefined;
-}
-
-export function clearLiveControlRealtimeForTest(): void {
-	listeners.clear();
-}
+import type { LiveAgentControlRequest } from "./live-agent-control.ts";
+
+export interface LiveControlRealtimeMessage {
+	type: "live-control";
+	version: 1;
+	request: LiveAgentControlRequest;
+}
+
+type Listener = (request: LiveAgentControlRequest) => void | Promise<void>;
+
+const listeners = new Set<Listener>();
+
+export function publishLiveControlRealtime(request: LiveAgentControlRequest): void {
+	for (const listener of [...listeners]) void listener(request);
+}
+
+export function subscribeLiveControlRealtime(listener: Listener): () => void {
+	listeners.add(listener);
+	return () => listeners.delete(listener);
+}
+
+export function liveControlRealtimeMessage(request: LiveAgentControlRequest): LiveControlRealtimeMessage {
+	return { type: "live-control", version: 1, request };
+}
+
+export function parseLiveControlRealtimeMessage(raw: unknown): LiveAgentControlRequest | undefined {
+	if (!raw || typeof raw !== "object" || Array.isArray(raw)) return undefined;
+	const message = raw as { type?: unknown; version?: unknown; request?: unknown };
+	if (message.type !== "live-control" || message.version !== 1 || !message.request || typeof message.request !== "object" || Array.isArray(message.request)) return undefined;
+	const request = message.request as Partial<LiveAgentControlRequest>;
+	return typeof request.id === "string" && typeof request.runId === "string" && typeof request.taskId === "string" && (request.operation === "steer" || request.operation === "follow-up" || request.operation === "stop" || request.operation === "resume") && typeof request.createdAt === "string" ? request as LiveAgentControlRequest : undefined;
+}
+
+export function clearLiveControlRealtimeForTest(): void {
+	listeners.clear();
+}