@henryqw/pi-subagent 1.1.1 → 2.0.2

package/README.md

@@ -1,18 +1,37 @@
-# @henryqw/pi-subagent
+# `@henryqw/pi-subagent`
 
-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`.
+Delegate one bounded task to one isolated Pi process. Main chooses the role and model class per call.
 
 ## Install
 
 ```bash
+pi install npm:@henryqw/pi-task-models
+pi install npm:@henryqw/pi-multi-codex
 pi install npm:@henryqw/pi-subagent
 ```
 
-## Configure roles
+## With
+
+| Package | Why |
+| --- | --- |
+| `@henryqw/pi-task-models` | Required. Shared `fast` / `balanced` / `frontier` routes. |
+| `@henryqw/pi-multi-codex` | Required. Child uses Main's active Codex slot. |
+
+## Use
+
+| Surface | Type | Purpose |
+| --- | --- | --- |
+| `delegate_task` | tool | Start one isolated child for `role`, `task`, and optional `modelClass`. |
+
+`modelClass` is `fast`, `balanced`, or `frontier`. Omitted class uses `balanced`. Primary route is resolved against current scoped text models; fallback is tried only before launch. If no route is usable, delegation rejects with `Run /task-models`. A started child is never retried.
+
+Each call starts one isolated child (`pi --mode json -p --no-session`). Ambient extensions and skills are off; only role resources load. Child uses the delegated working directory and Main's project approval. Abort kills the child process group. Streaming output is capped at 50 KiB.
+
+TUI shows one row per Subagent with role, route, task, tokens, and elapsed time. Terminal rows drop after one second.
 
-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`.
+## Config
+
+Role files live in `~/.pi/agent/config/pi-subagent/*.md`. Model routes live in `~/.pi/agent/config/pi-task-models.json`.
 
 ```markdown
 ---
@@ -30,76 +49,27 @@ Review only requested change. Return ranked findings with file and line evidence
 Do not edit files.
 ```
 
-Fields:
-
 | Field | Required | Meaning |
 | --- | --- | --- |
 | `name` | yes | Role selected by Main |
-| `description` | yes | Tells Main when to use role |
-| `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 |
+| `description` | yes | Tells Main when to use the role |
+| `tools` | no | Omit for Pi `defaultTools`; a non-empty list is an exact allowlist; `[]` means none |
+| `extensions` | no | Absolute/`~/` paths or package sources. Repository-relative paths are rejected. |
+| `skills` | no | Effective Pi skill names, resolved from Main's registry |
 | 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: 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 or manually editing model config. `/subagent` applies changes immediately.
-
-## Execution
+Missing skills warn and skip; they do not block delegation. No repo-controlled `.pi/agents` roles. No package-local model picker.
 
-Main calls `delegate_task` with:
+## Remove
 
-- `role`: configured role name
-- `task`: one bounded task
-- `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" }
-  }
-}
+```bash
+pi remove npm:@henryqw/pi-subagent
 ```
 
-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.
-
-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.
-
-## Widget
+## Development
 
-TUI shows one aligned row per Subagent:
-
-```text
-⠼  scout[haiku:low]       find auth flow     18.4k   8s
-✓  reviewer[sonnet:high]  inspect auth diff  22.1k  14s
-✗  worker[sonnet:high]    fix token expiry   31.8k  27s
-■  scout[haiku:low]       map routes          6.2k   5s
+```bash
+npm test --workspace @henryqw/pi-subagent
+npm run typecheck --workspace @henryqw/pi-subagent
+npm run pack:check --workspace @henryqw/pi-subagent
 ```
-
-Spinner means working; terminal icons mean success, failure, or abort. Token column sums `usage.totalTokens` across Subagent turns. Terminal rows auto-remove after one second; empty widget renders nothing. Role/route and task columns truncate to preserve right-aligned token and elapsed columns on narrow terminals.
-
-## Scouting roles
-
-Treat scouting result as index, not file dump. Put conclusions first, followed by exact file/line references, short snippets only, risks, and unexamined scope. Main can read cited files when more detail is needed. Split work when useful index cannot fit within output cap.
-
-## Deliberate limits
-
-- User roles only; no repo-controlled `.pi/agents` trust flow.
-- One task per call; Main handles orchestration.
-- No custom profile schema; role Markdown already groups instructions, tools, extensions, and skills.
-- No persistent child sessions or interactive panes.
-- No full-result artifact or retrieval protocol; split oversized work instead.

package/extensions/subagent.ts

@@ -1,16 +1,26 @@
 import { spawn } from "node:child_process";
-import { existsSync, mkdirSync, readFileSync, readdirSync, writeFileSync } from "node:fs";
+import { existsSync, readFileSync, readdirSync } from "node:fs";
 import { mkdtemp, rm, writeFile } from "node:fs/promises";
 import { tmpdir } from "node:os";
-import { basename, dirname, isAbsolute, join } from "node:path";
-import { getSupportedThinkingLevels, StringEnum } from "@earendil-works/pi-ai";
+import { basename, isAbsolute, join } from "node:path";
+import { fileURLToPath } from "node:url";
+import { 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 {
+	modelReference,
+	orderedProfileRoutes,
+	PROFILE_NAMES,
+	readTaskModelsConfig,
+	resolveTaskModelRoute,
+	type ProfileName,
+	type ResolvedTaskRoute,
+} from "@henryqw/pi-task-models";
 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 MODEL_CLASSES = PROFILE_NAMES;
+const CODEX_ALIAS = /^openai-codex-(?:[2-9]|[1-9]\d+)$/;
+const MULTI_CODEX_EXTENSION = fileURLToPath(import.meta.resolve("@henryqw/pi-multi-codex/extensions/multi-codex.ts"));
 const MAX_OUTPUT_BYTES = 50 * 1024;
 const MAX_JSON_EVENT_BYTES = 1024 * 1024;
 const WIDGET_KEY = "subagent-status";
@@ -19,10 +29,7 @@ const TERMINAL_DISPLAY_MS = 1_000;
 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 ModelClass = ProfileName;
 type Role = {
 	name: string;
 	description: string;
@@ -49,62 +56,27 @@ 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;
-};
+const isNumberedCodexProvider = (provider: string): boolean => CODEX_ALIAS.test(provider);
 
-function readConfig(): { value: Config; invalid: boolean } {
+function resolveTaskRoute(ctx: ExtensionContext, modelClass: ModelClass): ResolvedTaskRoute {
+	let config;
 	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 };
+		config = readTaskModelsConfig();
+	} catch {
+		throw new Error("Couldn't read task model config. Run /task-models.");
 	}
-}
 
-function writeConfig(config: Config): void {
-	const file = configPath();
-	mkdirSync(dirname(file), { recursive: true });
-	writeFileSync(file, `${JSON.stringify(config, null, 2)}\n`);
+	const profile = config.profiles[modelClass];
+	if (!profile) throw new Error(`No ${modelClass} task model profile is configured. Run /task-models.`);
+	for (const route of orderedProfileRoutes(profile)) {
+		const resolved = resolveTaskModelRoute(ctx, route);
+		if (resolved) return resolved;
+	}
+	throw new Error(`No usable ${modelClass} task model route. Run /task-models.`);
 }
 
-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.`);
@@ -466,7 +438,7 @@ 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" }),
 	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.",
+		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 the shared balanced profile.",
 	})),
 });
 
@@ -499,8 +471,6 @@ 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;
 		clearInterval(widgetTimer);
@@ -573,15 +543,8 @@ export default function subagentExtension(pi: ExtensionAPI): void {
 		requestWidgetRender();
 	};
 
-	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();
@@ -591,48 +554,6 @@ 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",
@@ -646,34 +567,14 @@ export default function subagentExtension(pi: ExtensionAPI): void {
 				throw new Error(`Unknown Subagent role: ${params.role}. Available roles: ${roles.map(({ name }) => name).join(", ") || "none"}.`);
 			}
 
-			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 ${modelReferenceValue}.`);
-			}
+			const resolvedRoute = resolveTaskRoute(ctx, modelClass);
+			const model = resolvedRoute.model;
+			const modelReferenceValue = modelReference(model);
+			const thinkingLevel = resolvedRoute.thinkingLevel;
 
 			const resolvedSkills = resolveSkillPaths(pi, role.skills);
 			if (resolvedSkills.missing.length) {
@@ -689,7 +590,10 @@ export default function subagentExtension(pi: ExtensionAPI): void {
 			try {
 				await writeFile(promptPath, role.systemPrompt, { encoding: "utf8", mode: 0o600 });
 				const args = ["--mode", "json", "-p", "--no-session", "--no-extensions", "--no-skills"];
-				for (const extension of role.extensions) args.push("--extension", extension);
+				const extensions = isNumberedCodexProvider(model.provider)
+					? [...role.extensions, MULTI_CODEX_EXTENSION]
+					: role.extensions;
+				for (const extension of new Set(extensions)) args.push("--extension", extension);
 				for (const skill of resolvedSkills.paths) args.push("--skill", skill);
 				if (role.tools !== undefined) {
 					if (role.tools.length) args.push("--tools", role.tools.join(","));

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@henryqw/pi-subagent",
-  "version": "1.1.1",
+  "version": "2.0.2",
   "description": "Delegate one task to an isolated Pi role with explicit extensions and skills.",
   "keywords": [
     "pi-package",
@@ -44,5 +44,9 @@
     "extensions": [
       "./extensions/subagent.ts"
     ]
+  },
+  "dependencies": {
+    "@henryqw/pi-multi-codex": "^0.3.8",
+    "@henryqw/pi-task-models": "^0.1.0"
   }
 }