@henryqw/pi-subagent 25.0.0 → 25.0.1

package/README.md

@@ -181,7 +181,7 @@ Role Markdown lives in `~/.pi/agent/config/pi-subagent/` and requires frontmatte
 
 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 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. 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/mcp-role.js

@@ -22,17 +22,69 @@ export function parseRoleMcpAllowlist(value) {
 function isRecord(value) {
     return typeof value === "object" && value !== null && !Array.isArray(value);
 }
-const isStringRecord = (value) => isRecord(value) && Object.values(value).every((item) => typeof item === "string");
-/** Documented optional fields of an `mcpServers` entry and their shapes (see Pi's docs/mcp.md). */
-const FIELD_CHECKS = {
-    args: [(value) => Array.isArray(value) && value.every((item) => typeof item === "string"), "an array of strings"],
+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"],
-    cwd: [(value) => typeof value === "string", "a string"],
-    timeout: [(value) => typeof value === "number" && Number.isFinite(value) && value > 0, "a positive number"],
-    enabled: [(value) => typeof value === "boolean", "a boolean"],
     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
@@ -56,23 +108,13 @@ export function loadRoleMcpConfig(agentDir, allowlist) {
     const missing = allowlist.filter((name) => !Object.hasOwn(configured, name));
     if (missing.length)
         throw new Error(`Role MCP servers are not configured: ${missing.join(", ")}.`);
+    const namespaces = new Map();
     const servers = allowlist.map((name) => {
-        const value = configured[name];
-        if (!isRecord(value))
-            throw new Error(`${path}: MCP server "${name}" 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) {
-            throw new Error(`${path}: MCP server "${name}" needs either a "command" (stdio) or a "url" (http or streamable-http).`);
-        }
-        for (const [field, [valid, shape]] of Object.entries(FIELD_CHECKS)) {
-            if (value[field] !== undefined && !valid(value[field]))
-                throw new Error(`${path}: MCP server "${name}" field "${field}" must be ${shape}.`);
-        }
-        const { toolExposure: _toolExposure, ...config } = value;
-        return { name, config: { ...config, exposure: "direct" }, source: path, scope: "global" };
+        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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@henryqw/pi-subagent",
-  "version": "25.0.0",
+  "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.99.1 <0.100.0",
-    "@earendil-works/pi-coding-agent": ">=0.99.1 <0.100.0",
-    "@earendil-works/pi-tui": ">=0.99.1 <0.100.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.99.1",
-    "@earendil-works/pi-coding-agent": "0.99.1",
-    "@earendil-works/pi-tui": "0.99.1",
+    "@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"
   }
 }