pi-session-mcp 0.0.0-stage → 0.6.2

package/dist/mcp-config.js

@@ -0,0 +1,70 @@
+import { isAbsolute } from "node:path";
+const aliasPattern = /^[a-z][a-z0-9_-]{0,23}$/;
+const environmentPattern = /^[A-Z_][A-Z0-9_]{0,127}$/;
+export const MAX_MCP_SERVERS = 8;
+export const MAX_MCP_TOOLS = 64;
+export function mcpToolName(server, tool) {
+    return `mcp_${server}_${tool}`;
+}
+function record(value) {
+    return value !== null && typeof value === "object" && !Array.isArray(value)
+        && (Object.getPrototypeOf(value) === Object.prototype || Object.getPrototypeOf(value) === null);
+}
+function keysAre(value, allowed) {
+    return Object.keys(value).every((key) => allowed.includes(key));
+}
+function text(value, maximum) {
+    return typeof value === "string" && value.length > 0 && value.length <= maximum && !value.includes("\0");
+}
+/** Also used at the adapter boundary: a manually constructed profile must not bypass policy. */
+export function isMcpServers(value, permissionProfile = "coding") {
+    if (permissionProfile !== "read-only" && permissionProfile !== "coding")
+        return false;
+    if (!record(value) || Object.keys(value).length > MAX_MCP_SERVERS)
+        return false;
+    const toolNames = new Set();
+    for (const [serverAlias, server] of Object.entries(value)) {
+        if (!aliasPattern.test(serverAlias) || !record(server) || !keysAre(server, ["command", "args", "envFrom", "tools"]))
+            return false;
+        if (!text(server.command, 4096) || !isAbsolute(server.command))
+            return false;
+        if (server.args !== undefined && (!Array.isArray(server.args) || server.args.length > 128
+            || !server.args.every((arg) => typeof arg === "string" && arg.length <= 4096 && !arg.includes("\0"))))
+            return false;
+        if (server.envFrom !== undefined && (!record(server.envFrom) || Object.keys(server.envFrom).length > 64
+            || !Object.entries(server.envFrom).every(([target, source]) => environmentPattern.test(target)
+                && typeof source === "string" && environmentPattern.test(source))))
+            return false;
+        if (!record(server.tools) || Object.keys(server.tools).length === 0)
+            return false;
+        const remoteNames = new Set();
+        for (const [toolAlias, grant] of Object.entries(server.tools)) {
+            if (!aliasPattern.test(toolAlias) || !record(grant) || !keysAre(grant, ["name", "readOnly"])
+                || !text(grant.name, 256) || typeof grant.readOnly !== "boolean")
+                return false;
+            if (permissionProfile === "read-only" && !grant.readOnly)
+                return false;
+            const exposedName = mcpToolName(serverAlias, toolAlias);
+            // Underscore-containing aliases can otherwise create cross-server name collisions.
+            if (toolNames.has(exposedName) || remoteNames.has(grant.name))
+                return false;
+            toolNames.add(exposedName);
+            remoteNames.add(grant.name);
+            if (toolNames.size > MAX_MCP_TOOLS)
+                return false;
+        }
+    }
+    return true;
+}
+export function snapshotMcpServers(servers) {
+    return Object.freeze(Object.fromEntries(Object.entries(servers).map(([alias, server]) => [alias, Object.freeze({
+            command: server.command,
+            args: Object.freeze([...(server.args ?? [])]),
+            envFrom: Object.freeze({ ...server.envFrom }),
+            tools: Object.freeze(Object.fromEntries(Object.entries(server.tools).map(([name, grant]) => [name, Object.freeze({ ...grant })]))),
+        })])));
+}
+/** Safe discovery metadata; never project commands, arguments, paths, or environment references. */
+export function configuredMcpToolNames(servers) {
+    return Object.entries(servers).flatMap(([server, config]) => Object.keys(config.tools).map((tool) => mcpToolName(server, tool))).sort();
+}

package/dist/mcp-session-tools.d.ts

@@ -0,0 +1,54 @@
+import type { ToolDefinition } from "@earendil-works/pi-coding-agent";
+import { type McpServerConfig, type McpServers } from "./mcp-config.js";
+export declare const MCP_STARTUP_TIMEOUT_MS = 10000;
+export declare const MCP_CALL_TIMEOUT_MS = 30000;
+export declare const MCP_CLOSE_TIMEOUT_MS = 4500;
+export interface McpRemoteTool {
+    readonly name: string;
+    readonly description?: string | undefined;
+    readonly inputSchema: {
+        readonly type: "object";
+        readonly [key: string]: unknown;
+    };
+}
+export interface McpToolPage {
+    readonly tools: readonly McpRemoteTool[];
+    readonly nextCursor?: string | undefined;
+}
+export interface McpCallResult {
+    readonly content: readonly {
+        readonly type: string;
+        readonly [key: string]: unknown;
+    }[];
+    readonly structuredContent?: unknown;
+    readonly isError?: boolean | undefined;
+}
+/** One connection is owned by one session. Implementations must tolerate repeated close calls. */
+export interface McpConnection {
+    connect(signal: AbortSignal): Promise<void>;
+    listTools(cursor: string | undefined, signal: AbortSignal): Promise<McpToolPage>;
+    callTool(name: string, args: Record<string, unknown>, signal: AbortSignal): Promise<McpCallResult>;
+    close(): Promise<void>;
+}
+export type McpConnectionFactory = (server: McpServerConfig, cwd: string) => McpConnection;
+export interface SessionMcpTools {
+    readonly tools: ToolDefinition[];
+    close(): Promise<void>;
+}
+export interface McpBridgeOptions {
+    readonly startupMs?: number;
+    readonly callMs?: number;
+    readonly closeMs?: number;
+    readonly signal?: AbortSignal;
+}
+export type McpStartupErrorCode = "external_mcp_unavailable" | "external_mcp_no_tools" | "external_mcp_grant_tool_missing";
+export interface McpStartupFailure {
+    readonly code: McpStartupErrorCode;
+    readonly serverAlias?: string;
+    readonly toolAlias?: string;
+    readonly discoveredToolCount?: number;
+}
+/** Returns only classifications created by this module, never lookalike foreign errors. */
+export declare function classifyMcpStartupError(error: unknown): McpStartupFailure | undefined;
+/** Explicit, fail-closed tool grants. No extension loading, model calls, or global MCP config. */
+export declare function connectSessionMcpTools(configured: McpServers, permissionProfile: "read-only" | "coding", cwd: string, factory: McpConnectionFactory, options?: McpBridgeOptions): Promise<SessionMcpTools>;

package/dist/mcp-session-tools.js

@@ -0,0 +1,323 @@
+import { isMcpServers, mcpToolName, snapshotMcpServers } from "./mcp-config.js";
+export const MCP_STARTUP_TIMEOUT_MS = 10_000;
+export const MCP_CALL_TIMEOUT_MS = 30_000;
+// The stdio SDK allows 2s for EOF and 2s for SIGTERM before sending SIGKILL.
+// This bound must exceed that escalation window and remain below registry cleanup (5s).
+export const MCP_CLOSE_TIMEOUT_MS = 4_500;
+const MAX_DISCOVERED_TOOLS = 512;
+const MAX_DISCOVERY_PAGES = 16;
+const MAX_RESULT_BYTES = 256 * 1024;
+const RESULT_LIMIT_MESSAGE = "External MCP result exceeds the bridge limit of 262144 bytes; request less data.";
+const MAX_ERROR_RESULT_BYTES = 1024;
+const MAX_ERROR_MESSAGE_CHARACTERS = 200;
+const SOURCE_TOO_LARGE_MESSAGE = JSON.stringify({
+    code: "SOURCE_TOO_LARGE",
+    message: "Requested source exceeds the response limit; increase maxBytes.",
+});
+class McpStartupError extends Error {
+    code;
+    serverAlias;
+    toolAlias;
+    discoveredToolCount;
+    constructor(code, details = {}) {
+        super("External MCP operation failed");
+        this.name = "McpStartupError";
+        this.code = code;
+        if (details.serverAlias !== undefined)
+            this.serverAlias = details.serverAlias;
+        if (details.toolAlias !== undefined)
+            this.toolAlias = details.toolAlias;
+        if (details.discoveredToolCount !== undefined)
+            this.discoveredToolCount = details.discoveredToolCount;
+    }
+}
+function startupFailure(code, details = {}) {
+    return new McpStartupError(code, details);
+}
+/** Returns only classifications created by this module, never lookalike foreign errors. */
+export function classifyMcpStartupError(error) {
+    if (!(error instanceof McpStartupError))
+        return undefined;
+    return Object.freeze({
+        code: error.code,
+        ...(error.serverAlias === undefined ? {} : { serverAlias: error.serverAlias }),
+        ...(error.toolAlias === undefined ? {} : { toolAlias: error.toolAlias }),
+        ...(error.discoveredToolCount === undefined ? {} : { discoveredToolCount: error.discoveredToolCount }),
+    });
+}
+function failure() { return new Error("External MCP operation failed"); }
+async function bounded(operation, milliseconds, onTimeout = () => undefined) {
+    let timer;
+    const timeout = new Promise((_, reject) => {
+        timer = setTimeout(() => {
+            onTimeout();
+            reject(failure());
+        }, milliseconds);
+    });
+    try {
+        return await Promise.race([operation, timeout]);
+    }
+    finally {
+        if (timer !== undefined)
+            clearTimeout(timer);
+    }
+}
+function object(value) {
+    return value !== null && typeof value === "object" && !Array.isArray(value);
+}
+function remoteTool(value) {
+    return object(value)
+        && typeof value.name === "string" && value.name.length > 0 && value.name.length <= 256
+        && (value.description === undefined || typeof value.description === "string")
+        && object(value.inputSchema) && value.inputSchema.type === "object";
+}
+function closedObject(value, fields) {
+    if (!object(value))
+        return false;
+    const prototype = Object.getPrototypeOf(value);
+    if (prototype !== Object.prototype && prototype !== null)
+        return false;
+    return Reflect.ownKeys(value).every((key) => typeof key === "string" && fields.includes(key)
+        && Object.getOwnPropertyDescriptor(value, key)?.get === undefined
+        && Object.getOwnPropertyDescriptor(value, key)?.set === undefined);
+}
+function sourceTooLarge(value) {
+    return closedObject(value, ["code", "message"])
+        && Object.keys(value).length === 2
+        && value.code === "SOURCE_TOO_LARGE" && typeof value.message === "string"
+        && value.message.length > 0 && Array.from(value.message).length <= MAX_ERROR_MESSAGE_CHARACTERS
+        // Reject control/format characters, path separators, URL schemes and domain-like indicators.
+        // Even admitted ordinary foreign text is never copied into the controller message.
+        && !/[\p{Cc}\p{Cf}\u2028\u2029]/u.test(value.message)
+        && !/[\\/]|[a-z][a-z0-9+.-]*:|\b[a-z0-9-]+\.[a-z][a-z0-9-]+/iu.test(value.message);
+}
+// The only accepted raw JSON grammar is a two-member object with string values.
+// Decode the keys before comparing them so escaped duplicate keys cannot be hidden
+// by JSON.parse's last-key-wins behavior. Structured content is already SDK-decoded.
+const jsonString = '"(?:[^"\\\\\\u0000-\\u001f]|\\\\(?:["\\\\/bfnrt]|u[0-9a-fA-F]{4}))*"';
+const jsonWhitespace = "[\\t\\n\\r ]*";
+const jsonMember = `${jsonWhitespace}(${jsonString})${jsonWhitespace}:${jsonWhitespace}${jsonString}${jsonWhitespace}`;
+const errorTextObject = new RegExp(`^${jsonWhitespace}\\{${jsonMember},${jsonMember}\\}${jsonWhitespace}$`);
+function sourceTooLargeText(text) {
+    const match = errorTextObject.exec(text);
+    if (!match || JSON.parse(match[1]) === JSON.parse(match[2]))
+        return undefined;
+    const parsed = JSON.parse(text);
+    return sourceTooLarge(parsed) ? parsed : undefined;
+}
+function projectedErrorMessage(result) {
+    if (!closedObject(result, ["content", "structuredContent", "isError"])
+        || result.isError !== true || !Array.isArray(result.content)
+        || Buffer.byteLength(JSON.stringify(result), "utf8") > MAX_ERROR_RESULT_BYTES)
+        return undefined;
+    let textError;
+    if (result.content.length === 1) {
+        const block = result.content[0];
+        if (!closedObject(block, ["type", "text"]) || Object.keys(block).length !== 2
+            || block.type !== "text" || typeof block.text !== "string")
+            return undefined;
+        textError = sourceTooLargeText(block.text);
+        if (!textError)
+            return undefined;
+    }
+    else if (result.content.length !== 0)
+        return undefined;
+    if (result.structuredContent !== undefined) {
+        if (!sourceTooLarge(result.structuredContent))
+            return undefined;
+        if (textError && (textError.code !== result.structuredContent.code
+            || textError.message !== result.structuredContent.message))
+            return undefined;
+    }
+    else if (!textError)
+        return undefined;
+    return SOURCE_TOO_LARGE_MESSAGE;
+}
+/** Explicit, fail-closed tool grants. No extension loading, model calls, or global MCP config. */
+export async function connectSessionMcpTools(configured, permissionProfile, cwd, factory, options = {}) {
+    if (!isMcpServers(configured, permissionProfile))
+        throw failure();
+    const servers = snapshotMcpServers(configured);
+    const connections = [];
+    const lifetime = new AbortController();
+    const closeMs = options.closeMs ?? MCP_CLOSE_TIMEOUT_MS;
+    const callMs = options.callMs ?? MCP_CALL_TIMEOUT_MS;
+    let closing;
+    const connectionClosures = new WeakMap();
+    const closeConnection = (connection) => {
+        const existing = connectionClosures.get(connection);
+        if (existing)
+            return existing;
+        // Join an in-progress transport close instead of racing its process escalation.
+        const pending = bounded(Promise.resolve().then(() => connection.close()), closeMs).then(() => undefined, () => undefined);
+        connectionClosures.set(connection, pending);
+        void pending.then(() => { if (connectionClosures.get(connection) === pending)
+            connectionClosures.delete(connection); });
+        return pending;
+    };
+    const close = () => {
+        if (!closing) {
+            lifetime.abort();
+            options.signal?.removeEventListener("abort", onShutdown);
+            closing = Promise.all(connections.map(closeConnection)).then(() => undefined);
+        }
+        return closing;
+    };
+    const ensureOpen = () => { if (lifetime.signal.aborted)
+        throw failure(); };
+    // Keep the shutdown link for the entire session, including pending SDK construction.
+    const onShutdown = () => { void close(); };
+    options.signal?.addEventListener("abort", onShutdown, { once: true });
+    if (options.signal?.aborted)
+        onShutdown();
+    const initialize = async () => {
+        ensureOpen();
+        const tools = [];
+        for (const [serverAlias, server] of Object.entries(servers)) {
+            try {
+                ensureOpen();
+                const connection = factory(server, cwd);
+                connections.push(connection);
+                // If an implementation ignores cancellation, still clean up a late connection.
+                await Promise.resolve().then(() => {
+                    ensureOpen();
+                    return connection.connect(lifetime.signal);
+                }).finally(async () => {
+                    // A late failure can own a process too; cleanup is not success-only.
+                    if (lifetime.signal.aborted)
+                        await closeConnection(connection);
+                });
+                ensureOpen();
+                const discovered = new Map();
+                const cursors = new Set();
+                let cursor;
+                for (let pageIndex = 0;; pageIndex++) {
+                    ensureOpen();
+                    if (pageIndex >= MAX_DISCOVERY_PAGES) {
+                        throw startupFailure("external_mcp_unavailable", { serverAlias });
+                    }
+                    const page = await connection.listTools(cursor, lifetime.signal);
+                    ensureOpen();
+                    if (!object(page) || !Array.isArray(page.tools)
+                        || (page.nextCursor !== undefined && typeof page.nextCursor !== "string")) {
+                        throw startupFailure("external_mcp_unavailable", { serverAlias });
+                    }
+                    for (const tool of page.tools) {
+                        if (!remoteTool(tool) || discovered.has(tool.name) || discovered.size >= MAX_DISCOVERED_TOOLS) {
+                            throw startupFailure("external_mcp_unavailable", { serverAlias });
+                        }
+                        discovered.set(tool.name, tool);
+                    }
+                    if (page.nextCursor === undefined)
+                        break;
+                    if (cursors.has(page.nextCursor)) {
+                        throw startupFailure("external_mcp_unavailable", { serverAlias });
+                    }
+                    cursors.add(page.nextCursor);
+                    cursor = page.nextCursor;
+                }
+                if (discovered.size === 0) {
+                    throw startupFailure("external_mcp_no_tools", { serverAlias, discoveredToolCount: 0 });
+                }
+                for (const [toolAlias, grant] of Object.entries(server.tools)) {
+                    const remote = discovered.get(grant.name);
+                    if (!remote) {
+                        throw startupFailure("external_mcp_grant_tool_missing", {
+                            serverAlias,
+                            toolAlias,
+                            discoveredToolCount: discovered.size,
+                        });
+                    }
+                    // MCP JSON Schemas are passed intact to Pi's JSON-Schema argument validator.
+                    const parameters = structuredClone(remote.inputSchema);
+                    tools.push({
+                        name: mcpToolName(serverAlias, toolAlias),
+                        label: `MCP ${serverAlias}/${toolAlias}`,
+                        description: remote.description ?? `Call the configured ${serverAlias}/${toolAlias} MCP tool.`,
+                        parameters,
+                        promptSnippet: "Call an explicitly granted external MCP tool.",
+                        executionMode: "sequential",
+                        async execute(_id, args, signal) {
+                            ensureOpen();
+                            if (!object(args) || signal?.aborted)
+                                throw failure();
+                            const call = new AbortController();
+                            let rejectCancellation;
+                            const cancellation = new Promise((_, reject) => { rejectCancellation = reject; });
+                            void cancellation.catch(() => undefined);
+                            const cancel = () => { call.abort(); rejectCancellation(failure()); };
+                            lifetime.signal.addEventListener("abort", cancel, { once: true });
+                            signal?.addEventListener("abort", cancel, { once: true });
+                            let projectedError;
+                            try {
+                                // Check again after subscribing; close/abort must never race a new call admission.
+                                if (lifetime.signal.aborted || signal?.aborted)
+                                    throw failure();
+                                const result = await bounded(Promise.race([cancellation, Promise.resolve().then(() => {
+                                        if (call.signal.aborted)
+                                            throw failure();
+                                        return connection.callTool(grant.name, args, call.signal);
+                                    })]), callMs, cancel);
+                                if (call.signal.aborted)
+                                    throw failure();
+                                if (result.isError !== undefined && typeof result.isError !== "boolean")
+                                    throw failure();
+                                if (result.isError === true) {
+                                    const message = projectedErrorMessage(result);
+                                    if (message === undefined)
+                                        throw failure();
+                                    // A private per-execution identity, never a foreign error's name/code/message,
+                                    // is the only exception permitted to survive the sanitizing catch below.
+                                    projectedError = new Error(message);
+                                    throw projectedError;
+                                }
+                                if (Buffer.byteLength(JSON.stringify(result), "utf8") > MAX_RESULT_BYTES) {
+                                    projectedError = new Error(RESULT_LIMIT_MESSAGE);
+                                    throw projectedError;
+                                }
+                                const content = result.content.map((block) => ({
+                                    type: "text", text: block.type === "text" && typeof block.text === "string" ? block.text : JSON.stringify(block),
+                                }));
+                                if (content.length === 0 && result.structuredContent !== undefined) {
+                                    content.push({ type: "text", text: JSON.stringify(result.structuredContent) });
+                                }
+                                return { content, details: {
+                                        server: serverAlias, tool: toolAlias,
+                                        ...(result.structuredContent === undefined ? {} : { structuredContent: result.structuredContent }),
+                                    } };
+                            }
+                            catch (error) {
+                                // A transport exception or MCP isError must not become a successful Pi tool result.
+                                if (!call.signal.aborted && projectedError !== undefined && error === projectedError)
+                                    throw error;
+                                throw failure();
+                            }
+                            finally {
+                                call.abort();
+                                lifetime.signal.removeEventListener("abort", cancel);
+                                signal?.removeEventListener("abort", cancel);
+                            }
+                        },
+                    });
+                }
+            }
+            catch (error) {
+                if (error instanceof McpStartupError)
+                    throw error;
+                throw startupFailure("external_mcp_unavailable", { serverAlias });
+            }
+        }
+        ensureOpen();
+        return tools;
+    };
+    try {
+        const tools = await bounded(initialize(), options.startupMs ?? MCP_STARTUP_TIMEOUT_MS, () => lifetime.abort());
+        return { tools, close };
+    }
+    catch (error) {
+        await close();
+        if (error instanceof McpStartupError)
+            throw error;
+        throw startupFailure("external_mcp_unavailable");
+    }
+}

package/dist/mcp-stdio-client.d.ts

@@ -0,0 +1,3 @@
+import { type McpConnectionFactory } from "./mcp-session-tools.js";
+/** Uses only the MCP SDK's public exports. No HTTP, shell, or global MCP config. */
+export declare const createStdioMcpConnection: McpConnectionFactory;

package/dist/mcp-stdio-client.js

@@ -0,0 +1,59 @@
+import { Client } from "@modelcontextprotocol/client";
+import { StdioClientTransport } from "@modelcontextprotocol/client/stdio";
+import packageMetadata from "../package.json" with { type: "json" };
+import { MCP_CALL_TIMEOUT_MS, MCP_STARTUP_TIMEOUT_MS } from "./mcp-session-tools.js";
+/** Uses only the MCP SDK's public exports. No HTTP, shell, or global MCP config. */
+export const createStdioMcpConnection = (server, cwd) => {
+    const env = {};
+    for (const [target, source] of Object.entries(server.envFrom ?? {})) {
+        const value = process.env[source];
+        if (value === undefined)
+            throw new Error("External MCP environment is unavailable");
+        env[target] = value;
+    }
+    const transport = new StdioClientTransport({
+        command: server.command, args: [...(server.args ?? [])], cwd, env, stderr: "pipe",
+    });
+    // The SDK supplies its small default OS environment; never spread process.env.
+    // Drain child diagnostics without copying secrets to controller stdout/stderr.
+    transport.stderr?.on("data", () => undefined);
+    const client = new Client({ name: "pi-session-mcp-session", version: packageMetadata.version }, { capabilities: {} });
+    client.onerror = () => undefined;
+    const discoveredTools = new Map();
+    return {
+        async connect(signal) {
+            await client.connect(transport, { signal, timeout: MCP_STARTUP_TIMEOUT_MS });
+            if (!client.getServerCapabilities()?.tools)
+                throw new Error("External MCP tools capability is unavailable");
+        },
+        async listTools(cursor, signal) {
+            // `Client.listTools({})` auto-aggregates and hides cursor loops. Issue one
+            // validated protocol request per page so the bridge owns completeness limits.
+            const page = await client.request({
+                method: "tools/list",
+                params: cursor === undefined ? {} : { cursor },
+            }, { signal, timeout: MCP_STARTUP_TIMEOUT_MS });
+            for (const tool of page.tools)
+                discoveredTools.set(tool.name, tool);
+            return page;
+        },
+        callTool(name, args, signal) {
+            const toolDefinition = discoveredTools.get(name);
+            if (!toolDefinition)
+                throw new Error("External MCP tool definition is unavailable");
+            return client.callTool({ name, arguments: args }, {
+                signal, timeout: MCP_CALL_TIMEOUT_MS, maxTotalTimeout: MCP_CALL_TIMEOUT_MS, resetTimeoutOnProgress: false,
+                toolDefinition,
+            });
+        },
+        async close() {
+            // Close the transport too if initialization failed before Client took ownership.
+            try {
+                await client.close();
+            }
+            finally {
+                await transport.close();
+            }
+        },
+    };
+};

package/dist/package-metadata.d.ts

@@ -0,0 +1,18 @@
+export declare const PACKAGE_NAME: string;
+export declare const PACKAGE_VERSION: string;
+export declare const PACKAGE_NODE_ENGINE: string;
+export interface LoadedPackageMetadata {
+    readonly version: string;
+    readonly engines: {
+        readonly node?: string;
+    };
+    /** Absent in an npm installation: npm never ships a lockfile inside a package. */
+    readonly lockVersion?: string;
+}
+type ReadFile = (path: string, encoding: "utf8") => Promise<string>;
+export declare function isMissingFile(error: unknown): boolean;
+/** The lockfile text of a Git checkout, or undefined for an npm installation. Other read errors propagate. */
+export declare function readLockfile(packageRoot: string, readFile: ReadFile): Promise<string | undefined>;
+/** Read the package and lock metadata using the same shape as production. */
+export declare function readPackageMetadata(packageRoot: string, readFile: ReadFile): Promise<LoadedPackageMetadata>;
+export {};

package/dist/package-metadata.js

@@ -0,0 +1,32 @@
+import packageMetadata from "../package.json" with { type: "json" };
+import { join } from "node:path";
+export const PACKAGE_NAME = packageMetadata.name;
+export const PACKAGE_VERSION = packageMetadata.version;
+export const PACKAGE_NODE_ENGINE = packageMetadata.engines.node;
+export function isMissingFile(error) {
+    return typeof error === "object" && error !== null && error.code === "ENOENT";
+}
+/** The lockfile text of a Git checkout, or undefined for an npm installation. Other read errors propagate. */
+export async function readLockfile(packageRoot, readFile) {
+    try {
+        return await readFile(join(packageRoot, "package-lock.json"), "utf8");
+    }
+    catch (error) {
+        if (isMissingFile(error))
+            return undefined;
+        throw error;
+    }
+}
+/** Read the package and lock metadata using the same shape as production. */
+export async function readPackageMetadata(packageRoot, readFile) {
+    const packageJson = JSON.parse(await readFile(join(packageRoot, "package.json"), "utf8"));
+    const lockText = await readLockfile(packageRoot, readFile);
+    const lock = lockText === undefined ? undefined : JSON.parse(lockText);
+    const engines = packageJson.engines?.node;
+    const lockVersion = lock?.packages?.[""]?.version;
+    return {
+        version: packageJson.version,
+        engines: engines === undefined ? {} : { node: engines },
+        ...(lockVersion === undefined ? {} : { lockVersion: lockVersion }),
+    };
+}

package/dist/pi-adapter.d.ts

@@ -0,0 +1,42 @@
+import type { PermissionProfile, ResolvedExecutionProfile, ThinkingLevel } from "./execution-profile.js";
+export type { PermissionProfile };
+export type PiTurnOutcome = {
+    status: "completed";
+    assistantText: string;
+} | {
+    status: "failed";
+} | {
+    status: "aborted";
+};
+export interface PiAppliedSelection {
+    readonly provider: string;
+    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 declare class PiSessionCreationError extends Error {
+    readonly code: PiSessionCreationErrorCode;
+    constructor(code: PiSessionCreationErrorCode);
+}
+export interface PiSessionHandle {
+    readonly sdkSessionId: string;
+    /** Only whitelisted, post-verified selection metadata may cross the adapter boundary. */
+    readonly appliedSelection: PiAppliedSelection;
+    /**
+     * `onActivity` is an optional content-free liveness callback, invoked after a completed
+     * tool execution and after a completed assistant message. It receives no event payload
+     * and must only be used for timestamping; it never carries tool names, arguments,
+     * results, text, paths, or credentials.
+     */
+    prompt(text: string, preflight: (accepted: boolean) => void, onActivity?: () => void): Promise<PiTurnOutcome>;
+    abort(): Promise<void>;
+    /** May await bounded external-resource cleanup; synchronous fakes remain supported. */
+    dispose(): void | Promise<void>;
+}
+export interface PiSessionAdapter {
+    create(input: {
+        cwd: string;
+        executionProfile: ResolvedExecutionProfile;
+        signal?: AbortSignal;
+    }): Promise<PiSessionHandle>;
+}

package/dist/pi-adapter.js

@@ -0,0 +1,22 @@
+const PI_SESSION_CREATION_MESSAGES = {
+    unknown_provider: "Execution profile provider is not in the local Pi catalog",
+    unknown_model: "Execution profile model is not in the local Pi catalog",
+    local_authentication_missing: "Local authentication for the execution profile is missing",
+    local_authentication_unavailable: "Local authentication for the execution profile is unavailable",
+    model_unavailable: "Execution profile model is not locally available",
+    thinking_level_unavailable: "Execution profile thinking level is unavailable for the model",
+    execution_selection_mismatch: "Execution profile could not be applied",
+    external_mcp_unavailable: "Configured external MCP tools are unavailable",
+    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",
+    pi_session_creation_failed: "Pi session creation failed",
+};
+export class PiSessionCreationError extends Error {
+    code;
+    constructor(code) {
+        super(PI_SESSION_CREATION_MESSAGES[code]);
+        this.name = "PiSessionCreationError";
+        this.code = code;
+    }
+}

package/dist/process-diagnostics.d.ts

@@ -0,0 +1,8 @@
+import { type ConfigErrorCode } from "./config.js";
+export interface StartupDiagnostic {
+    readonly level: "error";
+    readonly event: "startup_failed";
+    readonly stage: "startup";
+    readonly code: ConfigErrorCode | "startup_failed";
+}
+export declare function startupFailureDiagnostic(error: unknown): StartupDiagnostic;

package/dist/process-diagnostics.js

@@ -0,0 +1,9 @@
+import { ConfigError } from "./config.js";
+export function startupFailureDiagnostic(error) {
+    return {
+        level: "error",
+        event: "startup_failed",
+        stage: "startup",
+        code: error instanceof ConfigError ? error.code : "startup_failed",
+    };
+}