pi-session-mcp 0.0.0-stage → 0.6.2

package/dist/client-adapters/types.d.ts

@@ -0,0 +1,54 @@
+/** Safe, client-neutral contract used by the setup lifecycle. */
+export type ClientName = "codex" | "claude-code";
+export type ClientScope = "user" | "project" | "local";
+export type RegistrationState = "absent" | "equivalent" | "divergent" | "unsupported";
+export interface CommandResult {
+    readonly exitCode: number;
+    readonly stdout: string;
+    readonly stderr: string;
+}
+export interface CommandRunner {
+    run(command: string, args: readonly string[], signal?: AbortSignal): Promise<CommandResult>;
+}
+export interface CommandExecution {
+    readonly signal?: AbortSignal;
+    readonly runner?: CommandRunner;
+}
+export interface ClientRegistration {
+    readonly client: ClientName;
+    readonly scope: ClientScope;
+    readonly name: "pi-session-mcp";
+    readonly state: RegistrationState;
+    readonly command: "node" | "unknown";
+    readonly hasExpectedConfig: boolean;
+    readonly supported: boolean;
+}
+export interface ClientCapabilities {
+    readonly client: ClientName;
+    readonly version: string;
+    readonly supportsJson: boolean;
+    readonly supportsAdd: boolean;
+    readonly supportsRemove: boolean;
+    readonly scopes: readonly ClientScope[];
+}
+export interface RegistrationIntent {
+    readonly scope: ClientScope;
+    readonly nodePath: string;
+    readonly entryPath: string;
+    readonly configPath: string;
+}
+export interface RegistrationPlan {
+    readonly client: ClientName;
+    readonly scope: ClientScope;
+    readonly state: RegistrationState;
+    readonly operation: "none" | "add" | "replace";
+    readonly reason: "already_registered" | "missing" | "divergent" | "unsupported";
+}
+export interface ClientAdapter {
+    readonly client: ClientName;
+    discover(): Promise<ClientCapabilities>;
+    inspect(scope: ClientScope, intent: RegistrationIntent): Promise<ClientRegistration>;
+    plan(intent: RegistrationIntent): Promise<RegistrationPlan>;
+    add(intent: RegistrationIntent, execution?: CommandExecution): Promise<void>;
+    remove(scope: ClientScope, execution?: CommandExecution): Promise<void>;
+}

package/dist/client-adapters/types.js

@@ -0,0 +1 @@
+export {};

package/dist/config.d.ts

@@ -0,0 +1,50 @@
+import { z } from "zod";
+import { type ConfiguredExecutionProfile } from "./execution-profile.js";
+export type ConfigErrorCode = "config_path_required" | "invalid_execution_profile_config" | "invalid_thinking_level";
+export declare class ConfigError extends Error {
+    readonly code: ConfigErrorCode;
+    constructor(code: ConfigErrorCode);
+}
+export declare const configSchema: z.ZodObject<{
+    workspaces: z.ZodRecord<z.ZodString, z.ZodString>;
+    executionProfiles: z.ZodRecord<z.ZodString, z.ZodObject<{
+        default: z.ZodBoolean;
+        permissionProfile: z.ZodEnum<{
+            coding: "coding";
+            "read-only": "read-only";
+        }>;
+        provider: z.ZodString;
+        model: z.ZodString;
+        thinkingLevel: z.ZodEnum<{
+            high: "high";
+            low: "low";
+            max: "max";
+            medium: "medium";
+            minimal: "minimal";
+            off: "off";
+            xhigh: "xhigh";
+        }>;
+        mcpServers: z.ZodOptional<z.ZodCustom<Readonly<Record<string, import("./mcp-config.js").McpServerConfig>>, Readonly<Record<string, import("./mcp-config.js").McpServerConfig>>>>;
+    }, z.core.$strict>>;
+}, z.core.$strict>;
+/** The only supported reload behavior: a running controller keeps the snapshot it loaded at startup. */
+export declare const RELOAD_POLICY: "restart-required";
+export type ReloadPolicy = typeof RELOAD_POLICY;
+export declare const CONFIGURATION_FINGERPRINT_PATTERN: RegExp;
+/** Path-free, secret-free metadata captured from the exact configuration bytes read at load time. */
+export interface ConfigurationMetadata {
+    readonly fingerprint: `sha256:${string}`;
+    readonly reloadPolicy: ReloadPolicy;
+}
+export interface AppConfig {
+    readonly workspaces: ReadonlyMap<string, string>;
+    readonly executionProfiles: ReadonlyMap<string, ConfiguredExecutionProfile>;
+    readonly defaultExecutionProfile: string;
+    readonly configuration: ConfigurationMetadata;
+}
+/**
+ * The configuration path comes only from the caller or from `PI_SESSION_MCP_CONFIG`.
+ * There is no default file: a server's working directory is the client's project,
+ * which may be untrusted, so a file found there must never become the policy.
+ */
+export declare function loadConfig(path?: string | undefined): Promise<AppConfig>;

package/dist/config.js

@@ -0,0 +1,88 @@
+import { createHash } from "node:crypto";
+import { readFile } from "node:fs/promises";
+import { dirname, resolve } from "node:path";
+import { z } from "zod";
+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 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(),
+}).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" });
+    }
+});
+const CONFIG_ERROR_MESSAGES = {
+    config_path_required: "Configuration path is required",
+    invalid_execution_profile_config: "Execution profile configuration is invalid",
+    invalid_thinking_level: "Execution profile thinking level is invalid",
+};
+export class ConfigError extends Error {
+    code;
+    constructor(code) {
+        super(CONFIG_ERROR_MESSAGES[code]);
+        this.name = "ConfigError";
+        this.code = code;
+    }
+}
+export const configSchema = z.object({
+    workspaces: z.record(alias, z.string().min(1)),
+    executionProfiles: z.record(alias, profileSchema).superRefine((profiles, context) => {
+        const entries = Object.entries(profiles);
+        if (entries.length === 0)
+            context.addIssue({ code: "custom", message: "At least one execution profile is required" });
+        const defaults = entries.filter(([, profile]) => profile.default);
+        if (defaults.length !== 1)
+            context.addIssue({ code: "custom", message: "Exactly one execution profile must be the default" });
+        if (defaults.length === 1 && defaults[0][1].permissionProfile !== "read-only")
+            context.addIssue({ code: "custom", message: "The default execution profile must be read-only" });
+    }),
+}).strict();
+/** The only supported reload behavior: a running controller keeps the snapshot it loaded at startup. */
+export const RELOAD_POLICY = "restart-required";
+export const CONFIGURATION_FINGERPRINT_PATTERN = /^sha256:[0-9a-f]{64}$/;
+function configurationFingerprint(bytes) {
+    return `sha256:${createHash("sha256").update(bytes).digest("hex")}`;
+}
+/**
+ * The configuration path comes only from the caller or from `PI_SESSION_MCP_CONFIG`.
+ * There is no default file: a server's working directory is the client's project,
+ * which may be untrusted, so a file found there must never become the policy.
+ */
+export async function loadConfig(path = process.env.PI_SESSION_MCP_CONFIG) {
+    if (!path)
+        throw new ConfigError("config_path_required");
+    const absoluteConfig = resolve(path);
+    // One read: the same bytes feed both the fingerprint and the parse.
+    const bytes = await readFile(absoluteConfig);
+    const configuration = Object.freeze({
+        fingerprint: configurationFingerprint(bytes),
+        reloadPolicy: RELOAD_POLICY,
+    });
+    const input = JSON.parse(bytes.toString("utf8"));
+    let parsed;
+    try {
+        parsed = configSchema.parse(input);
+    }
+    catch (error) {
+        if (error instanceof z.ZodError) {
+            const thinkingLevelIssue = error.issues.some((issue) => issue.path.at(-1) === "thinkingLevel");
+            throw new ConfigError(thinkingLevelIssue ? "invalid_thinking_level" : "invalid_execution_profile_config");
+        }
+        throw error;
+    }
+    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({
+            alias: key, ...value,
+            ...(mcpServers === undefined ? {} : { mcpServers: snapshotMcpServers(mcpServers) }),
+        })]));
+    const defaultEntry = [...executionProfiles].find(([, profile]) => profile.default);
+    if (!defaultEntry)
+        throw new Error("Execution profile configuration is invalid");
+    return { workspaces, executionProfiles, defaultExecutionProfile: defaultEntry[0], configuration };
+}

package/dist/doctor-cli.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/doctor-cli.js

@@ -0,0 +1,11 @@
+import { parseDoctorArgs, renderDoctorHuman, renderDoctorJson, runDoctor } from "./doctor.js";
+const options = parseDoctorArgs(process.argv.slice(2));
+if (!options) {
+    process.stderr.write("Usage: doctor [--json]\n");
+    process.exitCode = 64;
+}
+else {
+    const result = await runDoctor();
+    process.stdout.write(options.json ? renderDoctorJson(result) : renderDoctorHuman(result));
+    process.exitCode = result.exitCode;
+}

package/dist/doctor.d.ts

@@ -0,0 +1,47 @@
+import { type AppConfig } from "./config.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 interface DoctorCheck {
+    readonly id: DoctorCheckId;
+    readonly severity: DoctorSeverity;
+    readonly subject: string;
+    readonly remediation?: string;
+}
+export interface DoctorResult {
+    readonly schemaVersion: 1;
+    readonly ok: boolean;
+    readonly packageVersion?: string;
+    readonly checks: readonly DoctorCheck[];
+    readonly exitCode: Exclude<DoctorExitCode, 64>;
+}
+export interface DoctorPackageMetadata {
+    readonly version: string;
+    readonly engines?: {
+        readonly node?: string;
+    };
+    readonly lockVersion?: string;
+    readonly expectedVersion?: string;
+}
+export interface DoctorFileSystem {
+    readonly readFile: (path: string, encoding: "utf8") => Promise<string>;
+    readonly stat: (path: string) => Promise<{
+        readonly isDirectory: () => boolean;
+        readonly isFile: () => boolean;
+        readonly mtimeMs?: number;
+    }>;
+    readonly access: (path: string, mode: number) => Promise<void>;
+}
+export interface DoctorDependencies {
+    readonly packageRoot?: string;
+    readonly nodeVersion?: string;
+    readonly fileSystem?: DoctorFileSystem;
+    readonly loadConfig?: () => Promise<AppConfig>;
+    readonly packageMetadata?: () => Promise<DoctorPackageMetadata>;
+}
+export declare function runDoctor(dependencies?: DoctorDependencies): Promise<DoctorResult>;
+export declare function renderDoctorJson(result: DoctorResult): string;
+export declare function renderDoctorHuman(result: DoctorResult): string;
+export declare function parseDoctorArgs(args: readonly string[]): {
+    json: boolean;
+} | undefined;

package/dist/doctor.js

@@ -0,0 +1,178 @@
+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 { 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"];
+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 }); }
+function isMissing(error) { return typeof error === "object" && error !== null && "code" in error && ["ENOENT", "config_path_required"].includes(String(error.code)); }
+/** The lockfile's modification time, or undefined for an npm installation, which has no lockfile. */
+async function lockfileMtime(fs, root) {
+    try {
+        return (await fs.stat(join(root, "package-lock.json"))).mtimeMs;
+    }
+    catch (error) {
+        if (isMissing(error))
+            return undefined;
+        throw error;
+    }
+}
+function isUnreadable(error) { return typeof error === "object" && error !== null && "code" in error && ["EACCES", "EPERM"].includes(String(error.code)); }
+function isSemver(value) { return /^\d+\.\d+\.\d+(?:-[0-9A-Za-z.-]+)?(?:\+[0-9A-Za-z.-]+)?$/.test(value); }
+function satisfiesNode(version, range) {
+    const minimum = range.match(/>=\s*(\d+)(?:\.(\d+))?(?:\.(\d+))?/);
+    const actual = version.match(/^(\d+)\.(\d+)\.(\d+)/);
+    if (!minimum || !actual)
+        return false;
+    const want = [Number(minimum[1]), Number(minimum[2] ?? 0), Number(minimum[3] ?? 0)];
+    const got = [Number(actual[1]), Number(actual[2]), Number(actual[3])];
+    return got[0] > want[0] || (got[0] === want[0] && (got[1] > want[1] || (got[1] === want[1] && got[2] >= want[2])));
+}
+/** Build inputs beyond the manifests. An installed package has none of them, which is not staleness. */
+async function productionBuildInputMtimes(root) {
+    const mtimes = [];
+    for (const name of ["tsconfig.json", "tsconfig.build.json"]) {
+        try {
+            mtimes.push((await stat(join(root, name))).mtimeMs);
+        }
+        catch (error) {
+            if (!isMissing(error))
+                throw error;
+        }
+    }
+    const visit = async (directory) => {
+        for (const entry of await readdir(directory, { withFileTypes: true })) {
+            const path = join(directory, entry.name);
+            if (entry.isDirectory())
+                await visit(path);
+            else if (entry.isFile() && entry.name.endsWith(".ts"))
+                mtimes.push((await stat(path)).mtimeMs);
+        }
+    };
+    try {
+        await visit(join(root, "src"));
+    }
+    catch (error) {
+        if (!isMissing(error))
+            throw error;
+    }
+    return mtimes;
+}
+export async function runDoctor(dependencies = {}) {
+    const fs = dependencies.fileSystem ?? defaultFileSystem;
+    const root = dependencies.packageRoot ?? process.cwd();
+    const checks = [];
+    let metadata;
+    try {
+        const injected = dependencies.packageMetadata !== undefined;
+        if (dependencies.packageMetadata)
+            metadata = await dependencies.packageMetadata();
+        else {
+            metadata = await readPackageMetadata(root, fs.readFile);
+        }
+        if (!metadata || !isSemver(metadata.version) || typeof metadata.engines?.node !== "string" || !/>=\s*\d+/.test(metadata.engines.node))
+            throw new Error("invalid package metadata");
+        if (!injected && metadata.lockVersion !== undefined && !isSemver(metadata.lockVersion))
+            throw new Error("invalid lock metadata");
+    }
+    catch {
+        checks.push(failure("package_metadata_unreadable", "package metadata", "repair package metadata"));
+    }
+    const nodeRange = metadata?.engines?.node;
+    if (nodeRange && !satisfiesNode(dependencies.nodeVersion ?? process.versions.node, nodeRange))
+        checks.push(failure("node_version_unsupported", "Node.js", "use a supported Node.js version"));
+    else if (nodeRange)
+        checks.push(ok("node_version_unsupported", "Node.js"));
+    let buildMtime;
+    try {
+        const build = await fs.stat(join(root, "dist", "main.js"));
+        if (build.isFile()) {
+            buildMtime = build.mtimeMs;
+            checks.push(ok("build_missing", "build output"));
+        }
+        else
+            checks.push(failure("build_missing", "build output", "run the production build"));
+    }
+    catch (error) {
+        checks.push(failure("build_missing", "build output", isMissing(error) ? "run the production build" : "check build output access"));
+    }
+    if (buildMtime !== undefined) {
+        try {
+            const packageMtime = (await fs.stat(join(root, "package.json"))).mtimeMs;
+            const lockMtime = await lockfileMtime(fs, root);
+            const inputMtimes = [packageMtime, lockMtime].filter((value) => value !== undefined);
+            if (!dependencies.fileSystem)
+                inputMtimes.push(...await productionBuildInputMtimes(root));
+            if (inputMtimes.some((mtime) => mtime > buildMtime))
+                checks.push(warning("build_stale", "build output", "run the production build"));
+            else
+                checks.push(ok("build_stale", "build output"));
+        }
+        catch {
+            checks.push(warning("build_stale", "build output", "rebuild to establish current build state"));
+        }
+    }
+    if (metadata) {
+        const expectedVersion = metadata.expectedVersion ?? metadata.lockVersion;
+        if (expectedVersion && metadata.version !== expectedVersion)
+            checks.push(warning("version_mismatch", "package version", "reinstall matching build artifacts"));
+        else
+            checks.push(ok("version_mismatch", "package version"));
+    }
+    let config;
+    try {
+        config = await (dependencies.loadConfig ?? (() => loadConfig()))();
+        checks.push(ok("config_invalid", "configuration"));
+    }
+    catch (error) {
+        if (isMissing(error))
+            checks.push(failure("config_missing", "configuration", "create PI_SESSION_MCP_CONFIG configuration"));
+        else if (isUnreadable(error))
+            checks.push(failure("config_unreadable", "configuration", "grant configuration read access"));
+        else
+            checks.push(failure("config_invalid", "configuration", "fix configuration using the documented schema"));
+    }
+    if (config) {
+        for (const [alias, path] of [...config.workspaces].sort(([a], [b]) => a.localeCompare(b))) {
+            try {
+                const info = await fs.stat(path);
+                if (!info.isDirectory())
+                    checks.push(failure("workspace_not_directory", alias, "point the workspace alias to a directory"));
+                else {
+                    checks.push(ok("workspace_not_directory", alias));
+                    try {
+                        await fs.access(path, constants.R_OK);
+                        checks.push(ok("workspace_unreadable", alias));
+                    }
+                    catch {
+                        checks.push(failure("workspace_unreadable", alias, "grant workspace read access"));
+                    }
+                    const canWrite = [...config.executionProfiles.values()].some((profile) => profile.permissionProfile === "coding");
+                    if (canWrite) {
+                        try {
+                            await fs.access(path, constants.W_OK);
+                            checks.push(ok("workspace_not_writable", alias));
+                        }
+                        catch {
+                            checks.push(failure("workspace_not_writable", alias, "grant coding workspace write access"));
+                        }
+                    }
+                }
+            }
+            catch (error) {
+                checks.push(failure(isMissing(error) ? "workspace_missing" : "workspace_unreadable", alias, isMissing(error) ? "fix the workspace alias target" : "grant workspace access"));
+            }
+        }
+    }
+    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");
+    const result = { schemaVersion: 1, ok: !hasError, ...(metadata ? { packageVersion: metadata.version } : {}), checks: Object.freeze(checks), exitCode: hasError ? 2 : checks.some((check) => check.severity === "warning") ? 1 : 0 };
+    return Object.freeze(result);
+}
+export function renderDoctorJson(result) { return JSON.stringify(result) + "\n"; }
+export function renderDoctorHuman(result) { return result.checks.map((check) => `${check.severity.toUpperCase()} ${check.id} [${check.subject}]${check.remediation ? `: ${check.remediation}` : ""}`).join("\n") + "\n"; }
+export function parseDoctorArgs(args) { return args.length === 0 ? { json: false } : args.length === 1 && args[0] === "--json" ? { json: true } : undefined; }

package/dist/entry-point.d.ts

@@ -0,0 +1,5 @@
+/**
+ * Whether the module at `importMetaUrl` is the script that Node started. npm
+ * installs `bin` entries as symlinks, so the comparison uses real paths.
+ */
+export declare function isEntryPoint(importMetaUrl: string, argv1: string | undefined): boolean;

package/dist/entry-point.js

@@ -0,0 +1,16 @@
+import { realpathSync } from "node:fs";
+import { fileURLToPath } from "node:url";
+/**
+ * Whether the module at `importMetaUrl` is the script that Node started. npm
+ * installs `bin` entries as symlinks, so the comparison uses real paths.
+ */
+export function isEntryPoint(importMetaUrl, argv1) {
+    if (!argv1)
+        return false;
+    try {
+        return realpathSync(fileURLToPath(importMetaUrl)) === realpathSync(argv1);
+    }
+    catch {
+        return false;
+    }
+}

package/dist/execution-profile.d.ts

@@ -0,0 +1,37 @@
+import { type McpServers } from "./mcp-config.js";
+export declare const ALIAS_PATTERN: RegExp;
+export type PermissionProfile = "read-only" | "coding";
+export type ThinkingLevel = "off" | "minimal" | "low" | "medium" | "high" | "xhigh" | "max";
+/** A profile as it appears in the strictly validated application config. */
+export interface ConfiguredExecutionProfile {
+    readonly alias: string;
+    readonly default: boolean;
+    readonly permissionProfile: PermissionProfile;
+    readonly provider: string;
+    readonly model: string;
+    readonly thinkingLevel: ThinkingLevel;
+    readonly mcpServers?: McpServers;
+}
+/** The immutable, server-side selection passed to the Pi adapter. */
+export interface ResolvedExecutionProfile {
+    readonly alias: string;
+    readonly permissionProfile: PermissionProfile;
+    readonly provider: string;
+    readonly model: string;
+    readonly thinkingLevel: ThinkingLevel;
+    readonly mcpServers?: McpServers;
+}
+export declare function toResolvedExecutionProfile(profile: ConfiguredExecutionProfile): ResolvedExecutionProfile;
+/** A small read-only map implementation which has no mutating methods at runtime. */
+export declare class ImmutableMap<K, V> implements ReadonlyMap<K, V> {
+    private readonly entriesMap;
+    constructor(entries: Iterable<readonly [K, V]>);
+    get size(): number;
+    get(key: K): V | undefined;
+    has(key: K): boolean;
+    entries(): MapIterator<[K, V]>;
+    keys(): MapIterator<K>;
+    values(): MapIterator<V>;
+    forEach(callbackfn: (value: V, key: K, map: ReadonlyMap<K, V>) => void, thisArg?: unknown): void;
+    [Symbol.iterator](): MapIterator<[K, V]>;
+}

package/dist/execution-profile.js

@@ -0,0 +1,29 @@
+import { snapshotMcpServers } from "./mcp-config.js";
+export const ALIAS_PATTERN = /^[a-z][a-z0-9_-]{0,63}$/;
+export function toResolvedExecutionProfile(profile) {
+    return Object.freeze({
+        alias: profile.alias,
+        permissionProfile: profile.permissionProfile,
+        provider: profile.provider,
+        model: profile.model,
+        thinkingLevel: profile.thinkingLevel,
+        ...(profile.mcpServers === undefined ? {} : { mcpServers: snapshotMcpServers(profile.mcpServers) }),
+    });
+}
+/** A small read-only map implementation which has no mutating methods at runtime. */
+export class ImmutableMap {
+    entriesMap;
+    constructor(entries) {
+        this.entriesMap = new Map(entries);
+    }
+    get size() { return this.entriesMap.size; }
+    get(key) { return this.entriesMap.get(key); }
+    has(key) { return this.entriesMap.has(key); }
+    entries() { return this.entriesMap.entries(); }
+    keys() { return this.entriesMap.keys(); }
+    values() { return this.entriesMap.values(); }
+    forEach(callbackfn, thisArg) {
+        this.entriesMap.forEach((value, key) => callbackfn.call(thisArg, value, key, this));
+    }
+    [Symbol.iterator]() { return this.entriesMap.entries(); }
+}

package/dist/main.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/main.js

@@ -0,0 +1,51 @@
+#!/usr/bin/env node
+import { serveStdio } from "@modelcontextprotocol/server/stdio";
+import { loadConfig } from "./config.js";
+import { startupFailureDiagnostic } from "./process-diagnostics.js";
+import { createServer } from "./server.js";
+import { SessionRegistry } from "./session-registry.js";
+import { SdkPiSessionAdapter } from "./sdk-pi-adapter.js";
+import { shutdownAndTerminate } from "./shutdown.js";
+function writeDiagnostic(diagnostic) {
+    process.stderr.write(JSON.stringify(diagnostic) + "\n");
+}
+async function main() {
+    let registry;
+    let handle;
+    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" }) });
+    }
+    catch (error) {
+        writeDiagnostic(startupFailureDiagnostic(error));
+        process.exitCode = 1;
+        return;
+    }
+    let stopping = false;
+    const shutdown = async (exitCode) => {
+        if (stopping)
+            return;
+        stopping = true;
+        await shutdownAndTerminate(() => registry.shutdown(), () => handle.close(), exitCode, {
+            report: (outcome) => {
+                if (outcome !== "completed")
+                    writeDiagnostic({
+                        level: "error", event: "shutdown_failed", stage: "shutdown",
+                        code: outcome === "timed_out" ? "shutdown_timeout" : "shutdown_failed",
+                    });
+            },
+            terminate: (code) => process.exit(code),
+        });
+    };
+    process.once("SIGINT", () => { void shutdown(130); });
+    process.once("SIGTERM", () => { void shutdown(143); });
+    // On stdin EOF the SDK closes only its transport and server instance; sessions and
+    // their MCP children need the same bounded shutdown as a signal. The first trigger wins.
+    const endOfInput = () => { void shutdown(0); };
+    process.stdin.once("end", endOfInput);
+    process.stdin.once("close", endOfInput);
+    if (process.stdin.readableEnded || process.stdin.destroyed)
+        endOfInput();
+}
+await main();

package/dist/mcp-config.d.ts

@@ -0,0 +1,22 @@
+/** Operator-owned configuration. MCP callers can select a profile, never supply this data. */
+export interface McpToolGrant {
+    readonly name: string;
+    /** An explicit operator assertion, never inferred from an MCP annotation. */
+    readonly readOnly: boolean;
+}
+export interface McpServerConfig {
+    readonly command: string;
+    readonly args?: readonly string[];
+    /** Child environment variable -> existing host environment variable (not a secret value). */
+    readonly envFrom?: Readonly<Record<string, string>>;
+    readonly tools: Readonly<Record<string, McpToolGrant>>;
+}
+export type McpServers = Readonly<Record<string, McpServerConfig>>;
+export declare const MAX_MCP_SERVERS = 8;
+export declare const MAX_MCP_TOOLS = 64;
+export declare function mcpToolName(server: string, tool: string): string;
+/** Also used at the adapter boundary: a manually constructed profile must not bypass policy. */
+export declare function isMcpServers(value: unknown, permissionProfile?: "read-only" | "coding"): value is McpServers;
+export declare function snapshotMcpServers(servers: McpServers): McpServers;
+/** Safe discovery metadata; never project commands, arguments, paths, or environment references. */
+export declare function configuredMcpToolNames(servers: McpServers): string[];