pi-subagents 0.35.0 → 0.36.0

package/src/shared/accessible-dir.ts

@@ -0,0 +1,25 @@
+import * as fs from "node:fs";
+import { DEFAULT_FILE_SYSTEM_RETRY_DELAYS_MS, runFileSystemOperationWithRetry, waitForFileSystemRetry } from "./file-system-retry.ts";
+
+type AccessibleDirFs = Pick<typeof fs, "accessSync" | "mkdirSync">;
+
+type AccessibleDirOptions = {
+	fs?: AccessibleDirFs;
+	retryDirectoryErrors?: boolean;
+	retryDelaysMs?: readonly number[];
+	wait?: (delayMs: number) => void;
+};
+
+export function ensureAccessibleDir(dirPath: string, options: AccessibleDirOptions = {}): void {
+	const fsImpl = options.fs ?? fs;
+	const retryDirectoryErrors = options.retryDirectoryErrors ?? process.platform === "win32";
+	const retryDelaysMs = retryDirectoryErrors ? options.retryDelaysMs ?? DEFAULT_FILE_SYSTEM_RETRY_DELAYS_MS : [];
+	const wait = options.wait ?? waitForFileSystemRetry;
+
+	runFileSystemOperationWithRetry(() => {
+		fsImpl.mkdirSync(dirPath, { recursive: true });
+	}, { retryDelaysMs, wait });
+	runFileSystemOperationWithRetry(() => {
+		fsImpl.accessSync(dirPath, fs.constants.R_OK | fs.constants.W_OK);
+	}, { retryDelaysMs, wait });
+}

package/src/shared/artifacts.ts

@@ -1,6 +1,6 @@
 import * as fs from "node:fs";
 import * as path from "node:path";
-import { TEMP_ARTIFACTS_DIR, type ArtifactPaths } from "./types.ts";
+import { TEMP_ARTIFACTS_DIR, type ArtifactPaths, type ArtifactDirPreference } from "./types.ts";
 import { getAgentDir } from "./utils.ts";
 const CLEANUP_MARKER_FILE = ".last-cleanup";
 const PROJECT_ARTIFACT_ROOT = ".pi-subagents";
@@ -17,13 +17,30 @@ export function getProjectChainRunsDir(cwd: string): string {
 	return path.join(getProjectSubagentsDir(cwd), "chain-runs");
 }
 
-export function getArtifactsDir(sessionFile: string | null, projectCwd?: string): string {
-	if (projectCwd) return getProjectArtifactsDir(projectCwd);
-	if (sessionFile) {
-		const sessionDir = path.dirname(sessionFile);
-		return path.join(sessionDir, "subagent-artifacts");
+export function getArtifactsDir(
+	sessionFile: string | null,
+	projectCwd?: string,
+	dirPreference: ArtifactDirPreference = "project",
+): string {
+	switch (dirPreference) {
+		case "session":
+			if (sessionFile) {
+				const sessionDir = path.dirname(sessionFile);
+				return path.join(sessionDir, "subagent-artifacts");
+			}
+			return TEMP_ARTIFACTS_DIR;
+		case "temp":
+			return TEMP_ARTIFACTS_DIR;
+		case "project":
+			if (projectCwd) return getProjectArtifactsDir(projectCwd);
+			if (sessionFile) {
+				const sessionDir = path.dirname(sessionFile);
+				return path.join(sessionDir, "subagent-artifacts");
+			}
+			return TEMP_ARTIFACTS_DIR;
+		default:
+			throw new Error(`Unsupported artifactDir ${JSON.stringify(dirPreference)}; expected "project", "session", or "temp".`);
 	}
-	return TEMP_ARTIFACTS_DIR;
 }
 
 export function getArtifactPaths(artifactsDir: string, runId: string, agent: string, index?: number): ArtifactPaths {
@@ -47,6 +64,19 @@ export function writeArtifact(filePath: string, content: string): void {
 	fs.writeFileSync(filePath, content, "utf-8");
 }
 
+export function formatOutputArtifactContent(input: {
+	output: string;
+	error?: string;
+	transcriptPath?: string;
+	metadataPath?: string;
+}): string {
+	if (input.output.trim() || !input.error) return input.output;
+	const lines = ["Subagent run failed before producing output.", "", "Error:", input.error];
+	if (input.transcriptPath) lines.push("", `Transcript: ${input.transcriptPath}`);
+	if (input.metadataPath) lines.push(`Metadata: ${input.metadataPath}`);
+	return lines.join("\n");
+}
+
 export function writeMetadata(filePath: string, metadata: object): void {
 	fs.writeFileSync(filePath, JSON.stringify(metadata, null, 2), "utf-8");
 }

package/src/shared/atomic-json.ts

@@ -1,5 +1,6 @@
 import * as fs from "node:fs";
 import * as path from "node:path";
+import { DEFAULT_FILE_SYSTEM_RETRY_DELAYS_MS, runFileSystemOperationWithRetry, waitForFileSystemRetry } from "./file-system-retry.ts";
 
 type AtomicJsonFs = Pick<typeof fs, "mkdirSync" | "writeFileSync" | "renameSync" | "rmSync">;
 
@@ -10,38 +11,11 @@ type AtomicJsonWriterOptions = {
 	random?: () => number;
 	mode?: number;
 	retryRenameErrors?: boolean;
+	retryDirectoryErrors?: boolean;
 	retryDelaysMs?: readonly number[];
 	wait?: (delayMs: number) => void;
 };
 
-const DEFAULT_RENAME_RETRY_DELAYS_MS = [10, 25, 50, 100, 200, 500, 1000, 2000, 4000] as const;
-const RETRYABLE_RENAME_ERROR_CODES = new Set(["EACCES", "EBUSY", "EPERM"]);
-const WAIT_BUFFER = typeof SharedArrayBuffer !== "undefined" ? new SharedArrayBuffer(4) : undefined;
-const WAIT_VIEW = WAIT_BUFFER ? new Int32Array(WAIT_BUFFER) : undefined;
-
-function waitSync(delayMs: number): void {
-	if (delayMs <= 0) return;
-	if (WAIT_VIEW) {
-		try {
-			// writeAtomicJson is synchronous because callers often update status from sync callbacks.
-			// Atomics.wait gives Windows rename locks time to clear without burning CPU.
-			Atomics.wait(WAIT_VIEW, 0, 0, delayMs);
-			return;
-		} catch {
-			// Fall through to the portable busy wait below.
-		}
-	}
-	const end = Date.now() + delayMs;
-	while (Date.now() < end) {
-		// Portable fallback for runtimes where Atomics.wait is unavailable.
-	}
-}
-
-function isRetryableRenameError(error: unknown): boolean {
-	const code = (error as NodeJS.ErrnoException | undefined)?.code;
-	return typeof code === "string" && RETRYABLE_RENAME_ERROR_CODES.has(code);
-}
-
 function renameWithRetry(
 	fsImpl: AtomicJsonFs,
 	sourcePath: string,
@@ -49,16 +23,9 @@ function renameWithRetry(
 	retryDelaysMs: readonly number[],
 	wait: (delayMs: number) => void,
 ): void {
-	for (let attempt = 0; ; attempt++) {
-		try {
-			fsImpl.renameSync(sourcePath, targetPath);
-			return;
-		} catch (error) {
-			const delayMs = retryDelaysMs[attempt];
-			if (delayMs === undefined || !isRetryableRenameError(error)) throw error;
-			wait(delayMs);
-		}
-	}
+	runFileSystemOperationWithRetry(() => {
+		fsImpl.renameSync(sourcePath, targetPath);
+	}, { retryDelaysMs, wait });
 }
 
 export function createAtomicJsonWriter(options: AtomicJsonWriterOptions = {}): (filePath: string, payload: object) => void {
@@ -68,17 +35,22 @@ export function createAtomicJsonWriter(options: AtomicJsonWriterOptions = {}): (
 	const random = options.random ?? Math.random;
 	const mode = options.mode;
 	const retryRenameErrors = options.retryRenameErrors ?? process.platform === "win32";
-	const retryDelaysMs = retryRenameErrors ? options.retryDelaysMs ?? DEFAULT_RENAME_RETRY_DELAYS_MS : [];
-	const wait = options.wait ?? waitSync;
+	const retryDirectoryErrors = options.retryDirectoryErrors ?? retryRenameErrors;
+	const retryDelaysMs = options.retryDelaysMs ?? DEFAULT_FILE_SYSTEM_RETRY_DELAYS_MS;
+	const renameRetryDelaysMs = retryRenameErrors ? retryDelaysMs : [];
+	const directoryRetryDelaysMs = retryDirectoryErrors ? retryDelaysMs : [];
+	const wait = options.wait ?? waitForFileSystemRetry;
 	return (filePath: string, payload: object): void => {
-		fsImpl.mkdirSync(path.dirname(filePath), { recursive: true });
+		runFileSystemOperationWithRetry(() => {
+			fsImpl.mkdirSync(path.dirname(filePath), { recursive: true });
+		}, { retryDelaysMs: directoryRetryDelaysMs, wait });
 		const tempPath = path.join(
 			path.dirname(filePath),
 			`.${path.basename(filePath)}.${pid}.${now()}.${random().toString(36).slice(2)}.tmp`,
 		);
 		try {
 			fsImpl.writeFileSync(tempPath, JSON.stringify(payload, null, 2), mode === undefined ? "utf-8" : { encoding: "utf-8", mode });
-			renameWithRetry(fsImpl, tempPath, filePath, retryDelaysMs, wait);
+			renameWithRetry(fsImpl, tempPath, filePath, renameRetryDelaysMs, wait);
 		} finally {
 			fsImpl.rmSync(tempPath, { force: true });
 		}

package/src/shared/child-transcript.ts

@@ -3,6 +3,30 @@ import * as path from "node:path";
 import type { Message } from "@earendil-works/pi-ai";
 import { extractTextFromContent, extractToolArgsPreview } from "./utils.ts";
 
+const MAX_TOOL_PAYLOAD_BYTES = 32 * 1024;
+const TOOL_PAYLOAD_TRUNCATION_MARKER = "\n\n… payload truncated";
+
+function boundedPayload(value: unknown, maxBytes = MAX_TOOL_PAYLOAD_BYTES): string | undefined {
+	let text: string;
+	if (typeof value === "string") text = value;
+	else {
+		try {
+			const serialized = JSON.stringify(value, null, 2);
+			if (serialized === undefined) return undefined;
+			text = serialized;
+		} catch {
+			return undefined;
+		}
+	}
+	if (!text.trim()) return undefined;
+	const payload = Buffer.from(text, "utf-8");
+	if (payload.length <= maxBytes) return text;
+	const markerBytes = Buffer.byteLength(TOOL_PAYLOAD_TRUNCATION_MARKER, "utf-8");
+	let end = Math.max(0, maxBytes - markerBytes);
+	while (end > 0 && (payload[end]! & 0xc0) === 0x80) end--;
+	return `${payload.subarray(0, end).toString("utf-8")}${TOOL_PAYLOAD_TRUNCATION_MARKER}`;
+}
+
 export const CHILD_TRANSCRIPT_ARTIFACT_VERSION = 1;
 const DEFAULT_MAX_CHILD_TRANSCRIPT_BYTES = 50 * 1024 * 1024;
 
@@ -19,8 +43,10 @@ type ChildTranscriptMessage = Message & {
 interface ChildTranscriptEvent {
 	type?: string;
 	message?: ChildTranscriptMessage;
+	toolCallId?: string;
 	toolName?: string;
 	args?: unknown;
+	isError?: boolean;
 }
 
 interface ChildTranscriptWriterInput {
@@ -147,6 +173,27 @@ export function createChildTranscriptWriter(input: ChildTranscriptWriterInput):
 
 	const writeMessage = (sourceEventType: string, message: ChildTranscriptMessage) => {
 		const text = extractTextFromContent(message.content);
+		if (message.role === "toolResult") {
+			const output = boundedPayload(text);
+			writeRecord({
+				...baseRecord("message"),
+				sourceEventType,
+				role: message.role,
+				toolCallId: message.toolCallId,
+				toolName: message.toolName,
+				isError: message.isError,
+				...(output ? { text: output, outputTruncated: output.includes("… payload truncated") } : {}),
+				message: {
+					role: message.role,
+					toolCallId: message.toolCallId,
+					toolName: message.toolName,
+					isError: message.isError,
+					content: output ? [{ type: "text", text: output }] : [],
+					...(message.timestamp !== undefined ? { timestamp: message.timestamp } : {}),
+				},
+			});
+			return;
+		}
 		writeRecord({
 			...baseRecord("message"),
 			sourceEventType,
@@ -178,11 +225,14 @@ export function createChildTranscriptWriter(input: ChildTranscriptWriterInput):
 			}
 			if (event.type === "tool_execution_start" && event.toolName) {
 				const args = eventArgs(event);
+				const argsPayload = boundedPayload(args);
 				writeRecord({
 					...baseRecord("tool_start"),
 					sourceEventType: event.type,
+					...(event.toolCallId ? { toolCallId: event.toolCallId } : {}),
 					toolName: event.toolName,
 					...(Object.keys(args).length > 0 ? { argsPreview: extractToolArgsPreview(args) } : {}),
+					...(argsPayload ? { argsPayload } : {}),
 				});
 				return;
 			}
@@ -190,7 +240,9 @@ export function createChildTranscriptWriter(input: ChildTranscriptWriterInput):
 				writeRecord({
 					...baseRecord("tool_end"),
 					sourceEventType: event.type,
+					...(event.toolCallId ? { toolCallId: event.toolCallId } : {}),
 					...(event.toolName ? { toolName: event.toolName } : {}),
+					...(typeof event.isError === "boolean" ? { isError: event.isError } : {}),
 				});
 			}
 		},

package/src/shared/file-system-retry.ts

@@ -0,0 +1,47 @@
+const WAIT_BUFFER = typeof SharedArrayBuffer !== "undefined" ? new SharedArrayBuffer(4) : undefined;
+const WAIT_VIEW = WAIT_BUFFER ? new Int32Array(WAIT_BUFFER) : undefined;
+const RETRYABLE_FILE_SYSTEM_ERROR_CODES = new Set(["EACCES", "EBUSY", "EPERM"]);
+
+export const DEFAULT_FILE_SYSTEM_RETRY_DELAYS_MS = [10, 25, 50, 100, 200, 500, 1000, 2000, 4000] as const;
+
+export type FileSystemRetryOptions = {
+	retryDelaysMs?: readonly number[];
+	wait?: (delayMs: number) => void;
+};
+
+export function waitForFileSystemRetry(delayMs: number): void {
+	if (delayMs <= 0) return;
+	if (WAIT_VIEW) {
+		try {
+			// Callers are synchronous status/result writers; Atomics.wait gives
+			// Windows directory and rename locks time to clear without burning CPU.
+			Atomics.wait(WAIT_VIEW, 0, 0, delayMs);
+			return;
+		} catch {
+			// Fall through to the portable busy wait below.
+		}
+	}
+	const end = Date.now() + delayMs;
+	while (Date.now() < end) {
+		// Portable fallback for runtimes where Atomics.wait is unavailable.
+	}
+}
+
+export function isRetryableFileSystemError(error: unknown): boolean {
+	const code = (error as NodeJS.ErrnoException | undefined)?.code;
+	return typeof code === "string" && RETRYABLE_FILE_SYSTEM_ERROR_CODES.has(code);
+}
+
+export function runFileSystemOperationWithRetry<T>(operation: () => T, options: FileSystemRetryOptions = {}): T {
+	const retryDelaysMs = options.retryDelaysMs ?? DEFAULT_FILE_SYSTEM_RETRY_DELAYS_MS;
+	const wait = options.wait ?? waitForFileSystemRetry;
+	for (let attempt = 0; ; attempt++) {
+		try {
+			return operation();
+		} catch (error) {
+			const delayMs = retryDelaysMs[attempt];
+			if (delayMs === undefined || !isRetryableFileSystemError(error)) throw error;
+			wait(delayMs);
+		}
+	}
+}

package/src/shared/settings.ts

@@ -6,7 +6,7 @@ import * as fs from "node:fs";
 import * as path from "node:path";
 import type { AgentConfig } from "../agents/agents.ts";
 import { normalizeSkillInput } from "../agents/skills.ts";
-import { CHAIN_RUNS_DIR, type AcceptanceInput, type JsonSchemaObject, type OutputMode, type ToolBudgetConfig } from "./types.ts";
+import { CHAIN_RUNS_DIR, type AcceptanceInput, type AgentContract, type ChainGateLayer, type JsonSchemaObject, type OutputMode, type ToolBudgetConfig } from "./types.ts";
 const CHAIN_DIR_MAX_AGE_MS = 24 * 60 * 60 * 1000; // 24 hours
 const INITIAL_PROGRESS_CONTENT = "# Progress\n\n## Status\nIn Progress\n\n## Tasks\n\n## Files Changed\n\n## Notes\n";
 
@@ -57,6 +57,8 @@ export interface SequentialStep {
 	model?: string;
 	toolBudget?: ToolBudgetConfig;
 	acceptance?: AcceptanceInput;
+	agentContract?: AgentContract;
+	gateOn?: ChainGateLayer;
 }
 
 /** Parallel task item within a parallel step */
@@ -77,6 +79,8 @@ export interface ParallelTaskItem {
 	model?: string;
 	toolBudget?: ToolBudgetConfig;
 	acceptance?: AcceptanceInput;
+	agentContract?: AgentContract;
+	gateOn?: ChainGateLayer;
 }
 
 export interface DynamicExpandSpec {
@@ -106,6 +110,8 @@ export interface DynamicParallelStep {
 	phase?: string;
 	label?: string;
 	acceptance?: AcceptanceInput;
+	agentContract?: AgentContract;
+	gateOn?: ChainGateLayer;
 }
 
 /** Parallel step: multiple agents running concurrently */
@@ -115,6 +121,8 @@ export interface ParallelStep {
 	failFast?: boolean;
 	worktree?: boolean;
 	cwd?: string;
+	agentContract?: AgentContract;
+	gateOn?: ChainGateLayer;
 }
 
 /** Union type for chain steps */