pi-subagents 0.35.1 → 0.37.0

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/launch-contract.ts

@@ -0,0 +1,123 @@
+import { createHash } from "node:crypto";
+import * as fs from "node:fs";
+import type { AgentConfig } from "../agents/agents.ts";
+
+export const AGENT_DEFINITION_PROJECTION_VERSION = 1 as const;
+export const LAUNCH_BINDING_PROJECTION_VERSION = 1 as const;
+
+function stableJson(value: unknown): string {
+	if (Array.isArray(value)) return `[${value.map(stableJson).join(",")}]`;
+	if (value && typeof value === "object") {
+		return `{${Object.entries(value as Record<string, unknown>)
+			.filter(([, entry]) => entry !== undefined)
+			.sort(([a], [b]) => a.localeCompare(b))
+			.map(([key, entry]) => `${JSON.stringify(key)}:${stableJson(entry)}`)
+			.join(",")}}`;
+	}
+	return JSON.stringify(value);
+}
+
+function sha256(value: unknown): string {
+	return createHash("sha256").update(stableJson(value)).digest("hex");
+}
+
+function fileDigest(filePath: string): string | undefined {
+	try {
+		return createHash("sha256").update(fs.readFileSync(filePath)).digest("hex");
+	} catch {
+		return undefined;
+	}
+}
+
+/** Public-safe, deterministic evidence for the parsed launch-affecting agent definition. */
+export function projectAgentDefinition(agent: AgentConfig): Record<string, unknown> {
+	return {
+		version: AGENT_DEFINITION_PROJECTION_VERSION,
+		name: agent.name,
+		localName: agent.localName,
+		packageName: agent.packageName,
+		filePath: agent.filePath,
+		fileContentDigest: fileDigest(agent.filePath),
+		systemPrompt: agent.systemPrompt,
+		systemPromptMode: agent.systemPromptMode,
+		inheritProjectContext: agent.inheritProjectContext,
+		inheritSkills: agent.inheritSkills,
+		model: agent.model,
+		fallbackModels: agent.fallbackModels,
+		thinking: agent.thinking,
+		tools: agent.tools,
+		mcpDirectTools: agent.mcpDirectTools,
+		extensions: agent.extensions,
+		subagentOnlyExtensions: agent.subagentOnlyExtensions,
+		skills: agent.skills,
+		skillPath: agent.skillPath,
+		output: agent.output,
+		defaultReads: agent.defaultReads,
+		defaultProgress: agent.defaultProgress,
+		defaultContext: agent.defaultContext,
+		defaultAsync: agent.defaultAsync,
+		defaultTimeoutMs: agent.defaultTimeoutMs,
+		defaultTurnBudget: agent.defaultTurnBudget,
+		defaultAcceptance: agent.defaultAcceptance,
+		acceptanceRole: agent.acceptanceRole,
+		interactive: agent.interactive,
+		maxSubagentDepth: agent.maxSubagentDepth,
+		completionGuard: agent.completionGuard,
+		toolBudget: agent.toolBudget,
+		memory: agent.memory,
+	};
+}
+
+export function agentDefinitionDigest(agent: AgentConfig): string {
+	return sha256(projectAgentDefinition(agent));
+}
+
+export interface LaunchBindingInput {
+	definitionDigest: string;
+	/** Caller task; runtime acceptance/output task annotations are explicitly outside the preflight-known subset. */
+	task?: string;
+	model?: string;
+	modelCandidates?: string[];
+	thinking?: string;
+	systemPrompt?: string | null;
+	systemPromptMode?: AgentConfig["systemPromptMode"];
+	inheritProjectContext: boolean;
+	inheritSkills: boolean;
+	skills?: string[];
+	tools?: string[];
+	extensions?: string[];
+	subagentOnlyExtensions?: string[];
+	mcpDirectTools?: string[];
+	outputPath?: string;
+	outputMode?: string;
+	structuredOutputSchema?: unknown;
+}
+
+/** Canonical projection of the resolved inputs handed to the child. */
+export function projectLaunchBinding(input: LaunchBindingInput): Record<string, unknown> {
+	return {
+		version: LAUNCH_BINDING_PROJECTION_VERSION,
+		definitionDigest: input.definitionDigest,
+		taskDigest: input.task === undefined ? undefined : sha256(input.task),
+		// The ordered candidate set already contains each attempted model; keeping only
+		// this set makes retries correlate to the same preflight binding.
+		modelCandidates: input.modelCandidates,
+		thinking: input.thinking,
+		systemPromptDigest: input.systemPrompt === undefined || input.systemPrompt === null ? undefined : sha256(input.systemPrompt),
+		systemPromptMode: input.systemPromptMode,
+		inheritProjectContext: input.inheritProjectContext,
+		inheritSkills: input.inheritSkills,
+		skills: input.skills,
+		tools: input.tools,
+		extensions: input.extensions,
+		subagentOnlyExtensions: input.subagentOnlyExtensions,
+		mcpDirectTools: input.mcpDirectTools,
+		outputPath: input.outputPath,
+		outputMode: input.outputMode,
+		structuredOutputSchema: input.structuredOutputSchema,
+	};
+}
+
+export function launchBindingDigest(input: LaunchBindingInput): string {
+	return sha256(projectLaunchBinding(input));
+}

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 */