pi-subagents 0.69.0 → 0.70.0

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

@@ -1,128 +0,0 @@
-import {
-	resolveMaxSubagentSpawnsPerSession,
-	type ExtensionConfig,
-	type SpawnBudgetSnapshot,
-	type SubagentState,
-} from "../../shared/types.ts";
-
-const MAX_GRANT_HISTORY = 20;
-
-function sessionState(state: SubagentState, config: ExtensionConfig, sessionId: string | null) {
-	let counters = state.subagentSpawns;
-	if (!counters || counters.sessionId !== sessionId) {
-		counters = {
-			sessionId,
-			count: 0,
-			configuredLimit: resolveMaxSubagentSpawnsPerSession(config.maxSubagentSpawnsPerSession) ?? null,
-			granted: 0,
-			grantHistory: [],
-		};
-		state.subagentSpawns = counters;
-	}
-	if (counters.configuredLimit === undefined) {
-		counters.configuredLimit = resolveMaxSubagentSpawnsPerSession(config.maxSubagentSpawnsPerSession) ?? null;
-	}
-	counters.granted ??= 0;
-	counters.grantHistory ??= [];
-	return counters;
-}
-
-export function getSpawnBudgetSnapshot(
-	state: SubagentState,
-	config: ExtensionConfig,
-	sessionId: string | null = state.currentSessionId,
-): SpawnBudgetSnapshot {
-	const counters = sessionState(state, config, sessionId);
-	const configuredLimit = counters.configuredLimit ?? null;
-	const granted = configuredLimit === null ? 0 : counters.granted ?? 0;
-	const limit = configuredLimit === null ? null : configuredLimit + granted;
-	return {
-		used: counters.count,
-		configuredLimit,
-		granted,
-		limit,
-		remaining: limit === null ? null : Math.max(0, limit - counters.count),
-		grantRemaining: configuredLimit === null ? null : Math.max(0, configuredLimit - granted),
-		grantHistory: [...(counters.grantHistory ?? [])],
-	};
-}
-
-export function formatSpawnBudgetSummary(snapshot: SpawnBudgetSnapshot): string {
-	if (snapshot.limit === null) return "unlimited";
-	return `${snapshot.used}/${snapshot.limit} used, ${snapshot.remaining} remaining (configured ${snapshot.configuredLimit}; granted ${snapshot.granted}; grant allowance ${snapshot.grantRemaining})`;
-}
-
-export function formatSpawnBudget(snapshot: SpawnBudgetSnapshot): string {
-	return `Spawn budget: ${formatSpawnBudgetSummary(snapshot)}`;
-}
-
-export function preflightSpawnBudget(
-	state: SubagentState,
-	config: ExtensionConfig,
-	sessionId: string | null,
-	requested: number,
-): { snapshot: SpawnBudgetSnapshot; error?: string } {
-	const snapshot = getSpawnBudgetSnapshot(state, config, sessionId);
-	if (requested <= 0 || snapshot.limit === null || requested <= (snapshot.remaining ?? 0)) return { snapshot };
-	return {
-		snapshot,
-		error: `Subagent spawn limit reached for this session (${snapshot.used}/${snapshot.limit} used, ${requested} requested). ${snapshot.remaining} remaining; the declared run cannot fit, so no children were started. Grant budget explicitly from the root interactive session or start a new session.`,
-	};
-}
-
-export function reserveSpawnBudget(
-	state: SubagentState,
-	config: ExtensionConfig,
-	sessionId: string | null,
-	requested: number,
-): { snapshot: SpawnBudgetSnapshot; error?: string } {
-	const checked = preflightSpawnBudget(state, config, sessionId, requested);
-	if (checked.error || requested <= 0 || checked.snapshot.limit === null) return checked;
-	state.subagentSpawns!.count += requested;
-	return { snapshot: getSpawnBudgetSnapshot(state, config, sessionId) };
-}
-
-export function preflightSpawnBudgetGrant(
-	state: SubagentState,
-	config: ExtensionConfig,
-	sessionId: string,
-	additional: number,
-): { snapshot: SpawnBudgetSnapshot; error?: string } {
-	const snapshot = getSpawnBudgetSnapshot(state, config, sessionId);
-	if (!Number.isInteger(additional) || additional <= 0) {
-		return { snapshot, error: "action='grant-spawn-budget' requires additional to be a positive integer." };
-	}
-	if (snapshot.configuredLimit === null || snapshot.limit === null) {
-		return { snapshot, error: "The current session has no configured spawn cap, so it does not need a budget grant." };
-	}
-	if (additional > (snapshot.grantRemaining ?? 0)) {
-		return {
-			snapshot,
-			error: `Spawn budget grant rejected: ${additional} requested but only ${snapshot.grantRemaining} of the original configured limit remains grantable.`,
-		};
-	}
-	return { snapshot };
-}
-
-export function grantSpawnBudget(
-	state: SubagentState,
-	config: ExtensionConfig,
-	sessionId: string,
-	additional: number,
-	now = Date.now(),
-): { snapshot: SpawnBudgetSnapshot; error?: string } {
-	const checked = preflightSpawnBudgetGrant(state, config, sessionId, additional);
-	if (checked.error) return checked;
-	const before = checked.snapshot;
-	if (before.limit === null) {
-		return { snapshot: before, error: "The current session has no configured spawn cap, so it does not need a budget grant." };
-	}
-	const counters = state.subagentSpawns!;
-	counters.granted = (counters.granted ?? 0) + additional;
-	const limit = before.limit + additional;
-	counters.grantHistory = [
-		...(counters.grantHistory ?? []),
-		{ sessionId, amount: additional, grantedAt: now, previousLimit: before.limit, limit },
-	].slice(-MAX_GRANT_HISTORY);
-	return { snapshot: getSpawnBudgetSnapshot(state, config, sessionId) };
-}

package/src/runs/shared/structured-output.ts

@@ -1,236 +0,0 @@
-import * as fs from "node:fs";
-import { createRequire } from "node:module";
-import * as os from "node:os";
-import * as path from "node:path";
-import { pathToFileURL } from "node:url";
-import { PI_CODING_AGENT_PACKAGE_ROOT_ENV } from "../../shared/utils.ts";
-import type { JsonSchemaObject } from "../../shared/types.ts";
-import type { ResolvedAcceptanceReportMode } from "./acceptance.ts";
-
-export const MISSING_STRUCTURED_OUTPUT_CALL_ERROR = "Missing structured_output call; this step has outputSchema and must finish by calling structured_output.";
-export const MISSING_STRUCTURED_ACCEPTANCE_REPORT_ERROR = "Missing acceptanceReport in structured_output call; acceptance.report is \"on\".";
-
-export interface StructuredOutputRuntime {
-	schema: JsonSchemaObject;
-	schemaPath: string;
-	outputPath: string;
-	acceptanceReportPath?: string;
-	acceptanceReportRequired?: boolean;
-}
-
-const SCHEMA_MAP_KEYWORDS = ["properties", "patternProperties", "$defs", "definitions", "dependentSchemas"] as const;
-const SCHEMA_SINGLE_KEYWORDS = ["additionalItems", "additionalProperties", "contains", "not", "propertyNames", "if", "then", "else", "unevaluatedItems", "unevaluatedProperties", "contentSchema"] as const;
-const SCHEMA_ARRAY_KEYWORDS = ["allOf", "anyOf", "oneOf", "prefixItems"] as const;
-
-function rewriteLocalJsonPointerRefs(schema: unknown, pointerPrefix: string, inheritsWrapperResource = true): unknown {
-	if (typeof schema === "boolean" || !schema || typeof schema !== "object" || Array.isArray(schema)) return schema;
-	const source = schema as Record<string, unknown>;
-	const rewritten: Record<string, unknown> = { ...source };
-	const sharesWrapperResource = inheritsWrapperResource && typeof source.$id !== "string";
-	if (sharesWrapperResource) {
-		for (const keyword of ["$ref", "$dynamicRef", "$recursiveRef"] as const) {
-			const ref = source[keyword];
-			if (ref === "#") rewritten[keyword] = pointerPrefix;
-			else if (typeof ref === "string" && ref.startsWith("#/")) rewritten[keyword] = `${pointerPrefix}${ref.slice(1)}`;
-		}
-	}
-	for (const keyword of SCHEMA_MAP_KEYWORDS) {
-		const entries = source[keyword];
-		if (!entries || typeof entries !== "object" || Array.isArray(entries)) continue;
-		rewritten[keyword] = Object.fromEntries(Object.entries(entries).map(([name, nested]) => [
-			name,
-			rewriteLocalJsonPointerRefs(nested, pointerPrefix, sharesWrapperResource),
-		]));
-	}
-	const items = source.items;
-	if (Array.isArray(items)) rewritten.items = items.map((nested) => rewriteLocalJsonPointerRefs(nested, pointerPrefix, sharesWrapperResource));
-	else if (items !== undefined) rewritten.items = rewriteLocalJsonPointerRefs(items, pointerPrefix, sharesWrapperResource);
-	for (const keyword of SCHEMA_SINGLE_KEYWORDS) {
-		if (source[keyword] !== undefined) rewritten[keyword] = rewriteLocalJsonPointerRefs(source[keyword], pointerPrefix, sharesWrapperResource);
-	}
-	for (const keyword of SCHEMA_ARRAY_KEYWORDS) {
-		if (Array.isArray(source[keyword])) rewritten[keyword] = source[keyword].map((nested) => rewriteLocalJsonPointerRefs(nested, pointerPrefix, sharesWrapperResource));
-	}
-	const dependencies = source.dependencies;
-	if (dependencies && typeof dependencies === "object" && !Array.isArray(dependencies)) {
-		rewritten.dependencies = Object.fromEntries(Object.entries(dependencies).map(([name, nested]) => [
-			name,
-			Array.isArray(nested) ? nested : rewriteLocalJsonPointerRefs(nested, pointerPrefix, sharesWrapperResource),
-		]));
-	}
-	return rewritten;
-}
-
-export function createStructuredOutputToolParameters(schema: JsonSchemaObject, options: { acceptanceReport?: "optional" | "required" } = {}): JsonSchemaObject {
-	return {
-		type: "object",
-		properties: {
-			value: rewriteLocalJsonPointerRefs(schema, "#/properties/value"),
-			...(options.acceptanceReport ? { acceptanceReport: { type: "object" } } : {}),
-		},
-		required: ["value", ...(options.acceptanceReport === "required" ? ["acceptanceReport"] : [])],
-		additionalProperties: false,
-	};
-}
-
-interface CompiledJsonSchema {
-	Check(value: unknown): boolean;
-	Errors(value: unknown): Iterable<{ instancePath?: string; message?: string }>;
-}
-
-type CompileJsonSchema = (schema: unknown) => CompiledJsonSchema;
-
-let cachedCompile: Promise<CompileJsonSchema> | undefined;
-
-export async function resolveCompileFromPackageRoot(packageRoot: string): Promise<CompileJsonSchema | undefined> {
-	const requireFromRoot = createRequire(path.join(packageRoot, "package.json"));
-	const resolved = requireFromRoot.resolve("typebox/compile");
-	const mod = (await import(pathToFileURL(resolved).href)) as { Compile?: unknown };
-	return typeof mod.Compile === "function" ? (mod.Compile as CompileJsonSchema) : undefined;
-}
-
-async function importCompile(): Promise<CompileJsonSchema> {
-	const failures: string[] = [];
-	try {
-		const mod = (await import("typebox/compile")) as { Compile?: unknown };
-		if (typeof mod.Compile === "function") return mod.Compile as CompileJsonSchema;
-		failures.push("typebox/compile did not export a Compile function");
-	} catch (error) {
-		failures.push(`direct import failed: ${error instanceof Error ? error.message : String(error)}`);
-	}
-	const packageRoot = process.env[PI_CODING_AGENT_PACKAGE_ROOT_ENV];
-	if (packageRoot) {
-		try {
-			const compile = await resolveCompileFromPackageRoot(packageRoot);
-			if (compile) return compile;
-			failures.push("Pi package root typebox/compile did not export a Compile function");
-		} catch (error) {
-			failures.push(`Pi package root import failed: ${error instanceof Error ? error.message : String(error)}`);
-		}
-	} else {
-		failures.push(`${PI_CODING_AGENT_PACKAGE_ROOT_ENV} is not set`);
-	}
-	throw new Error(`Cannot load typebox/compile for structured output validation (${failures.join("; ")})`);
-}
-
-function loadCompile(): Promise<CompileJsonSchema> {
-	if (!cachedCompile) {
-		cachedCompile = importCompile().catch((error) => {
-			cachedCompile = undefined;
-			throw error;
-		});
-	}
-	return cachedCompile;
-}
-
-export function assertJsonSchemaObject(schema: unknown, label = "outputSchema"): asserts schema is JsonSchemaObject {
-	if (!schema || typeof schema !== "object" || Array.isArray(schema)) {
-		throw new Error(`${label} must be a JSON Schema object.`);
-	}
-}
-
-export function createStructuredOutputRuntime(schema: JsonSchemaObject, baseDir?: string, options: { acceptanceReport?: ResolvedAcceptanceReportMode } = {}): StructuredOutputRuntime {
-	assertJsonSchemaObject(schema);
-	const rootDir = baseDir ?? os.tmpdir();
-	fs.mkdirSync(rootDir, { recursive: true });
-	const dir = fs.mkdtempSync(path.join(rootDir, "pi-subagent-structured-"));
-	const schemaPath = path.join(dir, "schema.json");
-	const outputPath = path.join(dir, "output.json");
-	fs.writeFileSync(schemaPath, JSON.stringify(schema), { mode: 0o600 });
-	return {
-		schema,
-		schemaPath,
-		outputPath,
-		...(options.acceptanceReport && options.acceptanceReport !== "off"
-			? { acceptanceReportPath: path.join(dir, "acceptance-report.json"), acceptanceReportRequired: options.acceptanceReport === "required" }
-			: {}),
-	};
-}
-
-export async function validateStructuredOutputValue(schema: JsonSchemaObject, value: unknown): Promise<{ status: "valid" } | { status: "invalid"; message: string }> {
-	const compile = await loadCompile();
-	let validator: CompiledJsonSchema;
-	try {
-		validator = compile(schema);
-	} catch (error) {
-		return { status: "invalid", message: `invalid outputSchema: ${error instanceof Error ? error.message : String(error)}` };
-	}
-	if (validator.Check(value)) return { status: "valid" };
-	const errors = [...validator.Errors(value)]
-		.slice(0, 8)
-		.map((error) => {
-			const pathText = error.instancePath ? error.instancePath.replace(/^\//, "").replace(/\//g, ".") : "root";
-			return `${pathText}: ${error.message}`;
-		});
-	return { status: "invalid", message: errors.join("; ") || "schema validation failed" };
-}
-
-export async function readStructuredOutput(runtime: StructuredOutputRuntime): Promise<{ value?: unknown; error?: string }> {
-	if (!fs.existsSync(runtime.outputPath)) {
-		return { error: MISSING_STRUCTURED_OUTPUT_CALL_ERROR };
-	}
-	let value: unknown;
-	try {
-		value = JSON.parse(fs.readFileSync(runtime.outputPath, "utf-8"));
-	} catch (error) {
-		return { error: `Failed to read structured output: ${error instanceof Error ? error.message : String(error)}` };
-	}
-	try {
-		const validation = await validateStructuredOutputValue(runtime.schema, value);
-		if (validation.status === "invalid") return { error: `Structured output validation failed: ${validation.message}` };
-	} catch (error) {
-		return { error: `Failed to validate structured output: ${error instanceof Error ? error.message : String(error)}` };
-	}
-	return { value };
-}
-
-export function readStructuredOutputAcceptanceReport(runtime: StructuredOutputRuntime): { value?: unknown; error?: string } {
-	if (!runtime.acceptanceReportPath) return {};
-	if (!fs.existsSync(runtime.acceptanceReportPath)) {
-		return runtime.acceptanceReportRequired ? { error: MISSING_STRUCTURED_ACCEPTANCE_REPORT_ERROR } : {};
-	}
-	try {
-		return { value: JSON.parse(fs.readFileSync(runtime.acceptanceReportPath, "utf-8")) as unknown };
-	} catch (error) {
-		return { error: `Failed to read structured output acceptance report: ${error instanceof Error ? error.message : String(error)}` };
-	}
-}
-
-/**
- * Capture callback that persists the structured output (and acceptance report)
- * to the runtime's files, for hosts that read the value back from disk.
- */
-export function createStructuredOutputFileCapture(runtime: StructuredOutputRuntime): (value: unknown, acceptanceReport: unknown | undefined) => void {
-	return (value, acceptanceReport) => {
-		fs.mkdirSync(path.dirname(runtime.outputPath), { recursive: true });
-		if (runtime.acceptanceReportPath && acceptanceReport !== undefined) {
-			fs.mkdirSync(path.dirname(runtime.acceptanceReportPath), { recursive: true });
-			fs.writeFileSync(runtime.acceptanceReportPath, JSON.stringify(acceptanceReport), { mode: 0o600 });
-		} else if (runtime.acceptanceReportPath && fs.existsSync(runtime.acceptanceReportPath)) {
-			fs.unlinkSync(runtime.acceptanceReportPath);
-		}
-		fs.writeFileSync(runtime.outputPath, JSON.stringify(value), { mode: 0o600 });
-	};
-}
-
-export function clearStructuredOutputCaptures(runtime: StructuredOutputRuntime): string | undefined {
-	let cleanupError: string | undefined;
-	for (const filePath of [runtime.outputPath, runtime.acceptanceReportPath]) {
-		if (!filePath) continue;
-		try {
-			if (fs.existsSync(filePath)) fs.unlinkSync(filePath);
-		} catch (error) {
-			cleanupError ??= `Failed to clear stale structured output capture ${filePath}: ${error instanceof Error ? error.message : String(error)}`;
-		}
-	}
-	return cleanupError;
-}
-
-export function cleanupStructuredOutputRuntime(runtime: StructuredOutputRuntime | undefined): void {
-	if (!runtime) return;
-	try {
-		fs.rmSync(path.dirname(runtime.schemaPath), { recursive: true, force: true });
-	} catch {
-		// Best-effort temp cleanup.
-	}
-}

package/src/runs/shared/subagent-control.ts

@@ -1,294 +0,0 @@
-import {
-	type ActivityState,
-	type ControlConfig,
-	type ControlEvent,
-	type ControlEventType,
-	type ControlNotificationChannel,
-	type ResolvedControlConfig,
-} from "../../shared/types.ts";
-import { isToolTimeoutExempt } from "./tool-timeout.ts";
-import { createHash } from "node:crypto";
-import { previewDisplayText } from "../../shared/display-text.ts";
-
-const CONTROL_EVENT_TYPES: ControlEventType[] = ["active_long_running", "needs_attention"];
-const CONTROL_NOTIFICATION_CHANNELS: ControlNotificationChannel[] = ["event", "async", "intercom"];
-const DEFAULT_NOTIFY_ON: ControlEventType[] = ["active_long_running", "needs_attention"];
-
-export const DEFAULT_CONTROL_CONFIG: ResolvedControlConfig = {
-	enabled: true,
-	needsAttentionAfterMs: 60_000,
-	needsAttentionAfterMsIsExplicit: false,
-	activeNoticeAfterMs: 240_000,
-	failedToolAttemptsBeforeAttention: 3,
-	notifyOn: DEFAULT_NOTIFY_ON,
-	notifyChannels: CONTROL_NOTIFICATION_CHANNELS,
-};
-
-function parsePositiveInt(value: unknown): number | undefined {
-	if (typeof value !== "number") return undefined;
-	if (!Number.isFinite(value) || !Number.isInteger(value) || value < 1) return undefined;
-	return value;
-}
-
-function parseControlList<T extends string>(value: unknown, allowed: readonly T[]): T[] | undefined {
-	if (!Array.isArray(value)) return undefined;
-	if (value.length === 0) return [];
-	const allowedSet = new Set(allowed);
-	const parsed = value.filter((entry): entry is T => typeof entry === "string" && allowedSet.has(entry as T));
-	return parsed.length > 0 ? Array.from(new Set(parsed)) : undefined;
-}
-
-export function resolveControlConfig(
-	globalConfig?: ControlConfig,
-	override?: ControlConfig,
-): ResolvedControlConfig {
-	const enabled = override?.enabled ?? globalConfig?.enabled ?? DEFAULT_CONTROL_CONFIG.enabled;
-	const overrideNeedsAttentionAfterMs = parsePositiveInt(override?.needsAttentionAfterMs);
-	const globalNeedsAttentionAfterMs = parsePositiveInt(globalConfig?.needsAttentionAfterMs);
-	const globalNeedsAttentionAfterMsIsExplicit = (globalConfig as Partial<ResolvedControlConfig> | undefined)?.needsAttentionAfterMsIsExplicit ?? globalNeedsAttentionAfterMs !== undefined;
-	const needsAttentionAfterMs = overrideNeedsAttentionAfterMs
-		?? globalNeedsAttentionAfterMs
-		?? DEFAULT_CONTROL_CONFIG.needsAttentionAfterMs;
-	const needsAttentionAfterMsIsExplicit = overrideNeedsAttentionAfterMs !== undefined
-		|| globalNeedsAttentionAfterMsIsExplicit;
-	const activeNoticeAfterMs = parsePositiveInt(override?.activeNoticeAfterMs)
-		?? parsePositiveInt(globalConfig?.activeNoticeAfterMs)
-		?? DEFAULT_CONTROL_CONFIG.activeNoticeAfterMs;
-	const activeNoticeAfterTurns = parsePositiveInt(override?.activeNoticeAfterTurns)
-		?? parsePositiveInt(globalConfig?.activeNoticeAfterTurns);
-	const activeNoticeAfterTokens = parsePositiveInt(override?.activeNoticeAfterTokens)
-		?? parsePositiveInt(globalConfig?.activeNoticeAfterTokens);
-	const failedToolAttemptsBeforeAttention = parsePositiveInt(override?.failedToolAttemptsBeforeAttention)
-		?? parsePositiveInt(globalConfig?.failedToolAttemptsBeforeAttention)
-		?? DEFAULT_CONTROL_CONFIG.failedToolAttemptsBeforeAttention;
-	const notifyOn = parseControlList(override?.notifyOn, CONTROL_EVENT_TYPES)
-		?? parseControlList(globalConfig?.notifyOn, CONTROL_EVENT_TYPES)
-		?? DEFAULT_CONTROL_CONFIG.notifyOn;
-	const notifyChannels = parseControlList(override?.notifyChannels, CONTROL_NOTIFICATION_CHANNELS)
-		?? parseControlList(globalConfig?.notifyChannels, CONTROL_NOTIFICATION_CHANNELS)
-		?? DEFAULT_CONTROL_CONFIG.notifyChannels;
-	return {
-		enabled,
-		needsAttentionAfterMs,
-		needsAttentionAfterMsIsExplicit,
-		activeNoticeAfterMs,
-		activeNoticeAfterTurns,
-		activeNoticeAfterTokens,
-		failedToolAttemptsBeforeAttention,
-		notifyOn: [...notifyOn],
-		notifyChannels: [...notifyChannels],
-	};
-}
-
-function scaledNeedsAttentionAfterMs(config: ResolvedControlConfig, thinking?: string | false): number {
-	if (config.needsAttentionAfterMsIsExplicit !== false) return config.needsAttentionAfterMs;
-	switch (thinking) {
-		case "medium":
-			return config.needsAttentionAfterMs * 2;
-		case "high":
-			return config.needsAttentionAfterMs * 5;
-		case "xhigh":
-		case "max":
-			return config.needsAttentionAfterMs * 10;
-		default:
-			return config.needsAttentionAfterMs;
-	}
-}
-
-export function deriveActivityState(input: {
-	config: ResolvedControlConfig;
-	startedAt: number;
-	lastActivityAt?: number;
-	turnCount?: number;
-	currentTool?: string;
-	thinking?: string | false;
-	now?: number;
-}): ActivityState | undefined {
-	if (!input.config.enabled || input.currentTool || (input.turnCount ?? 0) === 0) return undefined;
-	const now = input.now ?? Date.now();
-	const lastActivity = input.lastActivityAt ?? input.startedAt;
-	const ageMs = Math.max(0, now - lastActivity);
-	return ageMs > scaledNeedsAttentionAfterMs(input.config, input.thinking) ? "needs_attention" : undefined;
-}
-
-export function shouldEmitOpenToolAttention(input: {
-	config: ResolvedControlConfig;
-	currentTool?: string;
-	currentToolStartedAt?: number;
-	now?: number;
-}): boolean {
-	if (!input.config.enabled || !input.currentTool || input.currentToolStartedAt === undefined) return false;
-	if (isToolTimeoutExempt(input.currentTool)) return false;
-	const now = input.now ?? Date.now();
-	return Math.max(0, now - input.currentToolStartedAt) >= input.config.activeNoticeAfterMs;
-}
-
-export function buildControlEvent(input: {
-	type?: ControlEventType;
-	from?: ActivityState;
-	to: ActivityState;
-	runId: string;
-	agent: string;
-	index?: number;
-	ts?: number;
-	lastActivityAt?: number;
-	message?: string;
-	reason?: ControlEvent["reason"];
-	turns?: number;
-	tokens?: number;
-	toolCount?: number;
-	currentTool?: string;
-	toolCallId?: string;
-	currentToolDurationMs?: number;
-	currentPath?: string;
-	elapsedMs?: number;
-	recentFailureSummary?: string;
-	workflowKey?: string;
-	phase?: string;
-	label?: string;
-	taskPreview?: string;
-}): ControlEvent {
-	const ts = input.ts ?? Date.now();
-	const type = input.type ?? (input.to === "active_long_running" ? "active_long_running" : "needs_attention");
-	const elapsedMs = input.elapsedMs ?? (input.lastActivityAt ? Math.max(0, ts - input.lastActivityAt) : undefined);
-	const elapsedSeconds = elapsedMs !== undefined ? Math.floor(elapsedMs / 1000) : undefined;
-	const message = input.message ?? (type === "active_long_running"
-		? `${input.agent} is still active but long-running`
-		: elapsedSeconds !== undefined
-			? `${input.agent} needs attention (no observed activity for ${elapsedSeconds}s)`
-			: `${input.agent} needs attention`);
-	return {
-		type,
-		...(input.from ? { from: input.from } : {}),
-		to: input.to,
-		ts,
-		runId: input.runId,
-		agent: input.agent,
-		...(input.index !== undefined ? { index: input.index } : {}),
-		message,
-		reason: input.reason ?? (type === "active_long_running" ? "active_long_running" : "idle"),
-		...(input.turns !== undefined ? { turns: input.turns } : {}),
-		...(input.tokens !== undefined ? { tokens: input.tokens } : {}),
-		...(input.toolCount !== undefined ? { toolCount: input.toolCount } : {}),
-		...(input.currentTool ? { currentTool: input.currentTool } : {}),
-		...(input.toolCallId ? { toolCallId: input.toolCallId } : {}),
-		...(input.currentToolDurationMs !== undefined ? { currentToolDurationMs: input.currentToolDurationMs } : {}),
-		...(input.currentPath ? { currentPath: input.currentPath } : {}),
-		...(elapsedMs !== undefined ? { elapsedMs } : {}),
-		...(input.recentFailureSummary ? { recentFailureSummary: input.recentFailureSummary } : {}),
-		...(input.workflowKey ? { workflowKey: input.workflowKey } : {}),
-		...(input.phase ? { phase: input.phase } : {}),
-		...(input.label ? { label: input.label } : {}),
-		...(input.taskPreview ? { taskPreview: previewDisplayText(input.taskPreview, 160) } : {}),
-	};
-}
-
-export function shouldNotifyControlEvent(config: ResolvedControlConfig, event: ControlEvent): boolean {
-	return config.enabled && config.notifyOn.includes(event.type);
-}
-
-export function controlNotificationKey(event: ControlEvent, childIntercomTarget?: string): string {
-	const childKey = childIntercomTarget ?? (event.index !== undefined ? `${event.runId}:${event.index}` : event.runId);
-	const contextHash = createHash("sha256").update(formatControlNudge(event)).digest("hex").slice(0, 8);
-	return `${childKey}:${event.type}:${event.reason ?? "idle"}:${contextHash}`;
-}
-
-export function claimControlNotification(config: ResolvedControlConfig, event: ControlEvent, seenKeys: Set<string>, childIntercomTarget?: string): boolean {
-	if (!shouldNotifyControlEvent(config, event)) return false;
-	const key = controlNotificationKey(event, childIntercomTarget);
-	if (seenKeys.has(key)) return false;
-	seenKeys.add(key);
-	return true;
-}
-
-function formatLongRunningFacts(event: ControlEvent): string | undefined {
-	const facts: string[] = [];
-	if (event.elapsedMs !== undefined) facts.push(`elapsed ${Math.floor(Math.max(0, event.elapsedMs) / 1000)}s`);
-	if (event.turns !== undefined) facts.push(`${event.turns} turns`);
-	if (event.tokens !== undefined) facts.push(`${event.tokens} tokens`);
-	if (event.toolCount !== undefined) facts.push(`${event.toolCount} tools`);
-	if (event.currentTool) facts.push(`tool ${event.currentTool}${event.currentToolDurationMs !== undefined ? ` ${Math.floor(Math.max(0, event.currentToolDurationMs) / 1000)}s` : ""}`);
-	if (event.currentPath) facts.push(`path ${event.currentPath}`);
-	return facts.length > 0 ? facts.join(" | ") : undefined;
-}
-
-export function formatControlNudge(event: ControlEvent): string {
-	const scope = event.label ?? event.phase ?? event.workflowKey ?? event.taskPreview;
-	if (event.recentFailureSummary) return previewDisplayText(`Resolve the recent failure${scope ? ` for ${scope}` : ""}: ${event.recentFailureSummary}. Report the smallest next step or ask for a decision.`, 160);
-	if (event.currentTool || event.currentPath) {
-		const current = [event.currentTool ? `tool ${event.currentTool}` : undefined, event.currentPath ? `path ${event.currentPath}` : undefined].filter(Boolean).join(" at ");
-		return previewDisplayText(`Check ${current}${scope ? ` for ${scope}` : ""}. Report the smallest next step or ask for a decision.`, 160);
-	}
-	if (scope) return previewDisplayText(`Continue ${scope}. Report the smallest next step or ask for a decision.`, 160);
-	return "What are you blocked on? Reply with the smallest next step or ask for a decision.";
-}
-
-export function formatControlNoticeMessage(event: ControlEvent, childIntercomTarget?: string): string {
-	const runTarget = event.runId;
-	if (event.reason === "completion_guard") {
-		return [
-			`Subagent failed: ${event.agent}`,
-			`Run: ${runTarget}${event.index !== undefined ? ` step ${event.index + 1}` : ""}`,
-			`Signal: ${event.message}`,
-			"Next: read the output artifact or session from the subagent result, then retry with a more explicit implementation prompt or handle the fix directly.",
-			childIntercomTarget ? `Run intercom target (may be inactive): ${childIntercomTarget}` : undefined,
-		].filter((line): line is string => Boolean(line)).join("\n");
-	}
-
-	const nudgeMessage = formatControlNudge(event);
-	const steerCommand = `subagent({ action: "steer", id: "${runTarget}", ${event.index !== undefined ? `index: ${event.index}, ` : ""}message: ${JSON.stringify(nudgeMessage)} })`;
-	const nestedResumeCommand = `subagent({ action: "resume", id: "${runTarget}", message: ${JSON.stringify(nudgeMessage)} })`;
-	if (event.type === "active_long_running") {
-		const facts = formatLongRunningFacts(event);
-		return [
-			`Subagent active but long-running: ${event.agent}`,
-			`Run: ${runTarget}${event.index !== undefined ? ` step ${event.index + 1}` : ""}`,
-			`Signal: ${event.message}`,
-			facts ? `Facts: ${facts}` : undefined,
-			"Hint: Inspect status first. Use steer for a top-level live async child, routed resume for a live nested child, or resume to revive a paused/completed/failed child.",
-			`Top-level live async nudge: ${steerCommand}`,
-			`Routed live nested nudge: ${nestedResumeCommand}`,
-			childIntercomTarget ? `Direct intercom target: ${childIntercomTarget}` : undefined,
-			`Status: subagent({ action: "status", id: "${runTarget}" })`,
-			`Interrupt: subagent({ action: "interrupt", id: "${runTarget}" })`,
-		].filter((line): line is string => Boolean(line)).join("\n");
-	}
-
-	const supervisorHint = event.reason === "supervisor_request"
-		? "Supervisor request: reply to the pending request. If subagent_supervisor pending is empty, check intercom pending because an external intercom tool may own the request."
-		: undefined;
-	const facts = formatLongRunningFacts(event);
-	return [
-		`Subagent needs attention: ${event.agent}`,
-		`Run: ${runTarget}${event.index !== undefined ? ` step ${event.index + 1}` : ""}`,
-		`Signal: ${event.message}`,
-		facts ? `Facts: ${facts}` : undefined,
-		event.recentFailureSummary ? `Recent failures: ${event.recentFailureSummary}` : undefined,
-		supervisorHint,
-		"Hint: Inspect status first unless the run is clearly blocked. Use steer for a top-level live async child, routed resume for a live nested child, or resume to revive a paused/completed/failed child.",
-		`Top-level live async nudge: ${steerCommand}`,
-		`Routed live nested nudge: ${nestedResumeCommand}`,
-		childIntercomTarget ? `Direct intercom target: ${childIntercomTarget}` : undefined,
-		`Status: subagent({ action: "status", id: "${runTarget}" })`,
-		`Interrupt: subagent({ action: "interrupt", id: "${runTarget}" })`,
-	].filter((line): line is string => Boolean(line)).join("\n");
-}
-
-export function formatControlIntercomMessage(event: ControlEvent, childIntercomTarget?: string): string {
-	const statusLabel = event.reason === "completion_guard"
-		? "subagent failed"
-		: event.type === "active_long_running"
-			? "subagent active but long-running"
-			: "subagent needs attention";
-	return [
-		statusLabel,
-		"",
-		event.reason === "completion_guard"
-			? `${event.agent} failed in run ${event.runId}.`
-			: event.type === "active_long_running"
-				? `${event.agent} is still active but long-running in run ${event.runId}.`
-				: `${event.agent} needs attention in run ${event.runId}.`,
-		"",
-		formatControlNoticeMessage(event, childIntercomTarget),
-	].join("\n");
-}