@henryqw/pi-subagent 27.5.4 → 27.6.1

package/extensions/workflow.ts

@@ -1,8 +1,13 @@
+import { createHash } from "node:crypto";
+import { createReadStream } from "node:fs";
+import { lstat, readlink } from "node:fs/promises";
+import { posix } from "node:path";
 import { StringEnum } from "@earendil-works/pi-ai";
 import { DISPLAY_TEXT_CONTRACT } from "@henryqw/pi-subagent";
 import { PROFILE_NAMES } from "@henryqw/pi-task-models";
 import { Type, type Static } from "typebox";
 import { Check, Errors } from "typebox/value";
+import { runGit } from "../dist/git-process.js";
 import { ExecuteRequestSchema, parseExecuteRequest, type ExecuteRequest } from "../dist/schema.js";
 
 export const MAX_WORKFLOW_ENTRIES = 8;
@@ -25,13 +30,21 @@ export const DIRECT_ACCESS = ["read", "write"] as const;
 export type DirectAccess = (typeof DIRECT_ACCESS)[number];
 const ACCESS_GUIDANCE = `Declare "write" when the task may change files, Git state, or external resources, otherwise "read". "read" is not enforced (no sandbox): it skips checkout admission and runs concurrently. Use mode isolated for checked writes.`;
 const AccessSchema = StringEnum(DIRECT_ACCESS, { description: ACCESS_GUIDANCE });
+const DryRunSchema = Type.Boolean({ description: "Optional. When true, run every launch validation and return the resolved plan without starting workers, saving state, or reserving the checkout." });
 const ContinueFromSchema = Type.String({ pattern: "^D[1-9][0-9]*\\.[1-9][0-9]*$", description: "Optional direct worker reference such as D7.1. Continues that finished worker's Pi session in a new tab with this task; role must equal the recorded Role." });
 
+const PathsSchema = Type.Array(Type.String({ minLength: 1 }), {
+	minItems: 1,
+	maxItems: 32,
+	description: "Write tasks only: repo-relative globs (Node path.matchesGlob syntax, such as src/**) the task may change. The result flags changed paths outside them. Report only; nothing enforces it.",
+});
+
 export const DelegationSchema = Type.Object({
 	role: RoleSchema,
 	name: TaskNameSchema,
 	task: TaskSchema,
 	access: AccessSchema,
+	paths: Type.Optional(PathsSchema),
 	continueFrom: Type.Optional(ContinueFromSchema),
 	kind: Type.Optional(DirectKindSchema),
 	model: Type.Optional(ModelSchema),
@@ -44,6 +57,7 @@ export const DirectWorkflowSchema = Type.Object({
 	name: Type.Optional(TaskNameSchema),
 	task: Type.Optional(TaskSchema),
 	access: Type.Optional(AccessSchema),
+	paths: Type.Optional(PathsSchema),
 	continueFrom: Type.Optional(ContinueFromSchema),
 	kind: Type.Optional(DirectKindSchema),
 	model: Type.Optional(ModelSchema),
@@ -64,6 +78,7 @@ export const DelegateTaskParameters = Type.Object({
 	])),
 	finalChecks: ExecuteRequestSchema.properties.finalChecks,
 	finalJudgment: ExecuteRequestSchema.properties.finalJudgment,
+	dryRun: Type.Optional(DryRunSchema),
 }, { additionalProperties: false });
 
 export type Delegation = Static<typeof DelegationSchema> & { kind: "text" };
@@ -72,10 +87,10 @@ export type ParsedWorkflow =
 	| { mode: "single"; delegations: [Delegation] }
 	| { mode: "parallel"; delegations: Delegation[] }
 	| { mode: "chain"; delegations: Delegation[] };
-export type ParsedDelegateTask = { mode: "direct"; workflow: ParsedWorkflow } | { mode: "isolated"; request: ExecuteRequest };
+export type ParsedDelegateTask = ({ mode: "direct"; workflow: ParsedWorkflow } | { mode: "isolated"; request: ExecuteRequest }) & { dryRun: boolean };
 
 type DirectInput = Static<typeof DirectWorkflowSchema>;
-const DELEGATION_KEYS = ["role", "name", "task", "access", "continueFrom", "kind", "model", "modelClass"] as const;
+const DELEGATION_KEYS = ["role", "name", "task", "access", "paths", "continueFrom", "kind", "model", "modelClass"] as const;
 
 function text(value: string, path: string): string {
 	const normalized = value.trim();
@@ -89,12 +104,24 @@ function normalizeTaskName(value: string, path: string): string {
 	return normalized;
 }
 
+function normalizePaths(value: Static<typeof DelegationSchema>, path: string): string[] | undefined {
+	if (value.paths === undefined) return;
+	if (value.access !== "write") throw new Error(`${path}.paths requires access "write"; it declares where a write task may change files.`);
+	return value.paths.map((glob, index) => {
+		const normalized = text(glob, `${path}.paths[${index}]`);
+		if (normalized.startsWith("/") || normalized.split("/").includes("..")) throw new Error(`${path}.paths[${index}] must be a repo-relative glob without .. segments.`);
+		return normalized;
+	});
+}
+
 function normalizeDelegation(value: Static<typeof DelegationSchema>, path: string): Delegation {
+	const paths = normalizePaths(value, path);
 	return {
 		role: text(value.role, `${path}.role`),
 		name: normalizeTaskName(value.name, `${path}.name`),
 		task: text(value.task, `${path}.task`),
 		access: value.access,
+		...(paths === undefined ? {} : { paths }),
 		...(value.continueFrom === undefined ? {} : { continueFrom: value.continueFrom }),
 		kind: "text",
 		...(value.model === undefined ? {} : { model: text(value.model, `${path}.model`) }),
@@ -148,11 +175,124 @@ export function parseWorkflow(value: unknown): ParsedWorkflow {
 /** A direct request is a writer request when any task declares write access. */
 export const writesCheckout = (workflow: ParsedWorkflow): boolean => workflow.delegations.some(({ access }) => access === "write");
 
+/** `dryRun` is a tool-call option, not part of the direct workflow or the durable isolated request. */
 export function parseDelegateTask(value: unknown): ParsedDelegateTask {
+	let dryRun = false;
+	if (value && typeof value === "object" && !Array.isArray(value) && Object.hasOwn(value, "dryRun")) {
+		const { dryRun: option, ...rest } = value as Record<string, unknown>;
+		if (typeof option !== "boolean") throw new Error(`delegate_task dryRun must be a boolean, got ${JSON.stringify(option)}.`);
+		dryRun = option;
+		value = rest;
+	}
 	if (value && typeof value === "object" && !Array.isArray(value) && (value as { mode?: unknown }).mode === "isolated") {
-		return { mode: "isolated", request: parseExecuteRequest(value) };
+		return { mode: "isolated", request: parseExecuteRequest(value), dryRun };
+	}
+	return { mode: "direct", workflow: parseWorkflow(value), dryRun };
+}
+
+/** Main's checkout state: HEAD plus porcelain status and content identity of each dirty path. */
+export type CheckoutSnapshot = { head?: string; entries: Map<string, string>; fingerprint: string };
+
+export type ChangeReport = {
+	/** Set when HEAD moved to a commit that does not descend from the launch HEAD. */
+	headMove?: string;
+	commits: Array<{ oid: string; subject: string }>;
+	omittedCommits: number;
+	paths: Array<{ path: string; outside?: true }>;
+	omittedPaths: number;
+};
+
+export type CheckoutNote =
+	| { kind: "changes"; report: ChangeReport }
+	| { kind: "stale" }
+	| { kind: "unavailable"; check: "change report" | "stale-read check"; reason: string };
+
+export const CHANGE_REPORT_LIMITS = { commits: 10, paths: 20, subject: 120, reason: 500 } as const;
+
+async function contentIdentity(path: string): Promise<string> {
+	const stats = await lstat(path).catch(() => undefined);
+	if (!stats) return "absent";
+	if (stats.isSymbolicLink()) return `link ${await readlink(path)}`;
+	if (!stats.isFile()) return "other";
+	const hash = createHash("sha256");
+	for await (const chunk of createReadStream(path)) hash.update(chunk);
+	return hash.digest("hex");
+}
+
+// Background snapshots must not take index.lock while Main or a worker writes.
+async function git(cwd: string, args: string[], codes = [0]) {
+	const result = await runGit(["--no-optional-locks", ...args], cwd);
+	if (!codes.includes(result.code)) throw new Error(`git ${args[0]} exited ${result.code}: ${result.stderr.trim() || "no diagnostic"}`);
+	return result;
+}
+
+/** Snapshot the checkout that contains `cwd`; undefined outside a Git repository. Other Git failures throw. */
+export async function snapshotCheckout(cwd: string): Promise<CheckoutSnapshot | undefined> {
+	const top = await runGit(["--no-optional-locks", "rev-parse", "--show-toplevel"], cwd);
+	if (top.code !== 0 && /not a git repository/i.test(top.stderr)) return undefined;
+	const root = top.stdout.trim();
+	if (top.code !== 0 || !root) throw new Error(`git rev-parse exited ${top.code}: ${top.stderr.trim() || "no diagnostic"}`);
+	const head = (await git(root, ["rev-parse", "--verify", "--quiet", "HEAD"], [0, 1])).stdout.trim() || undefined;
+	// Porcelain paths are repository-relative; an index or worktree rename or copy lists its source after the destination.
+	const fields = (await git(root, ["status", "--porcelain=v1", "-z", "--untracked-files=all"])).stdout.split("\0");
+	const entries = new Map<string, string>();
+	for (let index = 0; index < fields.length; index++) {
+		const field = fields[index]!;
+		if (!field) continue;
+		const status = field.slice(0, 2);
+		entries.set(field.slice(3), status);
+		if (/[RC]/.test(status)) entries.set(fields[++index]!, status);
+	}
+	// Status alone misses a further edit to a path that was already dirty.
+	for (const [path, status] of entries) entries.set(path, `${status} ${await contentIdentity(posix.join(root, path))}`);
+	const fingerprint = createHash("sha256").update(JSON.stringify([head ?? null, [...entries].sort()])).digest("hex");
+	return { ...(head === undefined ? {} : { head }), entries, fingerprint };
+}
+
+/** Commits and changed paths between two snapshots of the same checkout. */
+export async function reportCheckoutChanges(cwd: string, before: CheckoutSnapshot, after: CheckoutSnapshot, declared?: readonly string[]): Promise<ChangeReport> {
+	const changed = new Set([...before.entries.keys(), ...after.entries.keys()].filter((path) => before.entries.get(path) !== after.entries.get(path)));
+	const report: ChangeReport = { commits: [], omittedCommits: 0, paths: [], omittedPaths: 0 };
+	const short = (oid: string) => oid.slice(0, 12);
+	if (before.head !== after.head && after.head === undefined) report.headMove = `HEAD moved from ${short(before.head!)} to an unborn branch`;
+	else if (before.head !== after.head) {
+		const range = before.head === undefined ? [after.head!] : [`${before.head}..${after.head}`];
+		const total = Number((await git(cwd, ["rev-list", "--count", ...range, "--"])).stdout.trim());
+		const log = (await git(cwd, ["log", "--no-show-signature", `--max-count=${CHANGE_REPORT_LIMITS.commits}`, "--format=%h%x00%s", ...range, "--"])).stdout;
+		report.commits = log.split("\n").filter(Boolean).map((line) => {
+			const [oid, subject = ""] = line.split("\0");
+			return { oid: oid!, subject: Array.from(subject).slice(0, CHANGE_REPORT_LIMITS.subject).join("") };
+		});
+		report.omittedCommits = Math.max(0, total - report.commits.length);
+		const names = before.head === undefined
+			? await git(cwd, ["ls-tree", "-r", "--name-only", "-z", "--full-tree", after.head!])
+			: await git(cwd, ["diff", "--name-only", "-z", "--no-renames", "--no-ext-diff", "--no-textconv", before.head, after.head!, "--"]);
+		for (const path of names.stdout.split("\0")) if (path) changed.add(path);
+		if (before.head !== undefined && (await git(cwd, ["merge-base", "--is-ancestor", before.head, after.head!], [0, 1])).code === 1) {
+			report.headMove = `HEAD moved from ${short(before.head)} to ${short(after.head!)}, which does not descend from it`;
+		}
+	}
+	const outside = (path: string) => declared !== undefined && !declared.some((glob) => posix.matchesGlob(path, glob));
+	// Outside paths come first so the cap never hides them.
+	const paths = [...changed].sort().map((path) => outside(path) ? { path, outside: true as const } : { path })
+		.sort((left, right) => Number(Boolean(right.outside)) - Number(Boolean(left.outside)));
+	report.paths = paths.slice(0, CHANGE_REPORT_LIMITS.paths);
+	report.omittedPaths = paths.length - report.paths.length;
+	return report;
+}
+
+/** Compare a task's launch snapshot with the checkout at its terminal outcome. Failures become a note, never a task failure. */
+export async function checkoutNote(cwd: string, before: CheckoutSnapshot | Error | undefined, write: boolean, declared?: readonly string[]): Promise<CheckoutNote | undefined> {
+	try {
+		if (before instanceof Error) throw before;
+		if (before === undefined) return;
+		const after = await snapshotCheckout(cwd);
+		if (after === undefined) throw new Error("the checkout is no longer a Git repository");
+		if (write) return { kind: "changes", report: await reportCheckoutChanges(cwd, before, after, declared) };
+		return after.fingerprint === before.fingerprint ? undefined : { kind: "stale" };
+	} catch (error) {
+		return { kind: "unavailable", check: write ? "change report" : "stale-read check", reason: Array.from(error instanceof Error ? error.message : String(error)).slice(0, CHANGE_REPORT_LIMITS.reason).join("") };
 	}
-	return { mode: "direct", workflow: parseWorkflow(value) };
 }
 
 export type WorkflowEntry = { id: string; index: number; delegation: Delegation };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@henryqw/pi-subagent",
-  "version": "27.5.4",
+  "version": "27.6.1",
   "description": "Delegate bounded direct work or durable checked isolated task graphs to Pi roles.",
   "keywords": [
     "pi-package",