pi-subagents 0.69.0 → 0.70.1

package/src/runs/shared/model-scope.ts

@@ -1,205 +0,0 @@
-/**
- * Optional model-scope enforcement for subagent model resolution.
- *
- * When `subagents.modelScope.enforce` is enabled in settings, a resolved model
- * that does not match any `allow` pattern is rejected. The severity depends on
- * where the model came from: an explicit caller-supplied model (`--model`,
- * tool-call `model`, or a TUI clarify pick) is a hard error, while a model
- * inherited from agent frontmatter / `defaultModel` / the parent session only
- * emits a warning so existing configurations keep working. Optional strict
- * enforcement makes inherited models hard errors too.
- *
- * The decision logic ({@link checkModelScope}) is a pure function of its
- * inputs so it can be unit-tested without touching the filesystem or config.
- */
-
-import { splitKnownThinkingSuffix } from "../../shared/model-info.ts";
-
-export interface ModelScopeRule {
-	enforce?: boolean;
-	/** Reject inherited models outside the allowlist instead of warning. */
-	strict?: boolean;
-	/** Glob-style allow patterns (only `*` is special), matched against `provider/id`. */
-	allow?: string[];
-}
-
-export interface ModelScopeConfig extends ModelScopeRule {
-	/** Additional restrictions keyed by canonical agent name. */
-	agents?: Record<string, ModelScopeRule>;
-}
-
-export interface ModelScopeCheckRule extends ModelScopeRule {
-	origin?: string;
-}
-
-export interface ResolvedModelScope extends ModelScopeCheckRule {
-	origin: string;
-}
-
-/** Where a resolved model originated, deciding enforcement severity. */
-export type ModelSource = "explicit" | "inherited";
-
-export interface ModelScopeViolation {
-	/** Resolved model id (without thinking suffix) that fell outside the scope. */
-	model: string;
-	severity: "warn" | "error";
-	message: string;
-	allowedPatterns: string[];
-	origin: string;
-}
-
-function stripThinkingSuffix(model: string): string {
-	return splitKnownThinkingSuffix(model).baseModel;
-}
-
-/** Escape RegExp specials except `*`, then turn `*` into `.*`. */
-function globToRegExp(pattern: string): RegExp {
-	const escaped = pattern.replace(/[.+^${}()|[\]\\]/g, "\\$&").replace(/\*/g, ".*");
-	return new RegExp(`^${escaped}$`, "i");
-}
-
-/**
- * Test whether a resolved model matches a single allow pattern. Both sides are
- * compared case-insensitively against the full `provider/id` (thinking suffix
- * stripped from the model).
- */
-export function matchesScopePattern(model: string, pattern: string): boolean {
-	return globToRegExp(pattern).test(stripThinkingSuffix(model));
-}
-
-/**
- * Pure scope decision. Returns a {@link ModelScopeViolation} when the model is
- * out of scope and enforcement is on, otherwise `undefined`. Enforcement with
- * no `allow` list is a no-op (the settings parser rejects that combination, but
- * this stays defensive for callers that build configs programmatically).
- */
-export function checkModelScope(
-	model: string | undefined,
-	scope: ModelScopeCheckRule | undefined,
-	source: ModelSource,
-): ModelScopeViolation | undefined {
-	if (!model || !scope?.enforce) return undefined;
-	const allow = scope.allow;
-	if (!allow || allow.length === 0) return undefined;
-	if (allow.some((pattern) => matchesScopePattern(model, pattern))) return undefined;
-
-	const baseModel = stripThinkingSuffix(model);
-	const severity: ModelScopeViolation["severity"] = source === "explicit" || scope.strict === true ? "error" : "warn";
-	const origin = scope.origin ?? "modelScope";
-	return {
-		model: baseModel,
-		severity,
-		allowedPatterns: allow,
-		origin,
-		message:
-			`Model '${baseModel}' is outside the configured subagent model scope (${origin}). ` +
-			`Allowed patterns: ${allow.join(", ")}.`,
-	};
-}
-
-function expandInheritPattern(pattern: string, parentModel: { provider: string; id: string } | undefined): string {
-	return pattern === "inherit" && parentModel ? `${parentModel.provider}/${parentModel.id}` : pattern;
-}
-
-function assertRecord(value: unknown, field: string, meta: { filePath: string }, expected = "an object"): Record<string, unknown> {
-	if (!value || typeof value !== "object" || Array.isArray(value)) {
-		throw new Error(`Subagent settings in '${meta.filePath}' have invalid '${field}'; expected ${expected}.`);
-	}
-	return value as Record<string, unknown>;
-}
-
-function parseAllowList(value: unknown, field: string, meta: { filePath: string }): string[] {
-	if (!Array.isArray(value)) {
-		throw new Error(`Subagent settings in '${meta.filePath}' have invalid '${field}'; expected an array of strings.`);
-	}
-	const allow: string[] = [];
-	for (const entry of value) {
-		if (typeof entry !== "string") {
-			throw new Error(`Subagent settings in '${meta.filePath}' have invalid '${field}'; expected an array of strings.`);
-		}
-		const trimmed = entry.trim();
-		if (trimmed) allow.push(trimmed);
-	}
-	if (allow.length === 0) {
-		throw new Error(`Subagent settings in '${meta.filePath}' have invalid '${field}'; expected a non-empty array of patterns.`);
-	}
-	return allow;
-}
-
-function parseScopeRule(input: Record<string, unknown>, field: string, meta: { filePath: string }): ModelScopeRule {
-	const rule: ModelScopeRule = {};
-	if ("enforce" in input) {
-		if (typeof input.enforce !== "boolean") throw new Error(`Subagent settings in '${meta.filePath}' have invalid '${field}.enforce'; expected a boolean.`);
-		rule.enforce = input.enforce;
-	}
-	if ("strict" in input) {
-		if (typeof input.strict !== "boolean") throw new Error(`Subagent settings in '${meta.filePath}' have invalid '${field}.strict'; expected a boolean.`);
-		rule.strict = input.strict;
-	}
-	if ("allow" in input) rule.allow = parseAllowList(input.allow, `${field}.allow`, meta);
-	return rule;
-}
-
-/** Resolve the global and matching agent policies into independent launch-time checks. */
-export function resolveModelScopesForAgent(
-	config: ModelScopeConfig | undefined,
-	agentName: string,
-	parentModel: { provider: string; id: string } | undefined,
-): ResolvedModelScope[] {
-	if (!config) return [];
-	const scopes: ResolvedModelScope[] = [];
-	if (config.allow) {
-		scopes.push({
-			...(config.enforce !== undefined ? { enforce: config.enforce } : {}),
-			...(config.strict !== undefined ? { strict: config.strict } : {}),
-			allow: config.allow.map((pattern) => expandInheritPattern(pattern, parentModel)),
-			origin: "modelScope",
-		});
-	}
-	const agentScope = config.agents?.[agentName];
-	if (agentScope?.allow) {
-		scopes.push({
-			enforce: agentScope.enforce ?? config.enforce,
-			strict: agentScope.strict ?? config.strict,
-			allow: agentScope.allow.map((pattern) => expandInheritPattern(pattern, parentModel)),
-			origin: `modelScope.agents.${agentName}`,
-		});
-	}
-	return scopes;
-}
-
-/**
- * Validate and normalize a raw `subagents.modelScope` value from settings.
- * Throws a descriptive error for malformed configs (matching the surrounding
- * settings-parsing style). Returns `undefined` when the field is absent.
- */
-export function parseModelScopeConfig(
-	value: unknown,
-	meta: { filePath: string },
-): ModelScopeConfig | undefined {
-	if (value === undefined) return undefined;
-	const input = assertRecord(value, "modelScope", meta);
-	const config: ModelScopeConfig = parseScopeRule(input, "modelScope", meta);
-
-	if ("agents" in input) {
-		const agents: Record<string, ModelScopeRule> = {};
-		for (const [rawName, rawScope] of Object.entries(assertRecord(input.agents, "modelScope.agents", meta, "an object keyed by agent name"))) {
-			const name = rawName.trim();
-			const field = `modelScope.agents.${name}`;
-			if (!name) throw new Error(`Subagent settings in '${meta.filePath}' have invalid 'modelScope.agents' key; expected a non-empty agent name.`);
-			const agentInput = assertRecord(rawScope, field, meta);
-			if ("agents" in agentInput) {
-				throw new Error(`Subagent settings in '${meta.filePath}' have invalid '${field}.agents'; nested agent scopes are not supported.`);
-			}
-			agents[name] = parseScopeRule(agentInput, field, meta);
-		}
-		config.agents = agents;
-	}
-
-	const hasAnyAllow = Boolean(config.allow?.length) || Object.values(config.agents ?? {}).some((scope) => Boolean(scope.allow?.length));
-	if (config.enforce === true && !hasAnyAllow) {
-		throw new Error(`Subagent settings in '${meta.filePath}' set modelScope.enforce without a non-empty 'allow' list; supply allowed model patterns or disable enforcement.`);
-	}
-
-	return Object.keys(config).length > 0 ? config : undefined;
-}

package/src/runs/shared/mutation-evidence.ts

@@ -1,199 +0,0 @@
-import { execFileSync } from "node:child_process";
-import { createHash } from "node:crypto";
-import * as fs from "node:fs";
-import * as os from "node:os";
-import * as path from "node:path";
-import type { ArtifactPaths, TimeoutRecoveryProjection, TimeoutRecoverySummary, TrackedMutationEvidence, TrackedMutationFingerprint, TrackedMutationSnapshot } from "../../shared/types.ts";
-
-const MAX_TRACKED_PATHS = 500;
-const MAX_HASH_BYTES = 1024 * 1024;
-const MAX_TIMEOUT_FILES = 20;
-
-function gitArguments(args: string[]): string[] {
-	// Mutation evidence must not block child startup on a stale fsmonitor daemon.
-	return ["-c", "core.fsmonitor=false", ...args];
-}
-
-function gitOutput(cwd: string, args: string[], maxBuffer = MAX_HASH_BYTES): string {
-	return execFileSync("git", gitArguments(args), { cwd, encoding: "utf-8", stdio: ["ignore", "pipe", "pipe"], maxBuffer, windowsHide: true });
-}
-
-function splitNul(output: string): string[] {
-	return output.split("\0").filter((part) => part.length > 0);
-}
-
-function hashLargeDiff(cwd: string, relativePath: string): string {
-	const tempDir = fs.mkdtempSync(path.join(os.tmpdir(), "pi-subagents-tracked-diff-"));
-	const diffPath = path.join(tempDir, "diff.patch");
-	try {
-		execFileSync("git", gitArguments(["diff", "--no-ext-diff", "--binary", `--output=${diffPath}`, "HEAD", "--", relativePath]), { cwd, stdio: "ignore", windowsHide: true });
-		const hash = createHash("sha256");
-		const buffer = Buffer.allocUnsafe(64 * 1024);
-		const fd = fs.openSync(diffPath, "r");
-		try {
-			for (;;) {
-				const bytesRead = fs.readSync(fd, buffer, 0, buffer.length, null);
-				if (bytesRead === 0) break;
-				hash.update(buffer.subarray(0, bytesRead));
-			}
-		} finally {
-			fs.closeSync(fd);
-		}
-		return hash.digest("hex");
-	} finally {
-		fs.rmSync(tempDir, { recursive: true, force: true });
-	}
-}
-
-function listChangedTrackedFiles(cwd: string): { paths: string[]; truncated: boolean } {
-	const paths = splitNul(gitOutput(cwd, ["diff", "--no-ext-diff", "--name-only", "-z", "HEAD", "--"], MAX_HASH_BYTES));
-	return { paths: paths.slice(0, MAX_TRACKED_PATHS), truncated: paths.length > MAX_TRACKED_PATHS };
-}
-
-function fingerprintPath(cwd: string, relativePath: string): TrackedMutationFingerprint {
-	try {
-		const diff = gitOutput(cwd, ["diff", "--no-ext-diff", "--binary", "HEAD", "--", relativePath], MAX_HASH_BYTES);
-		return { kind: "diff", digest: createHash("sha256").update(diff).digest("hex") };
-	} catch {
-		return { kind: "diff", digest: hashLargeDiff(cwd, relativePath) };
-	}
-}
-
-function sameFingerprint(left: TrackedMutationFingerprint | undefined, right: TrackedMutationFingerprint): boolean {
-	if (!left || left.kind !== "diff" || right.kind !== "diff") return false;
-	return left.digest === right.digest;
-}
-
-export function snapshotTrackedMutations(cwd: string): TrackedMutationSnapshot {
-	try {
-		const changed = listChangedTrackedFiles(cwd);
-		const fingerprints: Record<string, TrackedMutationFingerprint> = {};
-		for (const file of changed.paths) fingerprints[file] = fingerprintPath(cwd, file);
-		return { source: "tracked-files", trackedOnly: true, cwd, dirtyFiles: changed.paths, fingerprints, truncated: changed.truncated };
-	} catch (error) {
-		return { source: "tracked-files", trackedOnly: true, cwd, dirtyFiles: [], fingerprints: {}, unavailable: error instanceof Error ? error.message : String(error) };
-	}
-}
-
-export function collectTrackedMutationEvidence(snapshot: TrackedMutationSnapshot, cwd = snapshot.cwd): TrackedMutationEvidence {
-	if (snapshot.unavailable) {
-		return { source: "tracked-files", trackedOnly: true, changedFiles: [], attemptedMutation: false, unavailable: snapshot.unavailable };
-	}
-	try {
-		const current = listChangedTrackedFiles(cwd);
-		const startDirty = new Set(snapshot.dirtyFiles);
-		const candidates = new Set([...snapshot.dirtyFiles, ...current.paths]);
-		const changedFiles: string[] = [];
-		for (const file of candidates) {
-			if (!startDirty.has(file)) {
-				if (!snapshot.truncated) changedFiles.push(file);
-				continue;
-			}
-			if (!sameFingerprint(snapshot.fingerprints[file], fingerprintPath(cwd, file))) changedFiles.push(file);
-		}
-		changedFiles.sort();
-		return {
-			source: "tracked-files",
-			trackedOnly: true,
-			changedFiles,
-			attemptedMutation: changedFiles.length > 0,
-			truncated: snapshot.truncated || current.truncated || undefined,
-		};
-	} catch (error) {
-		return { source: "tracked-files", trackedOnly: true, changedFiles: [], attemptedMutation: false, unavailable: error instanceof Error ? error.message : String(error) };
-	}
-}
-
-function formatPathList(paths: string[]): string {
-	if (paths.length === 0) return "none";
-	const shown = paths.slice(0, MAX_TIMEOUT_FILES).join(", ");
-	return paths.length > MAX_TIMEOUT_FILES ? `${shown}, ... (${paths.length - MAX_TIMEOUT_FILES} more)` : shown;
-}
-
-/** Keep status and completion details to bounded routing evidence, not raw output or effects. */
-export function projectTimeoutRecovery(value: unknown): TimeoutRecoveryProjection | undefined {
-	if (!value || typeof value !== "object" || Array.isArray(value)) return undefined;
-	const source = value as Record<string, unknown>;
-	const termination = source.termination === "timed-out" || source.termination === "stopped" ? source.termination : undefined;
-	if (!termination || !Array.isArray(source.changedFiles)) return undefined;
-	const allChangedFiles = source.changedFiles.filter((file): file is string => typeof file === "string");
-	const changedFiles = allChangedFiles.slice(0, MAX_TIMEOUT_FILES);
-	const reportStatus = source.reportStatus === "missing"
-		|| source.reportStatus === "written"
-		|| source.reportStatus === "not-requested"
-		|| source.reportStatus === "unknown"
-		? source.reportStatus
-		: undefined;
-	return {
-		termination,
-		changedFiles,
-		...(source.truncated === true || allChangedFiles.length > changedFiles.length ? { truncated: true } : {}),
-		...(source.recoveryNeeded === true ? { recoveryNeeded: true } : {}),
-		...(source.reason === "timed-out-with-dirty-worktree" ? { reason: source.reason } : {}),
-		...(reportStatus ? { reportStatus } : {}),
-	};
-}
-
-/** Render only the bounded recovery route needed by a parent/operator. */
-export function formatTimeoutRecoveryLines(value: unknown, indent = ""): string[] {
-	const recovery = projectTimeoutRecovery(value);
-	if (!recovery?.recoveryNeeded) return [];
-	const changedFiles = recovery.changedFiles.length > 0
-		? `${recovery.changedFiles.join(", ")}${recovery.truncated ? ", …" : ""}`
-		: "none";
-	const changedFileCount = recovery.changedFiles.length > 0 ? `${recovery.changedFiles.length}${recovery.truncated ? "+" : ""}` : "0";
-	return [
-		`${indent}Recovery needed: review the diff and artifacts before resuming or launching dependent stages.`,
-		`${indent}Recovery evidence: requested report: ${recovery.reportStatus ?? "unknown"}; changed tracked files: ${changedFiles} (${changedFileCount}); classification: ${recovery.reason ?? recovery.termination}`,
-	];
-}
-
-export function buildTimeoutRecoverySummary(input: {
-	termination: "timed-out" | "stopped";
-	evidence: TrackedMutationEvidence;
-	requiredOutputMissing?: boolean;
-	currentTool?: string;
-	currentToolArgs?: string;
-	currentPath?: string;
-	sessionFile?: string;
-	transcriptPath?: string;
-	artifactPaths?: ArtifactPaths;
-}): TimeoutRecoverySummary {
-	const warning = "Inspect partial changes before retrying or resuming the child.";
-	const changedFiles = input.evidence.changedFiles.slice(0, MAX_TIMEOUT_FILES);
-	let reportStatus: "missing" | "written" | "not-requested" = "not-requested";
-	if (input.requiredOutputMissing === true) reportStatus = "missing";
-	else if (input.requiredOutputMissing === false) reportStatus = "written";
-	const recoveryNeeded = input.termination === "timed-out"
-		&& reportStatus === "missing"
-		&& input.evidence.changedFiles.length > 0;
-	const lines = [
-		"Recovery summary:",
-		`- termination: ${input.termination}`,
-		`- changed tracked files: ${input.evidence.unavailable ? `unavailable (${input.evidence.unavailable})` : formatPathList(input.evidence.changedFiles)}`,
-	];
-	if (input.requiredOutputMissing !== undefined) lines.push(`- requested report: ${reportStatus}`);
-	if (recoveryNeeded) lines.push("- Recovery needed: review the diff and artifacts before resuming or launching dependent stages.");
-	if (input.currentTool) lines.push(`- active tool: ${input.currentTool}${input.currentToolArgs ? ` — ${input.currentToolArgs}` : ""}`);
-	if (input.currentPath) lines.push(`- active path: ${input.currentPath}`);
-	if (input.sessionFile) lines.push(`- session file: ${input.sessionFile}`);
-	if (input.transcriptPath) lines.push(`- transcript: ${input.transcriptPath}`);
-	if (input.artifactPaths?.outputPath) lines.push(`- output artifact: ${input.artifactPaths.outputPath}`);
-	if (input.artifactPaths?.metadataPath) lines.push(`- metadata artifact: ${input.artifactPaths.metadataPath}`);
-	lines.push(`Warning: ${warning}`);
-	return {
-		termination: input.termination,
-		changedFiles,
-		truncated: input.evidence.changedFiles.length > changedFiles.length || input.evidence.truncated || undefined,
-		...(recoveryNeeded ? { recoveryNeeded: true, reason: "timed-out-with-dirty-worktree" as const } : {}),
-		reportStatus,
-		currentTool: input.currentTool,
-		currentToolArgs: input.currentToolArgs,
-		currentPath: input.currentPath,
-		sessionFile: input.sessionFile,
-		transcriptPath: input.transcriptPath,
-		artifactPaths: input.artifactPaths,
-		warning,
-		message: lines.join("\n"),
-	};
-}