pi-ui-extend 0.1.1

package/external/pi-tools-suite/src/async-subagents/core/registry.ts

@@ -0,0 +1,224 @@
+import * as fs from "node:fs";
+import * as path from "node:path";
+import { getRunRoot, isDir, resolveRunDir } from "./paths.js";
+
+export const SUBAGENT_REGISTRY_FILE = "registry.json";
+
+export interface SubagentRegistryRun {
+	runId: string;
+	runDir: string;
+	agentIds: string[];
+	createdAt: string;
+	updatedAt: string;
+}
+
+export interface SubagentRegistryAgent {
+	agentId: string;
+	runId: string;
+	runDir: string;
+	updatedAt: string;
+}
+
+export interface SubagentRegistry {
+	version: 1;
+	latestRunId?: string;
+	latestRunDir?: string;
+	runs: Record<string, SubagentRegistryRun>;
+	agents: Record<string, SubagentRegistryAgent>;
+}
+
+function emptyRegistry(): SubagentRegistry {
+	return { version: 1, runs: {}, agents: {} };
+}
+
+export function getSubagentRegistryPath(cwd: string): string {
+	return path.join(getRunRoot(cwd), SUBAGENT_REGISTRY_FILE);
+}
+
+export function loadSubagentRegistry(cwd: string): SubagentRegistry {
+	try {
+		const parsed = JSON.parse(fs.readFileSync(getSubagentRegistryPath(cwd), "utf-8"));
+		if (!isRecord(parsed)) return emptyRegistry();
+		const registry = emptyRegistry();
+		if (typeof parsed.latestRunId === "string") registry.latestRunId = parsed.latestRunId;
+		if (typeof parsed.latestRunDir === "string") registry.latestRunDir = parsed.latestRunDir;
+		if (isRecord(parsed.runs)) {
+			for (const [runId, value] of Object.entries(parsed.runs)) {
+				const run = normalizeRegistryRun(runId, value);
+				if (run) registry.runs[runId] = run;
+			}
+		}
+		if (isRecord(parsed.agents)) {
+			for (const [agentId, value] of Object.entries(parsed.agents)) {
+				const agent = normalizeRegistryAgent(agentId, value);
+				if (agent) registry.agents[agentId] = agent;
+			}
+		}
+		return registry;
+	} catch {
+		return emptyRegistry();
+	}
+}
+
+export function saveSubagentRegistry(cwd: string, registry: SubagentRegistry): void {
+	const registryPath = getSubagentRegistryPath(cwd);
+	fs.mkdirSync(path.dirname(registryPath), { recursive: true });
+	fs.writeFileSync(registryPath, `${JSON.stringify(registry, null, 2)}\n`, "utf-8");
+}
+
+export function recordSubagentRun(cwd: string, runDir: string, agentIds: string[]): SubagentRegistry {
+	const registry = loadSubagentRegistry(cwd);
+	const resolvedRunDir = path.resolve(runDir);
+	const runId = path.basename(resolvedRunDir);
+	const now = new Date().toISOString();
+	const uniqueAgentIds = [...new Set(agentIds.filter((id) => id.trim().length > 0))];
+	const previous = registry.runs[runId];
+	registry.runs[runId] = {
+		runId,
+		runDir: resolvedRunDir,
+		agentIds: uniqueAgentIds,
+		createdAt: previous?.createdAt ?? now,
+		updatedAt: now,
+	};
+	registry.latestRunId = runId;
+	registry.latestRunDir = resolvedRunDir;
+	for (const agentId of uniqueAgentIds) {
+		registry.agents[agentId] = { agentId, runId, runDir: resolvedRunDir, updatedAt: now };
+	}
+	saveSubagentRegistry(cwd, registry);
+	return registry;
+}
+
+export function removeSubagentRunsFromRegistry(cwd: string, runDirs: string[]): SubagentRegistry {
+	const registry = loadSubagentRegistry(cwd);
+	const removed = new Set(runDirs.map((runDir) => normalizePath(runDir)));
+	for (const [runId, run] of Object.entries(registry.runs)) {
+		if (removed.has(normalizePath(run.runDir))) delete registry.runs[runId];
+	}
+	for (const [agentId, agent] of Object.entries(registry.agents)) {
+		if (removed.has(normalizePath(agent.runDir))) delete registry.agents[agentId];
+	}
+	refreshLatestRun(registry);
+	saveSubagentRegistry(cwd, registry);
+	return registry;
+}
+
+export function resolveSubagentRunDir(cwd: string, runDir?: string): string {
+	if (hasText(runDir)) return resolveRunDir(cwd, runDir);
+	const latest = findLatestSubagentRunDir(cwd);
+	if (latest) return latest;
+	throw new Error(`runDir was omitted and no sub-agent runs were found under ${getRunRoot(cwd)}.`);
+}
+
+export function resolveSubagentAgentRunDir(cwd: string, agentId: string, runDir?: string): string {
+	if (hasText(runDir)) return resolveRunDir(cwd, runDir);
+	const registered = loadSubagentRegistry(cwd).agents[agentId]?.runDir;
+	if (registered && hasAgentRecord(registered, agentId)) return registered;
+	const scanned = findSubagentRunDirsForAgent(cwd, agentId)[0];
+	if (scanned) return scanned;
+	throw new Error(`runDir was omitted and agent "${agentId}" was not found under ${getRunRoot(cwd)}.`);
+}
+
+export function findLatestSubagentRunDir(cwd: string): string | undefined {
+	const registry = loadSubagentRegistry(cwd);
+	const latest = registry.latestRunDir;
+	if (latest && isDir(latest)) return latest;
+	const registered = Object.values(registry.runs)
+		.filter((run) => isDir(run.runDir))
+		.sort((a, b) => Date.parse(b.updatedAt) - Date.parse(a.updatedAt));
+	if (registered[0]) return registered[0].runDir;
+	return listSubagentRunDirs(cwd)[0];
+}
+
+export function findSubagentRunDirsForAgent(cwd: string, agentId: string): string[] {
+	return listSubagentRunDirs(cwd).filter((runDir) => hasAgentRecord(runDir, agentId));
+}
+
+export function listSubagentRunDirs(cwd: string): string[] {
+	const root = getRunRoot(cwd);
+	if (!isDir(root)) return [];
+	return fs.readdirSync(root, { withFileTypes: true })
+		.filter((entry) => entry.isDirectory())
+		.map((entry) => path.join(root, entry.name))
+		.filter(looksLikeRunDir)
+		.sort((a, b) => statMtimeMs(b) - statMtimeMs(a));
+}
+
+function refreshLatestRun(registry: SubagentRegistry): void {
+	const latest = Object.values(registry.runs)
+		.filter((run) => isDir(run.runDir))
+		.sort((a, b) => Date.parse(b.updatedAt) - Date.parse(a.updatedAt))[0];
+	if (latest) {
+		registry.latestRunId = latest.runId;
+		registry.latestRunDir = latest.runDir;
+		return;
+	}
+	delete registry.latestRunId;
+	delete registry.latestRunDir;
+}
+
+function looksLikeRunDir(runDir: string): boolean {
+	if (isDir(path.join(runDir, "prompts"))) return true;
+	try {
+		return fs.readdirSync(runDir, { withFileTypes: true })
+			.some((entry) => entry.isDirectory() && fs.existsSync(path.join(runDir, entry.name, "prompt.md")));
+	} catch {
+		return false;
+	}
+}
+
+function hasAgentRecord(runDir: string, agentId: string): boolean {
+	return fs.existsSync(path.join(runDir, agentId, "prompt.md"))
+		|| fs.existsSync(path.join(runDir, "prompts", `${agentId}.md`));
+}
+
+function normalizeRegistryRun(runId: string, value: unknown): SubagentRegistryRun | undefined {
+	if (!isRecord(value)) return undefined;
+	if (typeof value.runDir !== "string") return undefined;
+	const agentIds = Array.isArray(value.agentIds)
+		? value.agentIds.filter((id): id is string => typeof id === "string" && id.trim().length > 0)
+		: [];
+	return {
+		runId: typeof value.runId === "string" ? value.runId : runId,
+		runDir: value.runDir,
+		agentIds,
+		createdAt: typeof value.createdAt === "string" ? value.createdAt : new Date(0).toISOString(),
+		updatedAt: typeof value.updatedAt === "string" ? value.updatedAt : new Date(0).toISOString(),
+	};
+}
+
+function normalizeRegistryAgent(agentId: string, value: unknown): SubagentRegistryAgent | undefined {
+	if (!isRecord(value)) return undefined;
+	if (typeof value.runDir !== "string" || typeof value.runId !== "string") return undefined;
+	return {
+		agentId: typeof value.agentId === "string" ? value.agentId : agentId,
+		runId: value.runId,
+		runDir: value.runDir,
+		updatedAt: typeof value.updatedAt === "string" ? value.updatedAt : new Date(0).toISOString(),
+	};
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+	return typeof value === "object" && value !== null;
+}
+
+function hasText(value: string | undefined): value is string {
+	return typeof value === "string" && value.trim().length > 0;
+}
+
+function statMtimeMs(filePath: string): number {
+	try {
+		return fs.statSync(filePath).mtimeMs;
+	} catch {
+		return 0;
+	}
+}
+
+function normalizePath(filePath: string): string {
+	const resolved = path.resolve(filePath);
+	try {
+		return fs.realpathSync.native(resolved);
+	} catch {
+		return resolved;
+	}
+}

package/external/pi-tools-suite/src/async-subagents/core/retry.ts

@@ -0,0 +1,191 @@
+import * as fs from "node:fs";
+import * as path from "node:path";
+import type { AgentTask, RetryConfig } from "./types.js";
+import type { SpawnedAgent, AgentCompletionHandler } from "./types.js";
+import { isQuotaLimitCompletion, nextFallbackModel, rememberSessionModelFallback, selectSessionModelWithFallback } from "./model-fallback.js";
+import { spawnAgent, type SpawnAgentOptions } from "./spawn.js";
+import { getAgentState } from "./state.js";
+import { isoNow } from "./utils.js";
+
+export interface RetryableSpawnOptions extends SpawnAgentOptions {
+	retry: RetryConfig;
+	extraArgs?: string[];
+	/** Ordered fallback models for quota/rate-limit failures. Applies to this Pi process/session. */
+	fallbackModels?: string[];
+	signal?: AbortSignal;
+	onRpcEvent?: (event: import("./types.js").RpcEventRecord) => void;
+	/** Called each time a retry attempt starts. */
+	onRetry?: (attempt: number, maxRetries: number, delayMs: number) => void;
+}
+
+/**
+ * Spawn an agent with automatic retry on failure.
+ *
+ * Returns a promise that resolves with the final SpawnedAgent (possibly after retries).
+ * The `onComplete` callback is only called for the *final* attempt (success or all retries exhausted).
+ */
+export function spawnAgentWithRetry(
+	runDir: string,
+	task: AgentTask,
+	cwd: string,
+	onComplete: AgentCompletionHandler | undefined,
+	options: RetryableSpawnOptions,
+): { initial: SpawnedAgent; done: Promise<void> } {
+	const { retry, extraArgs = [], fallbackModels = [], signal, onRpcEvent, onRetry, ...spawnOpts } = options;
+	if (signal?.aborted) throw new Error("Aborted");
+	const maxRetries = retry.maxRetries > 0 ? retry.maxRetries : 0;
+	const initialModel = selectSessionModelWithFallback(task.model, fallbackModels);
+	let currentTask = initialModel?.fellBack ? { ...task, model: initialModel.model } : task;
+
+	let currentAttempt = 0;
+	let settled = false;
+	let retryTimer: NodeJS.Timeout | undefined;
+	let abortRetry: (() => void) | undefined;
+	let resolveAllDone: () => void;
+	let rejectAllDone: (error: Error) => void;
+	const allDone = new Promise<void>((resolve, reject) => {
+		resolveAllDone = resolve;
+		rejectAllDone = reject;
+	});
+
+	const settle = (completion: Parameters<AgentCompletionHandler>[0], error?: Error) => {
+		if (settled) return;
+		settled = true;
+		if (retryTimer) clearTimeout(retryTimer);
+		abortRetry?.();
+		clearRetryPending(completion.agentDir);
+		writeRetryCount(completion.agentDir, currentAttempt);
+		onComplete?.(completion);
+		if (error) rejectAllDone!(error);
+		else resolveAllDone!();
+	};
+
+	const handleCompletion: AgentCompletionHandler = (completion) => {
+		if (settled) return;
+		const fallbackModel = isQuotaLimitCompletion(completion, currentTask.model)
+			? nextFallbackModel(currentTask.model, fallbackModels)
+			: undefined;
+		if (fallbackModel) {
+			const failedModel = currentTask.model;
+			rememberSessionModelFallback(failedModel, fallbackModel);
+			writeModelFallbackLog(completion.agentDir, failedModel, fallbackModel, completion.exitCode);
+			currentTask = { ...currentTask, model: fallbackModel };
+			if (signal?.aborted) {
+				settle(completion);
+				return;
+			}
+			if (isStopRequested(completion.agentDir)) {
+				settle(refreshedCompletion(completion));
+				return;
+			}
+			try {
+				spawnAgent(runDir, currentTask, cwd, extraArgs, onRpcEvent, handleCompletion, spawnOpts);
+			} catch (error) {
+				settle(completion, error instanceof Error ? error : new Error(String(error)));
+			}
+			return;
+		}
+		const isRetryable = maxRetries > currentAttempt && shouldRetry(completion, retry);
+
+		if (!isRetryable) {
+			settle(completion);
+			return;
+		}
+
+		// Schedule retry with exponential backoff.
+		currentAttempt++;
+		const delayMs = retry.backoffMs * Math.pow(2, currentAttempt - 1);
+		onRetry?.(currentAttempt, maxRetries, delayMs);
+
+		// Write retry metadata.
+		writeRetryCount(completion.agentDir, currentAttempt);
+		writeRetryPending(completion.agentDir, delayMs);
+		writeRetryLog(completion.agentDir, currentAttempt, delayMs, completion.exitCode);
+
+		if (signal?.aborted) {
+			settle(completion);
+			return;
+		}
+
+		retryTimer = setTimeout(() => {
+			retryTimer = undefined;
+			abortRetry?.();
+			abortRetry = undefined;
+			if (settled) return;
+			if (signal?.aborted || isStopRequested(completion.agentDir)) {
+				settle(refreshedCompletion(completion));
+				return;
+			}
+			clearRetryPending(completion.agentDir);
+			try {
+				spawnAgent(runDir, currentTask, cwd, extraArgs, onRpcEvent, handleCompletion, spawnOpts);
+			} catch (error) {
+				settle(completion, error instanceof Error ? error : new Error(String(error)));
+			}
+		}, delayMs);
+		retryTimer.unref?.();
+
+		if (signal) {
+			const onAbort = () => settle(refreshedCompletion(completion));
+			signal.addEventListener("abort", onAbort, { once: true });
+			abortRetry = () => signal.removeEventListener("abort", onAbort);
+		}
+	};
+
+	const initial = spawnAgent(runDir, currentTask, cwd, extraArgs, onRpcEvent, handleCompletion, spawnOpts);
+	return { initial, done: allDone };
+}
+
+function shouldRetry(completion: Parameters<AgentCompletionHandler>[0], retry: RetryConfig): boolean {
+	if (completion.state.status === "stopped") return false;
+	if (completion.exitCode === 0) return false;
+	if (retry.retryableExitCodes === undefined) return true;
+	if (retry.retryableExitCodes.length === 0) return false;
+	return retry.retryableExitCodes.includes(completion.exitCode);
+}
+
+function writeRetryCount(agentDir: string, count: number): void {
+	try {
+		fs.writeFileSync(path.join(agentDir, "retry_count"), String(count), "utf-8");
+	} catch { /* best-effort */ }
+}
+
+function writeRetryPending(agentDir: string, delayMs: number): void {
+	try {
+		const nextRetryAt = new Date(Date.now() + delayMs).toISOString().replace(/\.\d{3}Z$/, "Z");
+		fs.writeFileSync(path.join(agentDir, "retry_pending"), isoNow(), "utf-8");
+		fs.writeFileSync(path.join(agentDir, "next_retry_at"), nextRetryAt, "utf-8");
+	} catch { /* best-effort */ }
+}
+
+function clearRetryPending(agentDir: string): void {
+	try {
+		fs.rmSync(path.join(agentDir, "retry_pending"), { force: true });
+		fs.rmSync(path.join(agentDir, "next_retry_at"), { force: true });
+	} catch { /* best-effort */ }
+}
+
+function writeRetryLog(agentDir: string, attempt: number, delayMs: number, exitCode: number): void {
+	try {
+		const line = `${isoNow()} retry=${attempt} delay=${delayMs}ms exitCode=${exitCode}\n`;
+		fs.appendFileSync(path.join(agentDir, "retry.log"), line, "utf-8");
+	} catch { /* best-effort */ }
+}
+
+function writeModelFallbackLog(agentDir: string, failedModel: string | undefined, fallbackModel: string, exitCode: number): void {
+	try {
+		const line = `${isoNow()} modelFallback ${failedModel ?? "(default)"} -> ${fallbackModel} exitCode=${exitCode}\n`;
+		fs.appendFileSync(path.join(agentDir, "model_fallback.log"), line, "utf-8");
+		fs.writeFileSync(path.join(agentDir, "model_fallback_from"), failedModel ?? "", "utf-8");
+		fs.writeFileSync(path.join(agentDir, "model_fallback_to"), fallbackModel, "utf-8");
+	} catch { /* best-effort */ }
+}
+
+function isStopRequested(agentDir: string): boolean {
+	return fs.existsSync(path.join(agentDir, "stop_requested"));
+}
+
+function refreshedCompletion(completion: Parameters<AgentCompletionHandler>[0]): Parameters<AgentCompletionHandler>[0] {
+	const refreshed = getAgentState(completion.runDir, completion.agentId, { includeLineCounts: false });
+	return refreshed ? { ...completion, exitCode: refreshed.exitCode ?? completion.exitCode, state: refreshed } : completion;
+}

package/external/pi-tools-suite/src/async-subagents/core/routing.ts

@@ -0,0 +1,259 @@
+import { complete } from "@earendil-works/pi-ai";
+import type { Api, Model } from "@earendil-works/pi-ai";
+import type { AgentTask } from "./types.js";
+import {
+	currentModelRef,
+	defaultSubagentType,
+	resolveSubagentRoutingConfig,
+	type ResolvedSubagentRoutingConfig,
+	type SubagentConfig,
+} from "./config.js";
+
+export interface SubagentRoutingContext {
+	model?: unknown;
+	modelRegistry?: {
+		find(provider: string, modelId: string): Model<Api> | undefined;
+		getApiKeyAndHeaders(model: Model<Api>): Promise<
+			| { ok?: true; apiKey?: string; headers?: Record<string, string> }
+			| { ok: false; error: string }
+		>;
+	};
+	hasUI?: boolean;
+	ui?: { notify?(message: string, level?: string): void };
+}
+
+export interface RoutedSubagentTasks {
+	tasks: AgentTask[];
+	usedLlm: boolean;
+	routes: Record<string, string>;
+	warnings: string[];
+}
+
+const ROUTER_SYSTEM_PROMPT = [
+	"You route Pi async sub-agent tasks to the best configured subagentType.",
+	"Choose exactly one allowed type for each task. Use the allowed type descriptions as the source of truth.",
+	"Prefer the most specific matching type over generic quick/deep. Use frontend for UI/UX implementation or visual frontend polish; use vision only for attached images/screenshots or image inspection.",
+	"Return only strict JSON with this shape: {\"routes\":[{\"id\":\"task-id\",\"subagentType\":\"type\"}]}",
+	"Do not include markdown, comments, explanations, or unknown types.",
+].join("\n");
+
+export async function routeSubagentTasks(
+	tasks: AgentTask[],
+	config: SubagentConfig,
+	ctx: SubagentRoutingContext,
+	signal?: AbortSignal,
+): Promise<RoutedSubagentTasks> {
+	const fallbackTasks = () => tasks.map((task) => withFallbackType(task, config));
+	const autoTasks = tasks.filter((task) => !hasText(task.subagentType));
+	if (autoTasks.length === 0) return { tasks, usedLlm: false, routes: {}, warnings: [] };
+
+	const routing = resolveSubagentRoutingConfig(config);
+	if (!routing.enabled) {
+		return { tasks: fallbackTasks(), usedLlm: false, routes: {}, warnings: ["LLM sub-agent routing is disabled; used defaultType fallback."] };
+	}
+	if (signal?.aborted) throw new Error("Aborted");
+
+	try {
+		const resolved = await resolveRoutingModel(ctx, routing);
+		if (!resolved) {
+			const warning = `LLM sub-agent routing model unavailable (${routing.model}); used defaultType fallback.`;
+			notifyRoutingWarning(ctx, routing, warning);
+			return { tasks: fallbackTasks(), usedLlm: false, routes: {}, warnings: [warning] };
+		}
+
+		const response = await complete(
+			resolved.model,
+			{
+				systemPrompt: ROUTER_SYSTEM_PROMPT,
+				messages: [
+					{
+						role: "user" as const,
+						content: [{ type: "text" as const, text: buildRoutingPrompt(autoTasks, config, routing) }],
+						timestamp: Date.now(),
+					},
+				],
+			},
+			{
+				apiKey: resolved.apiKey,
+				headers: resolved.headers,
+				cacheRetention: "none",
+				maxRetries: routing.maxRetries,
+				maxTokens: routing.maxTokens,
+				signal,
+				temperature: routing.temperature,
+				timeoutMs: routing.timeoutMs,
+			},
+		);
+		const routes = parseRoutingResponse(responseText(response), config, autoTasks);
+		const warnings = Object.keys(routes).length === autoTasks.length
+			? []
+			: [`LLM sub-agent routing returned ${Object.keys(routes).length}/${autoTasks.length} valid route(s); missing tasks used defaultType fallback.`];
+		for (const warning of warnings) notifyRoutingWarning(ctx, routing, warning);
+		return {
+			usedLlm: true,
+			routes,
+			warnings,
+			tasks: tasks.map((task) => applyRoute(task, config, routes)),
+		};
+	} catch (error) {
+		if (signal?.aborted || isAbortError(error)) throw error;
+		const warning = `LLM sub-agent routing failed (${errorMessage(error)}); used defaultType fallback.`;
+		notifyRoutingWarning(ctx, routing, warning);
+		return { tasks: fallbackTasks(), usedLlm: false, routes: {}, warnings: [warning] };
+	}
+}
+
+function applyRoute(task: AgentTask, config: SubagentConfig, routes: Record<string, string>): AgentTask {
+	if (hasText(task.subagentType)) return task;
+	const fallback = withFallbackType(task, config);
+	return routes[task.id] ? { ...fallback, subagentType: routes[task.id] } : fallback;
+}
+
+function withFallbackType(task: AgentTask, config: SubagentConfig): AgentTask {
+	if (hasText(task.subagentType)) return task;
+	const fallback = defaultSubagentType(config);
+	return fallback ? { ...task, subagentType: fallback } : task;
+}
+
+function buildRoutingPrompt(tasks: AgentTask[], config: SubagentConfig, routing: ResolvedSubagentRoutingConfig): string {
+	return [
+		"Choose subagentType for each task.",
+		"",
+		"Allowed types (type: description):",
+		...Object.entries(config.types).map(([name, profile]) => {
+			return `- ${name}: ${profile.description ?? "No description; use only when the task explicitly names this type."}`;
+		}),
+		"",
+		`Default fallback if genuinely ambiguous: ${defaultSubagentType(config) ?? "none"}`,
+		"",
+		"Tasks:",
+		JSON.stringify(tasks.map((task) => ({
+			id: task.id,
+			task: truncate(task.task, routing.maxTaskChars),
+			scope: truncate(task.scope, routing.maxTaskChars),
+			parentObjective: truncate(task.parentObjective, routing.maxTaskChars),
+			hasImages: Array.isArray(task.imagePaths) && task.imagePaths.length > 0,
+			focus: truncate(task.focus, routing.maxTaskChars),
+		})), null, 2),
+	].join("\n");
+}
+
+async function resolveRoutingModel(ctx: SubagentRoutingContext, routing: ResolvedSubagentRoutingConfig): Promise<{
+	model: Model<Api>;
+	apiKey?: string;
+	headers?: Record<string, string>;
+} | undefined> {
+	const configured = await resolveModelRef(ctx, routing.model);
+	if (configured) return configured;
+	const parentModel = currentModelRef(ctx.model);
+	return parentModel && parentModel !== routing.model ? resolveModelRef(ctx, parentModel) : undefined;
+}
+
+async function resolveModelRef(ctx: SubagentRoutingContext, modelRef: string): Promise<{
+	model: Model<Api>;
+	apiKey?: string;
+	headers?: Record<string, string>;
+} | undefined> {
+	const parsed = parseModelRef(modelRef);
+	if (!parsed || !ctx.modelRegistry) return undefined;
+	const model = ctx.modelRegistry.find(parsed.provider, parsed.modelId);
+	if (!model) return undefined;
+	const auth = await ctx.modelRegistry.getApiKeyAndHeaders(model);
+	if (auth.ok === false) return undefined;
+	return { model, apiKey: auth.apiKey, headers: auth.headers };
+}
+
+function parseModelRef(modelRef: string): { provider: string; modelId: string } | undefined {
+	const trimmed = modelRef.trim();
+	const slash = trimmed.indexOf("/");
+	if (slash <= 0 || slash === trimmed.length - 1) return undefined;
+	return { provider: trimmed.slice(0, slash), modelId: trimmed.slice(slash + 1) };
+}
+
+function parseRoutingResponse(raw: string, config: SubagentConfig, tasks: AgentTask[]): Record<string, string> {
+	const parsed = parseJsonObject(raw);
+	const allowedTypes = new Map(Object.keys(config.types).map((name) => [name.toLowerCase(), name]));
+	const taskIds = new Set(tasks.map((task) => task.id));
+	const routes: Record<string, string> = {};
+	if (Array.isArray(parsed)) collectRouteArray(parsed, taskIds, allowedTypes, routes);
+	else if (typeof parsed === "string" && tasks.length === 1) addRoute(routes, taskIds, allowedTypes, tasks[0]!.id, parsed);
+	else if (isRecord(parsed)) {
+		if (Array.isArray(parsed.routes)) collectRouteArray(parsed.routes, taskIds, allowedTypes, routes);
+		else {
+			for (const [id, value] of Object.entries(parsed)) {
+				if (typeof value === "string") addRoute(routes, taskIds, allowedTypes, id, value);
+				else if (isRecord(value)) addRoute(routes, taskIds, allowedTypes, id, value.subagentType ?? value.type);
+			}
+		}
+	}
+	if (Object.keys(routes).length === 0 && tasks.length === 1) addRoute(routes, taskIds, allowedTypes, tasks[0]!.id, raw.trim());
+	return routes;
+}
+
+function collectRouteArray(items: unknown[], taskIds: Set<string>, allowedTypes: Map<string, string>, routes: Record<string, string>): void {
+	for (const item of items) {
+		if (!isRecord(item)) continue;
+		addRoute(routes, taskIds, allowedTypes, item.id ?? item.taskId ?? item.agentId, item.subagentType ?? item.type);
+	}
+}
+
+function addRoute(routes: Record<string, string>, taskIds: Set<string>, allowedTypes: Map<string, string>, rawId: unknown, rawType: unknown): void {
+	if (typeof rawId !== "string" || typeof rawType !== "string") return;
+	const id = rawId.trim();
+	if (!taskIds.has(id)) return;
+	const type = allowedTypes.get(rawType.trim().toLowerCase());
+	if (type) routes[id] = type;
+}
+
+function parseJsonObject(raw: string): unknown {
+	const cleaned = raw.trim()
+		.replace(/^```(?:json)?\s*/iu, "")
+		.replace(/```$/u, "")
+		.trim();
+	try {
+		return JSON.parse(cleaned) as unknown;
+	} catch {
+		const match = /(?:\[[\s\S]*\]|\{[\s\S]*\})/.exec(cleaned);
+		if (!match) return undefined;
+		try {
+			return JSON.parse(match[0]) as unknown;
+		} catch {
+			return undefined;
+		}
+	}
+}
+
+function responseText(response: { content: Array<{ type: string; text?: string }> }): string {
+	return response.content
+		.filter((block): block is { type: "text"; text: string } => block.type === "text" && typeof block.text === "string")
+		.map((block) => block.text)
+		.join("\n");
+}
+
+function notifyRoutingWarning(ctx: SubagentRoutingContext, routing: ResolvedSubagentRoutingConfig, message: string): void {
+	if (!routing.debug || !ctx.hasUI) return;
+	ctx.ui?.notify?.(message, "warning");
+}
+
+function truncate(value: unknown, maxChars: number): string | undefined {
+	if (typeof value !== "string") return undefined;
+	const trimmed = value.trim();
+	if (!trimmed) return undefined;
+	return trimmed.length <= maxChars ? trimmed : `${trimmed.slice(0, maxChars).trimEnd()}…`;
+}
+
+function hasText(value: unknown): value is string {
+	return typeof value === "string" && value.trim().length > 0;
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+	return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+function isAbortError(error: unknown): boolean {
+	return error instanceof Error && /abort/i.test(error.name || error.message);
+}
+
+function errorMessage(error: unknown): string {
+	return error instanceof Error ? error.message : String(error);
+}