@narumitw/pi-subagents 2.1.3 → 3.0.0

package/src/subagents-extension.ts

@@ -1,355 +0,0 @@
-/**
- * Subagent Tool - Delegate tasks to specialized agents
- *
- * Spawns a separate `pi` process for each subagent invocation,
- * giving it an isolated context window.
- *
- * Supports blocking single, parallel, chain, workflow, and panel modes.
- *
- * Uses JSON mode to capture structured output from subagents.
- */
-
-import {
-	CONFIG_DIR_NAME,
-	type ExtensionAPI,
-	type ToolDefinition,
-} from "@earendil-works/pi-coding-agent";
-import { discoverAgentCatalog, formatAgentCatalog } from "./agents/catalog.js";
-import type {
-	ConsultationCwdPolicy,
-	ConsultResourcePolicy,
-	DelegationCwdPolicy,
-	SubagentSettings,
-} from "./agents/types.js";
-import { cachedModuleLoader, throwIfAborted } from "./cached-module-loader.js";
-import { renderCompletionMessage, SUBAGENT_COMPLETION_MESSAGE_TYPE } from "./completion-render.js";
-import {
-	type ConfigRegistrationDependencies,
-	registerSubagentConfigCommand,
-	registerSubagentConfigLifecycle,
-} from "./config-registration.js";
-import {
-	type ConsultRegistrationDependencies,
-	registerSubagentConsult,
-} from "./consult-registration.js";
-import {
-	type InspectRegistrationDependencies,
-	registerSubagentInspect,
-} from "./inspect-registration.js";
-import { MAX_BLOCKING_PARALLEL_CONCURRENCY } from "./limits.js";
-import { SubagentParams } from "./params.js";
-import { renderSubagentCall, renderSubagentResult } from "./render.js";
-import {
-	registerSubagentSessionGuidance,
-	type SubagentSessionGuidanceSnapshot,
-} from "./session-guidance-contract.js";
-import {
-	consumeSubagentSettingsNotice,
-	DEFAULT_CONSULT_RESOURCE_POLICY,
-	DEFAULT_CONSULTATION_CWD_POLICY,
-	DEFAULT_DELEGATION_CWD_POLICY,
-	inspectSubagentSettings,
-	readSubagentSettings,
-	resolveBlockingMaxParallelTasks,
-} from "./settings-reader.js";
-import { registerStatefulSubagents } from "./stateful-registration.js";
-import type { SubagentDetails } from "./subagent-details.js";
-import type { SubagentTransport } from "./transport.js";
-import {
-	registerUsageRecording,
-	type UsageRecordingDependencies,
-	type UsageSurfaceArm,
-} from "./usage-recording.js";
-import { resolveUsageRecordingEnabled } from "./usage-recording-config.js";
-
-type BlockingExecutionModule = Pick<typeof import("./execution.js"), "executeSubagent">;
-
-export interface SubagentsDependencies {
-	loadBlockingExecution?: () => Promise<BlockingExecutionModule>;
-	loadStatefulTransport?: () => Promise<SubagentTransport>;
-	config?: ConfigRegistrationDependencies;
-	consult?: ConsultRegistrationDependencies;
-	inspect?: InspectRegistrationDependencies;
-	usageRecording?: Partial<UsageRecordingDependencies>;
-}
-
-export default function (pi: ExtensionAPI, dependencies: SubagentsDependencies = {}) {
-	pi.registerMessageRenderer(SUBAGENT_COMPLETION_MESSAGE_TYPE, renderCompletionMessage);
-	const loadBlockingExecution = cachedModuleLoader(
-		dependencies.loadBlockingExecution ?? (() => import("./execution.js")),
-	);
-	const configOwner = registerSubagentConfigLifecycle(pi);
-	const usageRecording = registerUsageRecording(pi, dependencies.usageRecording);
-	const settings = readSubagentSettings();
-	let currentSettings: SubagentSettings | undefined = settings;
-	let currentCatalog = "";
-	const blockingEnabled = settings?.blocking?.enabled !== false;
-	const statefulEnabled = settings?.stateful?.enabled !== false;
-	if (blockingEnabled) {
-		registerBlockingSubagent(pi, () => currentSettings, statefulEnabled, loadBlockingExecution);
-	}
-
-	pi.on("session_start", async (event, ctx) => {
-		// Preserve a one-shot migration notice from extension load while refreshing
-		// validation against settings that may have changed before this session.
-		const loadNotice = consumeSubagentSettingsNotice();
-		const refreshedSettings = readSubagentSettings();
-		const refreshedNotice = consumeSubagentSettingsNotice();
-		if (!inspectSubagentSettings().error) currentSettings = refreshedSettings;
-		const notice = [
-			...new Set([loadNotice, refreshedNotice].filter((value) => value !== undefined)),
-		].join("\n");
-		if (notice) ctx.ui.notify(notice, "warning");
-
-		currentCatalog = formatAgentCatalog(
-			discoverAgentCatalog(ctx.cwd, ctx.isProjectTrusted(), refreshedSettings),
-		).text;
-		await usageRecording.startSession({
-			enabled: resolveUsageRecordingEnabled(currentSettings?.usageRecording),
-			surfaceArm: usageSurfaceArm(blockingEnabled, statefulRuntime.getRuntimeStatus().enabled),
-			reason: event.reason,
-			onWarning: (message) => {
-				if (ctx.hasUI) ctx.ui.notify(message, "warning");
-			},
-		});
-	});
-
-	const statefulRuntime = registerStatefulSubagents(pi, {
-		blockingEnabled,
-		settings: settings?.stateful,
-		getSettings: () => currentSettings,
-		loadTransport: dependencies.loadStatefulTransport,
-		usageRecording,
-	});
-	const getBlockingEnabled = () => blockingEnabled;
-	const getMaxParallelTasks = () => resolveBlockingMaxParallelTasks(currentSettings);
-	const getConsultResourcePolicy = () =>
-		currentSettings?.consult?.resources ?? DEFAULT_CONSULT_RESOURCE_POLICY;
-	const getConsultationCwdPolicy = () =>
-		currentSettings?.cwdPolicy?.consultation ?? DEFAULT_CONSULTATION_CWD_POLICY;
-	const getDelegationCwdPolicy = () =>
-		currentSettings?.cwdPolicy?.delegation ?? DEFAULT_DELEGATION_CWD_POLICY;
-	registerSubagentInspect(
-		pi,
-		{
-			...statefulRuntime,
-			getBlockingEnabled,
-			getMaxParallelTasks,
-			getConsultResourcePolicy,
-			getConsultationCwdPolicy,
-			getDelegationCwdPolicy,
-			getUsageRecordingStatus: () => usageRecording.getStatus(),
-		},
-		dependencies.inspect,
-	);
-	if (blockingEnabled) {
-		registerSubagentConsult(pi, { getSettings: () => currentSettings }, dependencies.consult);
-	}
-	const sessionGuidance = registerSubagentSessionGuidance(
-		pi,
-		(): SubagentSessionGuidanceSnapshot => {
-			const runtimeStatus = statefulRuntime.getRuntimeStatus();
-			return {
-				blockingEnabled,
-				statefulEnabled: runtimeStatus.enabled,
-				completionDelivery: runtimeStatus.completionDelivery,
-				blockingMaxParallelTasks: resolveBlockingMaxParallelTasks(currentSettings),
-				statefulLimits: runtimeStatus.limits,
-				consultationCwdPolicy: getConsultationCwdPolicy(),
-				delegationCwdPolicy: getDelegationCwdPolicy(),
-				consultResourcePolicy: getConsultResourcePolicy(),
-				agentCatalog: currentCatalog,
-			};
-		},
-		() => statefulRuntime.listAgents(),
-	);
-	registerSubagentConfigCommand(
-		pi,
-		{
-			...statefulRuntime,
-			setCompletionDelivery(value) {
-				statefulRuntime.setCompletionDelivery(value);
-				sessionGuidance.publish();
-			},
-			getBlockingEnabled,
-			getMaxParallelTasks,
-			getConsultResourcePolicy,
-			getConsultationCwdPolicy,
-			getDelegationCwdPolicy,
-			getUsageRecordingEnabled: () => usageRecording.getStatus().enabled,
-			getUsageRecordingStatus: () => usageRecording.getStatus(),
-			setUsageRecordingEnabled: async (value: boolean) => {
-				await usageRecording.setEnabled(value);
-				currentSettings = {
-					...(currentSettings ?? {}),
-					usageRecording: { ...(currentSettings?.usageRecording ?? {}), enabled: value },
-				};
-			},
-			setMaxParallelTasks(value: number) {
-				currentSettings = {
-					...(currentSettings ?? {}),
-					blocking: { ...(currentSettings?.blocking ?? {}), maxParallelTasks: value },
-				};
-				sessionGuidance.publish();
-			},
-			setConsultResourcePolicy(value: ConsultResourcePolicy) {
-				currentSettings = {
-					...(currentSettings ?? {}),
-					consult: { ...(currentSettings?.consult ?? {}), resources: value },
-				};
-				sessionGuidance.publish();
-			},
-			setConsultationCwdPolicy(value: ConsultationCwdPolicy) {
-				currentSettings = {
-					...(currentSettings ?? {}),
-					cwdPolicy: { ...(currentSettings?.cwdPolicy ?? {}), consultation: value },
-				};
-				sessionGuidance.publish();
-			},
-			setDelegationCwdPolicy(value: DelegationCwdPolicy) {
-				currentSettings = {
-					...(currentSettings ?? {}),
-					cwdPolicy: { ...(currentSettings?.cwdPolicy ?? {}), delegation: value },
-				};
-				sessionGuidance.publish();
-			},
-		},
-		configOwner,
-		dependencies.config,
-	);
-	pi.on("session_shutdown", (event) => usageRecording.shutdown(event.reason));
-}
-
-function usageSurfaceArm(blockingEnabled: boolean, statefulEnabled: boolean): UsageSurfaceArm {
-	if (blockingEnabled && statefulEnabled) return "all";
-	if (statefulEnabled) return "async-only";
-	if (blockingEnabled) return "blocking-only";
-	return "disabled";
-}
-
-function registerBlockingSubagent(
-	pi: ExtensionAPI,
-	getSettings: () => SubagentSettings | undefined,
-	statefulEnabled: boolean,
-	loadExecution: () => Promise<BlockingExecutionModule>,
-): void {
-	let deprecationWarningShown = false;
-	const activeControllers = new Set<AbortController>();
-	const activeWork = new Set<Promise<unknown>>();
-	const cancelAndWaitForWork = async (reason: string) => {
-		for (const controller of activeControllers) {
-			controller.abort(new DOMException(reason, "AbortError"));
-		}
-		await Promise.allSettled([...activeWork]);
-	};
-	pi.on("session_start", () => {
-		deprecationWarningShown = false;
-		return cancelAndWaitForWork("Blocking subagent session replaced");
-	});
-	pi.on("session_shutdown", () => cancelAndWaitForWork("Blocking subagent session shut down"));
-	const deprecationAlternatives = () =>
-		statefulEnabled
-			? "Prefer the main agent for tightly coupled work, subagent_spawn for detached work, subagent_await for an intentional retained-agent join, or subagent_consult for bounded synchronous read-only evidence."
-			: "Prefer the main agent for tightly coupled work or subagent_consult for bounded synchronous read-only evidence; enable the background workflow before using detached alternatives.";
-	const baseDescription = [
-		"Deprecated compatibility tool: do not choose subagent for new work.",
-		deprecationAlternatives(),
-		"Run specialized subagents as a blocking operation with isolated contexts.",
-		"The call blocks the main agent until every worker and optional aggregator finishes, so queued steering waits.",
-		"Modes: single (agent + task), parallel (tasks array), chain (sequential with {previous} placeholder), workflow (named dependency tasks with optional capability routing), or panel (independent reviewers plus evidence-preserving synthesis).",
-		"Parallel mode may include an aggregator fan-in step; workflow mode validates dependencies, authority, artifacts, scope conflicts, retries, and hedging before scheduling. Use subagent_consult instead for one synchronous child that must be executor-constrained to read-only tools.",
-		'Default agent scope is "user" (from ~/.pi/agent/agents).',
-		`To enable project-local agents in ${CONFIG_DIR_NAME}/agents, pass agentScope: "both" (or "project") as a top-level argument for that call.`,
-		`Configured parallel limits never exceed ${MAX_BLOCKING_PARALLEL_CONCURRENCY} concurrently started workers. The current call limit, working-directory policy, and available agent definitions are published in the pi-subagents session-guidance message.`,
-		"Working-directory policy controls launch targets and protected project resources, not filesystem access or sandboxing.",
-	].join(" ");
-	const promptGuidelines = [
-		statefulEnabled
-			? "The subagent tool is deprecated for new work; prefer the main agent, subagent_spawn with supported completion delivery, subagent_await for an intentional retained-agent join, or subagent_consult for bounded synchronous read-only evidence."
-			: "The subagent tool is deprecated for new work; prefer the main agent or subagent_consult for bounded synchronous read-only evidence, and enable the background workflow before using detached alternatives.",
-		"Use deprecated subagent only for an existing caller or an explicit user request whose blocking chain, fan-in, panel, or workflow semantics do not yet have a detached replacement.",
-		"When compatibility requires subagent, decide how many subagents to spawn from task shape instead of waiting for the user to specify a count.",
-		"The main agent retains overall planning, immediate critical-path work, integration, final verification, and the final answer.",
-		"Use no subagent for simple answers, quick targeted edits, latency-sensitive one-step work, tasks requiring frequent user back-and-forth, or critical-path work the main agent can perform directly.",
-		"One ordinary implementation worker should not replace work the main agent can perform directly; use a blocking single only when intentional synchronous isolation or a user-requested specialist justifies waiting.",
-		"Keep ordinary planning in the main agent, or use explicit workflow mode when a genuine dependency graph requires caller-authored orchestration.",
-		"Keep ordinary review in the main agent with a review skill and deterministic checks; reserve panel mode or custom verifier agents for consequential independent verification.",
-		"A compatibility subagent call blocks the main agent from processing queued steering until it returns; use it only when the explicit legacy workflow justifies making Pi unavailable.",
-		"If a blocking parallel subagent call is genuinely required, keep tasks independent, stay within the configured maximum from the current pi-subagents session-guidance message, and avoid write-heavy implementation touching the same files or shared state.",
-		"For parallel subagent calls, omit the aggregator key entirely unless a fan-in step is required; do not send null, empty strings, or an empty object for unused optional fields.",
-		"Use workflow mode for explicit dependencies or capability routing; declare read/write or ownership scopes, require structured-v2 artifacts when downstream tasks consume them, and use retry or hedging only with the required side-effect contract.",
-		"Use panel mode only for consequential review or research that benefits from at least two independent reviewers and one bounded synthesis; agreement is not proof, dissent and blocking objections remain visible, and simple or latency-sensitive work should not use a panel.",
-		'Do not use subagent with project-local agents unless the user explicitly wants project agents or sets agentScope to "project" or "both"; keep confirmation enabled for untrusted repositories.',
-		"When using subagent, write self-contained tasks with file paths, context, expected output, and whether the subagent may edit files.",
-		"Set subagent timeoutMs to the shortest realistic work deadline for the task difficulty, just as thinkingLevel should match reasoning difficulty; split oversized tasks instead of extending the deadline merely to compensate for broad scope. Use totalTimeoutMs to cap an entire blocking workflow, idleTimeoutMs for stalled work, and maxTurns or maxToolCalls to stop repeated work without progress. Every budget stop preserves a bounded checkpoint and may make one separately bounded summary attempt.",
-	];
-	const definition: ToolDefinition<typeof SubagentParams, SubagentDetails> = {
-		name: "subagent",
-		label: "Blocking Subagent · Deprecated",
-		description: baseDescription,
-		promptSnippet:
-			"Deprecated blocking subagent compatibility tool; prefer detached or read-only alternatives.",
-		promptGuidelines,
-		parameters: SubagentParams,
-
-		async execute(toolCallId, params, signal, onUpdate, ctx) {
-			const lifecycleController = new AbortController();
-			activeControllers.add(lifecycleController);
-			const effectiveSignal = signal
-				? AbortSignal.any([signal, lifecycleController.signal])
-				: lifecycleController.signal;
-			const work = (async () => {
-				throwIfAborted(effectiveSignal, "Blocking subagent execution was cancelled");
-				if (!deprecationWarningShown && ctx.hasUI) {
-					deprecationWarningShown = true;
-					ctx.ui.notify(
-						statefulEnabled
-							? "subagent is deprecated for new work. Prefer the main agent, subagent_spawn with completion delivery, subagent_await for an intentional join, or subagent_consult for synchronous read-only evidence."
-							: "subagent is deprecated for new work. Prefer the main agent or subagent_consult; enable the background workflow before using detached alternatives.",
-						"warning",
-					);
-				}
-				let executionModule: BlockingExecutionModule;
-				try {
-					executionModule = await loadExecution();
-				} catch (error) {
-					throwIfAborted(
-						effectiveSignal,
-						"Blocking subagent execution was cancelled while loading",
-					);
-					throw error;
-				}
-				throwIfAborted(effectiveSignal, "Blocking subagent execution was cancelled while loading");
-				return executionModule.executeSubagent(
-					toolCallId,
-					params,
-					effectiveSignal,
-					onUpdate,
-					ctx,
-					getSettings(),
-				);
-			})();
-			activeWork.add(work);
-			try {
-				return await work;
-			} finally {
-				activeControllers.delete(lifecycleController);
-				activeWork.delete(work);
-			}
-		},
-
-		renderCall(args, theme) {
-			return renderSubagentCall(args, theme);
-		},
-
-		renderResult(result, options, theme) {
-			return renderSubagentResult(result, options, theme);
-		},
-	};
-	pi.registerTool<typeof SubagentParams, SubagentDetails>(definition);
-	pi.on("tool_result", (event) => {
-		if (event.toolName !== "subagent") return;
-		if ((event.details as (SubagentDetails & { isError?: boolean }) | undefined)?.isError)
-			return { isError: true };
-	});
-}

package/src/subprocess-transport.ts

@@ -1,145 +0,0 @@
-import { discoverAgents } from "./agents/discovery.js";
-import type { AgentConfig, SubagentSettings, SubagentThinkingLevel } from "./agents/types.js";
-import {
-	CHILD_PEER_TOOL_NAMES,
-	childPeerBridgePath,
-	type PeerTransportRuntime,
-	peerBridgeEnvironment,
-} from "./peer-transport.js";
-import { resolvePiPromptResources } from "./prompt-resources.js";
-import type { ManagedAgent, TurnOutcome } from "./registry.js";
-import { getResultFinalOutput, runSingleAgent } from "./runner.js";
-import { readSubagentSettings, resolveSubagentThinkingLevel } from "./settings.js";
-import { buildStatefulTurnPrompt, resolveStatefulTurnTimeout } from "./stateful-prompt.js";
-import type { SubagentDetails } from "./subagent-details.js";
-import type { SubagentTransport } from "./transport.js";
-import type { TransportProgressCallback, TransportTelemetry } from "./transport-types.js";
-
-export function resolveStatefulSubprocessThinkingLevel(
-	agents: readonly Pick<AgentConfig, "name" | "thinkingLevel">[],
-	record: Pick<ManagedAgent, "agent" | "thinkingLevel">,
-): SubagentThinkingLevel | undefined {
-	return resolveSubagentThinkingLevel(agents, record.agent, record.thinkingLevel);
-}
-
-export interface SubprocessTransportOptions {
-	getSettings?: () => SubagentSettings | undefined;
-	peerRuntime?: PeerTransportRuntime;
-}
-
-export class SubprocessTransport implements SubagentTransport {
-	readonly kind = "subprocess" as const;
-
-	constructor(private readonly options: SubprocessTransportOptions = {}) {}
-
-	async runTurn(
-		record: ManagedAgent,
-		task: string,
-		signal: AbortSignal,
-		onProgress?: TransportProgressCallback,
-	): Promise<TurnOutcome> {
-		const startedAt = Date.now();
-		const starting: TransportTelemetry = {
-			transport: "subprocess",
-			phase: "starting",
-			updatedAt: startedAt,
-			timing: { startedAt, transportStartedAt: startedAt },
-		};
-		onProgress?.(starting);
-		const settings = this.options.getSettings ? this.options.getSettings() : readSubagentSettings();
-		const discovery = discoverAgents(record.cwd, record.agentScope ?? "user", settings);
-		const agent = discovery.agents.find((candidate) => candidate.name === record.agent);
-		const boundedTask = buildStatefulTurnPrompt(record, task);
-		const projectTrust =
-			record.target?.trust.projectTrusted ??
-			(record.agentScope === "project" || record.agentScope === "both");
-		const promptResources = agent?.systemPrompt.trim()
-			? await resolvePiPromptResources(record.cwd, projectTrust)
-			: undefined;
-		const makeDetails = (results: SubagentDetails["results"]): SubagentDetails => ({
-			mode: "single",
-			agentScope: record.agentScope ?? "user",
-			projectAgentsDir: discovery.projectAgentsDir,
-			results,
-		});
-		const credentials = this.options.peerRuntime
-			? await this.options.peerRuntime.issueCredentials(
-					record.id,
-					record.currentTurnGeneration ?? record.turnGeneration ?? 1,
-				)
-			: undefined;
-		let single: Awaited<ReturnType<typeof runSingleAgent>>;
-		try {
-			single = await runSingleAgent(
-				record.cwd,
-				discovery.agents,
-				record.agent,
-				boundedTask.text,
-				undefined,
-				undefined,
-				signal,
-				resolveStatefulSubprocessThinkingLevel(discovery.agents, record),
-				record.currentTimeoutMs ?? record.timeoutMs ?? resolveStatefulTurnTimeout(agent),
-				undefined,
-				makeDetails,
-				undefined,
-				{
-					projectTrust,
-					...(record.executionPlan ? { tools: record.executionPlan.effectiveTools } : {}),
-					appendSystemPromptPaths: promptResources?.appendSystemPromptPaths,
-					extensionPaths: credentials ? [childPeerBridgePath()] : undefined,
-					additionalTools: credentials ? [...CHILD_PEER_TOOL_NAMES] : undefined,
-					env: credentials ? peerBridgeEnvironment(credentials) : undefined,
-					timeoutResultFormat: record.resultFormat,
-					turnLimits: {
-						idleTimeoutMs: record.currentIdleTimeoutMs ?? record.idleTimeoutMs,
-						maxTurns: record.currentMaxTurns ?? record.maxTurns,
-						maxToolCalls: record.currentMaxToolCalls ?? record.maxToolCalls,
-					},
-					resultFormat: record.resultFormat,
-					contract: record.contract,
-					executionPlan: record.executionPlan,
-					displayTask: task,
-				},
-			);
-		} finally {
-			this.options.peerRuntime?.revoke(record.id);
-		}
-		const settledAt = Date.now();
-		const telemetry: TransportTelemetry = {
-			...starting,
-			phase: single.aborted ? "interrupted" : single.exitCode === 0 ? "settled" : "failed",
-			failurePhase: single.exitCode === 0 ? undefined : "running",
-			updatedAt: settledAt,
-			timing: {
-				...starting.timing,
-				promptAcceptedAt: single.processStarted ? startedAt : undefined,
-				firstActivityAt: single.messages.length > 0 ? settledAt : undefined,
-				settledAt,
-			},
-			provider: single.actualProvider,
-			model: single.actualModel ?? single.model,
-			thinkingLevel: single.thinkingLevel,
-			usage: {
-				input: single.usage.input,
-				output: single.usage.output,
-				cacheRead: single.usage.cacheRead,
-				cacheWrite: single.usage.cacheWrite,
-				totalTokens: single.usage.totalTokens ?? 0,
-				cost: single.usage.cost,
-				turns: single.usage.turns,
-			},
-		};
-		onProgress?.(telemetry);
-		return {
-			output: getResultFinalOutput(single),
-			exitCode: single.exitCode,
-			aborted: single.aborted,
-			truncated: single.truncated || boundedTask.truncated,
-			error: single.errorMessage || single.stderr || undefined,
-			policy: single.policy,
-			termination: single.termination,
-			telemetry,
-		};
-	}
-}

package/src/supervision.ts

@@ -1,104 +0,0 @@
-import { isResultError } from "./runner-outcome.js";
-import type { SingleResult } from "./runner-types.js";
-
-const HEDGE_LOSER_GRACE_MS = 5_000;
-
-export async function runHedgedAttempt(
-	run: (signal: AbortSignal | undefined) => Promise<SingleResult>,
-	parentSignal: AbortSignal | undefined,
-	hedgeAfterMs: number | undefined,
-	loserGraceMs = HEDGE_LOSER_GRACE_MS,
-): Promise<{ result: SingleResult; hedged: boolean }> {
-	if (hedgeAfterMs === undefined) return { result: await run(parentSignal), hedged: false };
-	const primaryLink = linkedAbortController(parentSignal);
-	const hedgeLink = linkedAbortController(parentSignal);
-	const primaryController = primaryLink.controller;
-	const hedgeController = hedgeLink.controller;
-	let hedgeStarted = false;
-	let hedgePromise: Promise<SingleResult> | undefined;
-	let timer: ReturnType<typeof setTimeout> | undefined;
-	const primaryPromise = run(primaryController.signal);
-	const primaryTagged = primaryPromise.then((result) => ({ source: "primary" as const, result }));
-	const delayedHedge = new Promise<{ source: "hedge"; result: SingleResult }>((resolve, reject) => {
-		timer = setTimeout(() => {
-			hedgeStarted = true;
-			hedgePromise = run(hedgeController.signal);
-			hedgePromise.then((result) => resolve({ source: "hedge", result }), reject);
-		}, hedgeAfterMs);
-	});
-	try {
-		const first = await Promise.race([primaryTagged, delayedHedge]);
-		if (!isResultError(first.result) || !hedgeStarted || !hedgePromise) {
-			return { result: first.result, hedged: hedgeStarted };
-		}
-		const other = first.source === "primary" ? await hedgePromise : await primaryPromise;
-		return {
-			result: isResultError(other) ? first.result : other,
-			hedged: true,
-		};
-	} finally {
-		if (timer) clearTimeout(timer);
-		primaryController.abort();
-		hedgeController.abort();
-		primaryLink.dispose();
-		hedgeLink.dispose();
-		await settleWithin(
-			[primaryPromise, hedgePromise].filter(
-				(value): value is Promise<SingleResult> => value !== undefined,
-			),
-			loserGraceMs,
-		);
-	}
-}
-
-export function isRetryableResult(result: SingleResult): boolean {
-	if (!isResultError(result)) return false;
-	if (result.outcome) return result.outcome.retryable;
-	return result.aborted === true || result.exitCode !== 0;
-}
-
-export async function supervisionDelay(
-	milliseconds: number,
-	signal: AbortSignal | undefined,
-): Promise<void> {
-	if (milliseconds <= 0 || signal?.aborted) return;
-	await new Promise<void>((resolve) => {
-		let timer: ReturnType<typeof setTimeout>;
-		const finish = () => {
-			clearTimeout(timer);
-			signal?.removeEventListener("abort", finish);
-			resolve();
-		};
-		timer = setTimeout(finish, milliseconds);
-		signal?.addEventListener("abort", finish, { once: true });
-	});
-}
-
-async function settleWithin(promises: Promise<unknown>[], timeoutMs: number): Promise<void> {
-	let timer: ReturnType<typeof setTimeout> | undefined;
-	try {
-		await Promise.race([
-			Promise.allSettled(promises),
-			new Promise<void>((resolve) => {
-				timer = setTimeout(resolve, timeoutMs);
-				timer.unref();
-			}),
-		]);
-	} finally {
-		if (timer) clearTimeout(timer);
-	}
-}
-
-function linkedAbortController(parentSignal: AbortSignal | undefined): {
-	controller: AbortController;
-	dispose(): void;
-} {
-	const controller = new AbortController();
-	const abort = () => controller.abort();
-	if (parentSignal?.aborted) controller.abort();
-	else parentSignal?.addEventListener("abort", abort, { once: true });
-	return {
-		controller,
-		dispose: () => parentSignal?.removeEventListener("abort", abort),
-	};
-}

package/src/task-path.ts

@@ -1,65 +0,0 @@
-import { createHash } from "node:crypto";
-
-export const ROOT_TASK_PATH = "/root";
-export const MAX_TASK_NAME_LENGTH = 128;
-export const MAX_TASK_PATH_LENGTH = 2_048;
-
-const TASK_NAME_PATTERN = /^[a-z0-9_]+$/u;
-
-export function validateTaskName(value: string): string {
-	if (!value) throw new Error("Subagent taskName must not be empty");
-	if (value === "root" || value === "." || value === "..") {
-		throw new Error(`Subagent taskName ${JSON.stringify(value)} is reserved`);
-	}
-	if (value.length > MAX_TASK_NAME_LENGTH) {
-		throw new Error(`Subagent taskName cannot exceed ${MAX_TASK_NAME_LENGTH} characters`);
-	}
-	if (value.includes("/")) throw new Error("Subagent taskName must not contain `/`");
-	if (!TASK_NAME_PATTERN.test(value)) {
-		throw new Error(
-			"Subagent taskName must use only lowercase ASCII letters, digits, and underscores",
-		);
-	}
-	return value;
-}
-
-export function validateTaskPath(value: string): string {
-	if (!value.startsWith(`${ROOT_TASK_PATH}/`) && value !== ROOT_TASK_PATH) {
-		throw new Error("Canonical subagent task paths must start with `/root`");
-	}
-	if (value.length > MAX_TASK_PATH_LENGTH) {
-		throw new Error(
-			`Canonical subagent task paths cannot exceed ${MAX_TASK_PATH_LENGTH} characters`,
-		);
-	}
-	if (value.endsWith("/") || value.includes("//")) {
-		throw new Error("Canonical subagent task paths must not contain empty segments");
-	}
-	for (const segment of value.slice(ROOT_TASK_PATH.length + 1).split("/")) {
-		if (segment) validateTaskName(segment);
-	}
-	return value;
-}
-
-export function joinTaskPath(parentPath: string, taskName: string): string {
-	const parent = validateTaskPath(parentPath);
-	const name = validateTaskName(taskName);
-	return validateTaskPath(`${parent}/${name}`);
-}
-
-export function resolveTaskPath(senderPath: string, reference: string): string {
-	if (!reference) throw new Error("Subagent task path reference must not be empty");
-	if (reference.startsWith("/")) return validateTaskPath(reference);
-	const sender = validateTaskPath(senderPath);
-	if (reference.endsWith("/")) {
-		throw new Error("Relative subagent task paths must not end with `/`");
-	}
-	let path = sender;
-	for (const segment of reference.split("/")) path = joinTaskPath(path, segment);
-	return path;
-}
-
-export function deriveTaskName(agentId: string): string {
-	const digest = createHash("sha256").update(agentId).digest("hex").slice(0, 32);
-	return `agent_${digest}`;
-}