feat(pi-subagent)!: add configurable model-class routing (#73)

Author: HenryQW

package-lock.json

@@ -9,13 +9,14 @@ Run one bounded task in one isolated Pi child process using a configured role.
 - **Main**: Pi session delegating work.
 - **Subagent**: isolated Pi child process handling one task.
 - **Role**: user-owned Markdown profile defining name, description, system instructions, exact tools, extensions, and Skill names.
-- **Route**: model and thinking-level pair selected for one delegation; defaults to Main route.
+- **Model Class**: `fast`, `balanced`, or `frontier`, chosen by Main from task complexity.
+- **Route**: configured model and thinking-level pair selected from Model Class; omitted class uses `balanced`, then Main route fallback.
 - **Delegated Task**: one bounded work request sent from Main to one Role.
 
 ## Invariants
 
 - One Delegated Task creates one ephemeral child process and no saved session.
 - Ambient child extensions and Skills stay disabled; Role explicitly selects resources.
 - Role Skill names resolve through Main's effective Pi Skill registry; unavailable names warn and skip without blocking delegation.
-- Main selects Role and may select Route per task.
-- Role config lives only in user `config/pi-subagent` directory; repository roles do not execute.
+- Main selects Role and Model Class per task; omitted class uses configured `balanced`, then Main route fallback.
+- Role config lives only in user `config/pi-subagent` directory; model routes live in user `config/pi-subagent.json`; repository roles do not execute.

packages/pi-subagent/CONTEXT.md

@@ -1,6 +1,6 @@
 # @henryqw/pi-subagent
 
-Delegate one bounded task to one isolated Pi process. Main chooses role and may override model and thinking level per task.
+Delegate one bounded task to one isolated Pi process. Main chooses role and model class per task.
 
 Based on Pi's authoritative [`examples/extensions/subagent`](https://github.com/earendil-works/pi/tree/main/packages/coding-agent/examples/extensions/subagent): child processes use `pi --mode json -p --no-session`.
 
@@ -12,7 +12,7 @@ pi install npm:@henryqw/pi-subagent
 
 ## Configure roles
 
-Use Pi's existing role Markdown format in package-owned `~/.pi/agent/config/pi-subagent/*.md`. No JSON config or profile layer.
+Use Pi's existing role Markdown format in package-owned `~/.pi/agent/config/pi-subagent/*.md`. Configure `fast`, `balanced`, and `frontier` model routes with `/subagent`.
 
 ```markdown
 ---
@@ -45,22 +45,35 @@ String lists may also use comma-separated text, matching Pi's example role files
 
 Skill entries use Pi Skill names, normally Skill directory names, not filesystem paths. At delegation time, package resolves names from Main's effective Pi Skill registry and passes matching files to child. Missing or unavailable Skills produce warning and are skipped; they do not block delegation. This preserves Main's trust and Skill collision decisions.
 
-Pi's example `agents/` directory contains sample Role files, not another runtime mechanism. This package reuses that Markdown format but ships no presets: model choice and capabilities stay explicit in user config. No nested `agents/` directory is needed because `pi-subagent` config contains only Roles.
+Pi's example `agents/` directory contains sample Role files, not another runtime mechanism. This package reuses that Markdown format but ships no presets: role capabilities and model routes stay explicit in user config. No nested `agents/` directory is needed because Roles remain Markdown files.
 
-Reload Pi after adding or changing role files so tool description exposes current roles.
+Reload Pi after adding or changing role files or manually editing model config. `/subagent` applies changes immediately.
 
 ## Execution
 
 Main calls `delegate_task` with:
 
 - `role`: configured role name
 - `task`: one bounded task
-- `model`: optional exact `provider/model`; defaults to Main model
-- `thinkingLevel`: optional; defaults to Main thinking level
+- `modelClass`: optional `fast`, `balanced`, or `frontier`; defaults to configured `balanced`, then Main route
+
+Run `/subagent` once per class. Select class, authenticated text model, and supported thinking level. Config lives in `~/.pi/agent/config/pi-subagent.json`:
+
+```json
+{
+  "models": {
+    "fast": { "model": "provider/fast-model", "thinkingLevel": "off" },
+    "balanced": { "model": "provider/balanced-model", "thinkingLevel": "medium" },
+    "frontier": { "model": "provider/frontier-model", "thinkingLevel": "max" }
+  }
+}
+```
+
+Explicit class routes must be configured and available. Omitted `modelClass` falls back to Main when `balanced` route is missing or stale.
 
 Each call starts isolated child process. Ambient extensions and skills are disabled. Only role resources load. Child uses delegated working directory and normal Pi project context files, inheriting Main's project approval decision. Abort terminates child process group.
 
-Model and thinking overrides must exist in Main model registry. Invalid role config, model, or thinking level fails before child starts.
+Configured model and thinking level must exist in Main model registry. Invalid role config or explicit model class fails before child starts.
 
 Main-visible streaming updates, final output, and errors are capped at 50 KiB of UTF-8 text. Error collection stays bounded while child runs; malformed JSON events above 1 MiB fail delegation. Truncated output ends with exact omitted-byte count.
 

packages/pi-subagent/README.md

@@ -1,14 +1,16 @@
 import { spawn } from "node:child_process";
-import { existsSync, readFileSync, readdirSync } from "node:fs";
+import { existsSync, mkdirSync, readFileSync, readdirSync, writeFileSync } from "node:fs";
 import { mkdtemp, rm, writeFile } from "node:fs/promises";
 import { tmpdir } from "node:os";
-import { basename, isAbsolute, join } from "node:path";
+import { basename, dirname, isAbsolute, join } from "node:path";
 import { getSupportedThinkingLevels, StringEnum } from "@earendil-works/pi-ai";
 import { type ExtensionAPI, type ExtensionContext, getAgentDir, parseFrontmatter, type Theme } from "@earendil-works/pi-coding-agent";
 import { type Component, truncateToWidth, type TUI, visibleWidth } from "@earendil-works/pi-tui";
 import { Type } from "typebox";
 
 const THINKING_LEVELS = ["off", "minimal", "low", "medium", "high", "xhigh", "max"] as const;
+const MODEL_CLASSES = ["fast", "balanced", "frontier"] as const;
+const configPath = () => join(getAgentDir(), "config", "pi-subagent.json");
 const MAX_OUTPUT_BYTES = 50 * 1024;
 const MAX_JSON_EVENT_BYTES = 1024 * 1024;
 const WIDGET_KEY = "subagent-status";
@@ -18,6 +20,9 @@ const MAX_WIDGET_ROWS = 8;
 const SPINNER_FRAMES = ["⠋", "⠙", "⠹", "⠸", "⠼", "⠴", "⠦", "⠧", "⠇", "⠏"];
 
 type ThinkingLevel = (typeof THINKING_LEVELS)[number];
+type ModelClass = (typeof MODEL_CLASSES)[number];
+type ConfiguredModel = { model: string; thinkingLevel: ThinkingLevel };
+type Config = { models: Partial<Record<ModelClass, ConfiguredModel>> };
 type Role = {
 	name: string;
 	description: string;
@@ -44,6 +49,62 @@ type WidgetItem = {
 	removeAt?: number;
 };
 
+const defaultConfig = (): Config => ({ models: {} });
+const isModelClass = (value: unknown): value is ModelClass =>
+	typeof value === "string" && MODEL_CLASSES.includes(value as ModelClass);
+const isThinkingLevel = (value: unknown): value is ThinkingLevel =>
+	typeof value === "string" && THINKING_LEVELS.includes(value as ThinkingLevel);
+const isModelReference = (value: unknown): value is string => {
+	if (typeof value !== "string" || value !== value.trim() || value.includes("\0")) return false;
+	const separator = value.indexOf("/");
+	return separator > 0 && separator < value.length - 1;
+};
+
+function readConfig(): { value: Config; invalid: boolean } {
+	try {
+		const value = JSON.parse(readFileSync(configPath(), "utf8")) as unknown;
+		if (!value || typeof value !== "object" || Array.isArray(value)) return { value: defaultConfig(), invalid: true };
+		const record = value as Record<string, unknown>;
+		if (Object.keys(record).some((key) => key !== "models")) return { value: defaultConfig(), invalid: true };
+		if (record.models === undefined) return { value: defaultConfig(), invalid: false };
+		if (!record.models || typeof record.models !== "object" || Array.isArray(record.models)) {
+			return { value: defaultConfig(), invalid: true };
+		}
+		const modelRecord = record.models as Record<string, unknown>;
+		const models: Config["models"] = {};
+		let invalid = Object.keys(modelRecord).some((key) => !isModelClass(key));
+		for (const modelClass of MODEL_CLASSES) {
+			if (!Object.hasOwn(modelRecord, modelClass)) continue;
+			const candidate = modelRecord[modelClass];
+			if (!candidate || typeof candidate !== "object" || Array.isArray(candidate)) {
+				invalid = true;
+				continue;
+			}
+			const route = candidate as Record<string, unknown>;
+			if (isModelReference(route.model) && isThinkingLevel(route.thinkingLevel)) {
+				models[modelClass] = { model: route.model, thinkingLevel: route.thinkingLevel };
+			} else invalid = true;
+		}
+		return { value: { models }, invalid };
+	} catch (error: unknown) {
+		if (error && typeof error === "object" && "code" in error && error.code === "ENOENT") {
+			return { value: defaultConfig(), invalid: false };
+		}
+		return { value: defaultConfig(), invalid: true };
+	}
+}
+
+function writeConfig(config: Config): void {
+	const file = configPath();
+	mkdirSync(dirname(file), { recursive: true });
+	writeFileSync(file, `${JSON.stringify(config, null, 2)}\n`);
+}
+
+const modelReference = (model: { provider: string; id: string }): string => `${model.provider}/${model.id}`;
+const availableTextModels = (ctx: ExtensionContext) => ctx.modelRegistry
+	.getAvailable()
+	.filter((model) => model.input.includes("text"));
+
 const cleanText = (value: unknown, field: string, file: string): string => {
 	if (typeof value !== "string" || !value.trim() || value.includes("\0")) {
 		throw new Error(`${file}: ${field} must be non-empty text.`);
@@ -404,9 +465,8 @@ async function runPi(
 const Parameters = Type.Object({
 	role: Type.String({ description: "Configured Subagent role name" }),
 	task: Type.String({ description: "One bounded task with needed context and expected result" }),
-	model: Type.Optional(Type.String({ description: "Exact provider/model; defaults to Main model" })),
-	thinkingLevel: Type.Optional(StringEnum(THINKING_LEVELS, {
-		description: "Thinking level; defaults to Main thinking level",
+	modelClass: Type.Optional(StringEnum(MODEL_CLASSES, {
+		description: "Classify task complexity: fast for narrow lookups or mechanical edits; balanced for normal bounded work; frontier for ambiguous, cross-cutting, or high-risk reasoning. Defaults to configured balanced, then Main route.",
 	})),
 });
 
@@ -439,6 +499,7 @@ export default function subagentExtension(pi: ExtensionAPI): void {
 	let widgetTimer: ReturnType<typeof setInterval> | undefined;
 	let spinnerIndex = 0;
 	let activeTui: TUI | undefined;
+	let config = defaultConfig();
 
 	const stopWidgetTimer = () => {
 		if (!widgetTimer) return;
@@ -512,7 +573,16 @@ export default function subagentExtension(pi: ExtensionAPI): void {
 		requestWidgetRender();
 	};
 
-	pi.on("session_start", (_event, ctx) => ensureWidget(ctx));
+	const refreshConfig = (ctx: ExtensionContext) => {
+		const loaded = readConfig();
+		config = loaded.value;
+		if (loaded.invalid) ctx.ui.notify("Invalid pi-subagent config values were ignored.", "warning");
+	};
+
+	pi.on("session_start", (_event, ctx) => {
+		ensureWidget(ctx);
+		refreshConfig(ctx);
+	});
 	pi.on("session_shutdown", (_event, ctx) => {
 		stopWidgetTimer();
 		widgetItems.clear();
@@ -521,10 +591,52 @@ export default function subagentExtension(pi: ExtensionAPI): void {
 		if (ctx.hasUI) ctx.ui.setWidget(WIDGET_KEY, undefined);
 	});
 
+	pi.registerCommand("subagent", {
+		description: "configure fast, balanced, and frontier Subagent model routes",
+		handler: async (args, ctx) => {
+			if (args.trim()) {
+				ctx.ui.notify("Usage: /subagent", "warning");
+				return;
+			}
+			refreshConfig(ctx);
+			const modelClass = await ctx.ui.select("Subagent model class", [...MODEL_CLASSES]);
+			if (!isModelClass(modelClass)) return;
+			const models = availableTextModels(ctx);
+			if (!models.length) {
+				ctx.ui.notify("No authenticated text models are available.", "warning");
+				return;
+			}
+			const saved = config.models[modelClass];
+			const references = models.map(modelReference).sort();
+			const selected = await ctx.ui.select(
+				`${modelClass} Subagent model · saved: ${saved?.model ?? "none"}`,
+				references,
+			);
+			const selectedModel = models.find((model) => modelReference(model) === selected);
+			if (!selectedModel) return;
+			const levels = getSupportedThinkingLevels(selectedModel);
+			const thinkingLevel = await ctx.ui.select(
+				`${modelClass} Subagent thinking level · saved: ${saved?.thinkingLevel ?? "none"}`,
+				levels,
+			);
+			if (!isThinkingLevel(thinkingLevel) || !levels.some((level) => level === thinkingLevel)) return;
+			try {
+				const latest = readConfig();
+				const route = { model: modelReference(selectedModel), thinkingLevel };
+				const next = { ...latest.value, models: { ...latest.value.models, [modelClass]: route } };
+				writeConfig(next);
+				config = next;
+				ctx.ui.notify(`${modelClass} Subagent set to ${route.model} with thinking ${thinkingLevel}.`, "info");
+			} catch {
+				ctx.ui.notify("Couldn't save pi-subagent model config.", "warning");
+			}
+		},
+	});
+
 	pi.registerTool({
 		name: "delegate_task",
 		label: "Subagent",
-		description: `Delegate one bounded task to one isolated Pi Subagent. Roles: ${roleSummary()}. Select model and thinking level only when task needs a different route. Request concise conclusions and file/line references; split broad scouting work.`,
+		description: `Delegate one bounded task to one isolated Pi Subagent. Roles: ${roleSummary()}. Choose fast for narrow work, balanced for normal work, or frontier for ambiguous and high-risk work. Request concise conclusions and file/line references; split broad scouting work.`,
 		parameters: Parameters,
 		async execute(toolCallId, params, signal, onUpdate, ctx) {
 			const task = cleanText(params.task, "task", "delegate_task");
@@ -534,16 +646,33 @@ export default function subagentExtension(pi: ExtensionAPI): void {
 				throw new Error(`Unknown Subagent role: ${params.role}. Available roles: ${roles.map(({ name }) => name).join(", ") || "none"}.`);
 			}
 
-			const modelReference = params.model ?? (ctx.model ? `${ctx.model.provider}/${ctx.model.id}` : undefined);
-			if (!modelReference || modelReference.includes("\0")) throw new Error("Subagent model is missing.");
-			const model = ctx.modelRegistry.getAvailable().find(
-				(candidate) => `${candidate.provider}/${candidate.id}` === modelReference && candidate.input.includes("text"),
-			);
-			if (!model) throw new Error(`Subagent model is unavailable: ${modelReference}.`);
-
-			const thinkingLevel = params.thinkingLevel ?? ctx.thinkingLevel;
+			refreshConfig(ctx);
+			if (!ctx.model) throw new Error("delegate_task requires an active Pi model.");
+			if (params.modelClass !== undefined && !isModelClass(params.modelClass)) {
+				throw new Error("delegate_task modelClass must be fast, balanced, or frontier.");
+			}
+			const modelClass = params.modelClass ?? "balanced";
+			const configuredModel = config.models[modelClass];
+			if (params.modelClass && !configuredModel) {
+				throw new Error(`No ${modelClass} Subagent model configured; run /subagent.`);
+			}
+			const selectedModelInfo = configuredModel && availableTextModels(ctx)
+				.find((model) => modelReference(model) === configuredModel.model);
+			if (params.modelClass && configuredModel && !selectedModelInfo) {
+				throw new Error(`Configured ${modelClass} Subagent model is unavailable; run /subagent.`);
+			}
+			const thinkingAvailable = Boolean(configuredModel && selectedModelInfo
+				&& getSupportedThinkingLevels(selectedModelInfo).some((level) => level === configuredModel.thinkingLevel));
+			if (params.modelClass && configuredModel && selectedModelInfo && !thinkingAvailable) {
+				throw new Error(`Configured ${modelClass} Subagent thinking level is unavailable; run /subagent.`);
+			}
+			const configuredRoute = thinkingAvailable ? configuredModel : undefined;
+			const modelReferenceValue = configuredRoute?.model ?? modelReference(ctx.model);
+			const model = configuredRoute ? selectedModelInfo : ctx.model;
+			if (!model) throw new Error("Subagent model metadata is unavailable.");
+			const thinkingLevel = configuredRoute?.thinkingLevel ?? ctx.thinkingLevel;
 			if (thinkingLevel && !getSupportedThinkingLevels(model).includes(thinkingLevel)) {
-				throw new Error(`Subagent thinking level ${thinkingLevel} is unavailable for ${modelReference}.`);
+				throw new Error(`Subagent thinking level ${thinkingLevel} is unavailable for ${modelReferenceValue}.`);
 			}
 
 			const resolvedSkills = resolveSkillPaths(pi, role.skills);
@@ -564,13 +693,13 @@ export default function subagentExtension(pi: ExtensionAPI): void {
 				for (const skill of resolvedSkills.paths) args.push("--skill", skill);
 				if (role.tools.length) args.push("--tools", role.tools.join(","));
 				else args.push("--no-tools");
-				args.push("--model", modelReference);
+				args.push("--model", modelReferenceValue);
 				if (thinkingLevel) args.push("--thinking", thinkingLevel);
 				args.push(ctx.isProjectTrusted() ? "--approve" : "--no-approve");
 				args.push("--append-system-prompt", promptPath, `Task: ${task}`);
 
 				startWidgetItem(toolCallId, role.name, model.id, thinkingLevel, task, ctx);
-				const details = { role: role.name, model: modelReference, thinkingLevel };
+				const details = { role: role.name, model: modelReferenceValue, thinkingLevel };
 				const result = await runPi(
 					args,
 					ctx.cwd,

packages/pi-subagent/extensions/subagent.ts

@@ -1,6 +1,6 @@
 {
   "name": "@henryqw/pi-subagent",
-  "version": "0.1.1",
+  "version": "1.0.0",
   "description": "Delegate one task to an isolated Pi role with explicit extensions and skills.",
   "keywords": [
     "pi-package",