pi-harness-runtime 1.1.407 → 1.1.408

package/packages/two-phase-review/src/rules.ts

@@ -0,0 +1,236 @@
+/**
+ * The workflow rules.
+ *
+ * The rules are injected into the system prompt: they tell the agent how the
+ * two phases are separated and what it has to do in the current phase.
+ */
+
+import type { ReviewChunk, ReviewSignal, TwoPhasePhase, TwoPhaseState } from "./types.js";
+import {
+	REVIEW_FIX_PREFIX,
+	REVIEW_PREFIX,
+	classifyTodo,
+	summarizeTodos,
+	type TodoLike,
+} from "./classify.js";
+import { summarizeSignals } from "./signals.js";
+
+/** The contract of the workflow. */
+export const TWO_PHASE_CONTRACT = `## Two-phase implementation and review
+
+A task with several steps runs in two phases.
+
+### Phase 1 - implementation
+- Work through every open implementation todo of the current request.
+- Do not start a comprehensive review between implementation todos. A review that is requested while the implementation runs is queued, not executed.
+- Keep the task-level checks active: syntax errors, broken imports, type errors of the code you write right now and failing required tests are part of the implementation and are fixed now.
+- Broader feedback (style, maintainability, a full diff review) is queued as one [REVIEW] todo. Never discard it.
+- Queued review work is not an implementation blocker. The request is not complete while implementation todos remain.
+
+### Phase 2 - review
+- The review covers the diff of the task, not the whole repository.
+- Review the scope in chunks, per module. Use independent reviewers for independent chunks.
+- Record every confirmed finding as a [REVIEW-FIX] todo, grouped by root cause and severity. A minor suggestion does not interrupt a running chunk.
+- Fix the confirmed findings after the review pass, check the changed area, and run one final integration review over the task diff.
+- The request is complete only when the implementation todos, the review chunks and the required fix todos are done or explicitly accepted.
+
+### Todo prefixes
+- [IMPLEMENT] implementation work of the current request
+- ${REVIEW_PREFIX} the queued review of the task diff
+- ${REVIEW_FIX_PREFIX} a confirmed finding that has to be fixed
+
+A user pause, an approval requirement, a security issue or any other safety rule stops the work immediately. The phase order never overrides the intent of the user.`;
+
+/** The current state of the workflow as the agent sees it. */
+export interface PhaseView {
+	phase: TwoPhasePhase;
+	/** How many implementation todos are still open. */
+	implementationOpen: number;
+	/** How many review todos are open. */
+	reviewOpen: number;
+	/** How many review-fix todos are open. */
+	reviewFixOpen: number;
+	/** How many files the review covers. */
+	scopeFiles: number;
+	/** The review chunks and their state. */
+	chunks: { id: string; label: string; status: string }[];
+	/** Is a review queued? */
+	queued: boolean;
+	/** The signals that queued the review. */
+	signals: ReviewSignal[];
+}
+
+/** Build the phase view from the state and the todo list. */
+export function buildPhaseView(state: TwoPhaseState, todos: TodoLike[]): PhaseView {
+	const summary = summarizeTodos(todos);
+	return {
+		phase: state.phase,
+		implementationOpen: summary.implementation,
+		reviewOpen: summary.review,
+		reviewFixOpen: summary.reviewFix,
+		scopeFiles: state.scopeFiles.length,
+		chunks: state.chunks.map((chunk) => ({
+			id: chunk.id,
+			label: chunk.label,
+			status: chunk.status,
+		})),
+		queued: state.signals.length > 0,
+		signals: state.signals,
+	};
+}
+
+/** The subject of the one queued review todo. */
+export function buildReviewTodoSubject(state: TwoPhaseState): string {
+	const summary = summarizeSignals(state.signals);
+	const first = summary.sources[0] ?? "review signal";
+	const more = summary.sources.length > 1 ? ` +${summary.sources.length - 1} more` : "";
+	return `${REVIEW_PREFIX} Review the task diff (queued by ${first}${more})`;
+}
+
+/** The description of the one queued review todo. */
+export function buildReviewTodoDescription(state: TwoPhaseState): string {
+	const summary = summarizeSignals(state.signals);
+	const lines: string[] = [];
+	if (summary.sources.length > 0) lines.push(`Source: ${summary.sources.join(", ")}`);
+	if (summary.reason) lines.push(`Reason: ${summary.reason}`);
+	if (state.scopeFiles.length > 0) {
+		const shown = state.scopeFiles.slice(0, 20);
+		const rest = state.scopeFiles.length - shown.length;
+		lines.push(`Scope: ${shown.join(", ")}${rest > 0 ? ` (+${rest} more)` : ""}`);
+	}
+	lines.push("The review starts after the implementation todos are done.");
+	return lines.join("\n");
+}
+
+/**
+ * The status line of the workflow.
+ *
+ * The line is plain ASCII: it is shown in the footer of the session.
+ */
+export function formatPhaseStatus(state: TwoPhaseState): string {
+	switch (state.phase) {
+		case "implementation":
+			return "[PHASE] implementation";
+		case "review_pending":
+			return "[PHASE] review_pending";
+		case "review": {
+			const done = state.chunks.filter((chunk) => chunk.status === "done").length;
+			return `[PHASE] review (${done}/${state.chunks.length} chunk(s), ${state.scopeFiles.length} file(s))`;
+		}
+		case "review_fixes":
+			return `[PHASE] review_fixes (${state.findings.length} finding(s))`;
+		case "complete":
+			return "[PHASE] complete";
+		default:
+			return "[PHASE] implementation";
+	}
+}
+
+/**
+ * The subject of the todo that covers one review chunk.
+ *
+ * The chunk id is part of the subject, so the runtime can tell which chunk a
+ * todo belongs to.
+ */
+export function buildChunkTodoSubject(chunk: ReviewChunk): string {
+	return `${REVIEW_PREFIX} ${chunk.id}: ${chunk.label}`;
+}
+
+/** The description of the todo that covers one review chunk. */
+export function buildChunkTodoDescription(chunk: ReviewChunk): string {
+	const files = chunk.files.map((file) => `- ${file}`).join("\n");
+	return [
+		`Review the files of ${chunk.id} (${chunk.label}):`,
+		files,
+		"",
+		`Review only this chunk. Record confirmed findings as ${REVIEW_FIX_PREFIX} todos grouped by root cause and severity.`,
+	].join("\n");
+}
+
+/** Does the todo item belong to the review chunk? */
+export function isChunkTodo(todo: TodoLike, chunk: ReviewChunk): boolean {
+	if (classifyTodo(todo) !== "review") return false;
+	const subject = todo.subject ?? "";
+	const at = subject.indexOf(chunk.id);
+	if (at < 0) return false;
+	// "chunk-1" must not match "chunk-10".
+	const after = subject.slice(at + chunk.id.length, at + chunk.id.length + 1);
+	return after === "" || !/[0-9a-z]/i.test(after);
+}
+
+/**
+ * Derive the status of the review chunks from the todo list.
+ *
+ * The status only moves forward: a chunk that is done stays done, so a todo
+ * list that is briefly empty (a restart, a compaction) can never erase the
+ * progress of the review.
+ */
+export function syncChunkStatus(state: TwoPhaseState, todos: TodoLike[]): TwoPhaseState {
+	if (state.chunks.length === 0) return state;
+	let changed = false;
+	const chunks = state.chunks.map((chunk) => {
+		if (chunk.status === "done") return chunk;
+		const done = todos.some(
+			(todo) => isChunkTodo(todo, chunk) && todo.status === "completed",
+		);
+		if (!done) return chunk;
+		changed = true;
+		return { ...chunk, status: "done" as const };
+	});
+	return changed ? { ...state, chunks } : state;
+}
+
+/**
+ * The reason a comprehensive review was deferred.
+ *
+ * The reason has to be actionable: the agent continues with the
+ * implementation and keeps the task-level checks alive.
+ */
+export function buildDeferralReason(
+	state: TwoPhaseState,
+	context: { source: string; implementationOpen: number },
+): string {
+	const sources = [...new Set(state.signals.map((signal) => signal.source))];
+	return [
+		`Phase 1 (implementation) is still running: ${context.implementationOpen} implementation todo(s) are open.`,
+		`The comprehensive review (${sources.join(", ") || context.source}) is queued and starts after the implementation todos are done.`,
+		"Continue with the implementation. Keep task-level checks (syntax errors, broken imports, type errors of the code you write now, failing required tests) active and fix them now.",
+	].join(" ");
+}
+
+/**
+ * The instruction for the current phase.
+ *
+ * The instruction is short: it names the phase, the open work and what the
+ * agent has to do next.
+ */
+export function buildPhaseInstruction(state: TwoPhaseState, view: PhaseView): string {
+	if (state.phase === "implementation") {
+		if (!view.queued) {
+			return `[two-phase] Phase 1 (implementation): ${view.implementationOpen} implementation todo(s) open. Finish the implementation first; keep task-level checks (type errors, failing tests, build) active. Do not start a comprehensive review.`;
+		}
+		const summary = summarizeSignals(state.signals);
+		return `[two-phase] Phase 1 (implementation): ${view.implementationOpen} implementation todo(s) open. A comprehensive review is queued (${summary.sources.join(", ") || "review signal"}) and must not start yet. Fix correctness problems of the current code now; queue broader feedback as one ${REVIEW_PREFIX} todo. The request is not complete while implementation todos remain.`;
+	}
+
+	if (state.phase === "review_pending") {
+		return `[two-phase] Phase 2 (review): the implementation is done, the review scope is being derived from the task diff (${view.scopeFiles} file(s)).`;
+	}
+
+	if (state.phase === "review") {
+		const chunkLines = view.chunks.map(
+			(chunk) => `- ${chunk.id}: ${chunk.label} [${chunk.status}]`,
+		);
+		return [
+			`[two-phase] Phase 2 (review): the implementation is done. Review scope: ${view.scopeFiles} file(s) in ${view.chunks.length} chunk(s).`,
+			...chunkLines,
+			`Review each chunk in scope (never the whole repository). Record confirmed findings as ${REVIEW_FIX_PREFIX} todos grouped by root cause and severity, fix them after the pass, then run one final integration review over the task diff. The request is not complete while review or fix items remain.`,
+		].join("\n");
+	}
+
+	if (state.phase === "review_fixes") {
+		return `[two-phase] Phase 2 (review fixes): ${view.reviewFixOpen} review-fix todo(s) open. Fix the confirmed findings, check the changed area, then run one final integration review over the task diff.`;
+	}
+
+	return "[two-phase] The task is complete: implementation, review and the required fixes are done.";
+}

package/packages/two-phase-review/src/runtime.ts

@@ -0,0 +1,392 @@
+/**
+ * The runtime wiring of the two-phase workflow.
+ *
+ * The wiring lives in the package so it can be tested without a Pi session:
+ * the extension API, the todo reader and the workspace are injected. Every
+ * decision that the runtime takes is conservative - when the state of the
+ * todo list is unknown, the workflow waits instead of guessing.
+ */
+
+import {
+	implementationTodos,
+	reviewFixTodos,
+	reviewTodos,
+	type TodoLike,
+} from "./classify.js";
+import {
+	detectReviewInvocation,
+	explicitReviewRequest,
+	parseExtraPatterns,
+} from "./signals.js";
+import { chunkScope, collectScope, currentRevision } from "./scope.js";
+import {
+	TwoPhaseStateStore,
+	allChunksDone,
+	createState,
+	hasQueuedReview,
+	markComplete,
+	recordSignal,
+	startReview,
+	transitionToReviewFixes,
+	transitionToReviewPending,
+} from "./state.js";
+import {
+	TWO_PHASE_CONTRACT,
+	buildChunkTodoSubject,
+	buildDeferralReason,
+	buildPhaseInstruction,
+	buildPhaseView,
+	buildReviewTodoDescription,
+	buildReviewTodoSubject,
+	formatPhaseStatus,
+	syncChunkStatus,
+} from "./rules.js";
+import type { TwoPhasePhase, TwoPhaseState } from "./types.js";
+
+/** The marker every message of the harness itself carries. */
+export const HARNESS_MESSAGE_MARKER = "[harness:";
+
+/** The part of the extension API the workflow needs. */
+export interface TwoPhaseExtensionApi {
+	on(event: string, handler: (...args: any[]) => unknown): void;
+	appendEntry?(type: string, data: unknown): void;
+	sendUserMessage?(content: string, options?: { deliverAs?: "steer" | "followUp" }): Promise<void> | void;
+}
+
+/** The part of the extension context the workflow needs. */
+export interface TwoPhaseExtensionContext {
+	sessionManager?: { getSessionId?: () => string | undefined };
+	ui?: { setStatus?: (key: string, value: string) => void };
+}
+
+/** The result of reading the todo list of the session. */
+export interface TodoReadResult {
+	/** Is the todo list readable at all? */
+	available: boolean;
+	/** The todo items (empty when the list is not readable). */
+	todos: TodoLike[];
+	/** Why the list is not readable. */
+	reason?: string;
+}
+
+/** Reads the todo list of the session. */
+export type TodoReader = (ctx: unknown) => Promise<TodoReadResult>;
+
+/** The options of the runtime. */
+export interface TwoPhaseRuntimeOptions {
+	pi: TwoPhaseExtensionApi;
+	/** Reads the todo list of the session. */
+	readTodos: TodoReader;
+	/** The root of the workspace (the Git repository of the task). */
+	workspaceRoot?: () => string;
+	/** Where the state of the workflow is stored. */
+	store?: TwoPhaseStateStore;
+	/** Writes a line into the log of the harness. */
+	log?: (message: string) => void;
+	/** Extra review tool patterns of the deployment. */
+	extraPatterns?: string[];
+}
+
+/** The runtime of the workflow. */
+export interface TwoPhaseRuntime {
+	/** The persisted state of the workflow. */
+	getState(): TwoPhaseState;
+	/** The phase the workflow is in (derived from the state and the todo list). */
+	getPhase(todos?: TodoLike[]): TwoPhasePhase;
+}
+
+function errorMessage(error: unknown): string {
+	if (error instanceof Error) return error.message;
+	return String(error);
+}
+
+/** The text of a message content (a string or a list of parts). */
+function messageText(content: unknown): string {
+	if (typeof content === "string") return content;
+	if (Array.isArray(content)) {
+		return content
+			.map((part) => {
+				if (!part || typeof part !== "object") return "";
+				const entry = part as { type?: string; text?: string };
+				return entry.type === "text" ? (entry.text ?? "") : "";
+			})
+			.join("\n");
+	}
+	return "";
+}
+
+/**
+ * Register the two-phase workflow in the session.
+ *
+ * The handlers are registered before the function returns, so a session that
+ * starts right after the registration is already covered.
+ */
+export async function initTwoPhaseReview(
+	options: TwoPhaseRuntimeOptions,
+): Promise<TwoPhaseRuntime> {
+	const { pi } = options;
+	const store = options.store ?? new TwoPhaseStateStore();
+	const log = options.log ?? (() => {});
+	const workspaceRoot = options.workspaceRoot ?? (() => process.cwd());
+	const extraPatterns = options.extraPatterns ?? parseExtraPatterns();
+
+	let state: TwoPhaseState = createState("default");
+	/** The last message of the human of this session (never a harness message). */
+	let lastUserMessage = "";
+	/** The messages the runtime sent itself. */
+	const sentMessages = new Set<string>();
+
+	const sessionId = (ctx: unknown): string => {
+		const context = ctx as TwoPhaseExtensionContext | undefined;
+		try {
+			return context?.sessionManager?.getSessionId?.() ?? "default";
+		} catch {
+			return "default";
+		}
+	};
+
+	/**
+	 * Persist a state.
+	 *
+	 * The state is only replaced when it was written: the file is the source
+	 * of truth, so a failed write must not change what the runtime believes.
+	 */
+	const persist = (next: TwoPhaseState): boolean => {
+		try {
+			state = store.write(next);
+			return true;
+		} catch (error) {
+			log(`state not written: ${errorMessage(error)}`);
+			return false;
+		}
+	};
+
+	const readTodos = async (ctx: unknown): Promise<TodoReadResult> => {
+		try {
+			const result = await options.readTodos(ctx);
+			if (!result || typeof result !== "object") {
+				return { available: false, todos: [], reason: "the todo reader returned nothing" };
+			}
+			return {
+				available: result.available !== false,
+				todos: Array.isArray(result.todos) ? result.todos : [],
+				reason: result.reason,
+			};
+		} catch (error) {
+			return { available: false, todos: [], reason: errorMessage(error) };
+		}
+	};
+
+	const updateStatus = (ctx: unknown): void => {
+		const context = ctx as TwoPhaseExtensionContext | undefined;
+		try {
+			context?.ui?.setStatus?.("harness-review", formatPhaseStatus(state));
+		} catch {
+			// The status line is a convenience, never a requirement.
+		}
+	};
+
+	/**
+	 * Keep the chunk status and the phase in sync with the todo list.
+	 *
+	 * The chunk status only moves forward, so a todo list that is briefly
+	 * empty can never erase the progress of the review.
+	 */
+	const syncProgress = (todos: TodoLike[]): void => {
+		const synced = syncChunkStatus(state, todos);
+		const openFixes = reviewFixTodos(todos).length;
+		let next = synced;
+		if (next.phase === "review" && allChunksDone(next)) {
+			next = openFixes > 0 ? transitionToReviewFixes(next) : markComplete(next);
+		} else if (next.phase === "review_fixes" && openFixes === 0) {
+			next = markComplete(next);
+		}
+		if (next !== state) persist(next);
+	};
+
+	pi.on("session_start", (_event: unknown, ctx: unknown) => {
+		const id = sessionId(ctx);
+		state = store.read(id) ?? createState(id);
+		if (!state.startRevision) {
+			const revision = currentRevision(workspaceRoot());
+			if (revision) state = { ...state, startRevision: revision };
+		}
+		// The intent of a previous session never carries over.
+		lastUserMessage = "";
+		persist(state);
+		updateStatus(ctx);
+	});
+
+	// The intent of the human wins over the phase order.
+	pi.on("message_end", (event: { message?: { role?: string; content?: unknown } }) => {
+		const message = event?.message;
+		if (!message || message.role !== "user") return;
+		const text = messageText(message.content).trim();
+		if (!text) return;
+		// A message of the harness is not the intent of the human.
+		if (sentMessages.has(text)) return;
+		if (text.startsWith(HARNESS_MESSAGE_MARKER)) return;
+		lastUserMessage = text;
+	});
+
+	// A comprehensive review is deferred while the implementation runs.
+	pi.on(
+		"tool_call",
+		async (event: { toolName?: string; input?: unknown }, ctx: unknown) => {
+			if (state.phase !== "implementation") return {};
+
+			const invocation = detectReviewInvocation(
+				event?.toolName ?? "",
+				event?.input,
+				extraPatterns,
+			);
+			if (!invocation) return {};
+			// The human asked for the review explicitly: the phase order does not win.
+			if (explicitReviewRequest(lastUserMessage)) return {};
+
+			const read = await readTodos(ctx);
+			if (!read.available) {
+				// The implementation state is unknown, so the review waits.
+				return {
+					block: true,
+					reason: `The todo list of the session is not readable (${read.reason ?? "unknown reason"}), so the workflow cannot prove that the implementation is done. The comprehensive review is deferred.`,
+				};
+			}
+
+			const openImplementation = implementationTodos(read.todos).length;
+			if (openImplementation === 0) return {};
+
+			const next = recordSignal(state, {
+				source: invocation.source,
+				files: invocation.files,
+				reason: invocation.reason,
+				at: new Date().toISOString(),
+			});
+			if (next !== state) {
+				if (!persist(next)) {
+					// The signal is not persisted, so it is not queued either.
+					return {
+						block: true,
+						reason: buildDeferralReason(state, {
+							source: invocation.source,
+							implementationOpen: openImplementation,
+						}),
+					};
+				}
+				// The queued item is part of the session, so a compaction cannot lose it.
+				try {
+					pi.appendEntry?.("harness-two-phase-review", {
+						queued: {
+							source: invocation.source,
+							files: invocation.files,
+							reason: invocation.reason,
+							subject: buildReviewTodoSubject(state),
+							description: buildReviewTodoDescription(state),
+						},
+					});
+				} catch {
+					// The session entry is a copy; the state file is the truth.
+				}
+			}
+			updateStatus(ctx);
+
+			return {
+				block: true,
+				reason: buildDeferralReason(state, {
+					source: invocation.source,
+					implementationOpen: openImplementation,
+				}),
+			};
+		},
+	);
+
+	// The implementation is done: the review scope is derived from the task diff.
+	pi.on("turn_end", async (_event: unknown, ctx: unknown) => {
+		const read = await readTodos(ctx);
+		if (!read.available) {
+			// The implementation state is unknown, so the phase does not move.
+			updateStatus(ctx);
+			return undefined;
+		}
+
+		if (state.phase === "implementation") {
+			if (implementationTodos(read.todos).length > 0) {
+				updateStatus(ctx);
+				return undefined;
+			}
+			const queued = hasQueuedReview(state) || reviewTodos(read.todos).length > 0;
+			if (!queued) {
+				updateStatus(ctx);
+				return undefined;
+			}
+
+			const scope = collectScope(workspaceRoot(), state.startRevision);
+			let next = transitionToReviewPending(state, scope.files);
+			next = startReview(next, chunkScope(scope.files));
+			if (!persist(next)) {
+				// Without a persisted state the review must not start.
+				updateStatus(ctx);
+				return undefined;
+			}
+			updateStatus(ctx);
+
+			const lines: string[] = [
+				"[harness:two-phase] The implementation todos of this request are done. Phase 2 (review) starts now.",
+				`Review scope: ${scope.files.length} file(s) (${scope.reason}).`,
+				...state.chunks.map((chunk) => `- ${chunk.id}: ${chunk.label}`),
+				"Review every chunk in scope (never the whole repository). Record confirmed findings as [REVIEW-FIX] todos grouped by root cause and severity, fix them after the pass, then run one final integration review over the task diff.",
+				"Create one [REVIEW] todo per chunk with the chunk id in the subject and complete it when the chunk is reviewed:",
+				...state.chunks.map((chunk) => `- ${buildChunkTodoSubject(chunk)}`),
+				`Keep exactly one queued review item: ${buildReviewTodoSubject(state)}`,
+			];
+			const message = lines.join("\n");
+			try {
+				sentMessages.add(message);
+				await pi.sendUserMessage?.(message, { deliverAs: "steer" });
+				log(`review started (${scope.files.length} file(s))`);
+			} catch (error) {
+				log(`review steer failed: ${errorMessage(error)}`);
+			}
+			return undefined;
+		}
+
+		// Phase 2: the chunk status and the phase follow the review todos.
+		syncProgress(read.todos);
+		updateStatus(ctx);
+		return undefined;
+	});
+
+	// The workflow rules and the current phase reach the agent.
+	pi.on("before_agent_start", async (event: { systemPrompt?: string }, ctx: unknown) => {
+		const read = await readTodos(ctx);
+		if (!read.available) return undefined;
+		syncProgress(read.todos);
+
+		const view = buildPhaseView(state, read.todos);
+		// The workflow is only active when it has something to say.
+		const active =
+			view.implementationOpen > 0 ||
+			view.reviewOpen > 0 ||
+			view.reviewFixOpen > 0 ||
+			state.signals.length > 0;
+		if (!active) return undefined;
+
+		// The system prompt is built per run, so the contract belongs to every
+		// run of the phase, not only to the first one.
+		const parts: string[] = [TWO_PHASE_CONTRACT];
+		const instruction = buildPhaseInstruction(state, view);
+		if (instruction) parts.push(instruction);
+
+		return { systemPrompt: `${event?.systemPrompt ?? ""}\n\n${parts.join("\n\n")}` };
+	});
+
+	return {
+		getState: () => state,
+		getPhase: (todos: TodoLike[] = []) => {
+			if (state.phase === "complete" && reviewFixTodos(todos).length > 0) {
+				return "review_fixes";
+			}
+			return state.phase;
+		},
+	};
+}