pi-subagents 0.32.0 → 0.33.0

package/src/runs/shared/tool-budget.ts

@@ -0,0 +1,74 @@
+import type { ResolvedToolBudget, ToolBudgetConfig, ToolBudgetState } from "../../shared/types.ts";
+
+export const DEFAULT_TOOL_BUDGET_BLOCK = ["read", "grep", "find", "ls"] as const;
+export const TOOL_BUDGET_ENV = "PI_SUBAGENT_TOOL_BUDGET";
+
+export function normalizeToolBudgetBlock(block: ToolBudgetConfig["block"] | undefined): "*" | string[] {
+	if (block === "*") return "*";
+	if (block === undefined) return [...DEFAULT_TOOL_BUDGET_BLOCK];
+	return [...new Set(block.map((tool) => tool.trim()).filter(Boolean))];
+}
+
+export function validateToolBudgetConfig(raw: unknown, label = "toolBudget"): { budget?: ResolvedToolBudget; error?: string } {
+	if (raw === undefined) return {};
+	if (!raw || typeof raw !== "object" || Array.isArray(raw)) return { error: `${label} must be an object with hard and optional soft/block.` };
+	const value = raw as ToolBudgetConfig;
+	if (typeof value.hard !== "number" || !Number.isInteger(value.hard) || value.hard < 1) {
+		return { error: `${label}.hard must be an integer >= 1.` };
+	}
+	if (value.soft !== undefined && (typeof value.soft !== "number" || !Number.isInteger(value.soft) || value.soft < 1)) {
+		return { error: `${label}.soft must be an integer >= 1 when provided.` };
+	}
+	if (value.soft !== undefined && value.soft > value.hard) {
+		return { error: `${label}.soft must be <= ${label}.hard.` };
+	}
+	if (value.block !== undefined && value.block !== "*") {
+		if (!Array.isArray(value.block)) return { error: `${label}.block must be "*" or an array of tool names.` };
+		if (value.block.length === 0) return { error: `${label}.block must contain at least one tool name.` };
+		for (const item of value.block) {
+			if (typeof item !== "string" || !item.trim()) return { error: `${label}.block must contain non-empty tool names.` };
+		}
+	}
+	return { budget: { hard: value.hard, ...(value.soft !== undefined ? { soft: value.soft } : {}), block: normalizeToolBudgetBlock(value.block) } };
+}
+
+export function initialToolBudgetState(budget: ResolvedToolBudget): ToolBudgetState {
+	return { ...budget, toolCount: 0, outcome: "within-budget" };
+}
+
+export function toolBudgetState(budget: ResolvedToolBudget, toolCount: number, blockedTool?: string): ToolBudgetState {
+	const overHard = toolCount > budget.hard;
+	const overSoft = budget.soft !== undefined && toolCount >= budget.soft;
+	return {
+		...budget,
+		toolCount,
+		outcome: overHard ? "hard-blocked" : overSoft ? "soft-reached" : "within-budget",
+		...(overSoft ? { softReachedAt: budget.soft } : {}),
+		...(overHard ? { hardReachedAt: budget.hard, blockedTool } : {}),
+	};
+}
+
+export function shouldBlockToolForBudget(budget: ResolvedToolBudget, toolName: string, nextToolCount: number): boolean {
+	if (nextToolCount <= budget.hard) return false;
+	return budget.block === "*" || budget.block.includes(toolName);
+}
+
+export function toolBudgetSoftNudge(budget: ResolvedToolBudget, toolCount: number): string {
+	return `Tool budget soft limit reached after ${toolCount} tool call${toolCount === 1 ? "" : "s"} (soft ${budget.soft}, hard ${budget.hard}). Stop starting new browsing/search work and finalize from the context you already have.`;
+}
+
+export function toolBudgetBlockedMessage(budget: ResolvedToolBudget, toolName: string, toolCount: number): string {
+	return `Tool budget hard limit reached after ${toolCount} tool call${toolCount === 1 ? "" : "s"} (hard ${budget.hard}). The '${toolName}' tool is blocked so you can finalize from the context you already have.`;
+}
+
+export function encodeToolBudgetEnv(budget: ResolvedToolBudget | undefined): string | undefined {
+	return budget ? JSON.stringify(budget) : undefined;
+}
+
+export function decodeToolBudgetEnv(value: string | undefined): ResolvedToolBudget | undefined {
+	if (!value?.trim()) return undefined;
+	const parsed = JSON.parse(value) as unknown;
+	const normalized = validateToolBudgetConfig(parsed, TOOL_BUDGET_ENV);
+	if (normalized.error) throw new Error(normalized.error);
+	return normalized.budget;
+}

package/src/runs/shared/turn-budget.ts

@@ -0,0 +1,52 @@
+import type { ResolvedTurnBudget, TurnBudgetState } from "../../shared/types.ts";
+
+export const DEFAULT_TURN_BUDGET_GRACE_TURNS = 1;
+
+export function appendTurnBudgetSystemPrompt(systemPrompt: string, budget: ResolvedTurnBudget | undefined): string {
+	if (!budget) return systemPrompt;
+	const grace = budget.graceTurns === 1 ? "1 additional assistant turn" : `${budget.graceTurns} additional assistant turns`;
+	const block = [
+		"## Turn budget",
+		`This child run has a soft budget of ${budget.maxTurns} assistant turn${budget.maxTurns === 1 ? "" : "s"}.`,
+		`After that, ${grace} may be allowed only for a final wrap-up.`,
+		"When you approach or reach the soft budget, stop starting new tool work and return the final answer immediately.",
+		"This runner uses process-mode execution, so live steering after launch may be unavailable; treat this instruction as the wrap-up request.",
+		"If you continue past the soft budget plus grace turns, the supervisor may abort the process and return only partial output.",
+	].join("\n");
+	return systemPrompt.trim() ? `${systemPrompt.trim()}\n\n${block}` : block;
+}
+
+export function turnBudgetSoftNote(budget: ResolvedTurnBudget, turnCount: number): string {
+	return `Turn budget wrap-up was requested after ${turnCount} assistant turn${turnCount === 1 ? "" : "s"} (soft limit ${budget.maxTurns}, grace ${budget.graceTurns}). Process-mode live steering is unavailable, so the child was warned at launch to wrap up by this budget. Output may be partial.`;
+}
+
+export function turnBudgetExceededMessage(budget: ResolvedTurnBudget, turnCount: number): string {
+	return `Subagent exceeded turn budget after ${turnCount} assistant turn${turnCount === 1 ? "" : "s"} (soft limit ${budget.maxTurns} + grace ${budget.graceTurns}).`;
+}
+
+export function formatTurnBudgetOutput(message: string, output: string): string {
+	return output.trim()
+		? `${message}\n\nPartial output before turn-budget abort:\n${output}`
+		: message;
+}
+
+export function initialTurnBudgetState(budget: ResolvedTurnBudget): TurnBudgetState {
+	return { ...budget, outcome: "within-budget", turnCount: 0 };
+}
+
+export function turnBudgetState(budget: ResolvedTurnBudget, turnCount: number, exceeded: boolean): TurnBudgetState {
+	return {
+		...budget,
+		turnCount,
+		outcome: exceeded ? "exceeded" : "wrap-up-requested",
+		wrapUpRequestedAtTurn: budget.maxTurns,
+		...(exceeded ? { exceededAtTurn: turnCount } : {}),
+	};
+}
+
+export function shouldAbortForTurnBudget(budget: ResolvedTurnBudget, turnCount: number, terminalAssistantStop: boolean): boolean {
+	const hardLimit = budget.maxTurns + budget.graceTurns;
+	if (turnCount < hardLimit) return false;
+	if (turnCount > hardLimit) return true;
+	return !terminalAssistantStop;
+}

package/src/shared/artifacts.ts

@@ -34,6 +34,7 @@ export function getArtifactPaths(artifactsDir: string, runId: string, agent: str
 		inputPath: path.join(artifactsDir, `${base}_input.md`),
 		outputPath: path.join(artifactsDir, `${base}_output.md`),
 		jsonlPath: path.join(artifactsDir, `${base}.jsonl`),
+		transcriptPath: path.join(artifactsDir, `${base}_transcript.jsonl`),
 		metadataPath: path.join(artifactsDir, `${base}_meta.json`),
 	};
 }

package/src/shared/atomic-json.ts

@@ -13,13 +13,26 @@ type AtomicJsonWriterOptions = {
 	wait?: (delayMs: number) => void;
 };
 
-const DEFAULT_RENAME_RETRY_DELAYS_MS = [10, 25, 50, 100, 200] as const;
+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) {
-		// writeAtomicJson is synchronous because callers often update status from sync callbacks.
+		// Portable fallback for runtimes where Atomics.wait is unavailable.
 	}
 }
 

package/src/shared/child-transcript.ts

@@ -0,0 +1,212 @@
+import * as fs from "node:fs";
+import * as path from "node:path";
+import type { Message } from "@earendil-works/pi-ai";
+import { extractTextFromContent, extractToolArgsPreview } from "./utils.ts";
+
+export const CHILD_TRANSCRIPT_ARTIFACT_VERSION = 1;
+const DEFAULT_MAX_CHILD_TRANSCRIPT_BYTES = 50 * 1024 * 1024;
+
+type ChildTranscriptSource = "foreground" | "async";
+type ChildTranscriptRecordType = "message" | "tool_start" | "tool_end" | "stdout" | "stderr" | "truncated";
+
+type ChildTranscriptMessage = Message & {
+	model?: string;
+	errorMessage?: string;
+	stopReason?: string;
+	usage?: unknown;
+};
+
+interface ChildTranscriptEvent {
+	type?: string;
+	message?: ChildTranscriptMessage;
+	toolName?: string;
+	args?: unknown;
+}
+
+interface ChildTranscriptWriterInput {
+	transcriptPath: string;
+	source: ChildTranscriptSource;
+	runId: string;
+	agent: string;
+	childIndex?: number;
+	cwd: string;
+	maxBytes?: number;
+}
+
+export interface ChildTranscriptWriter {
+	path: string;
+	writeInitialUserMessage(prompt: string): void;
+	writeChildEvent(event: ChildTranscriptEvent): void;
+	writeStdoutLine(line: string): void;
+	writeStderrLine(line: string): void;
+	writeStderrText(text: string): void;
+	getError(): string | undefined;
+}
+
+function errorMessage(error: unknown): string {
+	return error instanceof Error ? error.message : String(error);
+}
+
+function finiteNumber(value: unknown): number | undefined {
+	return typeof value === "number" && Number.isFinite(value) ? value : undefined;
+}
+
+function normalizeUsage(value: unknown): { input: number; output: number; cacheRead: number; cacheWrite: number; cost: number } | undefined {
+	if (!value || typeof value !== "object") return undefined;
+	const raw = value as Record<string, unknown>;
+	const rawCost = raw.cost;
+	const cost = rawCost && typeof rawCost === "object"
+		? finiteNumber((rawCost as { total?: unknown }).total) ?? 0
+		: finiteNumber(rawCost) ?? 0;
+	return {
+		input: finiteNumber(raw.input) ?? finiteNumber(raw.inputTokens) ?? 0,
+		output: finiteNumber(raw.output) ?? finiteNumber(raw.outputTokens) ?? 0,
+		cacheRead: finiteNumber(raw.cacheRead) ?? 0,
+		cacheWrite: finiteNumber(raw.cacheWrite) ?? 0,
+		cost,
+	};
+}
+
+function eventArgs(event: ChildTranscriptEvent): Record<string, unknown> {
+	return event.args && typeof event.args === "object" && !Array.isArray(event.args)
+		? event.args as Record<string, unknown>
+		: {};
+}
+
+export function createChildTranscriptWriter(input: ChildTranscriptWriterInput): ChildTranscriptWriter {
+	let bytesWritten = 0;
+	let writeError: string | undefined;
+	let truncated = false;
+	const maxBytes = input.maxBytes ?? DEFAULT_MAX_CHILD_TRANSCRIPT_BYTES;
+
+	const baseRecord = (recordType: ChildTranscriptRecordType) => {
+		const ts = Date.now();
+		return {
+			version: CHILD_TRANSCRIPT_ARTIFACT_VERSION,
+			recordType,
+			source: input.source,
+			runId: input.runId,
+			agent: input.agent,
+			...(input.childIndex !== undefined ? { childIndex: input.childIndex } : {}),
+			cwd: input.cwd,
+			ts,
+			timestamp: new Date(ts).toISOString(),
+		};
+	};
+
+	const writeTruncatedMarker = () => {
+		truncated = true;
+		const marker = `${JSON.stringify({
+			...baseRecord("truncated"),
+			maxBytes,
+			message: `Child transcript exceeded ${maxBytes} bytes; further records were omitted.`,
+		})}\n`;
+		const markerBytes = Buffer.byteLength(marker, "utf-8");
+		if (bytesWritten + markerBytes > maxBytes) return false;
+		try {
+			fs.appendFileSync(input.transcriptPath, marker, "utf-8");
+			bytesWritten += markerBytes;
+			return true;
+		} catch (error) {
+			writeError = `Failed to write child transcript '${input.transcriptPath}': ${errorMessage(error)}`;
+			return false;
+		}
+	};
+
+	const writeRecord = (record: Record<string, unknown>) => {
+		if (writeError || truncated) return;
+		const line = `${JSON.stringify(record)}\n`;
+		const bytes = Buffer.byteLength(line, "utf-8");
+		if (bytesWritten + bytes > maxBytes) {
+			writeTruncatedMarker();
+			return;
+		}
+		const markerProbe = `${JSON.stringify({
+			...baseRecord("truncated"),
+			maxBytes,
+			message: `Child transcript exceeded ${maxBytes} bytes; further records were omitted.`,
+		})}\n`;
+		if (bytesWritten + bytes + Buffer.byteLength(markerProbe, "utf-8") > maxBytes) {
+			writeTruncatedMarker();
+			return;
+		}
+		try {
+			fs.appendFileSync(input.transcriptPath, line, "utf-8");
+			bytesWritten += bytes;
+		} catch (error) {
+			writeError = `Failed to write child transcript '${input.transcriptPath}': ${errorMessage(error)}`;
+		}
+	};
+
+	try {
+		fs.mkdirSync(path.dirname(input.transcriptPath), { recursive: true });
+		fs.writeFileSync(input.transcriptPath, "", "utf-8");
+	} catch (error) {
+		writeError = `Failed to initialize child transcript '${input.transcriptPath}': ${errorMessage(error)}`;
+	}
+
+	const writeMessage = (sourceEventType: string, message: ChildTranscriptMessage) => {
+		const text = extractTextFromContent(message.content);
+		writeRecord({
+			...baseRecord("message"),
+			sourceEventType,
+			role: message.role,
+			...(text ? { text } : {}),
+			...(message.model ? { model: message.model } : {}),
+			...(message.stopReason ? { stopReason: message.stopReason } : {}),
+			...(message.errorMessage ? { errorMessage: message.errorMessage } : {}),
+			...(message.usage ? { usage: normalizeUsage(message.usage) } : {}),
+			message,
+		});
+	};
+
+	return {
+		path: input.transcriptPath,
+		writeInitialUserMessage(prompt: string) {
+			writeRecord({
+				...baseRecord("message"),
+				sourceEventType: "initial_prompt",
+				role: "user",
+				text: prompt,
+				message: { role: "user", content: [{ type: "text", text: prompt }] },
+			});
+		},
+		writeChildEvent(event: ChildTranscriptEvent) {
+			if ((event.type === "message_end" || event.type === "tool_result_end") && event.message) {
+				writeMessage(event.type, event.message);
+				return;
+			}
+			if (event.type === "tool_execution_start" && event.toolName) {
+				const args = eventArgs(event);
+				writeRecord({
+					...baseRecord("tool_start"),
+					sourceEventType: event.type,
+					toolName: event.toolName,
+					...(Object.keys(args).length > 0 ? { argsPreview: extractToolArgsPreview(args) } : {}),
+				});
+				return;
+			}
+			if (event.type === "tool_execution_end") {
+				writeRecord({
+					...baseRecord("tool_end"),
+					sourceEventType: event.type,
+					...(event.toolName ? { toolName: event.toolName } : {}),
+				});
+			}
+		},
+		writeStdoutLine(line: string) {
+			if (!line.trim()) return;
+			writeRecord({ ...baseRecord("stdout"), text: line });
+		},
+		writeStderrLine(line: string) {
+			if (!line.trim()) return;
+			writeRecord({ ...baseRecord("stderr"), text: line });
+		},
+		writeStderrText(text: string) {
+			for (const line of text.split(/\r?\n/)) this.writeStderrLine(line);
+		},
+		getError() {
+			return writeError;
+		},
+	};
+}

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 } from "./types.ts";
+import { CHAIN_RUNS_DIR, type AcceptanceInput, 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";
 
@@ -55,6 +55,7 @@ export interface SequentialStep {
 	progress?: boolean;
 	skill?: string | string[] | false;
 	model?: string;
+	toolBudget?: ToolBudgetConfig;
 	acceptance?: AcceptanceInput;
 }
 
@@ -74,6 +75,7 @@ export interface ParallelTaskItem {
 	progress?: boolean;
 	skill?: string | string[] | false;
 	model?: string;
+	toolBudget?: ToolBudgetConfig;
 	acceptance?: AcceptanceInput;
 }