@narumitw/pi-subagents 2.1.4 → 3.0.0

package/src/workflow-planning.ts

@@ -1,172 +0,0 @@
-import type { AgentConfig } from "./agents/types.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[];
-	requiredEvidence?: string[];
-	integrationOwner?: boolean;
-	verifierFor?: string;
-	dependencyPolicy?: "completed" | "settled";
-	acceptanceRequired?: boolean;
-	maxReworkCycles?: 0 | 1;
-};
-
-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,
-	verifiedTarget?: { id: string; maxReworkCycles: 0 | 1 },
-): 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,
-		);
-		let defaultIntegrationOwnerIndex = -1;
-		if (!hasExplicitIntegrationOwner) {
-			for (let index = resolvedWorkflowTasks.length - 1; index >= 0; index--) {
-				if (resolvedWorkflowTasks[index]?.verifierFor === undefined) {
-					defaultIntegrationOwnerIndex = index;
-					break;
-				}
-			}
-		}
-		if (!hasExplicitIntegrationOwner && defaultIntegrationOwnerIndex < 0) {
-			throw new Error("Workflow has no non-verifier integration owner candidate");
-		}
-		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 === defaultIntegrationOwnerIndex),
-					...(verifiedTarget?.id === task.id
-						? { acceptanceRequired: true, maxReworkCycles: verifiedTarget.maxReworkCycles }
-						: {}),
-				}),
-			),
-		});
-	}
-	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 ?? [],
-		requiredEvidence: request.requiredEvidence ?? contract?.requiredEvidence ?? [],
-		integrationOwner: request.integrationOwner,
-		verifierFor: request.verifierFor,
-		dependencyPolicy: request.dependencyPolicy,
-		acceptanceRequired: request.acceptanceRequired,
-		maxReworkCycles: request.maxReworkCycles,
-	};
-}

package/src/workflow-tree-identity.ts

@@ -1,289 +0,0 @@
-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-ui.ts

@@ -1,69 +0,0 @@
-import type { ExtensionCommandContext } from "@earendil-works/pi-coding-agent";
-import type { DelegationWorkflow } from "./settings/inspection.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 how subagents run and reload?" : "Save how subagents run?",
-		[
-			`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 "Background plus compatibility methods (async + sync)";
-		case "async-only":
-			return "Keep Pi available (async)";
-		case "blocking-only":
-			return "Compatibility blocking methods (sync)";
-		case "disabled":
-			return "Subagents 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 awaitEnabled = (value: DelegationWorkflow) => blockingEnabled(value) && asyncEnabled(value);
-	const effects: string[] = [];
-	if (blockingEnabled(current) !== blockingEnabled(next)) {
-		effects.push(
-			blockingEnabled(next)
-				? "Allow deprecated blocking `subagent` and supported read-only `subagent_consult`"
-				: "Remove deprecated blocking `subagent` and supported read-only `subagent_consult`",
-		);
-	}
-	if (asyncEnabled(current) !== asyncEnabled(next)) {
-		effects.push(
-			asyncEnabled(next)
-				? "Allow background tools: `subagent_spawn`, `subagent_send`, `subagent_manage`, and `subagent_mailbox`"
-				: "Remove background tools: `subagent_spawn`, `subagent_send`, `subagent_manage`, and `subagent_mailbox`",
-		);
-	}
-	if (awaitEnabled(current) !== awaitEnabled(next)) {
-		effects.push(
-			awaitEnabled(next)
-				? "Allow the blocking retained-agent join: `subagent_await`"
-				: "Remove the blocking retained-agent join: `subagent_await`",
-		);
-	}
-	return effects;
-}