@explyt/ai-agent 0.1.0-rc.1

package/node_modules/pi-subagents/src/runs/shared/subagent-startup-retry.ts

@@ -0,0 +1,104 @@
+import type { Usage } from "../../shared/types.ts";
+import { formatProcessSignalError } from "./process-signal.ts";
+
+/**
+ * Retry delays for child processes that exit before any model or tool activity.
+ * The schedule is intentionally short and bounded to avoid amplifying persistent
+ * launch failures while allowing concurrent Pi startup locks to clear.
+ */
+export const SUBAGENT_STARTUP_RETRY_DELAYS_MS = [250, 750, 1500] as const;
+
+/** A genuine startup race should fail well before a model request can complete. */
+export const MAX_SUBAGENT_STARTUP_FAILURE_DURATION_MS = 2000;
+
+const SIGKILL_PROCESS_SIGNAL_ERROR = formatProcessSignalError("SIGKILL");
+
+export interface SubagentStartupFailureEvidence {
+	exitCode: number | null | undefined;
+	error?: string;
+	finalOutput?: string;
+	messageCount: number;
+	toolCount: number;
+	usage: Usage;
+	durationMs: number;
+	protocolError?: unknown;
+	processSignal?: string | null;
+	observedMutationAttempt?: boolean;
+	detached?: boolean;
+	interrupted?: boolean;
+	timedOut?: boolean;
+	stopped?: boolean;
+	turnBudgetExceeded?: boolean;
+}
+
+function hasUsage(usage: Usage): boolean {
+	return usage.input !== 0
+		|| usage.output !== 0
+		|| usage.cacheRead !== 0
+		|| usage.cacheWrite !== 0
+		|| usage.cost !== 0
+		|| usage.turns !== 0;
+}
+
+/**
+ * Classify only unexplained, zero-activity child exits as startup failures.
+ * This intentionally fails closed: any model output, tool activity, usage,
+ * mutation evidence, diagnostic, or lifecycle interruption prevents a retry.
+ */
+export function isRetryableSubagentStartupFailure(evidence: SubagentStartupFailureEvidence): boolean {
+	return evidence.exitCode !== undefined
+		&& evidence.exitCode !== null
+		&& evidence.exitCode !== 0
+		&& (!evidence.error?.trim() || evidence.error === SIGKILL_PROCESS_SIGNAL_ERROR)
+		&& !evidence.finalOutput?.trim()
+		&& evidence.messageCount === 0
+		&& evidence.toolCount === 0
+		&& !hasUsage(evidence.usage)
+		&& evidence.durationMs >= 0
+		&& evidence.durationMs <= MAX_SUBAGENT_STARTUP_FAILURE_DURATION_MS
+		&& evidence.protocolError === undefined
+		&& (evidence.processSignal === undefined || evidence.processSignal === null || evidence.processSignal === "SIGKILL")
+		&& evidence.observedMutationAttempt !== true
+		&& evidence.detached !== true
+		&& evidence.interrupted !== true
+		&& evidence.timedOut !== true
+		&& evidence.stopped !== true
+		&& evidence.turnBudgetExceeded !== true;
+}
+
+export function formatSubagentStartupRetryNote(input: {
+	model: string;
+	attempt: number;
+	maxAttempts: number;
+	delayMs: number;
+}): string {
+	return `[startup-retry] ${input.model} exited before model or tool activity (attempt ${input.attempt}/${input.maxAttempts}). Retrying the same model in ${input.delayMs}ms.`;
+}
+
+export function formatSubagentStartupRetryExhaustedError(input: {
+	model: string;
+	attempts: number;
+}): string {
+	return `Subagent failed to start after ${input.attempts} attempts on ${input.model}; no model, tool, output, usage, or diagnostic activity was observed. This may be a concurrent Pi startup race. Retry the run or temporarily lower subagent concurrency.`;
+}
+
+/** Wait for a retry delay, returning false when any lifecycle signal aborts it. */
+export async function waitForSubagentStartupRetry(delayMs: number, signals: Array<AbortSignal | undefined>): Promise<boolean> {
+	const activeSignals = signals.filter((signal): signal is AbortSignal => Boolean(signal));
+	if (activeSignals.some((signal) => signal.aborted)) return false;
+	if (delayMs <= 0) return true;
+
+	return await new Promise<boolean>((resolve) => {
+		let settled = false;
+		const finish = (shouldRetry: boolean): void => {
+			if (settled) return;
+			settled = true;
+			clearTimeout(timer);
+			for (const signal of activeSignals) signal.removeEventListener("abort", abort);
+			resolve(shouldRetry);
+		};
+		const abort = (): void => finish(false);
+		const timer = setTimeout(() => finish(true), delayMs);
+		for (const signal of activeSignals) signal.addEventListener("abort", abort, { once: true });
+	});
+}

package/node_modules/pi-subagents/src/runs/shared/task-intent.ts

@@ -0,0 +1,181 @@
+/**
+ * Shared task mutation-intent classifier.
+ *
+ * Single authority for reading a task's wording, answering two different
+ * questions from one prohibition analysis:
+ *
+ * - `classifyTaskMutationIntent` / `expectsImplementationMutation`: does the
+ *   task REQUIRE file changes? Consumed by the completion mutation guard,
+ *   which blocks completion, so its vocabulary is deliberately narrow.
+ * - `taskMayMutate`: COULD the task plausibly change files? Consumed by
+ *   acceptance level inference, which only raises evidence gates, so its
+ *   vocabulary is deliberately broad (any bare write verb).
+ *
+ * Explicit read-only wording ("do not modify", "review only") is a task-level
+ * intent only when no write imperative survives outside those phrases. A task
+ * like "Do not modify tests; implement the fix" is an implementation task with
+ * a scoped constraint, not a read-only task.
+ */
+
+const REVIEW_ONLY_PATTERNS = [
+	/\breview only\b/i,
+	/\bsuggest fixes only\b/i,
+	/\bonly return findings\b/i,
+	/\breturn findings only\b/i,
+];
+
+const REVIEWER_REQUIRED_EDIT_PATTERNS = [
+	/\bmust\s+(?:edit|modify|change|fix|patch|apply|implement)\b/i,
+	/\brequired\s+to\s+(?:edit|modify|change|fix|patch|apply|implement)\b/i,
+	/(?:^|[.!?\n]\s*)implement\s+(?:the\s+)?(?:approved|requested|specified|file|code|source|fix(?:es)?|changes?)\b/i,
+	/\bregardless\s+of\s+findings\b/i,
+	/\balways\s+(?:edit|modify|change|fix|patch|apply|implement)\b/i,
+	/\bapply\s+(?:the\s+)?fix(?:es)?\s+directly\b/i,
+	/\bmake\s+(?:the\s+)?code\s+changes\b/i,
+];
+
+// The prohibition's object ends at punctuation or at a coordinating word
+// (but/and/then), so a follow-on clause like "but implement the fix" stays in
+// the text for write-intent testing instead of being swallowed as the object.
+const NO_EDIT_PROHIBITION_PATTERN = /\b(?:do not|don't|must not)\s+(?:edit|modify|write(?:\s+to)?|touch|change)\b((?:(?!\b(?:but|and|then)\b)[^.;,:!?\n–—-])*)/gi;
+
+/** Objects of a no-edit prohibition that mean "the codebase in general" rather than a named scope. */
+const GENERIC_PROHIBITION_OBJECT = /^\s*(?:(?:any|all|the|these|those|your|our|existing|project|product|source|sources|config|configs|repo|repository)[\s/,-]*)*(?:files?|code|codebase|sources?|anything|repo(?:sitory)?)?\s*$/i;
+
+const SCOPED_NO_EDIT_CONSTRAINT_PATTERNS = [
+	/\bdo not edit files?\s+outside\b/i,
+	/\bdo not edit\s+outside\b/i,
+	/\bdo not edit\s+unrelated files?\b/i,
+	/\bdo not change\s+unrelated files?\b/i,
+	/\bdo not modify\s+unrelated files?\b/i,
+];
+
+const NO_TOOL_INTENT_PATTERNS = [
+	/\bno tools? needed\b/i,
+	/\bno tools? required\b/i,
+	/\bwithout using tools\b/i,
+	/\bdo not use tools\b/i,
+	/\bdon't use tools\b/i,
+];
+
+const READ_ONLY_DELIVERABLE_PATTERNS = [
+	/\b(?:draft|write|compose|prepare|produce)\s+(?:(?:a|an|the)\s+)?(?:github\s+)?(?:issue|bug report|issue draft|issue body|proposal|plan|report|summary|findings?|analysis|recommendations?)\b/i,
+	/\b(?:issue|bug report)\s+(?:draft|body|template)\b/i,
+	/\b(?:return|provide|produce)\s+(?:text|markdown|answer|findings?|recommendations?)\s+only\b/i,
+];
+
+const RESEARCH_AGENT_PATTERNS = [
+	/\binvestigate\b/i,
+	/\bscout\b/i,
+	/\bresearch(?:er)?\b/i,
+];
+
+const FIX_OR_PATCH_IMPLEMENTATION_PATTERN = /\b(?:fix|patch)\s+(?:(?:it|this|that|them|each|any|all|these|those)\b|(?:(?:a|an|the|any|all)\s+)?(?:(?:failing|failed|broken|flaky|red|cold|start|current|existing|reported|approved|known|regression|unit|integration|e2e|source|typescript|type-?script|ts|type-?check|compiler)\s+)*(?:bug|defect|issues?|problems?|failures?|regressions?|tests?|errors?|items?|typos?|code|source|implementation|component|function|module|class|method|logic|file|files|readme|docs?|changelog|package\.json|config|manifest|extension|prompt|command|lint(?:ing)?|build|ci|type-?check|type\s+checking)\b)/i;
+
+const WORKER_IMPLEMENTATION_PATTERNS = [
+	/\b(?:implement|edit|modify|refactor|delete)\b/i,
+	FIX_OR_PATCH_IMPLEMENTATION_PATTERN,
+	/\b(?:update|add|remove|replace|create)\b(?!\s+(?:(?:a|an|the)\s+)?(?:report|summary|findings?)(?:\b|$))/i,
+	/\bapply\s+(?:the\s+)?(?:(?:suggested|proposed|recommended)\s+)?(?:changes?|fix(?:es)?|patch)\b/i,
+	/\bmake\s+(?:the\s+)?changes\b/i,
+	/\bdo those fixes\b/i,
+];
+
+const GENERAL_IMPLEMENTATION_PATTERNS = [
+	/\b(?:implement|edit|modify|refactor)\b/i,
+	FIX_OR_PATCH_IMPLEMENTATION_PATTERN,
+	/\bapply\s+(?:the\s+)?(?:(?:suggested|proposed|recommended)\s+)?(?:changes?|fix(?:es)?|patch)\b/i,
+	/\bmake\s+(?:the\s+)?changes\b/i,
+	/\bdo those fixes\b/i,
+	/\b(?:update|add|remove|replace|delete|create)\s+(?:the\s+)?(?:file|files|code|source|implementation|test|tests|component|function|module|class|method|logic|import|imports|readme|docs?|changelog|package\.json|config|manifest|extension|prompt|command)\b/i,
+];
+
+export type TaskMutationIntent = { kind: "implementation" } | { kind: "read-only" } | { kind: "unknown" };
+
+function stripFrameworkInstructions(task: string): string {
+	return task
+		.split("\n")
+		.filter((line) => !/^\s*\[(?:Write to|Read from):/i.test(line))
+		.filter((line) => !/^\s*(?:Create and maintain progress at:|Update progress at:|\*\*Output:\*\*|Write your findings to(?: exactly this path)?:|Return the complete artifact in your final response\.|The runtime will persist it to exactly this path:|Do not call contact_supervisor merely because no write-capable tool is available\.|This path is authoritative for this run\.|Ignore any other output filename or output path mentioned elsewhere)/i.test(line))
+		.join("\n");
+}
+
+function stripPatterns(task: string, patterns: RegExp[]): string {
+	let stripped = task;
+	for (const pattern of patterns) {
+		const flags = pattern.flags.includes("g") ? pattern.flags : `${pattern.flags}g`;
+		stripped = stripped.replace(new RegExp(pattern.source, flags), " ");
+	}
+	return stripped;
+}
+
+interface NoEditProhibitionAnalysis {
+	/** True when any prohibition (or review-only/no-tool wording) is present. */
+	present: boolean;
+	/** True when a prohibition covers files/code in general; such wording wins over write verbs. */
+	blanket: boolean;
+	/** Task text with prohibition phrases and their objects removed, for write-intent testing. */
+	strippedText: string;
+}
+
+function analyzeNoEditProhibitions(taskText: string): NoEditProhibitionAnalysis {
+	let present = REVIEW_ONLY_PATTERNS.some((pattern) => pattern.test(taskText))
+		|| NO_TOOL_INTENT_PATTERNS.some((pattern) => pattern.test(taskText));
+	let blanket = present;
+	let strippedText = stripPatterns(taskText, [...REVIEW_ONLY_PATTERNS, ...NO_TOOL_INTENT_PATTERNS]);
+	strippedText = strippedText.replace(new RegExp(NO_EDIT_PROHIBITION_PATTERN.source, NO_EDIT_PROHIBITION_PATTERN.flags), (_match, object: string) => {
+		present = true;
+		if (GENERIC_PROHIBITION_OBJECT.test(object)) blanket = true;
+		return " ";
+	});
+	return { present, blanket, strippedText };
+}
+
+function taskHasReadOnlyDeliverable(taskText: string): boolean {
+	return READ_ONLY_DELIVERABLE_PATTERNS.some((pattern) => pattern.test(taskText));
+}
+
+function isReviewerStyleAgent(agent: string): boolean {
+	return /\b(?:advisor|reviewer|oracle)\b/i.test(agent);
+}
+
+function hasImplementationIntent(agent: string, taskText: string): boolean {
+	if (isReviewerStyleAgent(agent)) return REVIEWER_REQUIRED_EDIT_PATTERNS.some((pattern) => pattern.test(taskText));
+	if (agent === "worker") return WORKER_IMPLEMENTATION_PATTERNS.some((pattern) => pattern.test(taskText));
+	return GENERAL_IMPLEMENTATION_PATTERNS.some((pattern) => pattern.test(taskText));
+}
+
+export function classifyTaskMutationIntent(agent: string, task: string): TaskMutationIntent {
+	const taskText = stripFrameworkInstructions(task);
+	const taskTextWithoutScopedConstraints = stripPatterns(taskText, SCOPED_NO_EDIT_CONSTRAINT_PATTERNS);
+	const prohibitions = analyzeNoEditProhibitions(taskTextWithoutScopedConstraints);
+	if (prohibitions.present) {
+		if (prohibitions.blanket) return { kind: "read-only" };
+		return hasImplementationIntent(agent, prohibitions.strippedText) ? { kind: "implementation" } : { kind: "read-only" };
+	}
+
+	if (RESEARCH_AGENT_PATTERNS.some((pattern) => pattern.test(agent))) return { kind: "read-only" };
+	if (hasImplementationIntent(agent, taskText)) return { kind: "implementation" };
+	if (isReviewerStyleAgent(agent)) return { kind: "read-only" };
+	return taskHasReadOnlyDeliverable(taskTextWithoutScopedConstraints) ? { kind: "read-only" } : { kind: "unknown" };
+}
+
+export function expectsImplementationMutation(agent: string, task: string): boolean {
+	return classifyTaskMutationIntent(agent, task).kind === "implementation";
+}
+
+/** Bare write verbs that make a task write-capable for acceptance inference. */
+const MAY_MUTATE_VERB_PATTERN = /\b(?:fix|implement|update|write|edit|modify|migrate|delete|remove|refactor|commit)\b/i;
+
+/**
+ * Whether the task could plausibly change files. Blanket prohibitions win;
+ * write verbs inside a scoped prohibition's object or a read-only deliverable
+ * phrase ("write a summary report") do not count; any other bare write verb
+ * does.
+ */
+export function taskMayMutate(task: string): boolean {
+	const taskText = stripPatterns(stripFrameworkInstructions(task), SCOPED_NO_EDIT_CONSTRAINT_PATTERNS);
+	const prohibitions = analyzeNoEditProhibitions(taskText);
+	if (prohibitions.blanket) return false;
+	return MAY_MUTATE_VERB_PATTERN.test(stripPatterns(prohibitions.strippedText, READ_ONLY_DELIVERABLE_PATTERNS));
+}

package/node_modules/pi-subagents/src/runs/shared/tool-availability.ts

@@ -0,0 +1,83 @@
+import * as fs from "node:fs";
+import * as path from "node:path";
+
+export const REQUIRED_CHILD_TOOLS_ENV = "PI_SUBAGENT_REQUIRED_TOOLS";
+export const MCP_DIRECT_CHILD_TOOLS_ENV = "PI_SUBAGENT_MCP_DIRECT_TOOLS";
+export const CHILD_TOOL_DIAGNOSTIC_PATH_ENV = "PI_SUBAGENT_TOOL_DIAGNOSTIC_PATH";
+
+export interface ChildToolDiagnostic {
+	agent?: string;
+	required: string[];
+	available: string[];
+	missing: string[];
+	missingMcpDirectTools?: string[];
+}
+
+const PI_CORE_CHILD_TOOLS = new Set(["bash", "edit", "find", "grep", "ls", "read", "write"]);
+
+export function writeChildToolDiagnostic(
+	filePath: string,
+	required: string[],
+	available: string[],
+	agent?: string,
+	mcpDirectTools?: string[],
+): ChildToolDiagnostic | undefined {
+	const availableNames = new Set([...available, ...PI_CORE_CHILD_TOOLS]);
+	const missing = required.filter((name) => !availableNames.has(name));
+	if (missing.length === 0) {
+		fs.rmSync(filePath, { force: true });
+		return undefined;
+	}
+
+	const missingMcpDirectTools = mcpDirectTools?.length
+		? missing.filter((name) => mcpDirectTools.includes(name))
+		: [];
+	const diagnostic: ChildToolDiagnostic = {
+		agent,
+		required,
+		available,
+		missing,
+		...(missingMcpDirectTools.length > 0 ? { missingMcpDirectTools } : {}),
+	};
+	fs.mkdirSync(path.dirname(filePath), { recursive: true });
+	fs.writeFileSync(filePath, JSON.stringify(diagnostic), { mode: 0o600 });
+	return diagnostic;
+}
+
+export function readChildToolDiagnostic(filePath: string | undefined): ChildToolDiagnostic | undefined {
+	if (!filePath || !fs.existsSync(filePath)) return undefined;
+	const parsed = JSON.parse(fs.readFileSync(filePath, "utf-8")) as Partial<ChildToolDiagnostic>;
+	const stringArray = (value: unknown): value is string[] => Array.isArray(value) && value.every((entry) => typeof entry === "string" && entry.length > 0);
+	if (!stringArray(parsed.required) || !stringArray(parsed.available) || !stringArray(parsed.missing) || (parsed.agent !== undefined && typeof parsed.agent !== "string") || (parsed.missingMcpDirectTools !== undefined && !stringArray(parsed.missingMcpDirectTools))) {
+		throw new Error(`Malformed child tool diagnostic at '${filePath}'.`);
+	}
+	return {
+		...(parsed.agent ? { agent: parsed.agent } : {}),
+		required: parsed.required,
+		available: parsed.available,
+		missing: parsed.missing,
+		...(parsed.missingMcpDirectTools ? { missingMcpDirectTools: parsed.missingMcpDirectTools } : {}),
+	};
+}
+
+export function formatChildToolDiagnostic(diagnostic: ChildToolDiagnostic): string {
+	const subject = diagnostic.agent ? `Agent '${diagnostic.agent}'` : "Subagent";
+	return [
+		`${subject} requested unavailable child tools: ${diagnostic.missing.join(", ")}.`,
+		"The `tools` field is a strict allowlist; it does not load extension code.",
+		...(diagnostic.missingMcpDirectTools?.length
+			? [`Resolved MCP direct tools missing from the child registry: ${diagnostic.missingMcpDirectTools.join(", ")}. This indicates a host/pi-mcp-adapter registration problem, not a tool-call failure.`]
+			: []),
+		"For extension tools, add the provider path to `subagentOnlyExtensions` (child-only), `extensions`, or as a path-like entry in `tools`, while keeping each registered tool name in `tools`.",
+		"For MCP tools, verify the MCP adapter configuration and selected tool names. For builtin tools, verify the name against the installed Pi version.",
+	].join("\n");
+}
+
+export function readChildToolDiagnosticError(filePath: string | undefined): string | undefined {
+	try {
+		const diagnostic = readChildToolDiagnostic(filePath);
+		return diagnostic ? formatChildToolDiagnostic(diagnostic) : undefined;
+	} catch (error) {
+		return `Failed to read child tool availability diagnostic: ${error instanceof Error ? error.message : String(error)}`;
+	}
+}

package/node_modules/pi-subagents/src/runs/shared/tool-budget.ts

@@ -0,0 +1,80 @@
+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 const TOOL_BUDGET_ZERO_AUTH_ENV = "PI_SUBAGENT_TOOL_BUDGET_ZERO_AUTH";
+
+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",
+	options: { minimumHard?: 0 | 1 } = {},
+): { 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;
+	const minimumHard = options.minimumHard ?? 1;
+	if (typeof value.hard !== "number" || !Number.isInteger(value.hard) || value.hard < minimumHard) {
+		return { error: `${label}.hard must be an integer >= ${minimumHard}.` };
+	}
+	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, options: { allowZero?: boolean } = {}): ResolvedToolBudget | undefined {
+	if (!value?.trim()) return undefined;
+	const parsed = JSON.parse(value) as unknown;
+	const normalized = validateToolBudgetConfig(parsed, TOOL_BUDGET_ENV, options.allowZero ? { minimumHard: 0 } : undefined);
+	if (normalized.error) throw new Error(normalized.error);
+	return normalized.budget;
+}

package/node_modules/pi-subagents/src/runs/shared/turn-budget.ts

@@ -0,0 +1,98 @@
+import type { ResolvedTurnBudget, TurnBudgetState } from "../../shared/types.ts";
+
+export const DEFAULT_TURN_BUDGET_GRACE_TURNS = 1;
+
+export function resolveTurnBudgetConfig(
+	raw: unknown,
+	label = "turnBudget",
+): { turnBudget?: ResolvedTurnBudget; error?: string } {
+	if (raw === undefined) return {};
+	if (!raw || typeof raw !== "object" || Array.isArray(raw)) {
+		return { error: `${label} must be an object with maxTurns and optional graceTurns.` };
+	}
+	const unknownField = Object.keys(raw).find((key) => key !== "maxTurns" && key !== "graceTurns");
+	if (unknownField) return { error: `${label}.${unknownField} is not supported.` };
+	const budget = raw as { maxTurns?: unknown; graceTurns?: unknown };
+	if (typeof budget.maxTurns !== "number" || !Number.isInteger(budget.maxTurns) || budget.maxTurns < 1) {
+		return { error: `${label}.maxTurns must be an integer >= 1.` };
+	}
+	const graceTurns = budget.graceTurns ?? DEFAULT_TURN_BUDGET_GRACE_TURNS;
+	if (typeof graceTurns !== "number" || !Number.isInteger(graceTurns) || graceTurns < 0) {
+		return { error: `${label}.graceTurns must be an integer >= 0.` };
+	}
+	return { turnBudget: { maxTurns: budget.maxTurns, graceTurns } };
+}
+
+export function appendTurnBudgetSystemPrompt(systemPrompt: string, budget: { maxTurns: number; graceTurns?: number } | undefined): string {
+	if (!budget) return systemPrompt;
+	const graceTurns = budget.graceTurns ?? DEFAULT_TURN_BUDGET_GRACE_TURNS;
+	const grace = graceTurns === 1 ? "1 additional assistant turn" : `${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 turnBudgetDeferredNote(budget: ResolvedTurnBudget, turnCount: number): string {
+	return `Turn-budget termination was deferred at ${turnCount} assistant turn${turnCount === 1 ? "" : "s"} (soft limit ${budget.maxTurns} + grace ${budget.graceTurns}) because the assistant started tool work. The run ended before another safe assistant boundary; output may be partial.`;
+}
+
+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: { maxTurns: number; graceTurns?: number }): TurnBudgetState {
+	return { maxTurns: budget.maxTurns, graceTurns: budget.graceTurns ?? DEFAULT_TURN_BUDGET_GRACE_TURNS, 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 turnBudgetDeferredState(
+	budget: ResolvedTurnBudget,
+	turnCount: number,
+	terminationDeferredAtTurn = turnCount,
+): TurnBudgetState {
+	return {
+		...budget,
+		turnCount,
+		outcome: "termination-deferred",
+		wrapUpRequestedAtTurn: budget.maxTurns,
+		terminationDeferredAtTurn,
+	};
+}
+
+export function turnBudgetDecision(
+	budget: ResolvedTurnBudget,
+	turnCount: number,
+	terminalAssistantStop: boolean,
+	toolWorkActiveOrStarting: boolean,
+	enforceHardLimit = false,
+): "continue" | "defer" | "abort" {
+	const hardLimit = budget.maxTurns + budget.graceTurns;
+	if (terminalAssistantStop || turnCount < hardLimit) return "continue";
+	if (toolWorkActiveOrStarting && !enforceHardLimit) return "defer";
+	return "abort";
+}

package/node_modules/pi-subagents/src/runs/shared/usage-budget.ts

@@ -0,0 +1,65 @@
+import type { CostSummary, UsageBudgetConfig, UsageBudgetLimitConfig, UsageBudgetState } from "../../shared/types.ts";
+
+function validateLimit(value: unknown, label: string): { limit?: UsageBudgetLimitConfig; error?: string } {
+	if (!value || typeof value !== "object" || Array.isArray(value)) return { error: `${label} must be an object.` };
+	const raw = value as Record<string, unknown>;
+	const unknown = Object.keys(raw).find((key) => key !== "soft" && key !== "hard");
+	if (unknown) return { error: `${label}.${unknown} is not supported.` };
+	if (typeof raw.hard !== "number" || !Number.isFinite(raw.hard) || raw.hard <= 0) return { error: `${label}.hard must be a positive number.` };
+	if (raw.soft !== undefined && (typeof raw.soft !== "number" || !Number.isFinite(raw.soft) || raw.soft <= 0)) return { error: `${label}.soft must be a positive number.` };
+	if (typeof raw.soft === "number" && raw.soft > raw.hard) return { error: `${label}.soft must be less than or equal to ${label}.hard.` };
+	return { limit: { ...(typeof raw.soft === "number" ? { soft: raw.soft } : {}), hard: raw.hard } };
+}
+
+export function validateUsageBudgetConfig(value: unknown, label = "usageBudget"): { budget?: UsageBudgetConfig; error?: string } {
+	if (value === undefined) return {};
+	if (!value || typeof value !== "object" || Array.isArray(value)) return { error: `${label} must be an object.` };
+	const raw = value as Record<string, unknown>;
+	const unknown = Object.keys(raw).find((key) => key !== "tokens" && key !== "costUsd");
+	if (unknown) return { error: `${label}.${unknown} is not supported.` };
+	const budget: UsageBudgetConfig = {};
+	if (raw.tokens !== undefined) {
+		const tokens = validateLimit(raw.tokens, `${label}.tokens`);
+		if (tokens.error) return { error: tokens.error };
+		budget.tokens = tokens.limit;
+	}
+	if (raw.costUsd !== undefined) {
+		const costUsd = validateLimit(raw.costUsd, `${label}.costUsd`);
+		if (costUsd.error) return { error: costUsd.error };
+		budget.costUsd = costUsd.limit;
+	}
+	if (!budget.tokens && !budget.costUsd) return { error: `${label} must include tokens or costUsd.` };
+	return { budget };
+}
+
+function metricState(limit: UsageBudgetLimitConfig | undefined, used: number): UsageBudgetState["tokens"] {
+	if (!limit) return undefined;
+	return {
+		...limit,
+		used,
+		outcome: used >= limit.hard ? "hard-exceeded" : limit.soft !== undefined && used >= limit.soft ? "soft-exceeded" : "within-budget",
+	};
+}
+
+export function usageBudgetState(config: UsageBudgetConfig | undefined, totals: CostSummary | undefined): UsageBudgetState | undefined {
+	if (!config) return undefined;
+	const inputTokens = totals?.inputTokens ?? 0;
+	const outputTokens = totals?.outputTokens ?? 0;
+	const tokens = metricState(config.tokens, inputTokens + outputTokens);
+	const costUsd = metricState(config.costUsd, totals?.costUsd ?? 0);
+	const reason = tokens?.outcome === "hard-exceeded" ? "tokens" : costUsd?.outcome === "hard-exceeded" ? "costUsd" : undefined;
+	return {
+		version: 1,
+		source: "reported",
+		...(tokens ? { tokens } : {}),
+		...(costUsd ? { costUsd } : {}),
+		exhausted: reason !== undefined,
+		...(reason ? { reason } : {}),
+	};
+}
+
+export function usageBudgetExceededMessage(state: UsageBudgetState): string {
+	if (state.reason === "tokens" && state.tokens) return `Usage budget exhausted: reported tokens ${state.tokens.used} reached hard limit ${state.tokens.hard}.`;
+	if (state.reason === "costUsd" && state.costUsd) return `Usage budget exhausted: reported cost $${state.costUsd.used.toFixed(6)} reached hard limit $${state.costUsd.hard.toFixed(6)}.`;
+	return "Usage budget exhausted.";
+}