@hcflabs/pi-subagent 28.3.4 → 28.4.0

package/README.md

@@ -269,6 +269,8 @@ Role Markdown files in `~/.pi/agent/config/pi-subagent/` require frontmatter and
 | `mcps` | Optional exact global server names from `~/.pi/agent/mcp.json`, using native `mcpServers` format. Omitted or `[]` denies access to `mcp.json` servers. Servers that Role extensions register always connect. |
 | body | Required system instructions |
 
+A Role's `modelClass` selects a Task Profile. When the profile has a primary and a fallback that resolve in Main, the worker selects the Task Profile Model `task/<profile>`. A retryable error on the primary then moves the worker to the fallback. The launch record names the primary route. A designated `model` uses no fallback.
+
 The package ships `implementer`, `reviewer`, and `scout`; same-name user Roles override built-ins. Roles define capabilities, not access or isolation. Unknown frontmatter keys invalidate that file and report its path and key. Other valid Roles load; duplicate names become unavailable. Delegation to an invalid file's claimed Role fails with that file's error. Inspect `/subagent roles`.
 
 The built-in reviewer answers exactly `PASS` when it finds no actionable correctness risk. Otherwise, each finding starts with a priority and a confidence (`high`, `medium`, or `low`), for example `[P1] confidence: high`. Then it gives file and line evidence, the trigger, the impact, and the smallest fix. Each finding blocks approval.

package/dist/index.d.ts

@@ -73,6 +73,11 @@ export interface PreparedRoleLaunch extends ResolvedRoleLaunch {
 export interface CreateRoleLaunchInput {
     role: Role;
     route: ResolvedTaskRoute;
+    /**
+     * Task Profile of the route. When set, the child selects the Task Profile Model `task/<profile>`,
+     * so a retryable error on the primary route moves the child to the fallback route.
+     */
+    failoverProfile?: ProfileName;
     extensions?: readonly string[];
     tools?: readonly string[];
     env?: Readonly<Record<string, string>>;

package/dist/index.js

@@ -6,7 +6,7 @@ import { createConfigStore, extensionConfigDir, field, formatConfigIssues, parse
 import { hasDisplayControlCharacters } from "./display-text.js";
 import { DEFAULT_MAX_TURNS } from "./ephemeral.js";
 import { loadRoleMcpConfig, parseRoleMcpAllowlist } from "./mcp-role.js";
-import { loadTaskModelsConfig, modelReference, orderedProfileRoutes, PROFILE_NAMES, resolveConfiguredTaskRoute, resolveTaskModelRoute, } from "@hcflabs/pi-task-models";
+import { loadTaskModelsConfig, modelReference, orderedProfileRoutes, PROFILE_NAMES, resolveConfiguredTaskRoute, resolveTaskModelRoute, TASK_PROFILE_MODELS_EXTENSION, taskProfileModelReference, } from "@hcflabs/pi-task-models";
 export { DISPLAY_TEXT_CONTRACT, hasDisplayControlCharacters } from "./display-text.js";
 export { loadRoleMcpConfig, parseRoleMcpAllowlist } from "./mcp-role.js";
 export { addUsage, capEphemeralSubagentOutput, createEphemeralSubagentExecutor, DEFAULT_MAX_TURNS, EphemeralSubagentError, EXECUTION_BUDGET_ENV, formatDuration, } from "./ephemeral.js";
@@ -450,6 +450,14 @@ function resolveConfiguredRoute(ctx, profileName, profile) {
     }
     throw new Error(`No usable ${profileName} task model route. Run /task-models.`);
 }
+/** Return the profile when it has a primary and a fallback route that resolve in this session, so failover can help. */
+function failoverProfile(ctx, profileName, agentDir = getAgentDir()) {
+    const profile = loadTaskModelsConfig(agentDir).value.profiles[profileName];
+    if (!profile)
+        return undefined;
+    const usable = orderedProfileRoutes(profile).filter((route) => resolveTaskModelRoute(ctx, route) !== undefined);
+    return usable.length > 1 ? profileName : undefined;
+}
 export function resolveRoleSkills(pi, role) {
     const skills = new Map(pi.getCommands()
         .filter((command) => command.source === "skill")
@@ -512,6 +520,8 @@ function prepareRoleLaunchFromSkills(ctx, input, skills) {
         ROLE_MCP_EXTENSION,
         ...(role.tools.includes("git_read") ? [GIT_READ_EXTENSION] : []),
         ROLE_TOOLS_EXTENSION,
+        // The child runs with --no-extensions, so it loads the Task Profile Models only from this path.
+        ...(input.failoverProfile ? [TASK_PROFILE_MODELS_EXTENSION] : []),
     ];
     const env = Object.fromEntries(Object.entries(input.env ?? {}).map(([key, value]) => {
         if (!/^[A-Za-z_][A-Za-z0-9_]*$/.test(key))
@@ -527,7 +537,7 @@ function prepareRoleLaunchFromSkills(ctx, input, skills) {
     for (const skill of skills.paths)
         args.push("--skill", skill);
     args.push(`--${ROLE_TOOL_POLICY_FLAG}`, JSON.stringify(tools));
-    args.push("--model", modelReference(input.route.model));
+    args.push("--model", input.failoverProfile ? taskProfileModelReference(input.failoverProfile) : modelReference(input.route.model));
     if (input.route.thinkingLevel)
         args.push("--thinking", input.route.thinkingLevel);
     args.push(ctx.isProjectTrusted() ? "--approve" : "--no-approve");
@@ -546,11 +556,16 @@ function prepareRoleLaunchFromSkills(ctx, input, skills) {
 function prepareResolvedRoleLaunch(pi, ctx, input) {
     const { task, modelClass, agentDir, ...launchInput } = input;
     const selectedClass = modelClass ?? input.role.modelClass;
+    const route = selectedClass === undefined
+        ? resolveConfiguredTaskRoute(ctx, task, agentDir)
+        : resolveTaskRoute(ctx, selectedClass, agentDir);
+    // The route resolved, so the config loads. A task without a class uses its assigned or declared profile.
+    const profileName = selectedClass ?? loadTaskModelsConfig(agentDir).value.tasks[task.id] ?? task.defaultProfile;
+    const failover = failoverProfile(ctx, profileName, agentDir);
     return prepareRoleLaunchFromSkills(ctx, {
         ...launchInput,
-        route: selectedClass === undefined
-            ? resolveConfiguredTaskRoute(ctx, task, agentDir)
-            : resolveTaskRoute(ctx, selectedClass, agentDir),
+        route,
+        ...(failover ? { failoverProfile: failover } : {}),
     }, resolveRoleSkills(pi, input.role));
 }
 export function resolveRoleLaunch(pi, ctx, input) {
@@ -589,9 +604,12 @@ export async function resolveConfiguredRoleLaunch(pi, ctx, input) {
         ...namedSkills,
         paths: [...new Set([...namedSkills.paths, ...resources.skills])],
     };
+    const route = resolveTaskRoute(ctx, input.modelClass);
+    const failover = failoverProfile(ctx, input.modelClass);
     const prepared = prepareRoleLaunchFromSkills(ctx, {
         role: effectiveRole,
-        route: resolveTaskRoute(ctx, input.modelClass),
+        route,
+        ...(failover ? { failoverProfile: failover } : {}),
     }, skills);
     assertNoMissingRoleSkills(effectiveRole, prepared);
     const args = [

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hcflabs/pi-subagent",
-  "version": "28.3.4",
+  "version": "28.4.0",
   "description": "Delegate bounded direct work or durable checked isolated task graphs to Pi roles.",
   "keywords": [
     "pi-package",
@@ -74,7 +74,7 @@
     "@hcflabs/pi-herdr": "^0.7.0",
     "@hcflabs/pi-process": "^0.3.0",
     "@hcflabs/pi-repo": "^0.1.0",
-    "@hcflabs/pi-task-models": "^9.0.0",
+    "@hcflabs/pi-task-models": "^9.3.0",
     "proper-lockfile": "^4.1.2"
   },
   "devDependencies": {