@narumitw/pi-subagents 0.51.0 → 0.52.0

package/src/workflow-tree-identity.ts

@@ -0,0 +1,289 @@
+import { execFile } from "node:child_process";
+import { createHash, type Hash } from "node:crypto";
+import * as fs from "node:fs";
+import * as path from "node:path";
+
+export const WORKFLOW_TREE_IDENTITY_VERSION = "pi-subagents:workflow-tree:v1" as const;
+export const DEFAULT_WORKFLOW_TREE_MAX_BYTES = 1024 * 1024;
+const MAX_UNTRACKED_FILES = 256;
+
+export interface WorkflowTreeIdentity {
+	version: typeof WORKFLOW_TREE_IDENTITY_VERSION;
+	kind: "git-commit" | "git-dirty";
+	digest: string;
+}
+
+export interface CaptureWorkflowTreeIdentityOptions {
+	maxBytes?: number;
+	signal?: AbortSignal;
+}
+
+export async function captureWorkflowTreeIdentity(
+	cwd: string,
+	options: CaptureWorkflowTreeIdentityOptions = {},
+): Promise<WorkflowTreeIdentity> {
+	const maxBytes = options.maxBytes ?? DEFAULT_WORKFLOW_TREE_MAX_BYTES;
+	if (!Number.isSafeInteger(maxBytes) || maxBytes < 1) {
+		throw new Error("Workflow tree identity maxBytes must be a positive safe integer");
+	}
+	throwIfAborted(options.signal);
+	let canonicalCwd: string;
+	try {
+		canonicalCwd = await fs.promises.realpath(path.resolve(cwd));
+	} catch {
+		throw new Error("Workflow verification requires a readable Git repository directory");
+	}
+	const rootOutput = await git(
+		canonicalCwd,
+		["rev-parse", "--show-toplevel"],
+		64 * 1024,
+		options.signal,
+	).catch((error) => {
+		throw normalizedGitError(error, "Workflow verification requires a Git repository");
+	});
+	let repositoryRoot: string;
+	try {
+		repositoryRoot = await fs.promises.realpath(rootOutput.toString("utf8").trim());
+	} catch {
+		throw new Error("Workflow verification requires a readable Git repository root");
+	}
+	const relativeCwd = path.relative(repositoryRoot, canonicalCwd);
+	if (relativeCwd.startsWith("..") || path.isAbsolute(relativeCwd)) {
+		throw new Error("Workflow verification cwd is outside its Git repository");
+	}
+	const submodules = await git(
+		repositoryRoot,
+		["submodule", "status", "--recursive"],
+		64 * 1024,
+		options.signal,
+	).catch((error) => {
+		throw normalizedGitError(error, "Workflow tree identity could not inspect submodules");
+	});
+	if (submodules.toString("utf8").trim()) {
+		throw new Error("Workflow tree identity does not support repositories with submodules");
+	}
+	const head = (
+		await git(repositoryRoot, ["rev-parse", "HEAD"], 64 * 1024, options.signal).catch((error) => {
+			throw normalizedGitError(error, "Workflow verification requires a stable Git HEAD");
+		})
+	)
+		.toString("utf8")
+		.trim();
+	if (!/^[a-f0-9]{40,64}$/u.test(head)) {
+		throw new Error("Workflow verification requires a stable Git HEAD");
+	}
+	const commandLimit = maxBytes + 1;
+	const indexDiff = await git(
+		repositoryRoot,
+		["diff", "--binary", "--no-ext-diff", "--cached", "HEAD", "--"],
+		commandLimit,
+		options.signal,
+	).catch((error) => {
+		throw normalizedGitError(error, "Workflow tree identity exceeded its size limit");
+	});
+	const worktreeDiff = await git(
+		repositoryRoot,
+		["diff", "--binary", "--no-ext-diff", "--"],
+		commandLimit,
+		options.signal,
+	).catch((error) => {
+		throw normalizedGitError(error, "Workflow tree identity exceeded its size limit");
+	});
+	if (indexDiff.length > maxBytes || worktreeDiff.length > maxBytes) {
+		throw new Error("Workflow tree identity exceeded its size limit");
+	}
+	const untrackedOutput = await git(
+		repositoryRoot,
+		["ls-files", "--others", "--exclude-standard", "-z"],
+		commandLimit,
+		options.signal,
+	).catch((error) => {
+		throw normalizedGitError(error, "Workflow tree identity exceeded its size limit");
+	});
+	const untrackedEntries = splitNul(untrackedOutput).sort(Buffer.compare);
+	if (untrackedEntries.length > MAX_UNTRACKED_FILES) {
+		throw new Error("Workflow tree identity exceeded its untracked-file limit");
+	}
+	if (indexDiff.length === 0 && worktreeDiff.length === 0 && untrackedEntries.length === 0) {
+		return identity("git-commit", hashParts([Buffer.from("commit\0"), Buffer.from(head)]));
+	}
+	let consumed = indexDiff.length + worktreeDiff.length + untrackedOutput.length;
+	if (consumed > maxBytes) throw new Error("Workflow tree identity exceeded its size limit");
+	const hasher = createHash("sha256");
+	hasher.update("pi-subagents:workflow-tree:v1\0");
+	updateHashFrame(hasher, "head", head);
+	updateHashFrame(hasher, "index-diff", indexDiff);
+	updateHashFrame(hasher, "worktree-diff", worktreeDiff);
+	for (const rawRelativePath of untrackedEntries) {
+		throwIfAborted(options.signal);
+		const relativePath = decodeGitPath(rawRelativePath);
+		const candidate = path.resolve(repositoryRoot, relativePath);
+		const relative = path.relative(repositoryRoot, candidate);
+		if (!relative || relative.startsWith("..") || path.isAbsolute(relative)) {
+			throw new Error("Workflow tree identity encountered an unsafe untracked path");
+		}
+		let bytes: Buffer;
+		let kind: string;
+		try {
+			const stat = await fs.promises.lstat(candidate);
+			if (stat.isSymbolicLink()) {
+				kind = "symlink";
+				bytes = Buffer.from(await fs.promises.readlink(candidate), "utf8");
+			} else if (stat.isFile()) {
+				kind = "file";
+				if (stat.size > maxBytes - consumed) {
+					throw new Error("Workflow tree identity exceeded its size limit");
+				}
+				bytes = await readRegularFileNoFollow(candidate, stat, options.signal);
+			} else {
+				throw new Error("Workflow tree identity encountered an unsupported untracked file type");
+			}
+		} catch (error) {
+			if (error instanceof Error && error.name === "AbortError") throw error;
+			if (error instanceof Error && error.message.startsWith("Workflow tree identity")) {
+				throw error;
+			}
+			throw new Error("Workflow tree identity could not read an untracked entry");
+		}
+		consumed += rawRelativePath.length + bytes.length;
+		if (consumed > maxBytes) throw new Error("Workflow tree identity exceeded its size limit");
+		updateHashFrame(hasher, "untracked-kind", kind);
+		updateHashFrame(hasher, "untracked-path", rawRelativePath);
+		updateHashFrame(hasher, "untracked-content", bytes);
+	}
+	return identity("git-dirty", hasher.digest("hex"));
+}
+
+export function sameWorkflowTreeIdentity(
+	left: WorkflowTreeIdentity,
+	right: WorkflowTreeIdentity,
+): boolean {
+	return (
+		isWorkflowTreeIdentity(left) &&
+		isWorkflowTreeIdentity(right) &&
+		left.kind === right.kind &&
+		left.digest === right.digest
+	);
+}
+
+export function isWorkflowTreeIdentity(value: unknown): value is WorkflowTreeIdentity {
+	if (!value || typeof value !== "object" || Array.isArray(value)) return false;
+	const candidate = value as Partial<WorkflowTreeIdentity>;
+	if (
+		Object.keys(value as Record<string, unknown>).some(
+			(key) => !["version", "kind", "digest"].includes(key),
+		)
+	) {
+		return false;
+	}
+	return (
+		candidate.version === WORKFLOW_TREE_IDENTITY_VERSION &&
+		(candidate.kind === "git-commit" || candidate.kind === "git-dirty") &&
+		typeof candidate.digest === "string" &&
+		/^[a-f0-9]{64}$/u.test(candidate.digest)
+	);
+}
+
+function identity(kind: WorkflowTreeIdentity["kind"], digest: string): WorkflowTreeIdentity {
+	return { version: WORKFLOW_TREE_IDENTITY_VERSION, kind, digest };
+}
+
+function hashParts(parts: Buffer[]): string {
+	const hash = createHash("sha256");
+	for (const part of parts) hash.update(part);
+	return hash.digest("hex");
+}
+
+function updateHashFrame(hash: Hash, label: string, value: string | Buffer): void {
+	const labelBytes = Buffer.from(label, "utf8");
+	const valueBytes = typeof value === "string" ? Buffer.from(value, "utf8") : value;
+	const header = Buffer.allocUnsafe(8);
+	header.writeUInt32BE(labelBytes.length, 0);
+	header.writeUInt32BE(valueBytes.length, 4);
+	hash.update(header);
+	hash.update(labelBytes);
+	hash.update(valueBytes);
+}
+
+function splitNul(value: Buffer): Buffer[] {
+	const entries: Buffer[] = [];
+	let start = 0;
+	for (let index = 0; index < value.length; index++) {
+		if (value[index] !== 0) continue;
+		if (index > start) entries.push(value.subarray(start, index));
+		start = index + 1;
+	}
+	if (start < value.length) entries.push(value.subarray(start));
+	return entries;
+}
+
+function decodeGitPath(value: Buffer): string {
+	const decoded = value.toString("utf8");
+	if (!decoded || decoded.includes("\0") || !Buffer.from(decoded, "utf8").equals(value)) {
+		throw new Error("Workflow tree identity encountered an unsupported Git path encoding");
+	}
+	return decoded;
+}
+
+async function readRegularFileNoFollow(
+	filePath: string,
+	expected: fs.Stats,
+	signal: AbortSignal | undefined,
+): Promise<Buffer> {
+	throwIfAborted(signal);
+	const handle = await fs.promises.open(filePath, fs.constants.O_RDONLY | fs.constants.O_NOFOLLOW);
+	try {
+		const before = await handle.stat();
+		if (!before.isFile() || before.dev !== expected.dev || before.ino !== expected.ino) {
+			throw new Error("Workflow tree identity file changed during capture");
+		}
+		const content = await handle.readFile({ signal });
+		const after = await handle.stat();
+		if (
+			after.dev !== before.dev ||
+			after.ino !== before.ino ||
+			after.size !== before.size ||
+			after.mtimeMs !== before.mtimeMs
+		) {
+			throw new Error("Workflow tree identity file changed during capture");
+		}
+		return content;
+	} finally {
+		await handle.close();
+	}
+}
+
+function git(
+	cwd: string,
+	args: string[],
+	maxBuffer: number,
+	signal?: AbortSignal,
+): Promise<Buffer> {
+	throwIfAborted(signal);
+	return new Promise((resolve, reject) => {
+		execFile(
+			"git",
+			["-C", cwd, ...args],
+			{ encoding: "buffer", maxBuffer, signal },
+			(error, stdout) => {
+				if (error) reject(error);
+				else resolve(stdout);
+			},
+		);
+	});
+}
+
+function throwIfAborted(signal: AbortSignal | undefined): void {
+	if (!signal?.aborted) return;
+	const error = new Error("Workflow tree identity capture was cancelled");
+	error.name = "AbortError";
+	throw error;
+}
+
+function normalizedGitError(error: unknown, fallback: string): Error {
+	if (error instanceof Error && error.name === "AbortError") return error;
+	const message = error instanceof Error ? error.message : String(error);
+	return new Error(
+		/maxBuffer|stdout.*large|SIGTERM/iu.test(message) ? `${fallback}: size limit` : fallback,
+	);
+}

package/src/workflow-verification.ts

@@ -0,0 +1,296 @@
+import { redactPrivateText } from "./context.js";
+import { truncateUtf8 } from "./limits.js";
+import type { StructuredSubagentResultV2 } from "./result-contract.js";
+import { isWorkflowTreeIdentity, type WorkflowTreeIdentity } from "./workflow-tree-identity.js";
+
+export const WORKFLOW_VERIFICATION_VERSION = "pi-subagents:workflow-verification:v1" as const;
+export type WorkflowVerificationDecision = "accept" | "rework" | "reject";
+const MAX_FIELD_BYTES = 2 * 1024;
+const MAX_ITEMS = 32;
+const MAX_EVIDENCE_BYTES = 6 * 1024;
+const MAX_LIMITATION_BYTES = 4 * 1024;
+const MAX_INSTRUCTION_LIST_BYTES = 8 * 1024;
+const ID_PATTERN = /^[A-Za-z0-9][A-Za-z0-9._:-]{0,255}$/u;
+const PLAN_PATTERN = /^[a-f0-9]{64}$/u;
+
+export interface WorkflowVerificationReceipt {
+	version: typeof WORKFLOW_VERIFICATION_VERSION;
+	decision: WorkflowVerificationDecision;
+	targetTaskId: string;
+	targetTaskGeneration: number;
+	targetExecutionPlanId: string;
+	verifierTaskId: string;
+	verifierTaskGeneration: number;
+	verifierExecutionPlanId: string;
+	treeIdentity: WorkflowTreeIdentity;
+	summary: string;
+	evidence: string[];
+	limitations: string[];
+	createdAt: number;
+	truncated: boolean;
+}
+
+export interface WorkflowVerificationContext {
+	targetTaskId: string;
+	targetTaskGeneration: number;
+	targetExecutionPlanId: string;
+	verifierTaskId: string;
+	verifierTaskGeneration: number;
+	verifierExecutionPlanId: string;
+	treeIdentity: WorkflowTreeIdentity;
+	createdAt?: number;
+	sourceTruncated?: boolean;
+}
+
+export function createWorkflowVerificationReceipt(
+	result: StructuredSubagentResultV2,
+	context: WorkflowVerificationContext,
+): WorkflowVerificationReceipt {
+	validateContext(context);
+	const decision = verdict(result);
+	const boundedSummary = bound(result.summary);
+	if (!boundedSummary.value) throw new Error("Workflow verification verdict requires a summary");
+	const evidenceSource = [
+		...result.claims.flatMap((claim) => claim.evidence),
+		...result.verification.flatMap((item) => [item.summary, ...(item.evidence ?? [])]),
+	];
+	const evidence = boundList(evidenceSource, MAX_EVIDENCE_BYTES);
+	const limitations = boundList(
+		[...result.limitations, ...result.unresolvedDependencies],
+		MAX_LIMITATION_BYTES,
+	);
+	if (decision === "rework" && limitations.values.length === 0) {
+		throw new Error("Workflow verification rework requires a limitation or unresolved dependency");
+	}
+	if (decision === "reject" && evidence.values.length === 0) {
+		throw new Error("Workflow verification reject requires evidence");
+	}
+	return {
+		version: WORKFLOW_VERIFICATION_VERSION,
+		decision,
+		targetTaskId: context.targetTaskId,
+		targetTaskGeneration: context.targetTaskGeneration,
+		targetExecutionPlanId: context.targetExecutionPlanId,
+		verifierTaskId: context.verifierTaskId,
+		verifierTaskGeneration: context.verifierTaskGeneration,
+		verifierExecutionPlanId: context.verifierExecutionPlanId,
+		treeIdentity: structuredClone(context.treeIdentity),
+		summary: boundedSummary.value,
+		evidence: evidence.values,
+		limitations: limitations.values,
+		createdAt: context.createdAt ?? Date.now(),
+		truncated:
+			context.sourceTruncated === true ||
+			boundedSummary.truncated ||
+			evidence.truncated ||
+			limitations.truncated,
+	};
+}
+
+export function workflowVerificationInstruction(
+	targetTaskId: string,
+	treeIdentity: WorkflowTreeIdentity,
+	requirements: {
+		acceptanceCriteria?: readonly string[];
+		requiredEvidence?: readonly string[];
+	} = {},
+): string {
+	if (!ID_PATTERN.test(targetTaskId) || !isWorkflowTreeIdentity(treeIdentity)) {
+		throw new Error("Workflow verification instruction received invalid executor metadata");
+	}
+	const acceptanceCriteria = boundList(
+		requirements.acceptanceCriteria ?? [],
+		MAX_INSTRUCTION_LIST_BYTES,
+	).values;
+	const requiredEvidence = boundList(
+		requirements.requiredEvidence ?? [],
+		MAX_INSTRUCTION_LIST_BYTES,
+	).values;
+	return [
+		"You are the independent verifier for one staged workflow result.",
+		`Target task: ${JSON.stringify(targetTaskId)}.`,
+		`Acceptance criteria: ${JSON.stringify(acceptanceCriteria)}.`,
+		`Required evidence: ${JSON.stringify(requiredEvidence)}.`,
+		`Exact Git-visible tree identity: ${treeIdentity.version}:${treeIdentity.kind}:${treeIdentity.digest}.`,
+		"Do not modify the repository; the executor will reject acceptance if the tree identity changes.",
+		"Return the requested pi-subagents:result:v2 object with exactly one verdict encoding.",
+		'Accept only with status "completed", reasonCode "verification-accepted", at least one passed verification item, no failed verification item, and no unresolved dependency.',
+		'Request rework only with status "partial" or "needs-input", reasonCode "verification-rework", and a concrete limitation or unresolved dependency.',
+		'Reject only with status "failed" or "abstained", reasonCode "verification-rejected", and concrete evidence.',
+		"Agreement, confidence, and the implementation worker's own verification claims are not proof.",
+	].join("\n");
+}
+
+export function isWorkflowVerificationReceipt(
+	value: unknown,
+): value is WorkflowVerificationReceipt {
+	if (!value || typeof value !== "object" || Array.isArray(value)) return false;
+	const receipt = value as Partial<WorkflowVerificationReceipt>;
+	if (
+		Object.keys(value as Record<string, unknown>).some(
+			(key) =>
+				![
+					"version",
+					"decision",
+					"targetTaskId",
+					"targetTaskGeneration",
+					"targetExecutionPlanId",
+					"verifierTaskId",
+					"verifierTaskGeneration",
+					"verifierExecutionPlanId",
+					"treeIdentity",
+					"summary",
+					"evidence",
+					"limitations",
+					"createdAt",
+					"truncated",
+				].includes(key),
+		)
+	) {
+		return false;
+	}
+	return (
+		receipt.version === WORKFLOW_VERIFICATION_VERSION &&
+		(receipt.decision !== "rework" ||
+			(Array.isArray(receipt.limitations) && receipt.limitations.length > 0)) &&
+		(receipt.decision !== "reject" ||
+			(Array.isArray(receipt.evidence) && receipt.evidence.length > 0)) &&
+		["accept", "rework", "reject"].includes(String(receipt.decision)) &&
+		typeof receipt.targetTaskId === "string" &&
+		ID_PATTERN.test(receipt.targetTaskId) &&
+		Number.isSafeInteger(receipt.targetTaskGeneration) &&
+		Number(receipt.targetTaskGeneration) >= 1 &&
+		typeof receipt.targetExecutionPlanId === "string" &&
+		PLAN_PATTERN.test(receipt.targetExecutionPlanId) &&
+		typeof receipt.verifierTaskId === "string" &&
+		ID_PATTERN.test(receipt.verifierTaskId) &&
+		Number.isSafeInteger(receipt.verifierTaskGeneration) &&
+		Number(receipt.verifierTaskGeneration) >= 1 &&
+		typeof receipt.verifierExecutionPlanId === "string" &&
+		PLAN_PATTERN.test(receipt.verifierExecutionPlanId) &&
+		isWorkflowTreeIdentity(receipt.treeIdentity) &&
+		typeof receipt.summary === "string" &&
+		receipt.summary.length > 0 &&
+		Buffer.byteLength(receipt.summary, "utf8") <= MAX_FIELD_BYTES &&
+		validStrings(receipt.evidence, MAX_EVIDENCE_BYTES) &&
+		validStrings(receipt.limitations, MAX_LIMITATION_BYTES) &&
+		typeof receipt.createdAt === "number" &&
+		Number.isFinite(receipt.createdAt) &&
+		receipt.createdAt >= 0 &&
+		typeof receipt.truncated === "boolean"
+	);
+}
+
+function verdict(result: StructuredSubagentResultV2): WorkflowVerificationDecision {
+	if (result.version !== "pi-subagents:result:v2") {
+		throw new Error("Workflow verification requires structured-v2");
+	}
+	if (result.reasonCode === "verification-accepted" && result.status === "completed") {
+		if (result.verification.some((item) => item.status === "failed")) {
+			throw new Error("Workflow verification accept cannot contain failed evidence");
+		}
+		if (!result.verification.some((item) => item.status === "passed")) {
+			throw new Error("Workflow verification accept requires passed evidence");
+		}
+		if (result.unresolvedDependencies.length > 0) {
+			throw new Error("Workflow verification accept cannot contain unresolved dependencies");
+		}
+		return "accept";
+	}
+	if (
+		result.reasonCode === "verification-rework" &&
+		(result.status === "partial" || result.status === "needs-input")
+	) {
+		return "rework";
+	}
+	if (
+		result.reasonCode === "verification-rejected" &&
+		(result.status === "failed" || result.status === "abstained")
+	) {
+		return "reject";
+	}
+	throw new Error("Workflow verification result does not contain a valid verdict");
+}
+
+function validateContext(context: WorkflowVerificationContext): void {
+	for (const [label, value] of [
+		["target task", context.targetTaskId],
+		["verifier task", context.verifierTaskId],
+	] as const) {
+		if (!ID_PATTERN.test(value))
+			throw new Error(`Workflow verification has an invalid ${label} id`);
+	}
+	for (const [label, value] of [
+		["target", context.targetTaskGeneration],
+		["verifier", context.verifierTaskGeneration],
+	] as const) {
+		if (!Number.isSafeInteger(value) || value < 1) {
+			throw new Error(`Workflow verification has an invalid ${label} task generation`);
+		}
+	}
+	for (const value of [context.targetExecutionPlanId, context.verifierExecutionPlanId]) {
+		if (!PLAN_PATTERN.test(value)) {
+			throw new Error("Workflow verification has an invalid execution plan identity");
+		}
+	}
+	if (!isWorkflowTreeIdentity(context.treeIdentity)) {
+		throw new Error("Workflow verification has an invalid tree identity");
+	}
+	if (context.sourceTruncated !== undefined && typeof context.sourceTruncated !== "boolean") {
+		throw new Error("Workflow verification has an invalid truncation state");
+	}
+	if (
+		context.createdAt !== undefined &&
+		(!Number.isFinite(context.createdAt) || context.createdAt < 0)
+	) {
+		throw new Error("Workflow verification has an invalid creation time");
+	}
+}
+
+function bound(value: string): { value: string; truncated: boolean } {
+	const redacted = redactPrivateText(value).trim();
+	const truncated = truncateUtf8(redacted, MAX_FIELD_BYTES);
+	return { value: truncated.text, truncated: truncated.truncated };
+}
+
+function boundList(
+	values: readonly string[],
+	maxTotalBytes: number,
+): { values: string[]; truncated: boolean } {
+	let truncated = values.length > MAX_ITEMS;
+	let remaining = maxTotalBytes;
+	const result: string[] = [];
+	const seen = new Set<string>();
+	for (const raw of values.slice(0, MAX_ITEMS)) {
+		if (remaining < 1) {
+			truncated = true;
+			break;
+		}
+		const redacted = redactPrivateText(raw).trim();
+		const item = truncateUtf8(redacted, Math.min(MAX_FIELD_BYTES, remaining));
+		truncated ||= item.truncated;
+		if (!item.text || seen.has(item.text)) continue;
+		seen.add(item.text);
+		result.push(item.text);
+		remaining -= Buffer.byteLength(item.text, "utf8");
+	}
+	return { values: result, truncated };
+}
+
+function validStrings(value: unknown, maxTotalBytes: number): value is string[] {
+	return (
+		Array.isArray(value) &&
+		value.length <= MAX_ITEMS &&
+		value.reduce(
+			(total, item) =>
+				total + (typeof item === "string" ? Buffer.byteLength(item, "utf8") : maxTotalBytes + 1),
+			0,
+		) <= maxTotalBytes &&
+		value.every(
+			(item) =>
+				typeof item === "string" &&
+				item.length > 0 &&
+				Buffer.byteLength(item, "utf8") <= MAX_FIELD_BYTES,
+		)
+	);
+}