@fitchmultz/pi-subagents 0.0.0-stage → 0.44.5

package/src/runs/shared/mutating-tool-guard.ts

@@ -0,0 +1,194 @@
+interface FailedMutatingAttempt {
+	tool: string;
+	path?: string;
+	error: string;
+	ts: number;
+}
+
+interface MutatingFailureState {
+	consecutiveFailures: number;
+	lastFailureAt?: number;
+	recentFailures: FailedMutatingAttempt[];
+	lastMutatingPath?: string;
+	repeatedPathFailures: number;
+}
+
+const MUTATING_BASH_PATTERNS = [
+	/(^|[;&|()\s])rm\s+/,
+	/(^|[;&|()\s])mv\s+/,
+	/(^|[;&|()\s])cp\s+/,
+	/(^|[;&|()\s])mkdir\s+/,
+	/(^|[;&|()\s])touch\s+/,
+	/(^|[;&|()\s])git\s+apply\b/,
+	/(^|[;&|()\s])patch\s+/,
+	/(^|[;&|()\s])sed\s+[^\n;&|]*\s-i\b/,
+	/(^|[;&|()\s])perl\s+[^\n;&|]*\s-pi\b/,
+	/(^|[;&|()]|\n)\s*tee\s+[^|&;]+/,
+	/\b(writeFile|writeFileSync|appendFile|appendFileSync)\b/,
+	/\bwrite_text\s*\(/,
+	/\bopen\s*\([^)]*,\s*["'][wa]/,
+];
+
+export function resolveCurrentPath(toolName: string | undefined, args: Record<string, unknown> | undefined): string | undefined {
+	if (!toolName || !args) return undefined;
+	const direct = ["path", "file", "filename", "target", "cwd"];
+	for (const key of direct) {
+		const value = args[key];
+		if (typeof value === "string" && value.trim()) return value.trim();
+	}
+	if (toolName === "bash") {
+		const command = typeof args.command === "string" ? args.command : undefined;
+		if (!command) return undefined;
+		const redirect = command.match(/(?:>>?|tee\s+)\s*([^&>\s][^\s;&|]*)/);
+		if (redirect?.[1]) return redirect[1];
+	}
+	return undefined;
+}
+
+function hasUnquotedFileRedirection(command: string): boolean {
+	let inSingle = false;
+	let inDouble = false;
+	for (let i = 0; i < command.length; i++) {
+		const char = command[i]!;
+		if (char === "'" && !inDouble) {
+			inSingle = !inSingle;
+			continue;
+		}
+		if (char === '"' && !inSingle) {
+			inDouble = !inDouble;
+			continue;
+		}
+		if (inSingle || inDouble) continue;
+		if (char !== ">") continue;
+		if (command[i - 1] === "-") continue;
+		const isDouble = command[i + 1] === ">";
+		let cursor = i + (isDouble ? 2 : 1);
+		while (cursor < command.length && /\s/.test(command[cursor]!)) cursor++;
+		if (cursor >= command.length) continue;
+		const targetStart = command[cursor]!;
+		if (targetStart === "&" || targetStart === "|" || targetStart === ";") continue;
+		if (targetStart === "(" || targetStart === ")") continue;
+		return true;
+	}
+	return false;
+}
+
+export function isMutatingBashCommand(command: string): boolean {
+	return hasUnquotedFileRedirection(command) || MUTATING_BASH_PATTERNS.some((pattern) => pattern.test(command));
+}
+
+export function isMutatingTool(toolName: string | undefined, args: Record<string, unknown> | undefined): boolean {
+	if (!toolName || args?.preview === true) return false;
+	if (["edit", "write", "apply_edits", "apply_patch", "replace_text", "write_files"].includes(toolName)) return true;
+	if (toolName !== "bash") return false;
+	const command = typeof args?.command === "string" ? args.command : "";
+	if (!command.trim()) return false;
+	return isMutatingBashCommand(command);
+}
+
+export interface PendingMutationTool {
+	id?: string;
+	tool: string;
+	path?: string;
+	mutates: boolean;
+	startedAt?: number;
+}
+
+export interface MutationToolResult extends PendingMutationTool {
+	completedMutation: boolean;
+	errored: boolean;
+}
+
+export function createMutationCompletionTracker(): {
+	recordToolStart(input: { id?: string; toolName?: string; args?: Record<string, unknown>; path?: string; mutates?: boolean; startedAt?: number }): PendingMutationTool;
+	recordToolResult(input?: { toolCallId?: unknown; toolName?: unknown; isError?: unknown; details?: unknown }): MutationToolResult | undefined;
+} {
+	const pending: PendingMutationTool[] = [];
+	const take = (input?: { toolCallId?: unknown; toolName?: unknown }): PendingMutationTool | undefined => {
+		const id = typeof input?.toolCallId === "string" ? input.toolCallId : undefined;
+		if (id) {
+			const index = pending.findIndex((tool) => tool.id === id);
+			if (index >= 0) return pending.splice(index, 1)[0];
+		}
+		const name = typeof input?.toolName === "string" ? input.toolName : undefined;
+		if (name) {
+			const index = pending.findIndex((tool) => tool.tool === name);
+			if (index >= 0) return pending.splice(index, 1)[0];
+		}
+		return pending.shift();
+	};
+	return {
+		recordToolStart(input) {
+			const tool = input.toolName ?? "tool";
+			const entry = {
+				id: input.id,
+				tool,
+				path: input.path,
+				mutates: input.mutates ?? isMutatingTool(input.toolName, input.args),
+				startedAt: input.startedAt,
+			};
+			pending.push(entry);
+			return entry;
+		},
+		recordToolResult(input) {
+			const entry = take(input);
+			if (!entry) return undefined;
+			const errored = input?.isError === true;
+			const details = input?.details && typeof input.details === "object" ? input.details as { preview?: unknown; modifiedFiles?: unknown } : undefined;
+			const committed = Array.isArray(details?.modifiedFiles)
+				? details.modifiedFiles.some((file) => typeof file === "string" && file.trim().length > 0)
+				: !errored && !["apply_patch", "replace_text", "write_files"].includes(entry.tool);
+			return { ...entry, errored, completedMutation: entry.mutates && details?.preview !== true && committed };
+		},
+	};
+}
+
+export function resetMutatingFailureState(state: MutatingFailureState): void {
+	state.consecutiveFailures = 0;
+	state.lastFailureAt = undefined;
+	state.recentFailures = [];
+	state.lastMutatingPath = undefined;
+	state.repeatedPathFailures = 0;
+}
+
+export function createMutatingFailureState(): MutatingFailureState {
+	return {
+		consecutiveFailures: 0,
+		recentFailures: [],
+		repeatedPathFailures: 0,
+	};
+}
+
+export function recordMutatingFailure(
+	state: MutatingFailureState,
+	input: FailedMutatingAttempt,
+	windowMs: number,
+): void {
+	if (state.lastFailureAt === undefined || input.ts - state.lastFailureAt > windowMs) {
+		state.consecutiveFailures = 0;
+		state.recentFailures = [];
+		state.repeatedPathFailures = 0;
+		state.lastMutatingPath = undefined;
+	}
+	state.lastFailureAt = input.ts;
+	state.consecutiveFailures += 1;
+	if (input.path && state.lastMutatingPath === input.path) {
+		state.repeatedPathFailures += 1;
+	} else if (input.path) {
+		state.lastMutatingPath = input.path;
+		state.repeatedPathFailures = 1;
+	}
+	state.recentFailures.push(input);
+	if (state.recentFailures.length > 3) state.recentFailures.shift();
+}
+
+export function shouldEscalateMutatingFailures(state: MutatingFailureState, threshold: number): boolean {
+	return state.consecutiveFailures >= threshold || state.repeatedPathFailures >= threshold;
+}
+
+export function summarizeRecentMutatingFailures(state: MutatingFailureState): string | undefined {
+	if (state.recentFailures.length === 0) return undefined;
+	return state.recentFailures
+		.map((entry) => `${entry.tool}${entry.path ? `(${entry.path})` : ""}: ${entry.error}`)
+		.join(" | ");
+}

package/src/runs/shared/native-finalization.ts

@@ -0,0 +1,128 @@
+import { randomUUID } from "node:crypto";
+import * as fs from "node:fs";
+import * as path from "node:path";
+import { fileURLToPath } from "node:url";
+import type { Message } from "@earendil-works/pi-ai";
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import { Type } from "../../shared/native-typebox.ts";
+import type { AcceptanceLedger, ResolvedAcceptanceConfig } from "../../shared/types.ts";
+import { setPromptSection } from "../../shared/prompt-sections.ts";
+import { detectSubagentError, getFinalOutput } from "../../shared/utils.ts";
+import {
+	acceptanceFailureMessage, acceptanceSelfReviewConfig, createFinalizationReportRuntime,
+	evaluateAcceptance, formatAcceptanceFinalizationPrompt, readFinalizationReport,
+	resolveFinalizationOutput, stripAcceptanceReport,
+} from "./acceptance.ts";
+import { captureSingleOutputSnapshot, resolveSingleOutput, type SingleOutputSnapshot } from "./single-output.ts";
+import { readStructuredOutput, validateStructuredOutputValue, type StructuredOutputRuntime } from "./structured-output.ts";
+import { compactObservedMessage } from "./child-observations.ts";
+
+const CONFIG_ENV = "PI_SUBAGENT_FINALIZATION_CONFIG";
+export const FINALIZATION_EVENT = "subagent.finalization";
+
+export interface NativeFinalizationConfig {
+	nonce: string;
+	acceptance: ResolvedAcceptanceConfig;
+	reportRuntime: ReturnType<typeof createFinalizationReportRuntime>;
+	publicOutput?: StructuredOutputRuntime;
+	outputPath?: string;
+	outputSnapshot?: SingleOutputSnapshot;
+}
+
+export interface NativeFinalizationEvent {
+	type: typeof FINALIZATION_EVENT;
+	nonce: string;
+	turn: number;
+	lastEntryId?: string;
+	messageCount: number;
+	at: number;
+	submission: ReturnType<typeof readFinalizationReport> & { error?: string };
+	acceptance?: AcceptanceLedger;
+	resolvedOutput: ReturnType<typeof resolveSingleOutput>;
+	nextPrompt?: string;
+}
+
+export function createNativeFinalization(acceptance: ResolvedAcceptanceConfig, publicOutput?: StructuredOutputRuntime, outputPath?: string): NativeFinalizationConfig {
+	return { nonce: randomUUID(), acceptance, reportRuntime: createFinalizationReportRuntime(publicOutput?.schema), publicOutput,
+		outputPath, outputSnapshot: captureSingleOutputSnapshot(outputPath) };
+}
+
+export function nativeFinalizationLaunch(config: NativeFinalizationConfig): { extension: string; env: Record<string, string> } {
+	const configPath = path.join(path.dirname(config.reportRuntime.schemaPath), "finalization.json");
+	fs.writeFileSync(configPath, JSON.stringify(config), { mode: 0o600 });
+	return { extension: fileURLToPath(new URL(`native-finalization${import.meta.url.endsWith(".ts") ? ".ts" : ".js"}`, import.meta.url)), env: { [CONFIG_ENV]: configPath } };
+}
+
+/** Self-review includes structural and workspace checks; configured verification stays owner-run. */
+export default function registerNativeFinalization(pi: ExtensionAPI): void {
+	const configPath = process.env[CONFIG_ENV];
+	if (!configPath) return;
+	const config = JSON.parse(fs.readFileSync(configPath, "utf8")) as NativeFinalizationConfig;
+	const { acceptance, reportRuntime } = config;
+	const selfReview = acceptanceSelfReviewConfig(acceptance);
+	const messages: Message[] = [];
+	let messageOffset = 0;
+	let turn = 0;
+	let initialOutput = "";
+	let latestOutput = "";
+	let initialLedger: AcceptanceLedger | undefined;
+	let resolvedOutput: ReturnType<typeof resolveSingleOutput> = { fullOutput: "" };
+	const registerOutput = (runtime: StructuredOutputRuntime) => pi.registerTool({
+		name: "structured_output", label: "Structured Output", description: "Submit the complete output matching the current schema.",
+		parameters: Type.Object({ value: Type.Unsafe(runtime.schema) }, { additionalProperties: false }),
+		constrainedSampling: { type: "json_schema", strict: "prefer" },
+		execute: async (_id, args: { value: unknown }) => {
+			const validation = validateStructuredOutputValue(runtime.schema, args.value);
+			if (validation.status === "invalid") throw new Error(validation.message);
+			fs.writeFileSync(runtime.outputPath, JSON.stringify(args.value), { mode: 0o600 });
+			return { content: [{ type: "text", text: "Structured output captured." }], details: {}, terminate: true };
+		},
+	});
+	if (config.publicOutput) {
+		registerOutput(config.publicOutput);
+		pi.on("before_agent_start", (event) => setPromptSection(event.systemPromptOptions, "subagent_output",
+			"Your final action must call structured_output with JSON matching the current schema. Prose alone does not complete this output contract."));
+	}
+	pi.on("message_end", (event) => {
+		if (["assistant", "user", "toolResult"].includes(event.message.role)) {
+			latestOutput = getFinalOutput([event.message as Message]) || latestOutput;
+			messages.push(compactObservedMessage(event.message as Message));
+		}
+	});
+	pi.on("agent_before_settle", async (event, ctx) => {
+		if (event.outcome !== "completed") return;
+		const submission: NativeFinalizationEvent["submission"] = turn === 0
+			? { output: latestOutput }
+			: readFinalizationReport(messages, reportRuntime, { messageOffset });
+		if (turn === 0) {
+			initialOutput = submission.output;
+			const hiddenError = detectSubagentError(messages);
+			if (hiddenError.hasError) submission.error = hiddenError.details ?? `${hiddenError.errorType} failed`;
+			if (config.publicOutput) submission.error ??= readStructuredOutput(config.publicOutput).error;
+		}
+		const ledger = await evaluateAcceptance({ acceptance: selfReview, governing: acceptance, cwd: ctx.cwd,
+			output: submission.reportSubmissionError ? "" : submission.output, report: submission.reportSubmissionError ? undefined : submission.report });
+		initialLedger ??= ledger;
+		if (!submission.error && !submission.reportSubmissionError) {
+			const output = turn === 0 ? stripAcceptanceReport(submission.output) : resolveFinalizationOutput(submission.output, resolvedOutput.fullOutput);
+			resolvedOutput = resolveSingleOutput(config.outputPath, output, turn === 0 ? config.outputSnapshot : resolvedOutput.writtenSnapshot);
+			if (resolvedOutput.saveError) submission.error = `Failed to save output file '${config.outputPath}': ${resolvedOutput.saveError}`;
+		}
+		const continueReview = !submission.error && ledger.status !== "blocked" && turn < acceptance.finalization.maxTurns
+			&& (turn === 0 || Boolean(submission.reportSubmissionError) || ledger.status === "rejected");
+		const nextPrompt = continueReview ? formatAcceptanceFinalizationPrompt({ acceptance, initialOutput, initialLedger,
+			turn: turn + 1, maxTurns: acceptance.finalization.maxTurns,
+			previousFailure: submission.reportSubmissionError ?? acceptanceFailureMessage(ledger), nativeReport: true, outputSchema: config.publicOutput?.schema }) : undefined;
+		const marker: NativeFinalizationEvent = { type: FINALIZATION_EVENT, nonce: config.nonce, turn, lastEntryId: ctx.sessionManager.getLeafId() ?? undefined, messageCount: messages.length, at: Date.now(), submission, acceptance: ledger, resolvedOutput, nextPrompt };
+		fs.appendFileSync(path.join(path.dirname(reportRuntime.schemaPath), "boundaries.jsonl"), `${JSON.stringify(marker)}\n`, { mode: 0o600 });
+		if (!nextPrompt) return;
+		if (turn === 0) {
+			// Native registration refreshes the active schema after the public payload is captured.
+			registerOutput(reportRuntime);
+			pi.setActiveTools([...new Set([...pi.getActiveTools(), "structured_output"])]);
+		}
+		turn++;
+		messageOffset = messages.length;
+		return { entries: [...event.entries, { type: "custom_message", customType: "subagent-self-review", content: nextPrompt, display: false }], continue: true };
+	});
+}

package/src/runs/shared/native-usage.ts

@@ -0,0 +1,113 @@
+import type { Usage as NativeUsage } from "@earendil-works/pi-ai";
+import { isDeepStrictEqual } from "node:util";
+import type { Usage, UsageContribution } from "../../shared/types.ts";
+import { scanJournal, nativeProjection } from "../../shared/journal-reader.ts";
+
+export function snapshotNativeBaseline(file: string | undefined): { ids: Set<string>; entryCount: number; legacy: boolean; sessionId?: string } {
+	const ids = new Set<string>();
+	let first = true, native = false, entryCount = 0, legacy = false, sessionId: string | undefined;
+	if (file) try { scanJournal(file, (path) => !path.length || path.length === 1 && ["id", "type", "version"].includes(String(path[0])), ({ value }) => {
+		if (first) {
+			first = false; native = value?.type === "session";
+			if (native) {
+				if (typeof value.id !== "string" || !value.id) throw new SyntaxError("Invalid native session identity");
+				sessionId = value.id; legacy = value.version === 1;
+			}
+		} else if (native) entryCount++;
+		if (native && typeof value?.id === "string") ids.add(value.id);
+	}, { requireNewline: true }); }
+	catch (error) { if ((error as NodeJS.ErrnoException).code !== "ENOENT") throw error; }
+	return { ids, entryCount, legacy, sessionId };
+}
+
+export function snapshotNativeUsage(file: string | undefined): Set<string> { return snapshotNativeBaseline(file).ids; }
+
+export function addUsage(usage: Usage, value: NativeUsage, attribution?: Omit<UsageContribution, "usage">): void {
+	for (const key of ["input", "output", "cacheRead", "cacheWrite", "totalTokens", "reasoning", "cacheWrite1h"] as const) {
+		if (value[key] !== undefined && typeof value[key] !== "number") throw new Error(`Invalid native usage counter: ${key}`);
+	}
+	for (const [key, counter] of Object.entries(value)) {
+		if (typeof counter === "number" && (!Number.isFinite(counter) || counter < 0)) throw new Error(`Invalid native usage counter: ${key}`);
+	}
+	if (value.cost) for (const counter of Object.values(value.cost)) if (!Number.isFinite(counter) || counter < 0) throw new Error("Invalid native usage cost");
+	usage.input += value.input ?? 0;
+	usage.output += value.output ?? 0;
+	usage.cacheRead += value.cacheRead ?? 0;
+	usage.cacheWrite += value.cacheWrite ?? 0;
+	usage.cost += value.cost?.total ?? 0;
+	if (attribution) (usage.contributions ??= []).push({ ...attribution, usage: value });
+}
+
+export function validateNativeUsage(value: NativeUsage): void {
+	for (const key of ["input", "output", "cacheRead", "cacheWrite", "totalTokens"] as const) {
+		if (typeof value[key] !== "number" || !Number.isFinite(value[key]) || value[key] < 0) throw new Error(`Native usage ${key} is unavailable or invalid`);
+	}
+	for (const key of ["input", "output", "cacheRead", "cacheWrite", "total"] as const) {
+		if (!value.cost || typeof value.cost[key] !== "number" || !Number.isFinite(value.cost[key]) || value.cost[key] < 0) throw new Error(`Native usage cost.${key} is unavailable or invalid`);
+	}
+}
+
+export interface NativeUsageMetadata {
+	type: string;
+	id: string;
+	checkpoint?: boolean;
+	provider?: string;
+	model?: string;
+	usage?: NativeUsage;
+	message?: { role: string; timestamp?: number; toolCallId?: string; provider?: string; model?: string; responseModel?: string; usage?: NativeUsage };
+}
+
+/** One billing reducer for published journals and settled, once-audited in-memory sessions. */
+export function nativeUsageCollector(sessionId: string, baseline: ReadonlySet<string>, boundaries: Array<string | undefined> = []) {
+	const totals: Usage[] = Array.from({ length: Math.max(1, boundaries.length) }, () => ({ input: 0, output: 0, cacheRead: 0, cacheWrite: 0, cost: 0, turns: 0, contributions: [] }));
+	let segment = 0;
+	const contributions = new Map<string, UsageContribution>(), turns = new Set<string>();
+	return { totals, append(entry: NativeUsageMetadata) {
+		if (!entry || typeof entry !== "object") throw new SyntaxError("Invalid native entry");
+		if (entry.type === "message" && (!entry.message || typeof entry.message.role !== "string")) throw new SyntaxError("Invalid native message");
+		if (!baseline.has(entry.id) && entry.checkpoint !== true) {
+			let value: NativeUsage | undefined, provider: string | undefined, model: string | undefined;
+			if (entry.type === "usage") { value = entry.usage; provider = entry.provider; model = entry.model; }
+			else if (entry.type === "compaction" || entry.type === "branch_summary") value = entry.usage;
+			else if (entry.type === "message") {
+				if (entry.message?.role === "assistant") {
+					value = entry.message.usage; provider = entry.message.provider; model = entry.message.responseModel ?? entry.message.model;
+					if (!turns.has(entry.id)) { totals[segment]!.turns++; turns.add(entry.id); }
+				} else if (entry.message?.role === "toolResult") value = entry.message.usage;
+			}
+			if (!value && (entry.type === "usage" || entry.type === "message" && entry.message?.role === "assistant")) throw new Error(`Required native usage is unavailable: ${entry.id}`);
+			if (value) {
+				validateNativeUsage(value);
+				if (typeof entry.id !== "string" || !entry.id) throw new Error("Native usage entry identity is unavailable");
+				const next = { id: `${sessionId}:${entry.id}`, provider, model, usage: value };
+				const previous = contributions.get(next.id);
+				if (previous && !isDeepStrictEqual(previous, next)) throw new Error(`Conflicting native usage contribution: ${next.id}`);
+				if (!previous) { contributions.set(next.id, next); addUsage(totals[segment]!, value, { id: next.id, provider, model }); }
+			}
+		}
+		if (entry.id === boundaries[segment] && segment < totals.length - 1) segment++;
+	} };
+}
+
+/** Read native journals without opening a second writer or copying their transcripts. */
+export function readNativeUsage(file: string | undefined, baseline: ReadonlySet<string>, boundaries: Array<string | undefined> = [],
+	options: { terminalEntryId?: string; onEntry?: (entry: NativeUsageMetadata) => void; onBoundary?: (boundary: { sessionId: string; lastEntryId?: string }) => void } = {}): Usage[] | undefined {
+	if (!file) return;
+	let sessionId: string | undefined, first = true, lastEntryId: string | undefined, reached = false;
+	let collector: ReturnType<typeof nativeUsageCollector> | undefined;
+	const boundaryReached = Symbol("terminal entry");
+	try { scanJournal(file, (path, root) => path[0] === "message" && path[1] === "content" ? false : nativeProjection(path, root), ({ value: entry }) => {
+		if (first) {
+			first = false; sessionId = entry?.type === "session" ? entry.id : undefined;
+			if (sessionId) collector = nativeUsageCollector(sessionId, baseline, boundaries);
+		}
+		if (!collector) return;
+		options.onEntry?.(entry as NativeUsageMetadata);
+		collector.append(entry as NativeUsageMetadata);
+		if (entry.type !== "session") lastEntryId = entry.id;
+		if (entry.id === options.terminalEntryId) { reached = true; throw boundaryReached; }
+	}, { requireNewline: true }); } catch (error) { if ((error as NodeJS.ErrnoException).code === "ENOENT") return; if (error !== boundaryReached) throw error; }
+	if (options.terminalEntryId && !reached) throw new Error("Native accounting terminal entry is missing");
+	if (sessionId) options.onBoundary?.({ sessionId, lastEntryId });
+	return collector?.totals;
+}