pi-session-mcp 0.6.3 → 0.7.0

package/.pi-session-mcp-cli/config.js

@@ -2,19 +2,28 @@ import { createHash } from "node:crypto";
 import { readFile } from "node:fs/promises";
 import { dirname, resolve } from "node:path";
 import { z } from "zod";
+import { MAX_PROFILE_EXTENSIONS, parseExtensionSpec } from "./extension-spec.js";
 import { isMcpServers, snapshotMcpServers } from "./mcp-config.js";
 import { ALIAS_PATTERN, ImmutableMap, } from "./execution-profile.js";
 const alias = z.string().regex(ALIAS_PATTERN);
 const permissionProfile = z.enum(["read-only", "coding"]);
 const thinkingLevel = z.enum(["off", "minimal", "low", "medium", "high", "xhigh", "max"]);
+const extensionSpec = z.string().refine((value) => parseExtensionSpec(value) !== undefined);
 const profileSchema = z.object({
     default: z.boolean(), permissionProfile, provider: z.string().trim().min(1).max(256),
     model: z.string().trim().min(1).max(256), thinkingLevel,
     mcpServers: z.custom((value) => isMcpServers(value)).optional(),
+    extensions: z.array(extensionSpec).max(MAX_PROFILE_EXTENSIONS).optional(),
 }).strict().superRefine((profile, context) => {
     if (profile.mcpServers !== undefined && !isMcpServers(profile.mcpServers, profile.permissionProfile)) {
         context.addIssue({ code: "custom", path: ["mcpServers"], message: "MCP tool grants do not match the permission profile" });
     }
+    if (profile.extensions !== undefined) {
+        const names = profile.extensions.flatMap((spec) => parseExtensionSpec(spec)?.name ?? []);
+        if (new Set(names).size !== names.length) {
+            context.addIssue({ code: "custom", path: ["extensions"], message: "An extension package may appear only once per profile" });
+        }
+    }
 });
 const CONFIG_ERROR_MESSAGES = {
     config_path_required: "Configuration path is required",
@@ -77,9 +86,10 @@ export async function loadConfig(path = process.env.PI_SESSION_MCP_CONFIG) {
     }
     const base = dirname(absoluteConfig);
     const workspaces = new ImmutableMap(Object.entries(parsed.workspaces).map(([key, value]) => [key, resolve(base, value)]));
-    const executionProfiles = new ImmutableMap(Object.entries(parsed.executionProfiles).map(([key, { mcpServers, ...value }]) => [key, Object.freeze({
+    const executionProfiles = new ImmutableMap(Object.entries(parsed.executionProfiles).map(([key, { mcpServers, extensions, ...value }]) => [key, Object.freeze({
             alias: key, ...value,
             ...(mcpServers === undefined ? {} : { mcpServers: snapshotMcpServers(mcpServers) }),
+            ...(extensions === undefined ? {} : { extensions: Object.freeze(extensions.map((spec) => parseExtensionSpec(spec))) }),
         })]));
     const defaultEntry = [...executionProfiles].find(([, profile]) => profile.default);
     if (!defaultEntry)

package/.pi-session-mcp-cli/doctor-cli.js

@@ -1,11 +1,15 @@
+import { fileURLToPath } from "node:url";
 import { parseDoctorArgs, renderDoctorHuman, renderDoctorJson, runDoctor } from "./doctor.js";
+// The generated CLI lives one level below the package root. An npm executable runs
+// from any directory, so the working directory says nothing about the package.
+const PACKAGE_ROOT = fileURLToPath(new URL("..", import.meta.url));
 const options = parseDoctorArgs(process.argv.slice(2));
 if (!options) {
     process.stderr.write("Usage: doctor [--json]\n");
     process.exitCode = 64;
 }
 else {
-    const result = await runDoctor();
+    const result = await runDoctor({ packageRoot: PACKAGE_ROOT });
     process.stdout.write(options.json ? renderDoctorJson(result) : renderDoctorHuman(result));
     process.exitCode = result.exitCode;
 }

package/.pi-session-mcp-cli/doctor.js

@@ -2,9 +2,10 @@ import { access, readFile, readdir, stat } from "node:fs/promises";
 import { constants } from "node:fs";
 import { join } from "node:path";
 import { loadConfig } from "./config.js";
+import { PiExtensionError } from "./extension-spec.js";
 import { readPackageMetadata } from "./package-metadata.js";
 const defaultFileSystem = { readFile, stat, access };
-const CHECK_ORDER = ["node_version_unsupported", "package_metadata_unreadable", "build_missing", "build_stale", "version_mismatch", "config_missing", "config_unreadable", "config_invalid", "workspace_missing", "workspace_not_directory", "workspace_unreadable", "workspace_not_writable"];
+const CHECK_ORDER = ["node_version_unsupported", "package_metadata_unreadable", "build_missing", "build_stale", "version_mismatch", "config_missing", "config_unreadable", "config_invalid", "workspace_missing", "workspace_not_directory", "workspace_unreadable", "workspace_not_writable", "extension_missing", "extension_version_mismatch"];
 function failure(id, subject, remediation) { return Object.freeze({ id, severity: "error", subject, remediation }); }
 function warning(id, subject, remediation) { return Object.freeze({ id, severity: "warning", subject, remediation }); }
 function ok(id, subject) { return Object.freeze({ id, severity: "ok", subject }); }
@@ -174,6 +175,26 @@ export async function runDoctor(dependencies = {}) {
             }
         }
     }
+    if (config) {
+        const resolveExtension = dependencies.resolveExtension
+            ?? (async (extension) => (await import("./pi-extensions.js")).resolvePiExtension(extension));
+        for (const [alias, profile] of [...config.executionProfiles].sort(([a], [b]) => a.localeCompare(b))) {
+            for (const extension of profile.extensions ?? []) {
+                const subject = `${alias}:${extension.name}`;
+                try {
+                    await resolveExtension(extension);
+                    checks.push(ok("extension_missing", subject), ok("extension_version_mismatch", subject));
+                }
+                catch (error) {
+                    const code = error instanceof PiExtensionError ? error.code : "extension_load_failed";
+                    if (code === "extension_not_installed")
+                        checks.push(failure("extension_missing", subject, "install the pinned extension version with Pi"));
+                    else
+                        checks.push(ok("extension_missing", subject), failure("extension_version_mismatch", subject, "install the pinned extension version with Pi"));
+                }
+            }
+        }
+    }
     const rank = new Map(CHECK_ORDER.map((id, index) => [id, index]));
     checks.sort((a, b) => (rank.get(a.id) ?? 999) - (rank.get(b.id) ?? 999) || a.subject.localeCompare(b.subject));
     const hasError = checks.some((check) => check.severity === "error");

package/.pi-session-mcp-cli/execution-profile.js

@@ -8,6 +8,7 @@ export function toResolvedExecutionProfile(profile) {
         model: profile.model,
         thinkingLevel: profile.thinkingLevel,
         ...(profile.mcpServers === undefined ? {} : { mcpServers: snapshotMcpServers(profile.mcpServers) }),
+        ...(profile.extensions === undefined ? {} : { extensions: profile.extensions }),
     });
 }
 /** A small read-only map implementation which has no mutating methods at runtime. */

package/.pi-session-mcp-cli/extension-spec.js

@@ -0,0 +1,21 @@
+export const MAX_PROFILE_EXTENSIONS = 8;
+const MAX_SPEC_LENGTH = 256;
+/** `npm:<name>@<exact semver>`; the name may be scoped. Ranges, tags, git sources and paths never match. */
+const EXTENSION_SPEC_PATTERN = /^npm:((?:@[a-z0-9][a-z0-9._~-]*\/)?[a-z0-9][a-z0-9._~-]*)@(\d+\.\d+\.\d+(?:-[0-9A-Za-z.-]+)?(?:\+[0-9A-Za-z.-]+)?)$/;
+export function parseExtensionSpec(spec) {
+    if (spec.length > MAX_SPEC_LENGTH)
+        return undefined;
+    const match = EXTENSION_SPEC_PATTERN.exec(spec);
+    if (!match)
+        return undefined;
+    return Object.freeze({ spec, name: match[1], version: match[2] });
+}
+/** A classified extension resolution failure. It never carries a path or extension text. */
+export class PiExtensionError extends Error {
+    code;
+    constructor(code) {
+        super("Pi extension resolution failed");
+        this.name = "PiExtensionError";
+        this.code = code;
+    }
+}

package/.pi-session-mcp-cli/pi-extensions.js

@@ -0,0 +1,67 @@
+import { readFile, realpath, stat } from "node:fs/promises";
+import { isAbsolute, join, relative, sep } from "node:path";
+import { getAgentDir } from "@earendil-works/pi-coding-agent";
+import { PiExtensionError } from "./extension-spec.js";
+// The SDK has no side-effect-free lookup: `resolve()` runs `npm install`, and `getInstalledPath`
+// falls back to a synchronous `npm root -g` on a miss and accepts global installs made outside Pi.
+// So this only computes where Pi puts user-scope npm packages; a missing directory means not installed.
+function installedPathFromPi(source, agentDir) {
+    return join(agentDir, "npm", "node_modules", source.slice("npm:".length));
+}
+function inside(root, candidate) {
+    const path = relative(root, candidate);
+    return path !== "" && path !== ".." && !path.startsWith(`..${sep}`) && !isAbsolute(path);
+}
+function isMissing(error) {
+    return typeof error === "object" && error !== null && error.code === "ENOENT";
+}
+/**
+ * Resolves a pinned extension to the real directory of Pi's installed package.
+ * It never installs, never imports extension code and never reports a path.
+ */
+export async function resolvePiExtension(extension, dependencies = {}) {
+    const agentDir = dependencies.agentDir ?? getAgentDir();
+    const read = dependencies.readFile ?? ((path) => readFile(path, "utf8"));
+    const real = dependencies.realpath ?? realpath;
+    const statFile = dependencies.stat ?? stat;
+    let installed;
+    try {
+        installed = (dependencies.installedPath ?? installedPathFromPi)(`npm:${extension.name}`, agentDir);
+    }
+    catch {
+        throw new PiExtensionError("extension_load_failed");
+    }
+    if (installed === undefined)
+        throw new PiExtensionError("extension_not_installed");
+    let root;
+    let manifest;
+    try {
+        root = await real(installed);
+        manifest = JSON.parse((await read(join(root, "package.json"))).replace(/^\uFEFF/, ""));
+    }
+    catch (error) {
+        throw new PiExtensionError(isMissing(error) ? "extension_not_installed" : "extension_load_failed");
+    }
+    if (typeof manifest !== "object" || manifest === null || Array.isArray(manifest))
+        throw new PiExtensionError("extension_load_failed");
+    const { version, pi } = manifest;
+    if (version !== extension.version)
+        throw new PiExtensionError("extension_version_mismatch");
+    const entries = pi?.extensions;
+    if (!Array.isArray(entries) || entries.length === 0
+        || !entries.every((entry) => typeof entry === "string" && entry.length > 0 && !isAbsolute(entry))) {
+        throw new PiExtensionError("extension_load_failed");
+    }
+    for (const entry of entries) {
+        let target;
+        try {
+            target = await real(join(root, entry));
+            if (!inside(root, target) || !(await statFile(target)).isFile())
+                throw new PiExtensionError("extension_load_failed");
+        }
+        catch {
+            throw new PiExtensionError("extension_load_failed");
+        }
+    }
+    return root;
+}

package/CHANGELOG.md

@@ -2,6 +2,60 @@
 
 ## Unreleased
 
+## 0.7.0 — 2026-10-11
+
+This is a minor release because the public contract changes, as ADR 0003
+requires: four new error codes, and the `extensions` field of each execution
+profile in `pi_capabilities_get`.
+
+- Execution profiles can load Pi extensions that Pi has installed, pinned as
+  `npm:<name>@<exact version>` in a new `extensions` field. Such a session
+  loads the extension with its providers, tools, hooks and system-prompt
+  changes, in a model runtime of its own; `read-only` profiles never activate
+  extension tools. New errors: `extension_not_installed`,
+  `extension_version_mismatch`, `extension_load_failed`,
+  `extension_tool_conflict`. Doctor checks configured extensions offline.
+  `pi_capabilities_get` lists each profile's `extensions`. Client prompts no
+  longer dispatch extension commands, and an always-on guard keeps stdout
+  reserved for MCP frames. See ADR 0006 and #34.
+- `setup` now supports macOS, with the same guarantees as on Linux. It runs
+  `--dry-run`, `--apply`, `--verify`, `--rollback` and `--remove`, and keeps
+  the kernel fence and the process-group proof. On macOS:
+  - setup takes the ownership lock with `O_EXLOCK` when it opens the lock
+    file;
+  - it proves process-group cleanup with the trusted system `/bin/ps`;
+  - it accepts the ownership directory only on the APFS volume type of `/`.
+
+  Every other platform still refuses with `platform_unsupported`. Result codes,
+  statuses and exit codes are unchanged. CI now runs on Linux, macOS 15 and
+  macOS 26; the required `verify` check aggregates all three. On a real Mac,
+  setup acceptance passed for Claude Code; it has not run for Codex. See ADR
+  0005 and #32.
+- The client setup reference and the security policy no longer use the
+  project's former name. Both sentences now name the server or Pi Session MCP.
+- The installation guide now describes how to register a client without
+  `setup`: Doctor, the client's own registration commands, checks that are
+  weaker than `--verify` because no bounded direct MCP handshake exists outside
+  `setup`, and how to upgrade and remove. No acceptance level covers the
+  manual path.
+
+## 0.6.4 — 2026-10-10
+
+- `pi-session-mcp-doctor` now checks the package it belongs to, whatever the
+  current directory is. Previously it checked the current directory: in an npm
+  installation, run from another directory, it failed with
+  `package_metadata_unreadable` and `build_missing`, and inside another
+  checkout it reported that checkout. `npm run doctor` in a release checkout
+  and `setup` were not affected.
+- The installation guide and client setup reference now say that Codex
+  rewrites `config.toml` when a registration changes: it groups the
+  `[mcp_servers.*]` tables and drops comments directly above them. Copy the
+  file first if its comments matter.
+- The client setup reference now explains that `codex exec` rejects
+  `pi_session_prompt`, `pi_session_abort` and `pi_session_close` unless they
+  are approved, because it never asks and the tools are marked destructive. It
+  shows the per-run `-c` approvals.
+
 ## 0.6.3 — 2026-10-10
 
 - Doctor no longer reports a false `build_stale` warning right after

package/CONTRIBUTING.md

@@ -8,7 +8,7 @@ working on anything.
 
 ## Development setup
 
-Linux and Node.js 22.19.0 or newer:
+Linux or macOS and Node.js 22.19.0 or newer:
 
 ```bash
 npm ci

package/README.md

@@ -29,10 +29,10 @@ It is not the right tool when:
 
 ## Status
 
-The package version is **0.6.3**.
+The package version is **0.7.0**.
 
 - **Pre-1.0.** The public tool contract is stable within a minor line: a change to tools, fields, states or error codes needs a new minor release.
-- **Linux only**, Node.js 22.19.0 or newer.
+- **Linux and macOS**, Node.js 22.19.0 or newer. macOS is tested in CI on macOS 15 and 26 on Apple silicon; Intel Macs run the same code but are untested. Setup acceptance on a real Mac is recorded for Claude Code only; Codex is still pending. See [Acceptance](docs/acceptance.md#status). On other platforms `setup` refuses with `platform_unsupported`.
 - **Clients:** Codex CLI and Claude Code. The `setup` command does not pin client versions: it accepts a client whose public `mcp` command output matches the expected contract and fails closed otherwise.
 - **Out of scope by design:** HTTP, a web UI, persistence, resume, remote access and multi-user behavior. One trusted local MCP peer talks to one server process.
 - **Not a sandbox.** A `coding` profile restricts the Pi tools that a session may use. It does not isolate the process from the operating system.

package/SECURITY.md

@@ -33,5 +33,5 @@ scope, for example:
   operating-system sandbox, and this is a documented limit, not a defect.
 - Vulnerabilities in Pi, in the MCP clients, in model providers or in other
   dependencies belong to those projects. A dependency advisory that affects Pi
-  Control's own use of the dependency is in scope.
+  Session MCP's own use of the dependency is in scope.
 - The server trusts its one local MCP peer and the operator's configuration.

package/dist/capabilities.d.ts

@@ -21,5 +21,6 @@ export declare function projectCapabilities(workspaces: ReadonlyMap<string, stri
         provider: string;
         model: string;
         thinkingLevel: import("./execution-profile.js").ThinkingLevel;
+        extensions: string[];
     }[];
 };

package/dist/capabilities.js

@@ -14,13 +14,14 @@ export function projectCapabilities(workspaces, executionProfiles, configuration
             .map((alias) => ({ alias })),
         executionProfiles: [...executionProfiles.values()]
             .sort((left, right) => compareAliases(left.alias, right.alias))
-            .map(({ alias, default: isDefault, permissionProfile, provider, model, thinkingLevel }) => ({
+            .map(({ alias, default: isDefault, permissionProfile, provider, model, thinkingLevel, extensions }) => ({
             alias,
             default: isDefault,
             permissionProfile,
             provider,
             model,
             thinkingLevel,
+            extensions: (extensions ?? []).map((extension) => extension.spec),
         })),
     };
 }

package/dist/client-adapters/mcp-verifier.js

@@ -1,3 +1,4 @@
+import { MAX_PROFILE_EXTENSIONS, parseExtensionSpec } from "../extension-spec.js";
 import { PACKAGE_NAME, PACKAGE_VERSION } from "../package-metadata.js";
 export const MCP_VERIFY_TIMEOUT_MS = 5_000;
 export const MCP_MAX_FRAME_BYTES = 65_536;
@@ -98,13 +99,15 @@ function validCapabilities(value) {
         if (!profile || typeof profile !== "object")
             return false;
         const record = profile;
-        return exactKeys(record, ["alias", "default", "permissionProfile", "provider", "model", "thinkingLevel"])
+        return exactKeys(record, ["alias", "default", "permissionProfile", "provider", "model", "thinkingLevel", "extensions"])
             && typeof record.alias === "string" && ALIAS_PATTERN.test(record.alias)
             && typeof record.default === "boolean"
             && (record.permissionProfile === "read-only" || record.permissionProfile === "coding")
             && typeof record.provider === "string" && record.provider.length > 0 && record.provider.length <= 256
             && typeof record.model === "string" && record.model.length > 0 && record.model.length <= 256
-            && typeof record.thinkingLevel === "string" && ["off", "minimal", "low", "medium", "high", "xhigh", "max"].includes(record.thinkingLevel);
+            && typeof record.thinkingLevel === "string" && ["off", "minimal", "low", "medium", "high", "xhigh", "max"].includes(record.thinkingLevel)
+            && Array.isArray(record.extensions) && record.extensions.length <= MAX_PROFILE_EXTENSIONS
+            && record.extensions.every((spec) => typeof spec === "string" && parseExtensionSpec(spec) !== undefined);
     }))
         return false;
     const defaults = profiles.filter((profile) => profile.default === true);

package/dist/config.d.ts

@@ -25,6 +25,7 @@ export declare const configSchema: z.ZodObject<{
             xhigh: "xhigh";
         }>;
         mcpServers: z.ZodOptional<z.ZodCustom<Readonly<Record<string, import("./mcp-config.js").McpServerConfig>>, Readonly<Record<string, import("./mcp-config.js").McpServerConfig>>>>;
+        extensions: z.ZodOptional<z.ZodArray<z.ZodString>>;
     }, z.core.$strict>>;
 }, z.core.$strict>;
 /** The only supported reload behavior: a running controller keeps the snapshot it loaded at startup. */

package/dist/config.js

@@ -2,19 +2,28 @@ import { createHash } from "node:crypto";
 import { readFile } from "node:fs/promises";
 import { dirname, resolve } from "node:path";
 import { z } from "zod";
+import { MAX_PROFILE_EXTENSIONS, parseExtensionSpec } from "./extension-spec.js";
 import { isMcpServers, snapshotMcpServers } from "./mcp-config.js";
 import { ALIAS_PATTERN, ImmutableMap, } from "./execution-profile.js";
 const alias = z.string().regex(ALIAS_PATTERN);
 const permissionProfile = z.enum(["read-only", "coding"]);
 const thinkingLevel = z.enum(["off", "minimal", "low", "medium", "high", "xhigh", "max"]);
+const extensionSpec = z.string().refine((value) => parseExtensionSpec(value) !== undefined);
 const profileSchema = z.object({
     default: z.boolean(), permissionProfile, provider: z.string().trim().min(1).max(256),
     model: z.string().trim().min(1).max(256), thinkingLevel,
     mcpServers: z.custom((value) => isMcpServers(value)).optional(),
+    extensions: z.array(extensionSpec).max(MAX_PROFILE_EXTENSIONS).optional(),
 }).strict().superRefine((profile, context) => {
     if (profile.mcpServers !== undefined && !isMcpServers(profile.mcpServers, profile.permissionProfile)) {
         context.addIssue({ code: "custom", path: ["mcpServers"], message: "MCP tool grants do not match the permission profile" });
     }
+    if (profile.extensions !== undefined) {
+        const names = profile.extensions.flatMap((spec) => parseExtensionSpec(spec)?.name ?? []);
+        if (new Set(names).size !== names.length) {
+            context.addIssue({ code: "custom", path: ["extensions"], message: "An extension package may appear only once per profile" });
+        }
+    }
 });
 const CONFIG_ERROR_MESSAGES = {
     config_path_required: "Configuration path is required",
@@ -77,9 +86,10 @@ export async function loadConfig(path = process.env.PI_SESSION_MCP_CONFIG) {
     }
     const base = dirname(absoluteConfig);
     const workspaces = new ImmutableMap(Object.entries(parsed.workspaces).map(([key, value]) => [key, resolve(base, value)]));
-    const executionProfiles = new ImmutableMap(Object.entries(parsed.executionProfiles).map(([key, { mcpServers, ...value }]) => [key, Object.freeze({
+    const executionProfiles = new ImmutableMap(Object.entries(parsed.executionProfiles).map(([key, { mcpServers, extensions, ...value }]) => [key, Object.freeze({
             alias: key, ...value,
             ...(mcpServers === undefined ? {} : { mcpServers: snapshotMcpServers(mcpServers) }),
+            ...(extensions === undefined ? {} : { extensions: Object.freeze(extensions.map((spec) => parseExtensionSpec(spec))) }),
         })]));
     const defaultEntry = [...executionProfiles].find(([, profile]) => profile.default);
     if (!defaultEntry)

package/dist/doctor-cli.js

@@ -1,11 +1,15 @@
+import { fileURLToPath } from "node:url";
 import { parseDoctorArgs, renderDoctorHuman, renderDoctorJson, runDoctor } from "./doctor.js";
+// The generated CLI lives one level below the package root. An npm executable runs
+// from any directory, so the working directory says nothing about the package.
+const PACKAGE_ROOT = fileURLToPath(new URL("..", import.meta.url));
 const options = parseDoctorArgs(process.argv.slice(2));
 if (!options) {
     process.stderr.write("Usage: doctor [--json]\n");
     process.exitCode = 64;
 }
 else {
-    const result = await runDoctor();
+    const result = await runDoctor({ packageRoot: PACKAGE_ROOT });
     process.stdout.write(options.json ? renderDoctorJson(result) : renderDoctorHuman(result));
     process.exitCode = result.exitCode;
 }

package/dist/doctor.d.ts

@@ -1,7 +1,8 @@
 import { type AppConfig } from "./config.js";
+import { type ExtensionSpec } from "./extension-spec.js";
 export type DoctorSeverity = "ok" | "warning" | "error";
 export type DoctorExitCode = 0 | 1 | 2 | 64;
-export type DoctorCheckId = "node_version_unsupported" | "package_metadata_unreadable" | "build_missing" | "build_stale" | "version_mismatch" | "config_missing" | "config_unreadable" | "config_invalid" | "workspace_missing" | "workspace_not_directory" | "workspace_unreadable" | "workspace_not_writable";
+export type DoctorCheckId = "node_version_unsupported" | "package_metadata_unreadable" | "build_missing" | "build_stale" | "version_mismatch" | "config_missing" | "config_unreadable" | "config_invalid" | "workspace_missing" | "workspace_not_directory" | "workspace_unreadable" | "workspace_not_writable" | "extension_missing" | "extension_version_mismatch";
 export interface DoctorCheck {
     readonly id: DoctorCheckId;
     readonly severity: DoctorSeverity;
@@ -38,6 +39,8 @@ export interface DoctorDependencies {
     readonly fileSystem?: DoctorFileSystem;
     readonly loadConfig?: () => Promise<AppConfig>;
     readonly packageMetadata?: () => Promise<DoctorPackageMetadata>;
+    /** Reads the installed manifest of a pinned extension; never imports extension code. */
+    readonly resolveExtension?: (extension: ExtensionSpec) => Promise<string>;
 }
 export declare function runDoctor(dependencies?: DoctorDependencies): Promise<DoctorResult>;
 export declare function renderDoctorJson(result: DoctorResult): string;

package/dist/doctor.js

@@ -2,9 +2,10 @@ import { access, readFile, readdir, stat } from "node:fs/promises";
 import { constants } from "node:fs";
 import { join } from "node:path";
 import { loadConfig } from "./config.js";
+import { PiExtensionError } from "./extension-spec.js";
 import { readPackageMetadata } from "./package-metadata.js";
 const defaultFileSystem = { readFile, stat, access };
-const CHECK_ORDER = ["node_version_unsupported", "package_metadata_unreadable", "build_missing", "build_stale", "version_mismatch", "config_missing", "config_unreadable", "config_invalid", "workspace_missing", "workspace_not_directory", "workspace_unreadable", "workspace_not_writable"];
+const CHECK_ORDER = ["node_version_unsupported", "package_metadata_unreadable", "build_missing", "build_stale", "version_mismatch", "config_missing", "config_unreadable", "config_invalid", "workspace_missing", "workspace_not_directory", "workspace_unreadable", "workspace_not_writable", "extension_missing", "extension_version_mismatch"];
 function failure(id, subject, remediation) { return Object.freeze({ id, severity: "error", subject, remediation }); }
 function warning(id, subject, remediation) { return Object.freeze({ id, severity: "warning", subject, remediation }); }
 function ok(id, subject) { return Object.freeze({ id, severity: "ok", subject }); }
@@ -174,6 +175,26 @@ export async function runDoctor(dependencies = {}) {
             }
         }
     }
+    if (config) {
+        const resolveExtension = dependencies.resolveExtension
+            ?? (async (extension) => (await import("./pi-extensions.js")).resolvePiExtension(extension));
+        for (const [alias, profile] of [...config.executionProfiles].sort(([a], [b]) => a.localeCompare(b))) {
+            for (const extension of profile.extensions ?? []) {
+                const subject = `${alias}:${extension.name}`;
+                try {
+                    await resolveExtension(extension);
+                    checks.push(ok("extension_missing", subject), ok("extension_version_mismatch", subject));
+                }
+                catch (error) {
+                    const code = error instanceof PiExtensionError ? error.code : "extension_load_failed";
+                    if (code === "extension_not_installed")
+                        checks.push(failure("extension_missing", subject, "install the pinned extension version with Pi"));
+                    else
+                        checks.push(ok("extension_missing", subject), failure("extension_version_mismatch", subject, "install the pinned extension version with Pi"));
+                }
+            }
+        }
+    }
     const rank = new Map(CHECK_ORDER.map((id, index) => [id, index]));
     checks.sort((a, b) => (rank.get(a.id) ?? 999) - (rank.get(b.id) ?? 999) || a.subject.localeCompare(b.subject));
     const hasError = checks.some((check) => check.severity === "error");

package/dist/execution-profile.d.ts

@@ -1,3 +1,4 @@
+import type { ExtensionSpec } from "./extension-spec.js";
 import { type McpServers } from "./mcp-config.js";
 export declare const ALIAS_PATTERN: RegExp;
 export type PermissionProfile = "read-only" | "coding";
@@ -11,6 +12,7 @@ export interface ConfiguredExecutionProfile {
     readonly model: string;
     readonly thinkingLevel: ThinkingLevel;
     readonly mcpServers?: McpServers;
+    readonly extensions?: readonly ExtensionSpec[];
 }
 /** The immutable, server-side selection passed to the Pi adapter. */
 export interface ResolvedExecutionProfile {
@@ -20,6 +22,7 @@ export interface ResolvedExecutionProfile {
     readonly model: string;
     readonly thinkingLevel: ThinkingLevel;
     readonly mcpServers?: McpServers;
+    readonly extensions?: readonly ExtensionSpec[];
 }
 export declare function toResolvedExecutionProfile(profile: ConfiguredExecutionProfile): ResolvedExecutionProfile;
 /** A small read-only map implementation which has no mutating methods at runtime. */

package/dist/execution-profile.js

@@ -8,6 +8,7 @@ export function toResolvedExecutionProfile(profile) {
         model: profile.model,
         thinkingLevel: profile.thinkingLevel,
         ...(profile.mcpServers === undefined ? {} : { mcpServers: snapshotMcpServers(profile.mcpServers) }),
+        ...(profile.extensions === undefined ? {} : { extensions: profile.extensions }),
     });
 }
 /** A small read-only map implementation which has no mutating methods at runtime. */

package/dist/extension-spec.d.ts

@@ -0,0 +1,15 @@
+/** An exactly pinned Pi extension package, as configured on an execution profile. */
+export interface ExtensionSpec {
+    /** The configured text, for example `npm:pi-cursor-sdk@0.5.3`. Path-free and secret-free. */
+    readonly spec: string;
+    readonly name: string;
+    readonly version: string;
+}
+export declare const MAX_PROFILE_EXTENSIONS = 8;
+export declare function parseExtensionSpec(spec: string): ExtensionSpec | undefined;
+export type PiExtensionErrorCode = "extension_not_installed" | "extension_version_mismatch" | "extension_load_failed";
+/** A classified extension resolution failure. It never carries a path or extension text. */
+export declare class PiExtensionError extends Error {
+    readonly code: PiExtensionErrorCode;
+    constructor(code: PiExtensionErrorCode);
+}

package/dist/extension-spec.js

@@ -0,0 +1,21 @@
+export const MAX_PROFILE_EXTENSIONS = 8;
+const MAX_SPEC_LENGTH = 256;
+/** `npm:<name>@<exact semver>`; the name may be scoped. Ranges, tags, git sources and paths never match. */
+const EXTENSION_SPEC_PATTERN = /^npm:((?:@[a-z0-9][a-z0-9._~-]*\/)?[a-z0-9][a-z0-9._~-]*)@(\d+\.\d+\.\d+(?:-[0-9A-Za-z.-]+)?(?:\+[0-9A-Za-z.-]+)?)$/;
+export function parseExtensionSpec(spec) {
+    if (spec.length > MAX_SPEC_LENGTH)
+        return undefined;
+    const match = EXTENSION_SPEC_PATTERN.exec(spec);
+    if (!match)
+        return undefined;
+    return Object.freeze({ spec, name: match[1], version: match[2] });
+}
+/** A classified extension resolution failure. It never carries a path or extension text. */
+export class PiExtensionError extends Error {
+    code;
+    constructor(code) {
+        super("Pi extension resolution failed");
+        this.name = "PiExtensionError";
+        this.code = code;
+    }
+}

package/dist/main.js

@@ -1,5 +1,6 @@
 #!/usr/bin/env node
-import { serveStdio } from "@modelcontextprotocol/server/stdio";
+import { stdoutGuard } from "./stdout-guard-install.js";
+import { serveStdio, StdioServerTransport } from "@modelcontextprotocol/server/stdio";
 import { loadConfig } from "./config.js";
 import { startupFailureDiagnostic } from "./process-diagnostics.js";
 import { createServer } from "./server.js";
@@ -15,7 +16,10 @@ async function main() {
     try {
         const config = await loadConfig();
         registry = new SessionRegistry(new SdkPiSessionAdapter({ diagnosticSink: writeDiagnostic }), config.workspaces);
-        handle = serveStdio(() => createServer(registry, config.workspaces, config.executionProfiles, config.defaultExecutionProfile, config.configuration), { onerror: () => writeDiagnostic({ level: "error", event: "mcp_transport_error", stage: "transport", code: "mcp_transport_error" }) });
+        handle = serveStdio(() => createServer(registry, config.workspaces, config.executionProfiles, config.defaultExecutionProfile, config.configuration), {
+            transport: new StdioServerTransport(process.stdin, stdoutGuard.transportStdout),
+            onerror: () => writeDiagnostic({ level: "error", event: "mcp_transport_error", stage: "transport", code: "mcp_transport_error" }),
+        });
     }
     catch (error) {
         writeDiagnostic(startupFailureDiagnostic(error));

package/dist/pi-adapter.d.ts

@@ -13,7 +13,7 @@ export interface PiAppliedSelection {
     readonly model: string;
     readonly thinkingLevel: ThinkingLevel;
 }
-export type PiSessionCreationErrorCode = "unknown_provider" | "unknown_model" | "local_authentication_missing" | "local_authentication_unavailable" | "model_unavailable" | "thinking_level_unavailable" | "execution_selection_mismatch" | "external_mcp_unavailable" | "external_mcp_no_tools" | "external_mcp_grant_tool_missing" | "external_mcp_activation_mismatch" | "pi_session_creation_failed";
+export type PiSessionCreationErrorCode = "unknown_provider" | "unknown_model" | "local_authentication_missing" | "local_authentication_unavailable" | "model_unavailable" | "thinking_level_unavailable" | "execution_selection_mismatch" | "external_mcp_unavailable" | "external_mcp_no_tools" | "external_mcp_grant_tool_missing" | "external_mcp_activation_mismatch" | "extension_not_installed" | "extension_version_mismatch" | "extension_load_failed" | "extension_tool_conflict" | "pi_session_creation_failed";
 export declare class PiSessionCreationError extends Error {
     readonly code: PiSessionCreationErrorCode;
     constructor(code: PiSessionCreationErrorCode);

package/dist/pi-adapter.js

@@ -10,6 +10,10 @@ const PI_SESSION_CREATION_MESSAGES = {
     external_mcp_no_tools: "Configured external MCP server returned no tools",
     external_mcp_grant_tool_missing: "Configured external MCP grant is missing from discovery",
     external_mcp_activation_mismatch: "Configured external MCP tools could not be activated",
+    extension_not_installed: "Configured Pi extension is not installed",
+    extension_version_mismatch: "Configured Pi extension version is not installed",
+    extension_load_failed: "Configured Pi extension could not be loaded",
+    extension_tool_conflict: "Configured Pi extension tools conflict",
     pi_session_creation_failed: "Pi session creation failed",
 };
 export class PiSessionCreationError extends Error {

package/dist/pi-extensions.d.ts

@@ -0,0 +1,17 @@
+import { type ExtensionSpec } from "./extension-spec.js";
+export interface PiExtensionResolverDependencies {
+    /** Pi's agent directory; defaults to the SDK's `getAgentDir()`. */
+    readonly agentDir?: string;
+    /** Locates Pi's user-scope install of an npm source; the default only computes the path. */
+    readonly installedPath?: (source: string, agentDir: string) => string | undefined;
+    readonly readFile?: (path: string) => Promise<string>;
+    readonly realpath?: (path: string) => Promise<string>;
+    readonly stat?: (path: string) => Promise<{
+        isFile(): boolean;
+    }>;
+}
+/**
+ * Resolves a pinned extension to the real directory of Pi's installed package.
+ * It never installs, never imports extension code and never reports a path.
+ */
+export declare function resolvePiExtension(extension: ExtensionSpec, dependencies?: PiExtensionResolverDependencies): Promise<string>;