@narumitw/pi-subagents 0.49.3 → 0.51.0

package/src/work-item-persistence.ts

@@ -0,0 +1,218 @@
+import { createHash } from "node:crypto";
+import * as fs from "node:fs";
+import * as path from "node:path";
+import { getAgentDir, withFileMutationQueue } from "@earendil-works/pi-coding-agent";
+import { redactPrivateText } from "./context.js";
+import { WorkItemLedger, type WorkItemLedgerSnapshot } from "./work-item-ledger.js";
+
+const WORKFLOW_STATE_DIRECTORY = "pi-subagents-workflows";
+const DEFAULT_MAX_STORED_WORKFLOWS = 64;
+const DEFAULT_RETENTION_MS = 30 * 24 * 60 * 60 * 1000;
+const MAX_WORKFLOW_STATE_BYTES = 1024 * 1024;
+
+export interface SessionWorkflowPersistenceOptions {
+	stateDir?: string;
+	maxStoredWorkflows?: number;
+	retentionMs?: number;
+}
+
+export interface SessionWorkflowInspection {
+	workflows: WorkItemLedgerSnapshot[];
+	invalid: number;
+	omitted: number;
+}
+
+export class WorkItemPersistence {
+	constructor(
+		readonly filePath: string,
+		private readonly afterSave?: () => Promise<void>,
+	) {}
+
+	async save(snapshot: WorkItemLedgerSnapshot): Promise<void> {
+		const filePath = path.resolve(this.filePath);
+		const sanitized = sanitizeWorkflowSnapshot(snapshot);
+		const content = `${JSON.stringify(sanitized)}\n`;
+		if (Buffer.byteLength(content, "utf8") > MAX_WORKFLOW_STATE_BYTES) {
+			throw new Error("WorkItem workflow state exceeds the persistence size limit");
+		}
+		await withFileMutationQueue(filePath, async () => {
+			await fs.promises.mkdir(path.dirname(filePath), { recursive: true, mode: 0o700 });
+			const temporary = `${filePath}.${process.pid}.${Date.now()}.tmp`;
+			try {
+				await fs.promises.writeFile(temporary, content, { mode: 0o600 });
+				await fs.promises.rename(temporary, filePath);
+			} finally {
+				await fs.promises.rm(temporary, { force: true });
+			}
+		});
+		await this.afterSave?.();
+	}
+
+	load(): WorkItemLedger | undefined {
+		const filePath = path.resolve(this.filePath);
+		let source: string;
+		try {
+			const stat = fs.statSync(filePath);
+			if (stat.size > MAX_WORKFLOW_STATE_BYTES)
+				throw new Error("workflow state exceeds size limit");
+			source = fs.readFileSync(filePath, "utf8");
+		} catch (error) {
+			if ((error as NodeJS.ErrnoException).code === "ENOENT") return undefined;
+			throw error;
+		}
+		try {
+			return WorkItemLedger.restore(JSON.parse(source) as WorkItemLedgerSnapshot);
+		} catch {
+			const quarantine = `${filePath}.invalid-${Date.now()}`;
+			try {
+				fs.renameSync(filePath, quarantine);
+			} catch {
+				// A concurrent owner may already have handled the invalid file.
+			}
+			return undefined;
+		}
+	}
+}
+
+export function createSessionWorkItemPersistence(
+	owner: string,
+	workflowId: string,
+	options: SessionWorkflowPersistenceOptions = {},
+): WorkItemPersistence {
+	const maxStoredWorkflows = options.maxStoredWorkflows ?? DEFAULT_MAX_STORED_WORKFLOWS;
+	const retentionMs = options.retentionMs ?? DEFAULT_RETENTION_MS;
+	if (!Number.isSafeInteger(maxStoredWorkflows) || maxStoredWorkflows < 1) {
+		throw new Error("maxStoredWorkflows must be a positive safe integer");
+	}
+	if (!Number.isFinite(retentionMs) || retentionMs <= 0) {
+		throw new Error("workflow retentionMs must be a positive finite number");
+	}
+	const stateDir = resolveStateDirectory(options.stateDir);
+	const prefix = sessionPrefix(owner);
+	const filePath = path.join(stateDir, `${prefix}-${stableId(workflowId)}.json`);
+	return new WorkItemPersistence(filePath, () =>
+		pruneSessionWorkflows(stateDir, prefix, maxStoredWorkflows, retentionMs),
+	);
+}
+
+export function inspectSessionWorkflows(
+	owner: string,
+	options: SessionWorkflowPersistenceOptions = {},
+): SessionWorkflowInspection {
+	const stateDir = resolveStateDirectory(options.stateDir);
+	const prefix = `${sessionPrefix(owner)}-`;
+	const limit = options.maxStoredWorkflows ?? DEFAULT_MAX_STORED_WORKFLOWS;
+	if (!Number.isSafeInteger(limit) || limit < 1) {
+		throw new Error("maxStoredWorkflows must be a positive safe integer");
+	}
+	let entries: fs.Dirent[];
+	try {
+		entries = fs.readdirSync(stateDir, { withFileTypes: true });
+	} catch (error) {
+		if ((error as NodeJS.ErrnoException).code === "ENOENT") {
+			return { workflows: [], invalid: 0, omitted: 0 };
+		}
+		throw error;
+	}
+	const candidates = entries
+		.filter(
+			(entry) => entry.isFile() && entry.name.startsWith(prefix) && entry.name.endsWith(".json"),
+		)
+		.map((entry) => {
+			const filePath = path.join(stateDir, entry.name);
+			return { filePath, modifiedAt: safeModifiedAt(filePath) };
+		})
+		.sort((left, right) => right.modifiedAt - left.modifiedAt);
+	const workflows: WorkItemLedgerSnapshot[] = [];
+	let invalid = 0;
+	for (const candidate of candidates.slice(0, limit)) {
+		try {
+			const stat = fs.statSync(candidate.filePath);
+			if (stat.size > MAX_WORKFLOW_STATE_BYTES)
+				throw new Error("workflow state exceeds size limit");
+			const source = fs.readFileSync(candidate.filePath, "utf8");
+			workflows.push(
+				WorkItemLedger.restore(JSON.parse(source) as WorkItemLedgerSnapshot).snapshot(),
+			);
+		} catch {
+			invalid++;
+		}
+	}
+	return { workflows, invalid, omitted: Math.max(0, candidates.length - limit) };
+}
+
+function safeModifiedAt(filePath: string): number {
+	try {
+		return fs.statSync(filePath).mtimeMs;
+	} catch {
+		return 0;
+	}
+}
+
+function resolveStateDirectory(stateDir: string | undefined): string {
+	return path.resolve(stateDir ?? path.join(getAgentDir(), WORKFLOW_STATE_DIRECTORY));
+}
+
+function sessionPrefix(owner: string): string {
+	return stableId(`session:${owner}`);
+}
+
+function stableId(value: string): string {
+	return createHash("sha256").update(value).digest("hex").slice(0, 24);
+}
+
+async function pruneSessionWorkflows(
+	stateDir: string,
+	prefix: string,
+	maxStoredWorkflows: number,
+	retentionMs: number,
+): Promise<void> {
+	await withFileMutationQueue(path.join(stateDir, `${prefix}.prune`), async () => {
+		const cutoff = Date.now() - retentionMs;
+		const entries = (await fs.promises.readdir(stateDir, { withFileTypes: true }))
+			.filter(
+				(entry) =>
+					entry.isFile() && entry.name.startsWith(`${prefix}-`) && entry.name.endsWith(".json"),
+			)
+			.map((entry) => path.join(stateDir, entry.name));
+		const records = await Promise.all(
+			entries.map(async (filePath) => ({
+				filePath,
+				modifiedAt: (await fs.promises.stat(filePath)).mtimeMs,
+			})),
+		);
+		records.sort((left, right) => right.modifiedAt - left.modifiedAt);
+		await Promise.all(
+			records
+				.filter((record, index) => index >= maxStoredWorkflows || record.modifiedAt < cutoff)
+				.map((record) => fs.promises.rm(record.filePath, { force: true })),
+		);
+	});
+}
+
+function sanitizeWorkflowSnapshot(snapshot: WorkItemLedgerSnapshot): WorkItemLedgerSnapshot {
+	const sanitized = structuredClone(snapshot);
+	for (const item of sanitized.items) {
+		item.objective = redact(item.objective);
+		item.selectedAgentName = item.selectedAgentName ? redact(item.selectedAgentName) : undefined;
+		item.requiredCapabilities = item.requiredCapabilities.map(redact);
+		item.requiredTools = item.requiredTools.map(redact);
+		item.readPaths = item.readPaths.map(redact);
+		item.writePaths = item.writePaths.map(redact);
+		item.ownershipKeys = item.ownershipKeys.map(redact);
+		item.acceptanceCriteria = item.acceptanceCriteria.map(redact);
+		item.invalidationReasons = item.invalidationReasons.map(redact);
+		item.outcomeReason = item.outcomeReason ? redact(item.outcomeReason) : undefined;
+		for (const artifact of [...item.artifacts, ...item.artifactHistory]) {
+			artifact.kind = redact(artifact.kind);
+			artifact.version = redact(artifact.version);
+			artifact.digest = artifact.digest ? redact(artifact.digest) : undefined;
+		}
+	}
+	WorkItemLedger.restore(sanitized);
+	return sanitized;
+}
+
+function redact(value: string): string {
+	return redactPrivateText(value).trim();
+}

package/src/workflow-planning.ts

@@ -0,0 +1,150 @@
+import type { AgentConfig } from "./agents.js";
+import { routeByCapability } from "./capability-router.js";
+import { normalizeDelegationContract } from "./delegation-contract.js";
+import type { SubagentParams } from "./params.js";
+import { type WorkItemDefinition, WorkItemLedger } from "./work-item-ledger.js";
+
+export type WorkflowTask = NonNullable<SubagentParams["workflow"]>["tasks"][number];
+export type ResolvedWorkflowTask = WorkflowTask & { agent: string };
+type Aggregator = NonNullable<SubagentParams["aggregator"]>;
+
+type WorkRequest = {
+	contract?: unknown;
+	inputArtifacts?: string[];
+	inputArtifactVersions?: Record<string, string>;
+	requiredCapabilities?: string[];
+	requiredTools?: string[];
+	agent?: string;
+	sideEffectPolicy?: "read-only" | "idempotent" | "mutating";
+	readPaths?: string[];
+	writePaths?: string[];
+	ownershipKeys?: string[];
+	acceptanceCriteria?: string[];
+	integrationOwner?: boolean;
+	verifierFor?: string;
+	dependencyPolicy?: "completed" | "settled";
+};
+
+export function resolveWorkflowTasks(
+	params: SubagentParams,
+	agents: readonly AgentConfig[],
+): ResolvedWorkflowTask[] {
+	return (params.workflow?.tasks ?? []).map((task) => {
+		const contract = normalizeDelegationContract(task.contract);
+		const route = routeByCapability(agents, {
+			agent: task.agent,
+			requiredCapabilities: [
+				...(task.requiredCapabilities ?? []),
+				...(contract?.requestedAuthority?.capabilities ?? []),
+			],
+			requiredTools: [
+				...(task.requiredTools ?? []),
+				...(contract?.requestedAuthority?.tools ?? []),
+			],
+			requiredVerificationRole: task.requiredVerificationRole,
+			requiredSideEffectClass: contract?.sideEffectPolicy === "read-only" ? "read-only" : undefined,
+			preferredCostHint: task.preferredCostHint,
+			preferredLatencyHint: task.preferredLatencyHint,
+		});
+		return { ...task, agent: route.agent.name };
+	});
+}
+
+export function createBlockingWorkLedger(
+	params: SubagentParams,
+	resolvedWorkflowTasks: ResolvedWorkflowTask[],
+	aggregator: Aggregator | undefined,
+): WorkItemLedger | undefined {
+	if (params.agent && params.task) {
+		return WorkItemLedger.create({
+			workflowId: "blocking-single",
+			items: [definition("task-1", params.task, [], params)],
+		});
+	}
+	if (params.chain?.length) {
+		return WorkItemLedger.create({
+			workflowId: "blocking-chain",
+			items: params.chain.map((step, index) =>
+				definition(`step-${index + 1}`, step.task, index === 0 ? [] : [`step-${index}`], step),
+			),
+		});
+	}
+	if (params.tasks?.length) {
+		const items = params.tasks.map((task, index) =>
+			definition(`task-${index + 1}`, task.task, [], task),
+		);
+		if (aggregator) {
+			items.push(
+				definition(
+					"aggregator",
+					aggregator.task,
+					params.tasks.map((_task, index) => `task-${index + 1}`),
+					{ ...aggregator, dependencyPolicy: "settled" },
+				),
+			);
+		}
+		return WorkItemLedger.create({ workflowId: "blocking-parallel", items });
+	}
+	if (params.workflow && resolvedWorkflowTasks.length > 0) {
+		const hasExplicitIntegrationOwner = resolvedWorkflowTasks.some(
+			(task) => task.integrationOwner === true,
+		);
+		return WorkItemLedger.create({
+			workflowId: params.workflow.id ?? "blocking-workflow",
+			items: resolvedWorkflowTasks.map((task, index) =>
+				definition(task.id, task.task, task.dependsOn ?? [], {
+					...task,
+					integrationOwner:
+						task.integrationOwner ??
+						(!hasExplicitIntegrationOwner && index === resolvedWorkflowTasks.length - 1),
+				}),
+			),
+		});
+	}
+	return undefined;
+}
+
+function definition(
+	id: string,
+	task: string,
+	dependencies: string[],
+	request: WorkRequest,
+): WorkItemDefinition {
+	const contract = normalizeDelegationContract(request.contract);
+	return {
+		id,
+		objective: contract?.objective ?? task,
+		dependencies,
+		inputArtifacts: [
+			...(request.inputArtifacts ?? contract?.requiredInputs ?? []),
+			...(contract?.dependencies
+				.filter((dependency) => dependency.artifactId)
+				.map((dependency) => dependency.artifactId as string) ?? []),
+		],
+		inputArtifactVersions: {
+			...Object.fromEntries(
+				(contract?.dependencies ?? [])
+					.filter((dependency) => dependency.artifactId && dependency.version)
+					.map((dependency) => [dependency.artifactId as string, dependency.version as string]),
+			),
+			...(request.inputArtifactVersions ?? {}),
+		},
+		requiredCapabilities: [
+			...(request.requiredCapabilities ?? []),
+			...(contract?.requestedAuthority?.capabilities ?? []),
+		],
+		requiredTools: [
+			...(request.requiredTools ?? []),
+			...(contract?.requestedAuthority?.tools ?? []),
+		],
+		selectedAgentName: request.agent,
+		sideEffectPolicy: contract?.sideEffectPolicy ?? request.sideEffectPolicy ?? "mutating",
+		readPaths: request.readPaths ?? contract?.requestedAuthority?.readPaths ?? [],
+		writePaths: request.writePaths ?? contract?.requestedAuthority?.writePaths ?? [],
+		ownershipKeys: request.ownershipKeys ?? [],
+		acceptanceCriteria: request.acceptanceCriteria ?? contract?.acceptanceCriteria ?? [],
+		integrationOwner: request.integrationOwner,
+		verifierFor: request.verifierFor,
+		dependencyPolicy: request.dependencyPolicy,
+	};
+}

package/src/workflow-ui.ts

@@ -0,0 +1,61 @@
+import type { ExtensionCommandContext } from "@earendil-works/pi-coding-agent";
+import type { DelegationWorkflow } from "./settings.js";
+
+export async function showWorkflowPreview(
+	ctx: ExtensionCommandContext,
+	current: DelegationWorkflow,
+	next: DelegationWorkflow,
+	requiresReload: boolean,
+	signal: AbortSignal,
+): Promise<boolean> {
+	const changes = workflowEffects(current, next);
+	return ctx.ui.confirm(
+		requiresReload ? "Save delegation change and reload?" : "Save delegation change?",
+		[
+			`Current: ${workflowLabel(current)}`,
+			`New: ${workflowLabel(next)}`,
+			"",
+			"Effect:",
+			...(changes.length > 0 ? changes : ["Keep the current registered tools"]).map(
+				(effect) => `- ${effect}`,
+			),
+			`- ${requiresReload ? "Reload the extension to apply this tool surface" : "No reload is needed because the active tools already match"}`,
+		].join("\n"),
+		{ signal },
+	);
+}
+
+export function workflowLabel(value: DelegationWorkflow): string {
+	switch (value) {
+		case "all":
+			return "All delegation methods";
+		case "async-only":
+			return "Async only";
+		case "blocking-only":
+			return "Blocking only";
+		case "disabled":
+			return "Delegation disabled";
+	}
+}
+
+function workflowEffects(current: DelegationWorkflow, next: DelegationWorkflow): string[] {
+	const blockingEnabled = (value: DelegationWorkflow) =>
+		value === "all" || value === "blocking-only";
+	const asyncEnabled = (value: DelegationWorkflow) => value === "all" || value === "async-only";
+	const effects: string[] = [];
+	if (blockingEnabled(current) !== blockingEnabled(next)) {
+		effects.push(
+			blockingEnabled(next)
+				? "Add blocking `subagent` and read-only `subagent_consult`"
+				: "Remove blocking `subagent` and read-only `subagent_consult`",
+		);
+	}
+	if (asyncEnabled(current) !== asyncEnabled(next)) {
+		effects.push(
+			asyncEnabled(next)
+				? "Add reusable async lifecycle tools"
+				: "Remove reusable async lifecycle tools",
+		);
+	}
+	return effects;
+}

package/src/workspace.ts

@@ -14,23 +14,16 @@ export interface IsolatedWorkspace {
 	repositoryRoot: string;
 }
 
+export async function assertWorkspaceIsolationReady(cwd: string): Promise<void> {
+	await resolveWorkspaceBase(cwd);
+}
+
 export class WorkspaceManager {
 	private readonly owned = new Map<string, IsolatedWorkspace>();
 
 	async create(ownerId: string, cwd: string): Promise<IsolatedWorkspace> {
 		if (this.owned.has(ownerId)) throw new Error(`Workspace owner already exists: ${ownerId}`);
-		const resolvedCwd = path.resolve(cwd);
-		const repositoryRoot = (
-			await execFileAsync("git", ["-C", resolvedCwd, "rev-parse", "--show-toplevel"])
-		).stdout.trim();
-		const relativeCwd = path.relative(repositoryRoot, resolvedCwd);
-		if (relativeCwd.startsWith("..") || path.isAbsolute(relativeCwd)) {
-			throw new Error("Subagent cwd is outside the Git repository");
-		}
-		const status = (await execFileAsync("git", ["-C", repositoryRoot, "status", "--porcelain"]))
-			.stdout;
-		if (status.trim())
-			throw new Error("Isolated subagent workspace requires a clean Git repository");
+		const { repositoryRoot, relativeCwd } = await resolveWorkspaceBase(cwd);
 		const rootPath = await fs.promises.mkdtemp(path.join(os.tmpdir(), WORKTREE_PREFIX));
 		let registered = false;
 		try {
@@ -70,6 +63,40 @@ export class WorkspaceManager {
 		}
 	}
 
+	async cleanupPersisted(ownerId: string, cwd: string): Promise<void> {
+		const rootPath = findGeneratedWorktreeRoot(cwd);
+		if (!rootPath || !(await this.isOwned(rootPath, ownerId))) return;
+		let repositoryRoot: string | undefined;
+		try {
+			const commonDirectory = (
+				await execFileAsync("git", ["-C", rootPath, "rev-parse", "--git-common-dir"])
+			).stdout.trim();
+			const resolvedCommonDirectory = await fs.promises.realpath(
+				path.resolve(rootPath, commonDirectory),
+			);
+			repositoryRoot = path.dirname(resolvedCommonDirectory);
+		} catch {
+			// The ownership marker still permits bounded filesystem cleanup below.
+		}
+		if (repositoryRoot) {
+			await execFileAsync("git", [
+				"-C",
+				repositoryRoot,
+				"worktree",
+				"remove",
+				"--force",
+				rootPath,
+			]).catch(() => undefined);
+		}
+		await fs.promises.rm(rootPath, { recursive: true, force: true });
+		await fs.promises.rm(`${rootPath}.owner`, { force: true });
+		if (repositoryRoot) {
+			await execFileAsync("git", ["-C", repositoryRoot, "worktree", "prune"]).catch(
+				() => undefined,
+			);
+		}
+	}
+
 	async cleanup(ownerId: string): Promise<void> {
 		const workspace = this.owned.get(ownerId);
 		if (!workspace) return;
@@ -115,3 +142,33 @@ export class WorkspaceManager {
 		}
 	}
 }
+
+async function resolveWorkspaceBase(
+	cwd: string,
+): Promise<{ repositoryRoot: string; relativeCwd: string }> {
+	const resolvedCwd = await fs.promises.realpath(path.resolve(cwd));
+	const reportedRepositoryRoot = (
+		await execFileAsync("git", ["-C", resolvedCwd, "rev-parse", "--show-toplevel"])
+	).stdout.trim();
+	const repositoryRoot = await fs.promises.realpath(reportedRepositoryRoot);
+	const relativeCwd = path.relative(repositoryRoot, resolvedCwd);
+	if (relativeCwd.startsWith("..") || path.isAbsolute(relativeCwd)) {
+		throw new Error("Subagent cwd is outside the Git repository");
+	}
+	const status = (await execFileAsync("git", ["-C", repositoryRoot, "status", "--porcelain"]))
+		.stdout;
+	if (status.trim()) {
+		throw new Error("Isolated subagent workspace requires a clean Git repository");
+	}
+	return { repositoryRoot, relativeCwd };
+}
+
+function findGeneratedWorktreeRoot(cwd: string): string | undefined {
+	let current = path.resolve(cwd);
+	while (true) {
+		if (path.basename(current).startsWith(WORKTREE_PREFIX)) return current;
+		const parent = path.dirname(current);
+		if (parent === current) return undefined;
+		current = parent;
+	}
+}