@henryqw/pi-subagent 26.2.3 → 26.3.1

package/README.md

@@ -6,7 +6,7 @@ Delegate work to configured Pi Roles with [Herdr](https://herdr.dev/). Authorize
 
 ## Install
 
-Requires Pi 1.0.0 or later. Development and automated checks use Pi 1.0.0. Older Pi releases are no longer supported.
+Requires Pi 1.1.0 or later in the 1.x series. Development and automated checks use Pi 1.1.0. Older Pi releases are no longer supported.
 
 ```bash
 pi install npm:@henryqw/pi-task-models
@@ -229,7 +229,7 @@ Main's nested calls pass admission by their own tool names, not by script or anc
 
 To let a Role run `codemode` scripts, list `builtin:codemode` in `extensions` and `codemode` in `tools`; both are required, because the built-in registers the tool inactive and the Role tool policy activates it. `codemode` alone in `tools` fails the launch as an unavailable tool. Pi's `codemode.mode` and `codemode.inlineBudget` settings apply in the child unchanged, so the Role never forces codemode-only operation, and MCP configuration never activates `codemode` in a child. Scripts can call only the Role's active tools plus `codemode`/`deferred` extension and MCP tools; inactive base tools such as `bash` stay unreachable.
 
-The servers named in `mcps` come from the global `~/.pi/agent/mcp.json` only. In a Role that activates `codemode`, each selected server keeps its configured `exposure` and `toolExposure` (Pi's default `codemode` exposure makes tools callable from scripts without declaring them, `direct` declares them, `deferred` tools stay reachable from scripts, `hidden` tools stay unreachable), and an invalid exposure value fails the launch. In every other Role, selected servers are forced to `direct` exposure and `toolExposure` is ignored, because that child cannot reach undeclared tools. Declared tools appear to the model as `mcp__<server>__<tool>` once the server connects. Pi replaces `-` in server and tool names with `_` and appends a hash suffix when two tool names collide or a name exceeds 64 characters. Each selected entry is checked against Pi's documented `mcpServers` rules before launch, in Main and again in the child: a disabled, malformed, or unknown-transport entry, an invalid server name, two selected names that differ only in `-` and `_`, `auth.provider` over plain HTTP outside `localhost`, `127.0.0.1`, or `[::1]`, or a non-HTTPS `oauth.authServerMetadataUrl` outside those hosts fails the launch with the file path and field. The file is never modified; fix the entry or choose another server. Valid `auth`, `oauth`, and `description` fields are passed through so Pi's native provider auth and OAuth apply. `oauth.clientRegistration` must be `dcr` or `cimd`; `cimd` requires Pi 1.0.1 or later; Pi 1.0.0 rejects it before child launch. It cannot use `clientId` or `clientName`, and any `callbackUrl` must use localhost or 127.0.0.1 with path `/callback`. Project MCP overrides remain ignored: a project cannot change the Role's global server allowlist or exposure. Missing Skills, tools, MCP servers, Roles, or routes fail before productive work starts. Main-only delegation and recovery tools plus `ask_question` are excluded from children.
+The servers named in `mcps` come from the global `~/.pi/agent/mcp.json` only. In a Role that activates `codemode`, each selected server keeps its configured `exposure` and `toolExposure` (Pi's default `codemode` exposure makes tools callable from scripts without declaring them, `direct` declares them, `deferred` tools stay reachable from scripts, `hidden` tools stay unreachable), and an invalid exposure value fails the launch. In every other Role, selected servers are forced to `direct` exposure and `toolExposure` is ignored, because that child cannot reach undeclared tools. Declared tools appear to the model as `mcp__<server>__<tool>` once the server connects. Pi replaces `-` in server and tool names with `_` and appends a hash suffix when two tool names collide or a name exceeds 64 characters. Each selected entry is checked against Pi's documented `mcpServers` rules before launch, in Main and again in the child: a disabled, malformed, or unknown-transport entry, an invalid server name, two selected names that differ only in `-` and `_`, `auth.provider` over plain HTTP outside `localhost`, `127.0.0.1`, or `[::1]`, or a non-HTTPS `oauth.authServerMetadataUrl` outside those hosts fails the launch with the file path and field. The file is never modified; fix the entry or choose another server. Valid `auth`, `oauth`, and `description` fields are passed through so Pi's native provider auth and OAuth apply. `oauth.clientRegistration` must be `dcr` or `cimd`. A `cimd` entry cannot use `clientId` or `clientName`, and any `callbackUrl` must use localhost or 127.0.0.1 with path `/callback`. Project MCP overrides remain ignored: a project cannot change the Role's global server allowlist or exposure. Missing Skills, tools, MCP servers, Roles, or routes fail before productive work starts. Main-only delegation and recovery tools plus `ask_question` are excluded from children.
 
 ## API
 
@@ -246,7 +246,9 @@ The servers named in `mcps` come from the global `~/.pi/agent/mcp.json` only. In
 | `RoleLaunchRuntime`, `HerdrHostRuntime`, `CheckedGitRuntime` | classes | Supply launch, host, and Git behavior to the runner. |
 | `ExecutionPolicySnapshot`, `RunState`, `CoordinatorRuntime` | types | Describe persisted policy, state, and runner integration. |
 
-`createEphemeralSubagentExecutor` accepts global concurrency, turn/token, idle, and hard-runtime policy. Queued time consumes no child timeout. A run resolves resources only after receiving its permit and accepts abort, output, token, and activity callbacks. Output and diagnostics are bounded.
+Role route and launch helpers require only model routing fields and `isProjectTrusted()` from the context, plus `cwd` for configured package resources. They do not require UI methods.
+
+`createEphemeralSubagentExecutor` accepts global concurrency, turn/token, idle, and hard-runtime policy. Queued time consumes no child timeout. A run resolves resources only after receiving its permit and accepts abort, output, token, and activity callbacks. Output and diagnostics are bounded. A child that reports `agent_settled.aborted: true` returns a failure result with `stopReason: "aborted"`, even if its process exits with code 0. Collected output, usage, and child error text are kept. `aborted: false` does not prove provider success. A parent abort or timeout still rejects with `EphemeralSubagentError`.
 
 See [Orchestration and package-author API](./docs/orchestration.md) for the detailed contracts and recovery model.
 

package/dist/ephemeral.js

@@ -38,7 +38,7 @@ const PI_JSON_EVENTS = {
     summarization_retry_finished: true,
     bash_execution_update: true,
 };
-const CONSUMED_JSON_EVENTS = new Set(["message_start", "message_update", "message_end"]);
+const CONSUMED_JSON_EVENTS = new Set(["message_start", "message_update", "message_end", "agent_settled"]);
 const JSON_EVENT_TYPE = /^\s*\{\s*"type"\s*:\s*"([^"\\]+)"/;
 const JSON_STRING = `"(?:[^"\\\\\u0000-\u001f]|\\\\(?:["\\\\/bfnrt]|u[0-9a-fA-F]{4}))*"`;
 const JSON_OVERSIZED_TOOL_START = new RegExp(`^\\s*\\{\\s*"type"\\s*:\\s*"tool_execution_start"\\s*,\\s*"toolCallId"\\s*:\\s*(${JSON_STRING})\\s*,\\s*"toolName"\\s*:\\s*(${JSON_STRING})(?=\\s*,)`);
@@ -429,6 +429,7 @@ async function runPi(prepared, input, budget, invocation) {
         let spawnError;
         let protocolError;
         let aborted = false;
+        let settlementAborted = false;
         let limit;
         let tokenBudget = "within";
         let startedTurns = 0;
@@ -528,6 +529,8 @@ async function runPi(prepared, input, budget, invocation) {
             }
             else {
                 const exitCode = code ?? 1;
+                if (settlementAborted)
+                    stopReason = "aborted";
                 const outcome = exitCode !== 0 || stopReason === "error" || stopReason === "aborted" ? "failure" : "success";
                 resolve({
                     outcome,
@@ -627,6 +630,14 @@ async function runPi(prepared, input, budget, invocation) {
             const record = event;
             if (typeof record.type !== "string" || !Object.hasOwn(PI_JSON_EVENTS, record.type))
                 return;
+            if (record.type === "agent_settled") {
+                if (typeof record.aborted !== "boolean") {
+                    protocolError = new Error("Subagent agent_settled.aborted must be a boolean.");
+                    stop(true);
+                    return;
+                }
+                settlementAborted ||= record.aborted;
+            }
             observeEvent();
             if (record.type === "turn_start") {
                 if (++startedTurns > budget.maxTurns) {

package/dist/index.d.ts

@@ -1,5 +1,5 @@
 import { type ExtensionAPI, type ExtensionContext } from "@earendil-works/pi-coding-agent";
-import { type AvailableModel, type ModelTask, type ProfileName, type ResolvedTaskRoute, type ThinkingLevel } from "@henryqw/pi-task-models";
+import { resolveTaskModelRoute, type AvailableModel, type ModelTask, type ProfileName, type ResolvedTaskRoute, type ThinkingLevel } from "@henryqw/pi-task-models";
 export { DISPLAY_TEXT_CONTRACT, hasDisplayControlCharacters } from "./display-text.ts";
 export { loadRoleMcpConfig, parseRoleMcpAllowlist } from "./mcp-role.ts";
 export { addUsage, capEphemeralSubagentOutput, createEphemeralSubagentExecutor, DEFAULT_MAX_TURNS, EphemeralSubagentError, EXECUTION_BUDGET_ENV, formatDuration, type EphemeralSubagentActivityEvent, type EphemeralSubagentErrorCode, type EphemeralSubagentExecutionBudget, type EphemeralSubagentExecutor, type EphemeralSubagentExecutorOptions, type EphemeralSubagentResult, type EphemeralSubagentRunInput, type EphemeralSubagentTimeout, } from "./ephemeral.ts";
@@ -83,7 +83,9 @@ export declare function loadBuiltinRole(name: BuiltinRoleName): Role;
  * user files are an error. Missing user directory returns the built-ins.
  */
 export declare function loadRoles(agentDir?: string): Role[];
-export declare function resolveTaskRoute(ctx: ExtensionContext, profileName: ProfileName, agentDir?: string): ResolvedTaskRoute;
+type TaskRouteContext = Parameters<typeof resolveTaskModelRoute>[0];
+type RoleLaunchContext = TaskRouteContext & Pick<ExtensionContext, "isProjectTrusted">;
+export declare function resolveTaskRoute(ctx: TaskRouteContext, profileName: ProfileName, agentDir?: string): ResolvedTaskRoute;
 export declare function resolveRoleSkills(pi: Pick<ExtensionAPI, "getCommands">, role: Role): ResolvedRoleSkills;
 /** Resolve all enabled package resources selected by one Role's extension sources. */
 export declare function resolveRolePackageResources(role: Role, ctx: Pick<ExtensionContext, "cwd" | "isProjectTrusted">): Promise<{
@@ -93,12 +95,12 @@ export declare function resolveRolePackageResources(role: Role, ctx: Pick<Extens
     themes: string[];
 }>;
 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 declare function resolveRoleLaunch(pi: Pick<ExtensionAPI, "getCommands">, ctx: RoleLaunchContext, input: ResolveRoleLaunchInput): ResolvedRoleLaunch;
 /** Prepare a resolved or resolvable Role launch while keeping its system prompt out of argv. */
-export declare function prepareRoleLaunch(pi: Pick<ExtensionAPI, "getCommands">, ctx: ExtensionContext, input: ResolveRoleLaunchInput): PreparedRoleLaunch;
-export declare function prepareRoleLaunch(pi: Pick<ExtensionAPI, "getCommands">, ctx: ExtensionContext, input: CreateRoleLaunchInput): PreparedRoleLaunch;
+export declare function prepareRoleLaunch(pi: Pick<ExtensionAPI, "getCommands">, ctx: RoleLaunchContext, input: ResolveRoleLaunchInput): PreparedRoleLaunch;
+export declare function prepareRoleLaunch(pi: Pick<ExtensionAPI, "getCommands">, ctx: RoleLaunchContext, input: CreateRoleLaunchInput): PreparedRoleLaunch;
 /** Resolve and prepare a configured Role with its package-owned resources. */
-export declare function resolveConfiguredRoleLaunch(pi: Pick<ExtensionAPI, "getCommands">, ctx: ExtensionContext, input: ResolveConfiguredRoleLaunchInput): Promise<PreparedRoleLaunch>;
+export declare function resolveConfiguredRoleLaunch(pi: Pick<ExtensionAPI, "getCommands">, ctx: RoleLaunchContext & Pick<ExtensionContext, "cwd">, input: ResolveConfiguredRoleLaunchInput): Promise<PreparedRoleLaunch>;
 /** Insert the system prompt pair after a caller has prepared its launch argv. */
 export declare function finalizeRoleLaunch(prepared: PreparedRoleLaunch): ResolvedRoleLaunch;
 export * from "./composition.ts";

package/dist/mcp-role.d.ts

@@ -1,4 +1,4 @@
-import { type LoadedMcpConfig } from "@earendil-works/pi-coding-agent";
+import type { LoadedMcpConfig } from "@earendil-works/pi-coding-agent";
 export declare function parseRoleMcpAllowlist(value: unknown): string[];
 /**
  * Select the Role's allowlisted servers from the global `mcp.json` in Pi's native `mcpServers`
@@ -9,5 +9,4 @@ export declare function parseRoleMcpAllowlist(value: unknown): string[];
  */
 export declare function loadRoleMcpConfig(agentDir: string, allowlist: readonly string[], options?: {
     codemode: boolean;
-    piVersion?: string;
 }): LoadedMcpConfig;

package/dist/mcp-role.js

@@ -1,6 +1,5 @@
 import { readFileSync } from "node:fs";
 import { join } from "node:path";
-import { VERSION } from "@earendil-works/pi-coding-agent";
 export function parseRoleMcpAllowlist(value) {
     if (typeof value !== "string")
         throw new Error("The Role MCP policy flag must contain a JSON array of MCP server names.");
@@ -72,7 +71,7 @@ const EXPOSURE_CHECKS = {
     toolExposure: [(value) => isRecord(value) && Object.values(value).every(isExposure), "an object mapping tool names to exposures"],
 };
 /** Validate one selected server against Pi's documented `mcpServers` rules; the native loader is bypassed by `loadConfig`. */
-function validateRoleMcpServer(path, name, value, codemode, piVersion) {
+function validateRoleMcpServer(path, name, value, codemode) {
     const fail = (message) => { throw new Error(`${path}: MCP server "${name}" ${message}`); };
     if (!SERVER_NAME.test(name))
         fail("has an invalid name (use letters, digits, \"_\" and \"-\").");
@@ -90,8 +89,6 @@ function validateRoleMcpServer(path, name, value, codemode, piVersion) {
             fail(`field "${field}" must be ${shape}.`);
     }
     if (http && isRecord(value.oauth) && value.oauth.clientRegistration === "cimd") {
-        if (piVersion === "1.0.0")
-            fail('field "oauth.clientRegistration" "cimd" requires Pi 1.0.1 or later; current Pi is 1.0.0.');
         if (value.oauth.clientId !== undefined || value.oauth.clientName !== undefined) {
             fail('field "oauth.clientRegistration" "cimd" cannot be combined with "oauth.clientId" or "oauth.clientName".');
         }
@@ -146,7 +143,7 @@ export function loadRoleMcpConfig(agentDir, allowlist, options = { codemode: fal
         if (clash)
             throw new Error(`${path}: Role MCP server "${name}" conflicts with "${clash}": names that differ only in "-" and "_" share one tool namespace.`);
         namespaces.set(mcpNamespace(name), name);
-        return { name, config: validateRoleMcpServer(path, name, configured[name], options.codemode, options.piVersion ?? VERSION), source: path, scope: "global" };
+        return { name, config: validateRoleMcpServer(path, name, configured[name], options.codemode), source: path, scope: "global" };
     });
     return { servers, autoEnableCodemode: false, errors: [] };
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@henryqw/pi-subagent",
-  "version": "26.2.3",
+  "version": "26.3.1",
   "description": "Delegate bounded direct work or durable checked isolated task graphs to Pi roles.",
   "keywords": [
     "pi-package",
@@ -40,9 +40,9 @@
     "pack:check": "npm pack --dry-run"
   },
   "peerDependencies": {
-    "@earendil-works/pi-ai": "^1.0.0",
-    "@earendil-works/pi-coding-agent": "^1.0.0",
-    "@earendil-works/pi-tui": "^1.0.0",
+    "@earendil-works/pi-ai": "^1.1.0",
+    "@earendil-works/pi-coding-agent": "^1.1.0",
+    "@earendil-works/pi-tui": "^1.1.0",
     "typebox": "^1.3.15"
   },
   "repository": {
@@ -74,9 +74,9 @@
     "proper-lockfile": "^4.1.2"
   },
   "devDependencies": {
-    "@earendil-works/pi-ai": "1.0.0",
-    "@earendil-works/pi-coding-agent": "1.0.0",
-    "@earendil-works/pi-tui": "1.0.0",
+    "@earendil-works/pi-ai": "1.1.0",
+    "@earendil-works/pi-coding-agent": "1.1.0",
+    "@earendil-works/pi-tui": "1.1.0",
     "@types/proper-lockfile": "^4.1.4"
   }
 }