pi-subagents 0.28.0 → 0.30.0

package/src/runs/shared/acceptance-evaluation.ts

@@ -1,221 +0,0 @@
-import { spawn, spawnSync } from "node:child_process";
-import * as path from "node:path";
-import type {
-	AcceptanceEvidenceKind,
-	AcceptanceLedger,
-	AcceptanceProvenanceLevel,
-	AcceptanceReport,
-	AcceptanceRuntimeCheck,
-	AcceptanceReviewResult,
-	AcceptanceVerifyCommand,
-	AcceptanceVerifyResult,
-	ResolvedAcceptanceConfig,
-	ResolvedAcceptanceGate,
-} from "../../shared/types.ts";
-import { parseAcceptanceReport } from "./acceptance-reports.ts";
-
-const LEVEL_RANK: Record<AcceptanceProvenanceLevel, number> = {
-	none: 0,
-	attested: 1,
-	checked: 2,
-	verified: 3,
-	reviewed: 4,
-};
-
-function isStringArray(value: unknown): value is string[] {
-	return Array.isArray(value) && value.every((item) => typeof item === "string");
-}
-
-function checkCriteriaSatisfied(criteria: ResolvedAcceptanceGate[], report: AcceptanceReport): AcceptanceRuntimeCheck[] {
-	const reports = new Map((report.criteriaSatisfied ?? []).filter((item) => item.id).map((item) => [item.id!, item]));
-	return criteria.filter((criterion) => criterion.severity !== "recommended").map((criterion) => {
-		const item = reports.get(criterion.id);
-		if (!item) return { id: `criterion:${criterion.id}`, status: "failed", message: `Required criterion '${criterion.id}' was not reported.` };
-		if (item.status !== "satisfied") return { id: `criterion:${criterion.id}`, status: "failed", message: `Required criterion '${criterion.id}' was reported as ${item.status}.` };
-		return { id: `criterion:${criterion.id}`, status: "passed", message: `Required criterion '${criterion.id}' satisfied.` };
-	});
-}
-
-function reportEvidencePresent(report: AcceptanceReport, kind: AcceptanceEvidenceKind): boolean {
-	switch (kind) {
-		case "changed-files": return isStringArray(report.changedFiles) && report.changedFiles.length > 0;
-		case "tests-added": return isStringArray(report.testsAddedOrUpdated) && report.testsAddedOrUpdated.length > 0;
-		case "commands-run": return Array.isArray(report.commandsRun) && report.commandsRun.length > 0;
-		case "validation-output": return isStringArray(report.validationOutput) && report.validationOutput.length > 0;
-		case "residual-risks": return isStringArray(report.residualRisks);
-		case "no-staged-files": return report.noStagedFiles === true;
-		case "diff-summary": return typeof report.diffSummary === "string" && report.diffSummary.trim().length > 0;
-		case "review-findings": return isStringArray(report.reviewFindings);
-		case "manual-notes": return Boolean((report.manualNotes ?? report.notes)?.trim());
-	}
-}
-
-function checkNoStagedFiles(cwd: string): AcceptanceRuntimeCheck {
-	const result = spawnSync("git", ["status", "--short"], { cwd, encoding: "utf-8" });
-	if (result.status !== 0) {
-		return { id: "no-staged-files", status: "not-applicable", message: "git status unavailable; no staged-files check skipped" };
-	}
-	const staged = result.stdout.split(/\r?\n/).filter((line) => line.length >= 2 && line[0] !== " " && line[0] !== "?");
-	return staged.length === 0
-		? { id: "no-staged-files", status: "passed", message: "No staged files detected." }
-		: { id: "no-staged-files", status: "failed", message: `Staged files present: ${staged.join(", ")}` };
-}
-
-function runStructuralChecks(acceptance: ResolvedAcceptanceConfig, report: AcceptanceReport, cwd: string): AcceptanceRuntimeCheck[] {
-	const checks: AcceptanceRuntimeCheck[] = [];
-	checks.push(...checkCriteriaSatisfied(acceptance.criteria, report));
-	for (const kind of acceptance.evidence) {
-		const present = reportEvidencePresent(report, kind);
-		checks.push({
-			id: `evidence:${kind}`,
-			status: present ? "passed" : "failed",
-			message: present ? `${kind} evidence present.` : `${kind} evidence missing from child report.`,
-		});
-	}
-	if (acceptance.evidence.includes("no-staged-files")) checks.push(checkNoStagedFiles(cwd));
-	return checks;
-}
-
-function trimOutput(value: string): string | undefined {
-	const trimmed = value.trim();
-	if (!trimmed) return undefined;
-	return trimmed.length > 12_000 ? `${trimmed.slice(0, 12_000)}\n...[truncated]` : trimmed;
-}
-
-function runVerifyCommand(command: AcceptanceVerifyCommand, defaultCwd: string): Promise<AcceptanceVerifyResult> {
-	return new Promise((resolve) => {
-		const startedAt = Date.now();
-		const cwd = command.cwd ? path.resolve(defaultCwd, command.cwd) : defaultCwd;
-		let stdout = "";
-		let stderr = "";
-		let timedOut = false;
-		const child = spawn(command.command, {
-			cwd,
-			env: { ...process.env, ...(command.env ?? {}) },
-			shell: true,
-			stdio: ["ignore", "pipe", "pipe"],
-			windowsHide: true,
-		});
-		const timeout = setTimeout(() => {
-			timedOut = true;
-			child.kill("SIGTERM");
-			setTimeout(() => child.kill("SIGKILL"), 1000).unref?.();
-		}, command.timeoutMs ?? 120_000);
-		timeout.unref?.();
-		child.stdout.on("data", (chunk: Buffer) => {
-			stdout += chunk.toString();
-		});
-		child.stderr.on("data", (chunk: Buffer) => {
-			stderr += chunk.toString();
-		});
-		child.on("close", (exitCode) => {
-			clearTimeout(timeout);
-			const durationMs = Date.now() - startedAt;
-			const passed = exitCode === 0 && !timedOut;
-			resolve({
-				id: command.id,
-				command: command.command,
-				cwd,
-				exitCode,
-				status: timedOut ? "timed-out" : passed ? "passed" : command.allowFailure ? "allowed-failure" : "failed",
-				stdout: trimOutput(stdout),
-				stderr: trimOutput(stderr),
-				durationMs,
-			});
-		});
-		child.on("error", (error) => {
-			clearTimeout(timeout);
-			resolve({
-				id: command.id,
-				command: command.command,
-				cwd,
-				exitCode: 1,
-				status: command.allowFailure ? "allowed-failure" : "failed",
-				stderr: error instanceof Error ? error.message : String(error),
-				durationMs: Date.now() - startedAt,
-			});
-		});
-	});
-}
-
-export async function evaluateAcceptance(input: {
-	acceptance: ResolvedAcceptanceConfig;
-	output: string;
-	cwd: string;
-	report?: AcceptanceReport;
-	reviewResult?: AcceptanceReviewResult;
-}): Promise<AcceptanceLedger> {
-	const acceptance = input.acceptance;
-	const ledger: AcceptanceLedger = {
-		status: acceptance.level === "none" ? "not-required" : "claimed",
-		explicit: acceptance.explicit,
-		effectiveAcceptance: acceptance,
-		inferredReason: acceptance.inferredReason,
-		criteria: acceptance.criteria,
-		runtimeChecks: [],
-		verifyRuns: [],
-	};
-	if (acceptance.level === "none") return ledger;
-
-	const parsed = input.report ? { report: input.report } : parseAcceptanceReport(input.output);
-	if (parsed.report) {
-		ledger.childReport = parsed.report;
-		ledger.status = "attested";
-	} else {
-		ledger.childReportParseError = parsed.error;
-		ledger.runtimeChecks.push({ id: "attestation", status: "failed", message: parsed.error ?? "Structured acceptance report missing." });
-		ledger.status = "rejected";
-		return ledger;
-	}
-
-	if (LEVEL_RANK[acceptance.level] >= LEVEL_RANK.checked) {
-		ledger.runtimeChecks = runStructuralChecks(acceptance, parsed.report, input.cwd);
-		if (ledger.runtimeChecks.some((check) => check.status === "failed")) {
-			ledger.status = "rejected";
-			return ledger;
-		}
-		ledger.status = "checked";
-	}
-
-	if (acceptance.verify.length > 0) {
-		ledger.verifyRuns = [];
-		for (const command of acceptance.verify) ledger.verifyRuns.push(await runVerifyCommand(command, input.cwd));
-		if (ledger.verifyRuns.some((run) => run.status === "failed" || run.status === "timed-out")) {
-			ledger.status = "rejected";
-			return ledger;
-		}
-		ledger.status = "verified";
-	}
-
-	if (acceptance.review) {
-		if (input.reviewResult) {
-			ledger.reviewResult = input.reviewResult;
-			ledger.status = input.reviewResult.status === "no-blockers" ? "reviewed" : "rejected";
-		} else {
-			const optionalReview = acceptance.review.required === false;
-			ledger.reviewResult = {
-				status: "needs-parent-decision",
-				findings: [{
-					severity: optionalReview ? "non-blocking" : "blocker",
-					issue: "Reviewed acceptance requires an independent reviewer result.",
-					rationale: "The run cannot be marked reviewed from child self-review or evidence alone.",
-				}],
-			};
-			if (!optionalReview) ledger.status = "rejected";
-		}
-	}
-
-	return ledger;
-}
-
-
-export function acceptanceFailureMessage(ledger: AcceptanceLedger): string | undefined {
-	if (ledger.status !== "rejected") return undefined;
-	const failedCheck = ledger.runtimeChecks.find((check) => check.status === "failed");
-	if (failedCheck) return `Acceptance rejected: ${failedCheck.message}`;
-	const failedVerify = ledger.verifyRuns.find((run) => run.status === "failed" || run.status === "timed-out");
-	if (failedVerify) return `Acceptance verification '${failedVerify.id}' ${failedVerify.status}.`;
-	if (ledger.reviewResult?.status === "needs-parent-decision") return "Acceptance review required but no automatic reviewer result is available.";
-	if (ledger.reviewResult?.status === "blockers") return "Acceptance review found blockers.";
-	return "Acceptance rejected.";
-}

package/src/runs/shared/acceptance-finalization.ts

@@ -1,173 +0,0 @@
-import type {
-	AcceptanceFinalizationTurn,
-	AcceptanceLedger,
-	ResolvedAcceptanceConfig,
-} from "../../shared/types.ts";
-import { acceptanceFailureMessage } from "./acceptance-evaluation.ts";
-import { formatEvidenceReportFieldMapping } from "./acceptance-contract.ts";
-import { stripAcceptanceReport } from "./acceptance-reports.ts";
-
-const INITIAL_OUTPUT_LIMIT = 8_000;
-
-function truncateForPrompt(value: string): string {
-	const trimmed = stripAcceptanceReport(value).trim();
-	if (trimmed.length <= INITIAL_OUTPUT_LIMIT) return trimmed || "(initial output was empty after removing acceptance-report)";
-	return `${trimmed.slice(0, INITIAL_OUTPUT_LIMIT)}\n...[truncated]`;
-}
-
-function formatReportForPrompt(ledger: AcceptanceLedger): string {
-	if (ledger.childReport) return JSON.stringify(ledger.childReport, null, 2);
-	return `Missing or malformed acceptance report: ${ledger.childReportParseError ?? "no parse detail"}`;
-}
-
-export function formatAcceptanceFinalizationPrompt(input: {
-	acceptance: ResolvedAcceptanceConfig;
-	initialOutput: string;
-	initialLedger: AcceptanceLedger;
-	turn: number;
-	maxTurns: number;
-	previousFailure?: string;
-}): string {
-	const lines = [
-		"## Acceptance Finalization",
-		"You are continuing the same subagent session. Before this run can be accepted, compare the current work to the acceptance contract and the evidence below.",
-		`This is finalization turn ${input.turn} of ${input.maxTurns}. The run will be rejected if the contract is still not satisfied after turn ${input.maxTurns}.`,
-		"",
-		"If a criterion is incomplete and fixable in this session, keep working now before returning the final report.",
-		"If a criterion cannot be satisfied in this session, report it as not-satisfied, explain the blocker in residualRisks, and say what input would unblock progress.",
-		"Do not claim a criterion is satisfied unless the current work has concrete evidence from files, commands, validation output, or other inspectable artifacts.",
-		"",
-		"## Acceptance Contract",
-		"Criteria:",
-		...(input.acceptance.criteria.length ? input.acceptance.criteria.map((criterion) => `- ${criterion.id}: ${criterion.must}`) : ["- No explicit criteria were configured; satisfy the requested task and required evidence/checks."]),
-		"",
-		`Required evidence: ${input.acceptance.evidence.join(", ") || "none explicitly requested"}`,
-	];
-	if (input.acceptance.evidence.length > 0) {
-		lines.push(
-			"",
-			"Structured evidence must be present in the final `acceptance-report` JSON fields. Markdown sections in the visible answer do not satisfy required evidence by themselves. If the previous visible output already included the evidence, copy or summarize it into the matching JSON field.",
-			"Evidence field mapping:",
-			...formatEvidenceReportFieldMapping(input.acceptance.evidence),
-		);
-	}
-	if (input.acceptance.verify.length > 0) {
-		lines.push("", "Runtime verification commands that must pass:", ...input.acceptance.verify.map((command) => `- ${command.id}: ${command.command}`));
-	}
-	if (input.acceptance.review) {
-		lines.push("", `Independent review gate after self-review: ${input.acceptance.review.required === false ? "optional" : "required"}${input.acceptance.review.agent ? ` by ${input.acceptance.review.agent}` : ""}.`);
-	}
-	if (input.acceptance.stopRules.length > 0) {
-		lines.push("", "Stop rules are hard constraints while deciding whether to continue, stop as blocked, or report success:", ...input.acceptance.stopRules.map((rule) => `- ${rule}`));
-	}
-	lines.push(
-		"",
-		"Initial visible output:",
-		truncateForPrompt(input.initialOutput),
-		"",
-		"Initial acceptance report:",
-		formatReportForPrompt(input.initialLedger),
-	);
-	if (input.previousFailure) {
-		lines.push("", "Previous finalization failure to address:", input.previousFailure);
-	}
-	lines.push(
-		"",
-		"Now do the self-check. If work was missing and you repaired it, report the repaired final state. Finish with exactly one fenced JSON block tagged `acceptance-report`.",
-		"```acceptance-report",
-		JSON.stringify({
-			criteriaSatisfied: [{ id: "criterion-1", status: "satisfied", evidence: "specific proof from the final state" }],
-			changedFiles: [],
-			testsAddedOrUpdated: [],
-			commandsRun: [{ command: "command", result: "passed", summary: "short result" }],
-			validationOutput: [],
-			residualRisks: [],
-			noStagedFiles: true,
-			diffSummary: "concise summary of changed behavior and important files",
-			reviewFindings: [],
-			manualNotes: "manual notes or external evidence, if any",
-			notes: "final self-review summary",
-		}, null, 2),
-		"```",
-	);
-	return lines.join("\n");
-}
-
-export function createFinalizationTurn(input: {
-	turn: number;
-	prompt: string;
-	rawOutput: string;
-	ledger: AcceptanceLedger;
-}): AcceptanceFinalizationTurn {
-	const failureMessage = acceptanceFailureMessage(input.ledger);
-	return {
-		turn: input.turn,
-		prompt: input.prompt,
-		status: input.ledger.status,
-		rawOutput: input.rawOutput,
-		...(input.ledger.childReport ? { report: input.ledger.childReport } : {}),
-		...(input.ledger.childReportParseError ? { parseError: input.ledger.childReportParseError } : {}),
-		runtimeChecks: input.ledger.runtimeChecks,
-		verifyRuns: input.ledger.verifyRuns,
-		...(failureMessage ? { failureMessage } : {}),
-	};
-}
-
-export function createFinalizationProcessFailureTurn(input: {
-	turn: number;
-	prompt: string;
-	rawOutput?: string;
-	message: string;
-}): AcceptanceFinalizationTurn {
-	return {
-		turn: input.turn,
-		prompt: input.prompt,
-		status: "rejected",
-		...(input.rawOutput ? { rawOutput: input.rawOutput } : {}),
-		runtimeChecks: [{ id: "finalization-process", status: "failed", message: input.message }],
-		verifyRuns: [],
-		failureMessage: `Acceptance rejected: ${input.message}`,
-	};
-}
-
-export function attachFinalizationToLedger(input: {
-	initialLedger: AcceptanceLedger;
-	authoritativeLedger: AcceptanceLedger;
-	turns: AcceptanceFinalizationTurn[];
-	status: "completed" | "failed";
-	maxTurns: number;
-}): AcceptanceLedger {
-	return {
-		...input.authoritativeLedger,
-		...(input.initialLedger.childReport ? { initialChildReport: input.initialLedger.childReport } : {}),
-		...(input.initialLedger.childReportParseError ? { initialChildReportParseError: input.initialLedger.childReportParseError } : {}),
-		finalization: {
-			mode: "self-review-loop",
-			status: input.status,
-			maxTurns: input.maxTurns,
-			turns: input.turns,
-		},
-	};
-}
-
-export function buildFinalizationProcessFailureLedger(input: {
-	initialLedger: AcceptanceLedger;
-	turns: AcceptanceFinalizationTurn[];
-	maxTurns: number;
-	message: string;
-}): AcceptanceLedger {
-	return attachFinalizationToLedger({
-		initialLedger: input.initialLedger,
-		authoritativeLedger: {
-			...input.initialLedger,
-			status: "rejected",
-			runtimeChecks: [
-				...input.initialLedger.runtimeChecks,
-				{ id: "finalization-process", status: "failed", message: input.message },
-			],
-		},
-		turns: input.turns,
-		status: "failed",
-		maxTurns: input.maxTurns,
-	});
-}

package/src/runs/shared/acceptance-reports.ts

@@ -1,127 +0,0 @@
-import type {
-	AcceptanceReport,
-} from "../../shared/types.ts";
-
-function extractBalancedJson(text: string, start: number): string | undefined {
-	let depth = 0;
-	let inString = false;
-	let escaped = false;
-	for (let i = start; i < text.length; i++) {
-		const char = text[i]!;
-		if (inString) {
-			if (escaped) escaped = false;
-			else if (char === "\\") escaped = true;
-			else if (char === "\"") inString = false;
-			continue;
-		}
-		if (char === "\"") {
-			inString = true;
-			continue;
-		}
-		if (char === "{") depth++;
-		if (char === "}") {
-			depth--;
-			if (depth === 0) return text.slice(start, i + 1);
-		}
-	}
-	return undefined;
-}
-
-export function parseAcceptanceReport(output: string): { report?: AcceptanceReport; error?: string } {
-	const fenced = [...output.matchAll(/```acceptance-report\s*\n([\s\S]*?)```/gi)]
-		.map((match) => match[1]?.trim())
-		.filter((value): value is string => Boolean(value));
-	const parseErrors: string[] = [];
-	for (const body of fenced) {
-		try {
-			const parsed = JSON.parse(body) as unknown;
-			const report = (parsed && typeof parsed === "object" && "acceptance" in parsed)
-				? (parsed as { acceptance?: unknown }).acceptance
-				: parsed;
-			if (isAcceptanceReport(report)) return { report };
-			parseErrors.push("acceptance-report block does not contain a valid acceptance report");
-		} catch (error) {
-			parseErrors.push(error instanceof Error ? error.message : String(error));
-		}
-	}
-	if (parseErrors.length > 0) return { error: `Failed to parse acceptance-report: ${parseErrors.join("; ")}` };
-	const markerIndex = output.search(/ACCEPTANCE_REPORT\s*:/i);
-	if (markerIndex !== -1) {
-		const jsonStart = output.indexOf("{", markerIndex);
-		if (jsonStart !== -1) {
-			const json = extractBalancedJson(output, jsonStart);
-			if (json) {
-				try {
-					const parsed = JSON.parse(json) as unknown;
-					if (isAcceptanceReport(parsed)) return { report: parsed };
-				} catch (error) {
-					return { error: error instanceof Error ? error.message : String(error) };
-				}
-			}
-		}
-	}
-	return { error: "Structured acceptance report not found." };
-}
-
-export function stripAcceptanceReport(output: string): string {
-	return output
-		.replace(/\n?```acceptance-report\s*\n[\s\S]*?```\s*$/i, "")
-		.replace(/\n?ACCEPTANCE_REPORT\s*:\s*\{[\s\S]*\}\s*$/i, "")
-		.trimEnd();
-}
-
-function isStringArray(value: unknown): value is string[] {
-	return Array.isArray(value) && value.every((item) => typeof item === "string");
-}
-
-function isCriterionReport(value: unknown): value is NonNullable<AcceptanceReport["criteriaSatisfied"]>[number] {
-	if (!value || typeof value !== "object" || Array.isArray(value)) return false;
-	const criterion = value as { id?: unknown; status?: unknown; evidence?: unknown };
-	if (criterion.id !== undefined && typeof criterion.id !== "string") return false;
-	if (criterion.status !== "satisfied" && criterion.status !== "not-satisfied" && criterion.status !== "not-applicable") return false;
-	return typeof criterion.evidence === "string" && criterion.evidence.trim().length > 0;
-}
-
-function isCommandReport(value: unknown): value is NonNullable<AcceptanceReport["commandsRun"]>[number] {
-	if (!value || typeof value !== "object" || Array.isArray(value)) return false;
-	const command = value as { command?: unknown; result?: unknown; summary?: unknown };
-	return typeof command.command === "string"
-		&& (command.result === "passed" || command.result === "failed" || command.result === "not-run")
-		&& typeof command.summary === "string";
-}
-
-function isAcceptanceReport(value: unknown): value is AcceptanceReport {
-	if (!value || typeof value !== "object" || Array.isArray(value)) return false;
-	const report = value as {
-		criteriaSatisfied?: unknown;
-		changedFiles?: unknown;
-		testsAddedOrUpdated?: unknown;
-		commandsRun?: unknown;
-		validationOutput?: unknown;
-		residualRisks?: unknown;
-		noStagedFiles?: unknown;
-		diffSummary?: unknown;
-		reviewFindings?: unknown;
-		manualNotes?: unknown;
-		notes?: unknown;
-	};
-	if (report.criteriaSatisfied !== undefined && (!Array.isArray(report.criteriaSatisfied) || !report.criteriaSatisfied.every(isCriterionReport))) return false;
-	if (report.changedFiles !== undefined && !isStringArray(report.changedFiles)) return false;
-	if (report.testsAddedOrUpdated !== undefined && !isStringArray(report.testsAddedOrUpdated)) return false;
-	if (report.commandsRun !== undefined && (!Array.isArray(report.commandsRun) || !report.commandsRun.every(isCommandReport))) return false;
-	if (report.validationOutput !== undefined && !isStringArray(report.validationOutput)) return false;
-	if (report.residualRisks !== undefined && !isStringArray(report.residualRisks)) return false;
-	if (report.noStagedFiles !== undefined && typeof report.noStagedFiles !== "boolean") return false;
-	if (report.diffSummary !== undefined && typeof report.diffSummary !== "string") return false;
-	if (report.reviewFindings !== undefined && !isStringArray(report.reviewFindings)) return false;
-	if (report.manualNotes !== undefined && typeof report.manualNotes !== "string") return false;
-	if (report.notes !== undefined && typeof report.notes !== "string") return false;
-	return report.criteriaSatisfied !== undefined
-		|| report.changedFiles !== undefined
-		|| report.testsAddedOrUpdated !== undefined
-		|| report.commandsRun !== undefined
-		|| report.residualRisks !== undefined
-		|| report.manualNotes !== undefined
-		|| report.reviewFindings !== undefined;
-}
-