@henryqw/pi-subagent 24.0.1 → 25.0.1

package/CONTEXT.md

@@ -62,7 +62,7 @@ Own Role-configured Pi delegation through one `delegate_task` surface:
 ### Resource and launch policy
 
 - Ambient child extensions and Skills stay disabled. Only Role/caller resources plus required internal adapters load.
-- Every Role requires `tools`, `extensions`, and `skills` arrays. Omitted or empty `mcps` denies MCP access. Direct `pi-mcp-adapter` loading is rejected because it bypasses the allowlist.
+- Every Role requires `tools`, `extensions`, and `skills` arrays. `extensions` may name Pi built-in extensions as `builtin:<name>`. `mcps` names servers from the global `~/.pi/agent/mcp.json`; their tools load in the child with direct exposure. Omitted or empty `mcps` denies MCP access. Direct `pi-mcp-adapter` loading is rejected because it bypasses the allowlist.
 - Selected extensions are trusted executable bundles, not a sandbox. All tools and lifecycle behavior they register load together.
 - Role Skill names resolve through Main's effective Pi registry. Missing Roles, Skills, tools, MCP servers, routes, models, or thinking levels fail before the first productive turn.
 - Route precedence is call model class, then Role default, then registered Model Task assignment/default. A direct model replaces only the route model and must support its thinking level.

package/README.md

@@ -13,18 +13,11 @@ pi install npm:@henryqw/pi-subagent
 
 Run `/task-models` and configure the `fast`, `balanced`, `frontier`, and `fav` routes you use.
 
-Install `pi-mcp-adapter` only when a Role declares an MCP server allowlist:
-
-```bash
-pi install npm:pi-mcp-adapter
-```
-
 ## Works with
 
 | Package | Relationship | Purpose |
 | --- | --- | --- |
 | [`@henryqw/pi-task-models`](https://pi.henry.wang/extensions/pi-task-models) | Required | Provides the configured model routes for delegated Roles. |
-| [`pi-mcp-adapter`](https://github.com/nicobailon/pi-mcp-adapter) | Required | Loads the MCP servers named in a Role's `mcps` allowlist, only for Roles that declare one. |
 
 ## Use
 
@@ -181,14 +174,14 @@ Role Markdown lives in `~/.pi/agent/config/pi-subagent/` and requires frontmatte
 | `name`, `description` | Required non-empty text without terminal control characters |
 | `modelClass` | Optional `fast`, `balanced`, `frontier`, or `fav` default |
 | `tools` | Required array of base tool names; `[]` selects none |
-| `extensions` | Required array of trusted absolute paths or supported package sources |
+| `extensions` | Required array of trusted absolute paths, supported package sources, or Pi built-in extensions such as `builtin:codemode` |
 | `skills` | Required array of effective Pi Skill names |
-| `mcps` | Optional exact MCP server names; omitted or `[]` denies MCP access |
+| `mcps` | Optional exact server names from `~/.pi/agent/mcp.json` in Pi's native `mcpServers` format; omitted or `[]` denies MCP access |
 | body | Required system instructions |
 
 Roles describe responsibility and capabilities. They do not choose isolation; each request does. A same-named user Role overrides a built-in Role. The package ships `implementer`, `reviewer`, and `scout`.
 
-Children disable ambient extension and Skill discovery. Only declared resources and required internal policy adapters load. 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.
+Children run with `--no-extensions`, so a Role must list the extension that registers its route model's provider, and only declared resources plus required internal policy adapters load. `builtin:<name>` entries load Pi built-in extensions (`builtin:codemode`, `builtin:tool-search`, `builtin:llama.cpp`) explicitly; `builtin:mcp` is rejected because it would connect every configured server and bypass `mcps`. The servers named in `mcps` come from the global `~/.pi/agent/mcp.json` only; their tools load in the child with direct exposure and are declared 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. 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
 

package/dist/index.d.ts

@@ -1,7 +1,7 @@
 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";
 export { DISPLAY_TEXT_CONTRACT, hasDisplayControlCharacters } from "./display-text.ts";
-export { parseRoleMcpAllowlist, selectRoleMcpConfig, type RoleMcpConfig } from "./mcp-role.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";
 export { createChildWorktree, finalizeChildWorktree, inspectIndexFlags, inspectWorktreeDirty, WorktreeSetupError, type WorktreeDirtyInspection, type WorktreeInfo, type WorktreePayload, } from "./worktree.ts";
 export { prepareExactReviewEvidence, REVIEW_MAX_PATCH_BYTES, REVIEW_MAX_PATHS, type PreparedReviewEvidence, type PrepareExactReviewEvidenceInput, } from "./review-evidence.ts";

package/dist/index.js

@@ -4,10 +4,10 @@ import { fileURLToPath } from "node:url";
 import { DefaultPackageManager, getAgentDir, parseFrontmatter, SettingsManager, } from "@earendil-works/pi-coding-agent";
 import { extensionConfigDir } from "@henryqw/pi-config-store";
 import { hasDisplayControlCharacters } from "./display-text.js";
-import { parseRoleMcpAllowlist, selectRoleMcpConfig } from "./mcp-role.js";
+import { loadRoleMcpConfig, parseRoleMcpAllowlist } from "./mcp-role.js";
 import { loadTaskModelsConfig, modelReference, orderedProfileRoutes, PROFILE_NAMES, resolveConfiguredTaskRoute, resolveTaskModelRoute, } from "@henryqw/pi-task-models";
 export { DISPLAY_TEXT_CONTRACT, hasDisplayControlCharacters } from "./display-text.js";
-export { parseRoleMcpAllowlist, selectRoleMcpConfig } from "./mcp-role.js";
+export { loadRoleMcpConfig, parseRoleMcpAllowlist } from "./mcp-role.js";
 export { addUsage, capEphemeralSubagentOutput, createEphemeralSubagentExecutor, DEFAULT_MAX_TURNS, EphemeralSubagentError, EXECUTION_BUDGET_ENV, formatDuration, } from "./ephemeral.js";
 export { createChildWorktree, finalizeChildWorktree, inspectIndexFlags, inspectWorktreeDirty, WorktreeSetupError, } from "./worktree.js";
 export { prepareExactReviewEvidence, REVIEW_MAX_PATCH_BYTES, REVIEW_MAX_PATHS, } from "./review-evidence.js";
@@ -66,12 +66,25 @@ const stringList = (value, field, source) => {
     }
     return value.map((item) => item.trim());
 };
+// Pi 0.99 built-in extensions (`builtin:<name>`, see Pi's settings docs); Pi exports no list of them.
+// `builtin:mcp` is excluded: it connects every server in mcp.json and would bypass the Role `mcps` allowlist.
+const BUILTIN_EXTENSION_NAMES = ["codemode", "tool-search", "llama.cpp"];
+const BUILTIN_EXTENSION_PREFIX = "builtin:";
 function validateExtension(extension, source) {
     const value = cleanText(extension, "extension", source);
+    if (value.startsWith(BUILTIN_EXTENSION_PREFIX)) {
+        if (value === `${BUILTIN_EXTENSION_PREFIX}mcp`) {
+            throw new Error(`${source} must select MCP servers with mcps instead of loading builtin:mcp directly.`);
+        }
+        if (!BUILTIN_EXTENSION_NAMES.includes(value.slice(BUILTIN_EXTENSION_PREFIX.length))) {
+            throw new Error(`${source}: unknown built-in extension ${value}; use ${BUILTIN_EXTENSION_NAMES.map((name) => `${BUILTIN_EXTENSION_PREFIX}${name}`).join(", ")}.`);
+        }
+        return value;
+    }
     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.`);
+        throw new Error(`${source}: extensions entries must be absolute paths, package sources, or builtin:<name>.`);
     }
     return value;
 }
@@ -231,7 +244,9 @@ export async function resolveRolePackageResources(role, ctx) {
     const resolved = await packageManager(ctx).resolveExtensionSources([...sources]);
     const resourceGroups = [resolved.extensions, resolved.skills, resolved.prompts, resolved.themes]
         .map((resources) => resources.filter((resource) => resource.enabled));
-    const resolvedSources = new Set(resourceGroups.flat().map((resource) => resource.metadata.source));
+    // Built-in extensions resolve to their `builtin:<name>` path with the bare source `builtin`.
+    const resolvedSources = new Set(resourceGroups.flat()
+        .map((resource) => resource.metadata.source === "builtin" ? resource.path : resource.metadata.source));
     const missing = sources.filter((source) => !resolvedSources.has(source));
     if (missing.length)
         throw new Error(`Role extension sources resolved no resources: ${missing.join(", ")}.`);
@@ -317,6 +332,9 @@ export function prepareRoleLaunch(pi, ctx, input) {
         ? prepareRoleLaunchFromSkills(ctx, input, resolveRoleSkills(pi, input.role))
         : prepareResolvedRoleLaunch(pi, ctx, input);
     assertNoMissingRoleSkills(input.role, prepared);
+    // Validate the mcp.json the child reads: its environment inherits Main's, with launch overrides on top.
+    if (input.role.mcps?.length)
+        loadRoleMcpConfig(prepared.env.PI_CODING_AGENT_DIR ?? getAgentDir(), input.role.mcps);
     return { ...prepared, role };
 }
 /** Resolve and prepare a configured Role with its package-owned resources. */
@@ -328,10 +346,8 @@ export async function resolveConfiguredRoleLaunch(pi, ctx, input) {
     if (matches.length !== 1)
         throw new Error(`Required configured Role ${roleName} is missing or ambiguous.`);
     const role = matches[0];
-    if (role.mcps?.length) {
-        const { loadMcpConfig } = await import("pi-mcp-adapter/config");
-        selectRoleMcpConfig(loadMcpConfig(join(getAgentDir(), "mcp.json"), ctx.cwd), role.mcps);
-    }
+    if (role.mcps?.length)
+        loadRoleMcpConfig(getAgentDir(), role.mcps);
     const resources = await resolveRolePackageResources(role, ctx);
     const effectiveRole = { ...role, extensions: resources.extensions };
     const namedSkills = resolveRoleSkills(pi, effectiveRole);

package/dist/mcp-role.d.ts

@@ -1,6 +1,8 @@
-export interface RoleMcpConfig {
-    mcpServers: Record<string, unknown>;
-    settings?: Record<string, unknown>;
-}
+import type { LoadedMcpConfig } from "@earendil-works/pi-coding-agent";
 export declare function parseRoleMcpAllowlist(value: unknown): string[];
-export declare function selectRoleMcpConfig(config: RoleMcpConfig, allowlist: readonly string[]): RoleMcpConfig;
+/**
+ * Select the Role's allowlisted servers from the global `mcp.json` in Pi's native `mcpServers`
+ * shape; the project `.pi/mcp.json` is ignored. A `--no-extensions` child has no codemode tool, so
+ * every selected server is forced to direct exposure and codemode is never activated.
+ */
+export declare function loadRoleMcpConfig(agentDir: string, allowlist: readonly string[]): LoadedMcpConfig;

package/dist/mcp-role.js

@@ -1,3 +1,5 @@
+import { readFileSync } from "node:fs";
+import { join } from "node:path";
 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.");
@@ -17,14 +19,102 @@ export function parseRoleMcpAllowlist(value) {
         throw new Error("The Role MCP policy flag contains duplicate MCP server names.");
     return names;
 }
-export function selectRoleMcpConfig(config, allowlist) {
-    const missing = allowlist.filter((name) => !Object.hasOwn(config.mcpServers, name));
+function isRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+const isString = (value) => typeof value === "string";
+const isStringRecord = (value) => isRecord(value) && Object.values(value).every(isString);
+const parseUrl = (value) => (typeof value === "string" && URL.canParse(value) ? new URL(value) : undefined);
+// Pi's native MCP rules (core/mcp-servers.ts); `validateMcpServerConfig` is not exported, so they are mirrored here.
+const SERVER_NAME = /^[A-Za-z0-9_-]+$/;
+const LOOPBACK_HOSTS = ["localhost", "127.0.0.1", "[::1]"];
+const isHttpsOrLoopback = (url) => url !== undefined && (url.protocol === "https:" || (url.protocol === "http:" && LOOPBACK_HOSTS.includes(url.hostname)));
+/** Tool namespace `mcp__<server>` replaces `-` with `_`, so names differing only there collide. */
+const mcpNamespace = (name) => name.replace(/-/g, "_");
+/** Documented `mcpServers` fields (Pi's docs/mcp.md) and their shapes, by transport; dotted keys are nested. */
+const COMMON_CHECKS = {
+    enabled: [(value) => typeof value === "boolean", "a boolean"],
+    timeout: [(value) => typeof value === "number" && Number.isFinite(value) && value > 0, "a positive number"],
+    description: [isString, "a string"],
+};
+const STDIO_CHECKS = {
+    args: [(value) => Array.isArray(value) && value.every(isString), "an array of strings"],
+    env: [isStringRecord, "an object of strings"],
+    cwd: [isString, "a string"],
+};
+const HTTP_CHECKS = {
+    url: [(value) => /^https?:$/.test(parseUrl(value)?.protocol ?? ""), "an http or https URL"],
+    headers: [isStringRecord, "an object of strings"],
+    oauth: [isRecord, "an object"],
+    "oauth.clientId": [isString, "a string"],
+    "oauth.clientSecret": [isString, "a string"],
+    "oauth.callbackPort": [(value) => Number.isInteger(value) && value >= 1 && value <= 65535, "a port number"],
+    "oauth.callbackUrl": [(value, server) => {
+            const url = parseUrl(value);
+            const port = server.oauth.callbackPort;
+            return url !== undefined && url.protocol === "http:" && LOOPBACK_HOSTS.includes(url.hostname) && url.search === "" && url.hash === ""
+                && (url.port === "" || port === undefined || Number(url.port) === port);
+        }, "an http URL on localhost, 127.0.0.1, or [::1] without query or fragment, on the \"oauth.callbackPort\" port"],
+    "oauth.scope": [isString, "a string"],
+    "oauth.clientName": [(value) => typeof value === "string" && value.trim() !== "", "a non-empty string"],
+    "oauth.authServerMetadataUrl": [(value) => isHttpsOrLoopback(parseUrl(value)), "an https URL, or http on localhost, 127.0.0.1, or [::1]"],
+    auth: [(value) => isRecord(value) && typeof value.provider === "string" && value.provider !== "", "an object with a non-empty \"provider\" string"],
+};
+/** Validate one selected server against Pi's documented `mcpServers` rules; the native loader is bypassed by `loadConfig`. */
+function validateRoleMcpServer(path, name, value) {
+    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 \"-\").");
+    if (!isRecord(value))
+        fail("must be an object.");
+    if (value.enabled === false)
+        throw new Error(`${path}: Role MCP server "${name}" is disabled.`);
+    const stdio = typeof value.command === "string" && value.command.trim() !== "" && (value.type === undefined || value.type === "stdio");
+    const http = typeof value.url === "string" && value.url.trim() !== "" && (value.type === undefined || value.type === "http" || value.type === "streamable-http");
+    if (stdio === http)
+        fail("needs either a \"command\" (stdio) or a \"url\" (http or streamable-http).");
+    for (const [field, [valid, shape]] of Object.entries({ ...COMMON_CHECKS, ...(stdio ? STDIO_CHECKS : HTTP_CHECKS) })) {
+        const fieldValue = field.split(".").reduce((parent, key) => (isRecord(parent) ? parent[key] : undefined), value);
+        if (fieldValue !== undefined && !valid(fieldValue, value))
+            fail(`field "${field}" must be ${shape}.`);
+    }
+    // The native transport sends the provider's token to `url`, so Pi only allows it over https or loopback.
+    if (value.auth !== undefined && !isHttpsOrLoopback(parseUrl(value.url))) {
+        fail("field \"auth\" requires \"url\" to use https, or http on localhost, 127.0.0.1, or [::1].");
+    }
+    const { toolExposure: _toolExposure, ...config } = value;
+    return { ...config, exposure: "direct" };
+}
+/**
+ * Select the Role's allowlisted servers from the global `mcp.json` in Pi's native `mcpServers`
+ * shape; the project `.pi/mcp.json` is ignored. A `--no-extensions` child has no codemode tool, so
+ * every selected server is forced to direct exposure and codemode is never activated.
+ */
+export function loadRoleMcpConfig(agentDir, allowlist) {
+    const path = join(agentDir, "mcp.json");
+    let parsed = {};
+    try {
+        parsed = JSON.parse(readFileSync(path, "utf8"));
+    }
+    catch (error) {
+        if (!(error instanceof Error && "code" in error && error.code === "ENOENT")) {
+            throw new Error(`${path}: ${error instanceof Error ? error.message : String(error)}`, { cause: error });
+        }
+    }
+    if (!isRecord(parsed) || (parsed.mcpServers !== undefined && !isRecord(parsed.mcpServers))) {
+        throw new Error(`${path}: expected an object with an "mcpServers" object.`);
+    }
+    const configured = parsed.mcpServers ?? {};
+    const missing = allowlist.filter((name) => !Object.hasOwn(configured, name));
     if (missing.length)
         throw new Error(`Role MCP servers are not configured: ${missing.join(", ")}.`);
-    const mcpServers = Object.fromEntries(allowlist.map((name) => [name, config.mcpServers[name]]));
-    const { agentPluginPaths: _agentPluginPaths, hostConfigDiscovery: _hostConfigDiscovery, ...settings } = config.settings ?? {};
-    return {
-        mcpServers,
-        ...(Object.keys(settings).length ? { settings } : {}),
-    };
+    const namespaces = new Map();
+    const servers = allowlist.map((name) => {
+        const clash = namespaces.get(mcpNamespace(name));
+        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]), source: path, scope: "global" };
+    });
+    return { servers, autoEnableCodemode: false, errors: [] };
 }

package/docs/orchestration.md

@@ -139,7 +139,7 @@ Every child launch:
 5. excludes Main-only delegation/recovery tools and `ask_question`; and
 6. prepends the delegated-subagent identity contract.
 
-An empty `tools` list adds no base tools, though selected extension tools can still activate. Omitted or empty `mcps` denies MCP access. Loading `pi-mcp-adapter` directly is rejected because it bypasses the allowlist.
+An empty `tools` list adds no base tools, though selected extension tools can still activate. Children run with `--no-extensions`, so a Role must list the extension that registers its route model's provider; `builtin:<name>` entries load Pi built-in extensions. `mcps` names servers from the global `~/.pi/agent/mcp.json` in Pi's native format, and their tools load in the child with direct exposure. Omitted or empty `mcps` denies MCP access. Loading `pi-mcp-adapter` directly is rejected because it bypasses the allowlist.
 
 Isolated Herdr Role launches receive the same turn, token, and child-runtime budget metadata as ephemeral launches. Retained workers therefore keep one non-refilling session budget across follow-ups rather than receiving a new request budget.
 

package/extensions/role-mcp.ts

@@ -1,16 +1,12 @@
-import { join } from "node:path";
-import { getAgentDir, type ExtensionAPI } from "@earendil-works/pi-coding-agent";
-import { createMcpAdapter } from "pi-mcp-adapter";
-import { loadMcpConfig } from "pi-mcp-adapter/config";
-import { roleMcpAllowlistFromArgv, ROLE_MCP_POLICY_FLAG, selectRoleMcpConfig } from "@henryqw/pi-subagent";
+import { createMcpExtension, getAgentDir, type ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import { loadRoleMcpConfig, roleMcpAllowlistFromArgv, ROLE_MCP_POLICY_FLAG } from "@henryqw/pi-subagent";
 
-export default function roleMcp(pi: ExtensionAPI): void {
+export default function roleMcp(pi: ExtensionAPI): void | Promise<void> {
 	pi.registerFlag(ROLE_MCP_POLICY_FLAG, {
 		description: "Internal Pi Subagent Role MCP policy",
 		type: "string",
 	});
-	// Pi binds extension flag values after factories load.
-	const allowlist = roleMcpAllowlistFromArgv(process.argv);
-	const config = selectRoleMcpConfig(loadMcpConfig(join(getAgentDir(), "mcp.json"), process.cwd()), allowlist);
-	createMcpAdapter({ config })(pi);
+	// Pi binds extension flag values after factories load. Throwing here exits the child non-zero.
+	const config = loadRoleMcpConfig(getAgentDir(), roleMcpAllowlistFromArgv(process.argv));
+	return createMcpExtension({ loadConfig: () => config })(pi);
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@henryqw/pi-subagent",
-  "version": "24.0.1",
+  "version": "25.0.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": ">=0.86.0 <0.88.0",
-    "@earendil-works/pi-coding-agent": ">=0.86.0 <0.88.0",
-    "@earendil-works/pi-tui": ">=0.86.0 <0.88.0",
+    "@earendil-works/pi-ai": ">=0.99.1 <0.100.0 || ^1.0.0",
+    "@earendil-works/pi-coding-agent": ">=0.99.1 <0.100.0 || ^1.0.0",
+    "@earendil-works/pi-tui": ">=0.99.1 <0.100.0 || ^1.0.0",
     "typebox": "^1.3.15"
   },
   "repository": {
@@ -74,9 +74,9 @@
     "proper-lockfile": "^4.1.2"
   },
   "devDependencies": {
-    "@earendil-works/pi-ai": "0.87.0",
-    "@earendil-works/pi-coding-agent": "0.87.0",
-    "@earendil-works/pi-tui": "0.87.0",
+    "@earendil-works/pi-ai": "1.0.0",
+    "@earendil-works/pi-coding-agent": "1.0.0",
+    "@earendil-works/pi-tui": "1.0.0",
     "@types/proper-lockfile": "^4.1.4"
   }
 }