@henryqw/pi-subagent 0.1.1 → 1.1.0

package/README.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
 ---
@@ -36,18 +36,20 @@ Fields:
 | --- | --- | --- |
 | `name` | yes | Role selected by Main |
 | `description` | yes | Tells Main when to use role |
-| `tools` | yes | Exact built-in and extension tool allowlist; use `[]` for none |
+| `tools` | no | Omit for Pi effective `defaultTools`; a non-empty list is an exact built-in and extension tool allowlist; use `[]` for none |
 | `extensions` | no | Absolute/user-home paths or package sources passed to Pi `--extension` |
 | `skills` | no | Effective Pi Skill names loaded for role |
 | Markdown body | yes | Role system instructions |
 
+Omitted `tools` uses Pi's effective `defaultTools` for built-ins. Tools registered by Role extensions stay active without listing their names. A non-empty `tools` list strictly allowlists both built-in and extension tools; `tools: []` sends `--no-tools`.
+
 String lists may also use comma-separated text, matching Pi's example role files. Repository-relative extension paths are rejected: child working directory is delegated project, so relative paths could load untrusted project code. Use absolute paths, `~/...`, or explicit package sources such as `npm:...`.
 
 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
 
@@ -55,12 +57,25 @@ 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.
 

package/extensions/subagent.ts

@@ -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,10 +20,13 @@ 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;
-	tools: string[];
+	tools?: string[];
 	extensions: string[];
 	skills: string[];
 	systemPrompt: 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.`);
@@ -100,7 +161,7 @@ export function loadRoles(agentDir = getAgentDir()): Role[] {
 			return {
 				name: cleanText(frontmatter.name, "name", file),
 				description: cleanText(frontmatter.description, "description", file),
-				tools: stringList(frontmatter.tools, "tools", file, true),
+				tools: frontmatter.tools === undefined ? undefined : stringList(frontmatter.tools, "tools", file, true),
 				extensions: extensionList(frontmatter.extensions, file),
 				skills: stringList(frontmatter.skills, "skills", file),
 				systemPrompt: cleanText(parsed.body, "system prompt", file),
@@ -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);
@@ -562,15 +691,17 @@ export default function subagentExtension(pi: ExtensionAPI): void {
 				const args = ["--mode", "json", "-p", "--no-session", "--no-extensions", "--no-skills"];
 				for (const extension of role.extensions) args.push("--extension", extension);
 				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);
+				if (role.tools !== undefined) {
+					if (role.tools.length) args.push("--tools", role.tools.join(","));
+					else args.push("--no-tools");
+				}
+				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,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@henryqw/pi-subagent",
-  "version": "0.1.1",
+  "version": "1.1.0",
   "description": "Delegate one task to an isolated Pi role with explicit extensions and skills.",
   "keywords": [
     "pi-package",
@@ -24,9 +24,9 @@
     "pack:check": "npm pack --dry-run"
   },
   "peerDependencies": {
-    "@earendil-works/pi-ai": "^0.84.1",
-    "@earendil-works/pi-coding-agent": "^0.84.1",
-    "@earendil-works/pi-tui": "^0.84.1",
+    "@earendil-works/pi-ai": "^0.84.2",
+    "@earendil-works/pi-coding-agent": "^0.84.2",
+    "@earendil-works/pi-tui": "^0.84.2",
     "typebox": "^1.3.7"
   },
   "repository": {