@henryqw/pi-subagent 2.1.0 → 2.2.0

package/CONTEXT.md

@@ -0,0 +1,27 @@
+# Pi Subagent Context
+
+## Purpose
+
+Provide validated user Roles, shared task-model Pi launch policy, generic managed Herdr Subagent hosting, and a `delegate_task` extension that runs one bounded task in one isolated child process.
+
+## Domain glossary
+
+- **Main**: Pi session delegating work.
+- **Subagent**: isolated Pi child process handling one task.
+- **Role**: user-owned Markdown profile defining name, description, system instructions, optional exact tool allowlist, extensions, and Skill names.
+- **Model Class**: `fast`, `balanced`, or `frontier`, assigned in shared task-model settings or overridden by Main from task complexity.
+- **Route**: configured model and thinking-level pair selected from a shared Model Class profile; the primary route precedes its optional fallback.
+- **Delegated Task**: one bounded work request sent from Main to one Role.
+- **Pi Launch**: reusable `{env,args}` policy for one Role, resolved model route, explicit caller resources, and project trust.
+- **Managed Subagent**: Pi agent hosted in a reconciled Herdr tab or pane; lifecycle orchestration remains with the caller.
+
+## Invariants
+
+- One Delegated Task creates one ephemeral child process and no saved session.
+- Ambient child extensions and Skills stay disabled; Role explicitly selects extensions and Skills. Omitted Role tools use Pi's effective `defaultTools` for built-ins; an explicit list is strict.
+- Role Skill names resolve through Main's effective Pi Skill registry; unavailable names warn and skip without blocking delegation.
+- Main selects Role and may override Model Class per task; omitted class uses shared `pi-subagent/delegateTask` assignment, initially `balanced`. Library callers select Role plus their own shared task ID.
+- The selected profile resolves primary then fallback only before launch when a route, model, or thinking level is unavailable. If neither route is usable, launch rejects with `Run /task-models`; a started child is never retried by this package.
+- Role config lives only in user `config/pi-subagent` directory; model routes live in shared `config/pi-task-models.json`; repository roles do not execute.
+- Numbered Codex routes prefer Main's active account slot and explicitly load the multi-Codex child extension.
+- Generic Herdr host functions validate workspace ownership and provisioning identity while callers retain domain state, prompts, and lifecycle decisions.

package/README.md

@@ -1,6 +1,6 @@
 # `@henryqw/pi-subagent`
 
-Delegate one bounded task to one isolated Pi process. Main chooses the role and may override shared task-model effort per call.
+Delegate one bounded task to one isolated Pi process, or reuse validated Role launch and managed Herdr hosting for durable workers. Main chooses Role and may override shared task-model effort per call.
 
 ## Install
 
@@ -60,6 +60,34 @@ Do not edit files.
 
 Missing skills warn and skip; they do not block delegation. No repo-controlled `.pi/agents` roles. No package-local model picker.
 
+## Library API
+
+Package root exports shared `Role` loading, Skill resolution, task-routed Pi launch, and generic managed Herdr lifecycle:
+
+```ts
+import {
+  loadRoles,
+  resolveRoleLaunch,
+  managedSubagentWorkspaceId,
+  reconcileManagedSubagentTab,
+  startManagedSubagent,
+} from "@henryqw/pi-subagent";
+
+const role = loadRoles().find(({ name }) => name === "reviewer")!;
+const launch = resolveRoleLaunch(pi, ctx, {
+  role,
+  taskId: "your-package/review",
+  extensions: [adapterExtensionPath],
+  tools: ["submit_review"],
+});
+const workspaceId = await managedSubagentWorkspaceId(ctx.cwd, mainPane, { execute });
+const host = { cwd: ctx.cwd, workspaceId };
+const tab = await reconcileManagedSubagentTab(host, { cwd: worktree, launch, label }, { execute });
+await startManagedSubagent(host, agentName, tab.paneId, launch, { execute });
+```
+
+`resolveRoleLaunch` uses shared task assignment and effective Pi registries. Caller tools extend explicit Role allowlists; omitted Role `tools` preserves Pi defaults. Generic host APIs contain no workflow prompts or durable state.
+
 ## Remove
 
 ```bash

package/dist/index.d.ts

@@ -0,0 +1,79 @@
+import { type ExtensionAPI, type ExtensionContext } from "@earendil-works/pi-coding-agent";
+import { type HerdrExecutor } from "@henryqw/pi-herdr";
+import { type AvailableModel, type ProfileName, type ResolvedTaskRoute, type ThinkingLevel } from "@henryqw/pi-task-models";
+export interface Role {
+    name: string;
+    description: string;
+    tools?: string[];
+    extensions: string[];
+    skills: string[];
+    systemPrompt: string;
+}
+export interface PiLaunch {
+    env: Record<string, string>;
+    args: string[];
+}
+export interface ResolvedRoleLaunch extends PiLaunch {
+    model: AvailableModel;
+    thinkingLevel: ThinkingLevel;
+    missingSkills: string[];
+}
+export interface CreateRoleLaunchInput {
+    role: Role;
+    route: ResolvedTaskRoute;
+    extensions?: readonly string[];
+    tools?: readonly string[];
+    env?: Readonly<Record<string, string>>;
+}
+export interface ResolveRoleLaunchInput extends Omit<CreateRoleLaunchInput, "route"> {
+    taskId: string;
+    agentDir?: string;
+}
+export interface ResolvedRoleSkills {
+    paths: string[];
+    missing: string[];
+}
+export declare const isProfileName: (value: unknown) => value is ProfileName;
+export declare function loadRoles(agentDir?: string): Role[];
+export declare function resolveTaskRoute(ctx: ExtensionContext, profileName: ProfileName, agentDir?: string): ResolvedTaskRoute;
+export declare function resolveRoleSkills(pi: Pick<ExtensionAPI, "getCommands">, role: Role): ResolvedRoleSkills;
+export declare function createRoleLaunch(pi: Pick<ExtensionAPI, "getCommands">, ctx: Pick<ExtensionContext, "isProjectTrusted">, input: CreateRoleLaunchInput): ResolvedRoleLaunch;
+export declare function resolveRoleLaunch(pi: Pick<ExtensionAPI, "getCommands">, ctx: ExtensionContext, input: ResolveRoleLaunchInput): ResolvedRoleLaunch;
+export interface ManagedSubagentHost {
+    cwd: string;
+    workspaceId: string;
+}
+export interface ManagedSubagentCommandOptions {
+    cwd: string;
+}
+export type ManagedSubagentExecutor = HerdrExecutor<ManagedSubagentCommandOptions>;
+export interface ManagedSubagentHostOptions {
+    execute: ManagedSubagentExecutor;
+    delay?: (milliseconds: number) => Promise<void>;
+}
+export interface ManagedSubagentTab {
+    tabId: string;
+    paneId: string;
+}
+export declare function launchEnvironmentArgs(launch: PiLaunch): string[];
+export declare function managedSubagentName(workspaceId: string, ...identity: string[]): string;
+export declare function managedSubagentWorkspaceId(cwd: string, mainPane: string, options: ManagedSubagentHostOptions): Promise<string>;
+/** Returns pane ID to Herdr status for agents owned by this workspace. */
+export declare function listManagedSubagents(host: ManagedSubagentHost, options: ManagedSubagentHostOptions): Promise<Map<string, string>>;
+export declare function createManagedSubagentTab(host: ManagedSubagentHost, cwd: string, launch: PiLaunch, label: string, options: ManagedSubagentHostOptions): Promise<ManagedSubagentTab>;
+export declare function reconcileManagedSubagentTab(host: ManagedSubagentHost, input: {
+    tabId?: string;
+    paneId?: string;
+    cwd: string;
+    launch: PiLaunch;
+    label: string;
+}, options: ManagedSubagentHostOptions): Promise<ManagedSubagentTab>;
+export declare function findManagedSubagentTab(host: ManagedSubagentHost, label: string, options: ManagedSubagentHostOptions): Promise<ManagedSubagentTab | undefined>;
+export declare function managedSubagentTabExists(host: ManagedSubagentHost, tabId: string, options: ManagedSubagentHostOptions): Promise<boolean>;
+export declare function reconcileManagedSubagentPane(host: ManagedSubagentHost, tabId: string, rootPaneId: string, cwd: string, launch: PiLaunch, label: string, options: ManagedSubagentHostOptions): Promise<string>;
+export declare function startManagedSubagent(host: ManagedSubagentHost, agent: string, pane: string, launch: PiLaunch, options: ManagedSubagentHostOptions, hooks?: {
+    beforeStart?: () => Promise<void>;
+    onStarted?: () => Promise<void>;
+}): Promise<"existing" | "started">;
+export declare function promptManagedSubagent(host: ManagedSubagentHost, agent: string, prompt: string | Record<string, unknown>, options: ManagedSubagentHostOptions): Promise<void>;
+export declare function retireManagedSubagentTab(host: ManagedSubagentHost, tabId: string, options: ManagedSubagentHostOptions): Promise<void>;

package/dist/index.js

@@ -0,0 +1,396 @@
+import { createHash } from "node:crypto";
+import { readFileSync, readdirSync } from "node:fs";
+import { isAbsolute, join } from "node:path";
+import { fileURLToPath } from "node:url";
+import { getAgentDir, parseFrontmatter } from "@earendil-works/pi-coding-agent";
+import { createHerdrClient, herdrCommandFailure, hasHerdrErrorCode } from "@henryqw/pi-herdr";
+import { modelReference, orderedProfileRoutes, PROFILE_NAMES, readTaskModelsConfig, resolveConfiguredTaskRoute, resolveTaskModelRoute, } from "@henryqw/pi-task-models";
+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"));
+export const isProfileName = (value) => typeof value === "string" && PROFILE_NAMES.includes(value);
+const cleanText = (value, field, source) => {
+    if (typeof value !== "string" || !value.trim() || value.includes("\0")) {
+        throw new Error(`${source}: ${field} must be non-empty text.`);
+    }
+    return value.trim();
+};
+const stringList = (value, field, source, required = false) => {
+    if (value === undefined) {
+        if (required)
+            throw new Error(`${source}: ${field} is required.`);
+        return [];
+    }
+    const values = typeof value === "string" ? value.split(",") : value;
+    if (!Array.isArray(values) || values.some((item) => typeof item !== "string" || !item.trim() || item.includes("\0"))) {
+        throw new Error(`${source}: ${field} must be an array of strings.`);
+    }
+    return values.map((item) => item.trim());
+};
+function validateExtension(extension, source) {
+    const value = cleanText(extension, "extension", source);
+    const packageSource = /^(?:npm|git|github|https?|ssh):/.test(value);
+    const userPath = isAbsolute(value) || value.startsWith("~/") || value.startsWith("~\\") || value.startsWith("file://");
+    if (!packageSource && !userPath) {
+        throw new Error(`${source}: extensions entries must be absolute paths or package sources.`);
+    }
+    return value;
+}
+function extensionList(value, source) {
+    return stringList(value, "extensions", source).map((extension) => validateExtension(extension, source));
+}
+export function loadRoles(agentDir = getAgentDir()) {
+    const dir = join(agentDir, "config", "pi-subagent");
+    let entries;
+    try {
+        entries = readdirSync(dir, { withFileTypes: true });
+    }
+    catch (error) {
+        if (error && typeof error === "object" && "code" in error && error.code === "ENOENT")
+            return [];
+        throw error;
+    }
+    const roles = entries
+        .filter((entry) => entry.name.endsWith(".md") && (entry.isFile() || entry.isSymbolicLink()))
+        .sort((a, b) => a.name.localeCompare(b.name))
+        .map((entry) => {
+        const file = join(dir, entry.name);
+        let parsed;
+        try {
+            parsed = parseFrontmatter(readFileSync(file, "utf8"));
+        }
+        catch (error) {
+            throw new Error(`${file}: ${error instanceof Error ? error.message : String(error)}`);
+        }
+        const frontmatter = parsed.frontmatter;
+        return {
+            name: cleanText(frontmatter.name, "name", file),
+            description: cleanText(frontmatter.description, "description", file),
+            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),
+        };
+    });
+    const names = new Set();
+    for (const role of roles) {
+        if (names.has(role.name))
+            throw new Error(`Duplicate Subagent role: ${role.name}.`);
+        names.add(role.name);
+    }
+    return roles;
+}
+export function resolveTaskRoute(ctx, profileName, agentDir = getAgentDir()) {
+    let config;
+    try {
+        config = readTaskModelsConfig(agentDir);
+    }
+    catch {
+        throw new Error("Couldn't read task model config. Run /task-models.");
+    }
+    return resolveConfiguredRoute(ctx, profileName, config.profiles[profileName]);
+}
+function resolveConfiguredRoute(ctx, profileName, profile) {
+    if (!profile)
+        throw new Error(`No ${profileName} 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 ${profileName} task model route. Run /task-models.`);
+}
+export function resolveRoleSkills(pi, role) {
+    const skills = new Map(pi.getCommands()
+        .filter((command) => command.source === "skill")
+        .map((command) => [command.name, command.sourceInfo.path]));
+    const paths = [];
+    const missing = [];
+    for (const name of role.skills) {
+        const path = skills.get(`skill:${name}`);
+        if (path)
+            paths.push(path);
+        else
+            missing.push(name);
+    }
+    return { paths, missing };
+}
+export function createRoleLaunch(pi, ctx, input) {
+    const role = input.role;
+    const skills = resolveRoleSkills(pi, role);
+    const extensions = [
+        ...role.extensions,
+        ...(input.extensions ?? []),
+        ...(CODEX_ALIAS.test(input.route.model.provider) ? [MULTI_CODEX_EXTENSION] : []),
+    ].map((extension) => validateExtension(extension, `Role ${role.name}`));
+    const tools = role.tools === undefined
+        ? undefined
+        : [...new Set([...role.tools, ...(input.tools ?? [])].map((tool) => cleanText(tool, "tool", `Role ${role.name}`)))];
+    const env = Object.fromEntries(Object.entries(input.env ?? {}).map(([key, value]) => {
+        if (!/^[A-Za-z_][A-Za-z0-9_]*$/.test(key))
+            throw new Error(`Invalid launch environment name: ${key}`);
+        if (typeof value !== "string" || value.includes("\0"))
+            throw new Error(`Invalid launch environment value: ${key}`);
+        return [key, value];
+    }));
+    const args = ["--no-session", "--no-extensions", "--no-skills"];
+    for (const extension of new Set(extensions))
+        args.push("--extension", extension);
+    for (const skill of skills.paths)
+        args.push("--skill", skill);
+    if (tools !== undefined) {
+        if (tools.length)
+            args.push("--tools", tools.join(","));
+        else
+            args.push("--no-tools");
+    }
+    args.push("--model", modelReference(input.route.model));
+    if (input.route.thinkingLevel)
+        args.push("--thinking", input.route.thinkingLevel);
+    args.push(ctx.isProjectTrusted() ? "--approve" : "--no-approve");
+    args.push("--append-system-prompt", cleanText(role.systemPrompt, "system prompt", `Role ${role.name}`));
+    return {
+        env,
+        args,
+        model: input.route.model,
+        thinkingLevel: input.route.thinkingLevel,
+        missingSkills: skills.missing,
+    };
+}
+export function resolveRoleLaunch(pi, ctx, input) {
+    const taskId = cleanText(input.taskId, "task ID", "Role launch");
+    return createRoleLaunch(pi, ctx, {
+        ...input,
+        route: resolveConfiguredTaskRoute(ctx, taskId, input.agentDir),
+    });
+}
+export function launchEnvironmentArgs(launch) {
+    return Object.entries(launch.env).flatMap(([key, value]) => {
+        if (!/^[A-Za-z_][A-Za-z0-9_]*$/.test(key) || typeof value !== "string" || value.includes("\0")) {
+            throw new Error(`Invalid launch environment: ${key}`);
+        }
+        return ["--env", `${key}=${value}`];
+    });
+}
+export function managedSubagentName(workspaceId, ...identity) {
+    const parts = [nonEmptyString(workspaceId, "Herdr workspace id"), ...identity.map((part, index) => nonEmptyString(part, `Subagent identity ${index}`))];
+    if (!identity.length)
+        throw new Error("Managed Subagent identity is required");
+    return `subagent-${createHash("sha256").update(JSON.stringify(parts)).digest("hex").slice(0, 23)}`;
+}
+export async function managedSubagentWorkspaceId(cwd, mainPane, options) {
+    const paneId = nonEmptyString(mainPane, "recorded main Herdr pane");
+    const pane = (await listPanes(cwd, options))
+        .map((entry, index) => object(entry, `Herdr pane ${index}`))
+        .find((entry) => entry.pane_id === paneId);
+    if (!pane)
+        throw new Error(`Recorded main Herdr pane is missing: ${paneId}`);
+    return nonEmptyString(pane.workspace_id, "recorded main Herdr workspace");
+}
+/** Returns pane ID to Herdr status for agents owned by this workspace. */
+export async function listManagedSubagents(host, options) {
+    const workspaceId = nonEmptyString(host.workspaceId, "recorded Herdr workspace");
+    const response = object(await createHerdrClient(options.execute).json(["agent", "list"], { cwd: host.cwd }), "Herdr agent list response");
+    const result = object(response.result, "Herdr agent list result");
+    return new Map(array(result.agents, "Herdr agents").flatMap((entry, index) => {
+        const agent = object(entry, `Herdr agent ${index}`);
+        if (nonEmptyString(agent.workspace_id, `Herdr agent ${index} workspace`) !== workspaceId)
+            return [];
+        return [[
+                nonEmptyString(agent.pane_id, `Herdr agent ${index} pane`),
+                nonEmptyString(agent.agent_status, `Herdr agent ${index} status`),
+            ]];
+    }));
+}
+export async function createManagedSubagentTab(host, cwd, launch, label, options) {
+    const response = await createHerdrClient(options.execute).json([
+        "tab", "create", "--workspace", nonEmptyString(host.workspaceId, "recorded Herdr workspace"), "--cwd", cwd,
+        ...launchEnvironmentArgs(launch), "--label", nonEmptyString(label, "Herdr tab label"), "--no-focus",
+    ], { cwd: host.cwd });
+    const result = object(object(response, "Herdr tab response").result, "Herdr tab result");
+    return {
+        tabId: nonEmptyString(object(result.tab, "Herdr tab").tab_id, "Herdr tab id"),
+        paneId: nonEmptyString(object(result.root_pane, "Herdr root pane").pane_id, "Herdr root pane id"),
+    };
+}
+export async function reconcileManagedSubagentTab(host, input, options) {
+    if (input.tabId && input.paneId && await managedSubagentTabExists(host, input.tabId, options)) {
+        return { tabId: input.tabId, paneId: input.paneId };
+    }
+    return await findManagedSubagentTab(host, input.label, options)
+        ?? await createManagedSubagentTab(host, input.cwd, input.launch, input.label, options);
+}
+export async function findManagedSubagentTab(host, label, options) {
+    const workspaceId = nonEmptyString(host.workspaceId, "recorded Herdr workspace");
+    const matches = (await listTabs(host.cwd, options))
+        .map((entry, index) => object(entry, `Herdr tab ${index}`))
+        .filter((tab, index) => nonEmptyString(tab.workspace_id, `Herdr tab ${index} workspace`) === workspaceId)
+        .filter((tab) => tab.label === label);
+    if (matches.length > 1)
+        throw new Error(`Multiple Herdr tabs match provisioning identity: ${label}`);
+    if (!matches.length)
+        return undefined;
+    const tabId = nonEmptyString(object(matches[0], "Herdr tab").tab_id, "Herdr tab id");
+    const panes = (await listPanes(host.cwd, options))
+        .filter((entry, index) => object(entry, `Herdr pane ${index}`).tab_id === tabId);
+    if (panes.length !== 1)
+        throw new Error(`Provisioned Herdr tab ${tabId} must contain exactly one root pane`);
+    return { tabId, paneId: nonEmptyString(object(panes[0], "Herdr pane").pane_id, "Herdr pane id") };
+}
+export async function managedSubagentTabExists(host, tabId, options) {
+    const expected = nonEmptyString(host.workspaceId, "recorded Herdr workspace");
+    const id = nonEmptyString(tabId, "Herdr tab id");
+    const tab = (await listTabs(host.cwd, options))
+        .map((entry, index) => object(entry, `Herdr tab ${index}`))
+        .find((entry) => entry.tab_id === id);
+    if (!tab)
+        return false;
+    const actual = nonEmptyString(tab.workspace_id, `Herdr tab ${id} workspace`);
+    if (actual !== expected)
+        throw new Error(`Herdr tab ${id} belongs to workspace ${actual}, expected initiating workspace ${expected}`);
+    return true;
+}
+export async function reconcileManagedSubagentPane(host, tabId, rootPaneId, cwd, launch, label, options) {
+    const tab = nonEmptyString(tabId, "Herdr tab id");
+    const workspace = nonEmptyString(host.workspaceId, "recorded Herdr workspace");
+    const ownerTab = (await listTabs(host.cwd, options))
+        .map((entry, index) => object(entry, `Herdr tab ${index}`))
+        .find((entry) => entry.tab_id === tab);
+    if (!ownerTab)
+        throw new Error(`Herdr tab is missing: ${tab}`);
+    const ownerWorkspace = nonEmptyString(ownerTab.workspace_id, `Herdr tab ${tab} workspace`);
+    if (ownerWorkspace !== workspace)
+        throw new Error(`Herdr tab ${tab} belongs to workspace ${ownerWorkspace}, expected initiating workspace ${workspace}`);
+    const root = nonEmptyString(rootPaneId, "Herdr root pane");
+    const panes = (await listPanes(host.cwd, options)).map((entry, index) => object(entry, `Herdr pane ${index}`));
+    const owner = panes.find((pane) => pane.pane_id === root);
+    if (!owner)
+        throw new Error(`Herdr root pane is missing: ${root}`);
+    if (owner.tab_id !== tab)
+        throw new Error(`Herdr root pane ${root} does not belong to tab ${tab}`);
+    const siblings = panes.filter((pane) => pane.tab_id === tab && pane.pane_id !== root);
+    const named = siblings.filter((pane) => pane.label === label);
+    if (named.length > 1)
+        throw new Error(`Multiple Herdr panes match provisioning identity: ${label}`);
+    if (named.length)
+        return nonEmptyString(named[0].pane_id, "Herdr Subagent pane id");
+    if (siblings.length > 1)
+        throw new Error(`Provisioned Herdr tab ${tab} has multiple Subagent panes`);
+    if (siblings.length)
+        return nonEmptyString(siblings[0].pane_id, "Herdr Subagent pane id");
+    const herdr = createHerdrClient(options.execute);
+    const response = await herdr.json([
+        "pane", "split", "--pane", root, "--direction", "right", "--cwd", cwd,
+        ...launchEnvironmentArgs(launch), "--no-focus",
+    ], { cwd: host.cwd });
+    const result = object(object(response, "Herdr pane response").result, "Herdr pane result");
+    const pane = nonEmptyString(object(result.pane, "Herdr Subagent pane").pane_id, "Herdr Subagent pane id");
+    await herdr.run(["pane", "rename", pane, nonEmptyString(label, "Herdr pane label")], { cwd: host.cwd });
+    return pane;
+}
+export async function startManagedSubagent(host, agent, pane, launch, options, hooks = {}) {
+    assertAgentName(agent);
+    const name = nonEmptyString(agent, "Herdr agent name");
+    const paneId = nonEmptyString(pane, "Herdr agent pane");
+    const existing = await getManagedSubagent(host, name, options);
+    if (existing) {
+        assertAgentPane(name, paneId, existing);
+        return "existing";
+    }
+    await hooks.beforeStart?.();
+    const arguments_ = ["agent", "start", name, "--kind", "pi", "--pane", paneId, "--", ...launch.args];
+    const herdr = createHerdrClient(options.execute);
+    for (let attempt = 1; attempt <= 5; attempt += 1) {
+        const result = await herdr.exec(arguments_, { cwd: host.cwd });
+        if (result.code === 0 && !result.killed) {
+            await hooks.onStarted?.();
+            return "started";
+        }
+        if (hasHerdrErrorCode(result, "agent_name_taken")) {
+            const raced = await getManagedSubagent(host, name, options);
+            if (!raced)
+                throw new Error(`Herdr agent ${name} reported agent_name_taken but could not be found; refusing to start a duplicate`);
+            assertAgentPane(name, paneId, raced);
+            return "existing";
+        }
+        if (!hasHerdrErrorCode(result, "agent_pane_busy") || attempt === 5) {
+            throw new Error(herdrCommandFailure(arguments_, result));
+        }
+        await (options.delay ?? delay)(250);
+    }
+    throw new Error(`Herdr agent ${name} could not be started`);
+}
+export async function promptManagedSubagent(host, agent, prompt, options) {
+    assertAgentName(agent);
+    const text = typeof prompt === "string" ? nonEmptyString(prompt, "Subagent prompt") : JSON.stringify(prompt);
+    await createHerdrClient(options.execute).run(["agent", "prompt", agent, text], { cwd: host.cwd });
+}
+export async function retireManagedSubagentTab(host, tabId, options) {
+    const id = nonEmptyString(tabId, "Herdr tab id");
+    try {
+        if (!(await managedSubagentTabExists(host, id, options)))
+            return;
+        await createHerdrClient(options.execute).run(["tab", "close", id], { cwd: host.cwd });
+    }
+    catch (error) {
+        if (!(await confirmsTabAbsent(host, id, options)))
+            throw error;
+    }
+}
+function assertAgentName(agent) {
+    if (!/^[a-z][a-z0-9_-]{0,31}$/.test(agent))
+        throw new Error(`Invalid Herdr agent name: ${agent}`);
+}
+function object(value, label) {
+    if (!value || typeof value !== "object" || Array.isArray(value))
+        throw new Error(`${label} must be an object`);
+    return value;
+}
+function array(value, label) {
+    if (!Array.isArray(value))
+        throw new Error(`${label} must be an array`);
+    return value;
+}
+function nonEmptyString(value, label) {
+    if (typeof value !== "string")
+        throw new Error(`${label} must be a string`);
+    if (!value.trim() || value.includes("\0"))
+        throw new Error(`${label} must not be empty`);
+    return value;
+}
+async function listTabs(cwd, options) {
+    const response = await createHerdrClient(options.execute).json(["tab", "list"], { cwd });
+    return array(object(object(response, "Herdr tab list response").result, "Herdr tab list result").tabs, "Herdr tabs");
+}
+async function listPanes(cwd, options) {
+    const response = await createHerdrClient(options.execute).json(["pane", "list"], { cwd });
+    return array(object(object(response, "Herdr pane list response").result, "Herdr pane list result").panes, "Herdr panes");
+}
+async function getManagedSubagent(host, name, options) {
+    const arguments_ = ["agent", "get", name];
+    const result = await createHerdrClient(options.execute).exec(arguments_, { cwd: host.cwd });
+    if (result.code !== 0 || result.killed) {
+        if (hasHerdrErrorCode(result, "agent_not_found"))
+            return undefined;
+        throw new Error(herdrCommandFailure(arguments_, result));
+    }
+    const response = object(JSON.parse(result.stdout), "Herdr agent get response");
+    return object(object(response.result, "Herdr agent get result").agent, `Herdr agent ${name}`);
+}
+function assertAgentPane(name, expected, agent) {
+    const actual = typeof agent.pane_id === "string" ? agent.pane_id : "missing";
+    if (actual !== expected) {
+        throw new Error(`Herdr agent name collision for ${name}: expected pane ${expected}, found ${actual}; refusing to reuse or replace it`);
+    }
+}
+async function confirmsTabAbsent(host, tabId, options) {
+    try {
+        const result = await createHerdrClient(options.execute).exec(["tab", "get", tabId], { cwd: host.cwd });
+        return !result.killed && result.code !== 0 && hasHerdrErrorCode(result, "tab_not_found");
+    }
+    catch {
+        return false;
+    }
+}
+async function delay(milliseconds) {
+    await new Promise((done) => { setTimeout(done, milliseconds); });
+}

package/extensions/subagent.ts

@@ -1,29 +1,15 @@
 import { spawn } from "node:child_process";
-import { existsSync, readFileSync, readdirSync } from "node:fs";
-import { mkdtemp, rm, writeFile } from "node:fs/promises";
-import { tmpdir } from "node:os";
-import { basename, isAbsolute, join } from "node:path";
-import { fileURLToPath } from "node:url";
+import { existsSync } from "node:fs";
+import { basename } from "node:path";
 import { StringEnum } from "@earendil-works/pi-ai";
-import { type ExtensionAPI, type ExtensionContext, getAgentDir, parseFrontmatter, type Theme } from "@earendil-works/pi-coding-agent";
+import { type ExtensionAPI, type ExtensionContext, type Theme } from "@earendil-works/pi-coding-agent";
 import { type Component, truncateToWidth, type TUI, visibleWidth } from "@earendil-works/pi-tui";
-import {
-	DEFAULT_TASK_ASSIGNMENTS,
-	modelReference,
-	orderedProfileRoutes,
-	PROFILE_NAMES,
-	readTaskModelsConfig,
-	resolveTaskModelRoute,
-	type ProfileName,
-	type ResolvedTaskRoute,
-} from "@henryqw/pi-task-models";
+import { modelReference, PROFILE_NAMES, type ProfileName } from "@henryqw/pi-task-models";
 import { Type } from "typebox";
+import { createRoleLaunch, isProfileName, loadRoles, resolveRoleLaunch, resolveTaskRoute } from "@henryqw/pi-subagent";
 
 const MODEL_CLASSES = PROFILE_NAMES;
 const SUBAGENT_TASK = "pi-subagent/delegateTask";
-const DEFAULT_MODEL_CLASS = DEFAULT_TASK_ASSIGNMENTS[SUBAGENT_TASK];
-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 CONSUMED_JSON_EVENTS = new Set(["message_start", "message_update", "message_end"]);
@@ -35,14 +21,6 @@ const MAX_WIDGET_ROWS = 8;
 const SPINNER_FRAMES = ["⠋", "⠙", "⠹", "⠸", "⠼", "⠴", "⠦", "⠧", "⠇", "⠏"];
 
 type ModelClass = ProfileName;
-type Role = {
-	name: string;
-	description: string;
-	tools?: string[];
-	extensions: string[];
-	skills: string[];
-	systemPrompt: string;
-};
 type ChildResult = {
 	exitCode: number;
 	output: string;
@@ -61,27 +39,7 @@ type WidgetItem = {
 	removeAt?: number;
 };
 
-const isModelClass = (value: unknown): value is ModelClass =>
-	typeof value === "string" && MODEL_CLASSES.includes(value as ModelClass);
-const isNumberedCodexProvider = (provider: string): boolean => CODEX_ALIAS.test(provider);
-
-function resolveTaskRoute(ctx: ExtensionContext, modelClass?: ModelClass): ResolvedTaskRoute {
-	let config;
-	try {
-		config = readTaskModelsConfig();
-	} catch {
-		throw new Error("Couldn't read task model config. Run /task-models.");
-	}
-
-	const profileName = modelClass ?? config.tasks[SUBAGENT_TASK] ?? DEFAULT_MODEL_CLASS;
-	const profile = config.profiles[profileName];
-	if (!profile) throw new Error(`No ${profileName} 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 ${profileName} task model route. Run /task-models.`);
-}
+const isModelClass = isProfileName;
 
 const cleanText = (value: unknown, field: string, file: string): string => {
 	if (typeof value !== "string" || !value.trim() || value.includes("\0")) {
@@ -90,70 +48,6 @@ const cleanText = (value: unknown, field: string, file: string): string => {
 	return value.trim();
 };
 
-const stringList = (value: unknown, field: string, file: string, required = false): string[] => {
-	if (value === undefined) {
-		if (required) throw new Error(`${file}: ${field} is required.`);
-		return [];
-	}
-	const values = typeof value === "string" ? value.split(",") : value;
-	if (!Array.isArray(values) || values.some((item) => typeof item !== "string" || !item.trim() || item.includes("\0"))) {
-		throw new Error(`${file}: ${field} must be an array of strings.`);
-	}
-	return values.map((item) => item.trim());
-};
-
-const extensionList = (value: unknown, file: string): string[] => {
-	const extensions = stringList(value, "extensions", file);
-	for (const extension of extensions) {
-		const packageSource = /^(?:npm|git|github|https?|ssh):/.test(extension);
-		const userPath = isAbsolute(extension) || extension.startsWith("~/") || extension.startsWith("~\\") || extension.startsWith("file://");
-		if (!packageSource && !userPath) {
-			throw new Error(`${file}: extensions entries must be absolute paths or package sources.`);
-		}
-	}
-	return extensions;
-};
-
-export function loadRoles(agentDir = getAgentDir()): Role[] {
-	const dir = join(agentDir, "config", "pi-subagent");
-	let entries;
-	try {
-		entries = readdirSync(dir, { withFileTypes: true });
-	} catch (error: unknown) {
-		if (error && typeof error === "object" && "code" in error && error.code === "ENOENT") return [];
-		throw error;
-	}
-
-	const roles = entries
-		.filter((entry) => entry.name.endsWith(".md") && (entry.isFile() || entry.isSymbolicLink()))
-		.sort((a, b) => a.name.localeCompare(b.name))
-		.map((entry): Role => {
-			const file = join(dir, entry.name);
-			let parsed: ReturnType<typeof parseFrontmatter>;
-			try {
-				parsed = parseFrontmatter(readFileSync(file, "utf8"));
-			} catch (error) {
-				throw new Error(`${file}: ${error instanceof Error ? error.message : String(error)}`);
-			}
-			const frontmatter = parsed.frontmatter;
-			return {
-				name: cleanText(frontmatter.name, "name", file),
-				description: cleanText(frontmatter.description, "description", file),
-				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),
-			};
-		});
-
-	const names = new Set<string>();
-	for (const role of roles) {
-		if (names.has(role.name)) throw new Error(`Duplicate Subagent role: ${role.name}.`);
-		names.add(role.name);
-	}
-	return roles;
-}
-
 function piInvocation(args: string[]): { command: string; args: string[] } {
 	const currentScript = process.argv[1];
 	const isBunVirtualScript = currentScript?.startsWith("/$bunfs/root/");
@@ -471,20 +365,6 @@ const roleSummary = (): string => {
 	}
 };
 
-function resolveSkillPaths(pi: ExtensionAPI, names: string[]): { paths: string[]; missing: string[] } {
-	const skills = new Map(pi.getCommands()
-		.filter((command) => command.source === "skill")
-		.map((command) => [command.name, command.sourceInfo.path]));
-	const paths: string[] = [];
-	const missing: string[] = [];
-	for (const name of names) {
-		const path = skills.get(`skill:${name}`);
-		if (path) paths.push(path);
-		else missing.push(name);
-	}
-	return { paths, missing };
-}
-
 export default function subagentExtension(pi: ExtensionAPI): void {
 	const widgetItems = new Map<string, WidgetItem>();
 	let widgetInstalled = false;
@@ -590,40 +470,22 @@ export default function subagentExtension(pi: ExtensionAPI): void {
 			if (params.modelClass !== undefined && !isModelClass(params.modelClass)) {
 				throw new Error("delegate_task modelClass must be fast, balanced, or frontier.");
 			}
-			const resolvedRoute = resolveTaskRoute(ctx, params.modelClass);
-			const model = resolvedRoute.model;
-			const modelReferenceValue = modelReference(model);
-			const thinkingLevel = resolvedRoute.thinkingLevel;
-
-			const resolvedSkills = resolveSkillPaths(pi, role.skills);
-			if (resolvedSkills.missing.length) {
+			const launch = params.modelClass === undefined
+				? resolveRoleLaunch(pi, ctx, { role, taskId: SUBAGENT_TASK })
+				: createRoleLaunch(pi, ctx, { role, route: resolveTaskRoute(ctx, params.modelClass) });
+			const modelReferenceValue = modelReference(launch.model);
+			const thinkingLevel = launch.thinkingLevel;
+			if (launch.missingSkills.length) {
 				ctx.ui.notify(
-					`Subagent role ${role.name} skipped unavailable Pi skills: ${resolvedSkills.missing.join(", ")}.`,
+					`Subagent role ${role.name} skipped unavailable Pi skills: ${launch.missingSkills.join(", ")}.`,
 					"warning",
 				);
 			}
 
-			const tempDir = await mkdtemp(join(tmpdir(), "pi-subagent-"));
-			const promptPath = join(tempDir, "system.md");
 			let widgetStatus: Exclude<WidgetStatus, "working"> = "failure";
 			try {
-				await writeFile(promptPath, role.systemPrompt, { encoding: "utf8", mode: 0o600 });
-				const args = ["--mode", "json", "-p", "--no-session", "--no-extensions", "--no-skills"];
-				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(","));
-					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 args = ["--mode", "json", "-p", ...launch.args, `Task: ${task}`];
+				startWidgetItem(toolCallId, role.name, launch.model.id, thinkingLevel, task, ctx);
 				const details = { role: role.name, model: modelReferenceValue, thinkingLevel };
 				const result = await runPi(
 					args,
@@ -642,11 +504,7 @@ export default function subagentExtension(pi: ExtensionAPI): void {
 				if (signal?.aborted) widgetStatus = "aborted";
 				throw error;
 			} finally {
-				try {
-					await rm(tempDir, { recursive: true, force: true });
-				} finally {
-					finishWidgetItem(toolCallId, widgetStatus);
-				}
+				finishWidgetItem(toolCallId, widgetStatus);
 			}
 		},
 	});

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@henryqw/pi-subagent",
-  "version": "2.1.0",
+  "version": "2.2.0",
   "description": "Delegate one task to an isolated Pi role with explicit extensions and skills.",
   "keywords": [
     "pi-package",
@@ -14,13 +14,24 @@
   },
   "license": "MIT",
   "files": [
+    "dist",
     "extensions",
     "README.md",
+    "CONTEXT.md",
     "LICENSE"
   ],
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
   "scripts": {
-    "test": "node --test test/*.test.ts",
-    "typecheck": "tsc --noEmit --allowImportingTsExtensions --target ES2022 --module NodeNext --moduleResolution NodeNext --skipLibCheck extensions/subagent.ts test/*.test.ts",
+    "build": "tsc --project tsconfig.build.json",
+    "test": "npm run build && node --test test/*.test.ts",
+    "typecheck": "tsc --noEmit --allowImportingTsExtensions --target ES2022 --module NodeNext --moduleResolution NodeNext --skipLibCheck src/*.ts extensions/*.ts test/*.test.ts",
+    "prepack": "npm run build",
     "pack:check": "npm pack --dry-run"
   },
   "peerDependencies": {
@@ -46,7 +57,8 @@
     ]
   },
   "dependencies": {
+    "@henryqw/pi-herdr": "^0.1.1",
     "@henryqw/pi-multi-codex": "^0.3.8",
-    "@henryqw/pi-task-models": "^0.2.0"
+    "@henryqw/pi-task-models": "^0.3.0"
   }
 }