@unbrained/pm-cli 2026.8.25 → 2026.8.27

package/dist/mcp/http-server.js

@@ -0,0 +1,451 @@
+#!/usr/bin/env node
+/**
+ * @module mcp/http-server
+ *
+ * Serves the pm MCP dispatcher through the sessionless 2026-07-28 Streamable
+ * HTTP POST binding with request-scoped JSON/SSE responses.
+ */
+
+!function(){try{var e="undefined"!=typeof window?window:"undefined"!=typeof global?global:"undefined"!=typeof globalThis?globalThis:"undefined"!=typeof self?self:{},n=(new e.Error).stack;n&&(e._sentryDebugIds=e._sentryDebugIds||{},e._sentryDebugIds[n]="7c5d2b34-e2ab-52a9-80a9-c5a28ce09dc7")}catch(e){}}();
+import { createServer, } from "node:http";
+import { PM_MCP_ERROR_CODES, PmMcpProtocolError } from "../sdk/mcp/protocol.js";
+import { PmMcpAuthorizationError, authorizeMcpHttpRequest, buildMcpProtectedResourceMetadata, createMcpStaticBearerVerifier, } from "../sdk/mcp/authorization.js";
+import { validateMcpHttpRequestHeaders } from "../sdk/mcp/transport.js";
+import { buildMcpToolCallErrorResult, closeMcpSubscription, handleRequest, isInvokedAsMcpMainModule, openMcpSubscription, resolveMcpToolSchemaForRequest, } from "./server.js";
+const DEFAULT_MAXIMUM_BODY_BYTES = 1024 * 1024;
+const DEFAULT_KEEP_ALIVE_MS = 15_000;
+const PM_MCP_HTTP_RUNTIMES = new WeakMap();
+/** Write one SSE event and wait for transport backpressure to clear. */
+export function writePmMcpSseEvent(response, payload) {
+    return new Promise((resolve, reject) => {
+        let settled = false;
+        const cleanup = () => {
+            response.off("drain", onDrain);
+            response.off("close", onClose);
+        };
+        const onDrain = () => {
+            settled = true;
+            cleanup();
+            resolve();
+        };
+        const onClose = () => {
+            settled = true;
+            cleanup();
+            reject(new Error("MCP response stream closed during backpressure"));
+        };
+        response.once("drain", onDrain);
+        response.once("close", onClose);
+        try {
+            if (response.write(`data: ${JSON.stringify(payload)}\n\n`) && !settled) {
+                settled = true;
+                cleanup();
+                resolve();
+            }
+        }
+        catch (error) {
+            cleanup();
+            reject(error);
+        }
+    });
+}
+function writeJson(response, status, payload, headers = {}) {
+    response.writeHead(status, {
+        "Cache-Control": "no-store",
+        "Content-Type": "application/json",
+        ...headers,
+    });
+    response.end(`${JSON.stringify(payload)}\n`);
+}
+function writeJsonRpcError(response, id, error) {
+    const authorizationError = error instanceof PmMcpAuthorizationError ? error : undefined;
+    const protocolError = error instanceof PmMcpProtocolError ? error : undefined;
+    const code = protocolError?.code ?? -32603;
+    const clientErrorCodes = new Set([
+        -32700,
+        -32600,
+        PM_MCP_ERROR_CODES.headerMismatch,
+        PM_MCP_ERROR_CODES.unsupportedProtocolVersion,
+        PM_MCP_ERROR_CODES.invalidParams,
+    ]);
+    const status = authorizationError?.httpStatus ??
+        (code === -32601 ? 404 : clientErrorCodes.has(code) ? 400 : 500);
+    writeJson(response, status, {
+        jsonrpc: "2.0",
+        id: id ?? null,
+        error: {
+            code,
+            message: error instanceof Error ? error.message : "Internal MCP error",
+            ...(protocolError ? { data: protocolError.data } : {}),
+        },
+    }, authorizationError?.challenge
+        ? { "WWW-Authenticate": authorizationError.challenge }
+        : {});
+}
+function finishCommittedMcpResponse(response) {
+    if (!response.headersSent && !response.writableEnded && !response.destroyed) {
+        return false;
+    }
+    if (!response.writableEnded && !response.destroyed)
+        response.end();
+    return true;
+}
+function writeMcpHttpDispatchError(response, rpcRequest, error) {
+    if (finishCommittedMcpResponse(response))
+        return;
+    const toolError = rpcRequest
+        ? buildMcpToolCallErrorResult(rpcRequest, error)
+        : undefined;
+    if (toolError && rpcRequest) {
+        writeJson(response, 200, {
+            jsonrpc: "2.0",
+            id: rpcRequest.id ?? null,
+            result: toolError,
+        });
+        return;
+    }
+    writeJsonRpcError(response, rpcRequest?.id, error);
+}
+function destroyFailedMcpHttpResponse(response, error) {
+    response.destroy(new Error("Unhandled MCP HTTP request failure", { cause: error }));
+}
+async function readRequestBody(request, maximumBytes) {
+    const chunks = [];
+    let observed = 0;
+    for await (const chunk of request) {
+        const buffer = Buffer.from(chunk);
+        observed += buffer.length;
+        if (observed > maximumBytes) {
+            throw new PmMcpProtocolError("MCP HTTP request body exceeds the configured limit", PM_MCP_ERROR_CODES.invalidParams, { maximumBytes });
+        }
+        chunks.push(buffer);
+    }
+    return Buffer.concat(chunks).toString("utf8");
+}
+function parseJsonRpcRequest(source) {
+    let value;
+    try {
+        value = JSON.parse(source);
+    }
+    catch {
+        throw new PmMcpProtocolError("Invalid JSON-RPC request body", -32700);
+    }
+    if (typeof value !== "object" ||
+        value === null ||
+        Array.isArray(value) ||
+        ("jsonrpc" in value && value.jsonrpc !== "2.0") ||
+        ("method" in value && typeof value.method !== "string")) {
+        throw new PmMcpProtocolError("Invalid JSON-RPC request", -32600);
+    }
+    return value;
+}
+function protectedResourcePaths(endpointPath) {
+    return new Set([
+        "/.well-known/oauth-protected-resource",
+        `/.well-known/oauth-protected-resource${endpointPath}`,
+    ]);
+}
+function routeMcpHttpBoundary(request, response, requestUrl, runtime) {
+    if (runtime.options.protectedResourceMetadata &&
+        request.method === "GET" &&
+        protectedResourcePaths(runtime.endpointPath).has(requestUrl.pathname)) {
+        writeJson(response, 200, { ...runtime.options.protectedResourceMetadata });
+        return true;
+    }
+    if (requestUrl.pathname !== runtime.endpointPath) {
+        writeJson(response, 404, { error: "Not found" });
+        return true;
+    }
+    if (request.method !== "POST") {
+        response.setHeader("Allow", "POST");
+        writeJson(response, 405, { error: "Method not allowed" });
+        return true;
+    }
+    const origin = request.headers.origin;
+    if (origin !== undefined && !runtime.allowedOrigins.has(origin)) {
+        writeJson(response, 403, { error: "Origin is not allowed" });
+        return true;
+    }
+    const accept = request.headers.accept;
+    const contentType = request.headers["content-type"];
+    if (typeof accept !== "string" ||
+        !accept.includes("application/json") ||
+        !accept.includes("text/event-stream") ||
+        typeof contentType !== "string" ||
+        !contentType.startsWith("application/json")) {
+        writeJson(response, 406, {
+            error: "MCP requires JSON and SSE content negotiation",
+        });
+        return true;
+    }
+    return false;
+}
+async function openHttpSubscription(input) {
+    if (typeof input.request.id !== "string" &&
+        typeof input.request.id !== "number") {
+        throw new PmMcpProtocolError("subscriptions/listen requires a JSON-RPC id", PM_MCP_ERROR_CODES.invalidParams);
+    }
+    const subscriptionId = input.request.id;
+    const subscriptionKey = Symbol("pm-mcp-http-subscription");
+    const active = {
+        id: subscriptionId,
+        key: subscriptionKey,
+        response: input.response,
+    };
+    let disconnected = input.response.destroyed || input.response.writableEnded;
+    let subscriptionOpened = false;
+    const closeActiveSubscription = () => {
+        disconnected = true;
+        if (active.timer)
+            clearInterval(active.timer);
+        input.runtime.activeSubscriptions.delete(subscriptionKey);
+        if (subscriptionOpened) {
+            closeMcpSubscription(subscriptionId, subscriptionKey);
+        }
+    };
+    input.response.once("close", closeActiveSubscription);
+    let responseStarted = false;
+    try {
+        await openMcpSubscription({
+            request: input.request,
+            key: subscriptionKey,
+            sink: (notification) => {
+                if (input.response.destroyed || input.response.writableEnded) {
+                    throw new Error("MCP response stream closed before acknowledgment");
+                }
+                if (!responseStarted) {
+                    responseStarted = true;
+                    input.response.setHeader("Cache-Control", "no-cache, no-store");
+                    input.response.setHeader("Connection", "keep-alive");
+                    input.response.setHeader("Content-Type", "text/event-stream");
+                    input.response.setHeader("X-Accel-Buffering", "no");
+                }
+                return writePmMcpSseEvent(input.response, notification);
+            },
+        });
+        subscriptionOpened = true;
+    }
+    catch (error) {
+        input.response.off("close", closeActiveSubscription);
+        throw error;
+    }
+    if (disconnected ||
+        input.response.destroyed ||
+        input.response.writableEnded) {
+        closeActiveSubscription();
+        return;
+    }
+    if (input.runtime.keepAliveMs > 0) {
+        active.timer = setInterval(() => input.response.write(":\r\n\r\n"), input.runtime.keepAliveMs);
+        active.timer.unref();
+    }
+    input.runtime.activeSubscriptions.set(subscriptionKey, active);
+}
+async function dispatchMcpHttpRpc(input) {
+    let rpcRequest;
+    try {
+        if (input.runtime.options.authorization) {
+            await authorizeMcpHttpRequest({
+                headers: input.request.headers,
+                requestUrl: input.requestUrl.href,
+                policy: input.runtime.options.authorization,
+            });
+        }
+        rpcRequest = parseJsonRpcRequest(await readRequestBody(input.request, input.runtime.maximumBodyBytes));
+        validateMcpHttpRequestHeaders({
+            headers: input.request.headers,
+            request: rpcRequest,
+            toolSchema: await resolveMcpToolSchemaForRequest(rpcRequest),
+        });
+        if (rpcRequest.method === "subscriptions/listen") {
+            await openHttpSubscription({
+                request: rpcRequest,
+                response: input.response,
+                runtime: input.runtime,
+            });
+            return;
+        }
+        const result = await (input.runtime.options.requestHandler ?? handleRequest)(rpcRequest);
+        if (!Object.prototype.hasOwnProperty.call(rpcRequest, "id")) {
+            input.response.writeHead(202);
+            input.response.end();
+            return;
+        }
+        writeJson(input.response, 200, {
+            jsonrpc: "2.0",
+            id: rpcRequest.id ?? null,
+            result: result ?? {},
+        });
+    }
+    catch (error) {
+        writeMcpHttpDispatchError(input.response, rpcRequest, error);
+    }
+}
+async function handleMcpHttpRequest(request, response, runtime) {
+    const requestUrl = new URL(request.url, "http://localhost");
+    if (routeMcpHttpBoundary(request, response, requestUrl, runtime))
+        return;
+    await dispatchMcpHttpRpc({ request, response, requestUrl, runtime });
+}
+/** Create a configured HTTP server without binding it. */
+export function createPmMcpHttpServer(options = {}) {
+    const runtime = {
+        activeSubscriptions: new Map(),
+        allowedOrigins: new Set(options.allowedOrigins ?? []),
+        endpointPath: options.endpointPath ?? "/mcp",
+        keepAliveMs: options.keepAliveMs ?? DEFAULT_KEEP_ALIVE_MS,
+        maximumBodyBytes: options.maximumBodyBytes ?? DEFAULT_MAXIMUM_BODY_BYTES,
+        options,
+    };
+    const server = createServer((request, response) => {
+        void handleMcpHttpRequest(request, response, runtime).catch(destroyFailedMcpHttpResponse.bind(undefined, response));
+    });
+    PM_MCP_HTTP_RUNTIMES.set(server, runtime);
+    server.on("close", () => {
+        closeActiveHttpSubscriptions(runtime);
+        PM_MCP_HTTP_RUNTIMES.delete(server);
+    });
+    return server;
+}
+function closeActiveHttpSubscriptions(runtime) {
+    for (const [key, active] of runtime.activeSubscriptions) {
+        if (active.timer)
+            clearInterval(active.timer);
+        const result = closeMcpSubscription(active.id, key);
+        if (result) {
+            active.response.write(`data: ${JSON.stringify({ jsonrpc: "2.0", id: active.id, result })}\n\n`);
+        }
+        active.response.end();
+    }
+    runtime.activeSubscriptions.clear();
+}
+/** Gracefully close subscriptions before stopping a Streamable HTTP server. */
+export async function closePmMcpHttpServer(server) {
+    const runtime = PM_MCP_HTTP_RUNTIMES.get(server);
+    if (runtime)
+        closeActiveHttpSubscriptions(runtime);
+    await new Promise((resolve, reject) => {
+        server.close((error) => (error ? reject(error) : resolve()));
+    });
+    server.closeAllConnections();
+}
+/** Bind the configured Streamable HTTP server and return its actual address. */
+export async function startPmMcpHttpServer(options = {}) {
+    const server = createPmMcpHttpServer(options);
+    const address = resolvePmMcpHttpListenAddress(options);
+    await new Promise((resolve, reject) => {
+        server.once("error", reject);
+        server.listen(address.port, address.host, () => {
+            server.off("error", reject);
+            resolve();
+        });
+    });
+    return server;
+}
+/** Resolve loopback-safe bind defaults without opening a socket. */
+export function resolvePmMcpHttpListenAddress(options = {}) {
+    return {
+        host: options.host ?? "127.0.0.1",
+        port: options.port ?? 3000,
+    };
+}
+function readMcpHttpEnvironment(environment) {
+    const configuredPort = environment.PM_MCP_HTTP_PORT?.trim();
+    const port = Number(configuredPort || "3000");
+    if (!Number.isInteger(port) || port < 0 || port > 65_535) {
+        throw new Error("PM_MCP_HTTP_PORT must be an integer from 0 through 65535");
+    }
+    return {
+        host: environment.PM_MCP_HTTP_HOST?.trim() || "127.0.0.1",
+        port,
+        allowedOrigins: (environment.PM_MCP_HTTP_ALLOWED_ORIGINS ?? "")
+            .split(",")
+            .map((entry) => entry.trim())
+            .filter(Boolean),
+        token: environment.PM_MCP_HTTP_BEARER_TOKEN?.trim() || undefined,
+        issuer: environment.PM_MCP_HTTP_AUTH_ISSUER?.trim() || undefined,
+        resource: environment.PM_MCP_HTTP_RESOURCE?.trim() || undefined,
+        scopes: (environment.PM_MCP_HTTP_SCOPES ?? "pm:read pm:write")
+            .split(/\s+/u)
+            .filter(Boolean),
+    };
+}
+function buildMcpHttpAuthorizationOptions(environment) {
+    const metadata = buildMcpProtectedResourceMetadata({
+        resource: environment.resource,
+        authorizationServers: [environment.issuer],
+        scopes: environment.scopes,
+    });
+    const acceptedIssuer = environment.issuer;
+    return {
+        protectedResourceMetadata: metadata,
+        authorization: {
+            issuer: acceptedIssuer,
+            resource: metadata.resource,
+            requiredScopes: environment.scopes,
+            resourceMetadataUrl: new URL("/.well-known/oauth-protected-resource", metadata.resource).href,
+            verifyAccessToken: createMcpStaticBearerVerifier({
+                token: environment.token,
+                claims: {
+                    principal: "configured-remote-client",
+                    issuer: acceptedIssuer,
+                    audience: metadata.resource,
+                    scopes: environment.scopes,
+                },
+            }),
+        },
+    };
+}
+function hasCompleteMcpHttpAuthorization(environment) {
+    return Boolean(environment.token && environment.issuer && environment.resource);
+}
+/** Resolve and harden executable HTTP options from an environment map. */
+export function resolvePmMcpHttpServerOptionsFromEnvironment(processEnvironment = process.env) {
+    const environment = readMcpHttpEnvironment(processEnvironment);
+    const hasAuthorization = hasCompleteMcpHttpAuthorization(environment);
+    if (environment.host !== "127.0.0.1" &&
+        environment.host !== "localhost" &&
+        !hasAuthorization) {
+        throw new Error("Non-loopback MCP HTTP requires PM_MCP_HTTP_BEARER_TOKEN, PM_MCP_HTTP_AUTH_ISSUER, and PM_MCP_HTTP_RESOURCE");
+    }
+    const base = {
+        host: environment.host,
+        port: environment.port,
+        allowedOrigins: environment.allowedOrigins,
+    };
+    return hasAuthorization
+        ? {
+            ...base,
+            ...buildMcpHttpAuthorizationOptions({
+                issuer: environment.issuer,
+                resource: environment.resource,
+                token: environment.token,
+                scopes: environment.scopes,
+            }),
+        }
+        : base;
+}
+/** Internal HTTP transport seams used only by direct integration tests. */
+export const _testOnly = {
+    /** Return the first active request-scoped transport key for one server. */
+    activeSubscriptionKey: (server) => PM_MCP_HTTP_RUNTIMES.get(server).activeSubscriptions.keys().next().value,
+    /** Open a stream against one server runtime without a network socket. */
+    openHttpSubscription: (server, request, response) => openHttpSubscription({
+        request,
+        response,
+        runtime: PM_MCP_HTTP_RUNTIMES.get(server),
+    }),
+    /** Exercise committed-response handling without a network race. */
+    writeMcpHttpDispatchError,
+    /** Exercise the terminal request rejection handler without a live socket. */
+    destroyFailedMcpHttpResponse,
+};
+/* c8 ignore start -- executable guard and process lifecycle are integration-tested */
+if (isInvokedAsMcpMainModule(process.argv[1], import.meta.url)) {
+    startPmMcpHttpServer(resolvePmMcpHttpServerOptionsFromEnvironment()).catch((error) => {
+        console.error(error instanceof Error ? error.message : String(error));
+        process.exit(1);
+    });
+}
+/* c8 ignore stop */
+//# sourceMappingURL=http-server.js.map
+//# debugId=7c5d2b34-e2ab-52a9-80a9-c5a28ce09dc7

package/dist/mcp/legacy-adapter.d.ts

@@ -0,0 +1,50 @@
+/**
+ * @module mcp/legacy-adapter
+ *
+ * Isolates the bounded MCP 2025-06-18 stdio compatibility surface from the
+ * canonical stateless dispatcher. No modern transport imports policy from it.
+ */
+import { type AgentClientInfo } from "../sdk/runtime-primitives.js";
+import { type PmMcpImplementation, type PmMcpServerCapabilities } from "../sdk/mcp/protocol.js";
+/** Minimal request shape consumed by the compatibility adapter. */
+export interface LegacyMcpRequest {
+    /** Legacy method name. */
+    method?: string;
+    /** Legacy method parameters. */
+    params?: Record<string, unknown>;
+}
+/** Host callbacks keep this adapter separate from canonical SDK policy. */
+export interface LegacyMcpAdapterOptions {
+    /** Immutable server identity. */
+    serverInfo: PmMcpImplementation;
+    /** Compatibility-era capabilities. */
+    capabilities: PmMcpServerCapabilities;
+    /** Model-facing usage instructions. */
+    instructions: string;
+    /** Parse bounded historical client identity. */
+    parseClientInfo: (value: unknown) => AgentClientInfo | undefined;
+    /** Resolve legacy tool definitions. */
+    listTools: (params: Record<string, unknown> | undefined) => Promise<Record<string, unknown>>;
+    /** Execute one legacy tool call. */
+    callTool: (params: Record<string, unknown> | undefined, clientInfo: AgentClientInfo | undefined) => Promise<Record<string, unknown>>;
+    /** List legacy resources. */
+    listResources: () => Record<string, unknown>;
+    /** Read one legacy resource. */
+    readResource: (params: Record<string, unknown> | undefined) => Promise<Record<string, unknown>>;
+    /** List legacy prompts. */
+    listPrompts: () => Record<string, unknown>;
+    /** Render one legacy prompt. */
+    getPrompt: (params: Record<string, unknown> | undefined) => Record<string, unknown>;
+}
+/** Explicit compatibility adapter with no cross-process or modern-session role. */
+export declare class LegacyMcpAdapter {
+    #private;
+    /** Create one process-local legacy stdio adapter. */
+    constructor(options: LegacyMcpAdapterOptions);
+    /** Read the bounded identity most recently supplied to legacy initialize. */
+    getClientInfo(): AgentClientInfo | undefined;
+    /** Validate and answer the historical initialize handshake. */
+    initialize(params: Record<string, unknown> | undefined): Record<string, unknown>;
+    /** Dispatch one unversioned request through the finite legacy method set. */
+    dispatch(request: LegacyMcpRequest): Promise<Record<string, unknown>>;
+}

package/dist/mcp/legacy-adapter.js

@@ -0,0 +1,64 @@
+/**
+ * @module mcp/legacy-adapter
+ *
+ * Isolates the bounded MCP 2025-06-18 stdio compatibility surface from the
+ * canonical stateless dispatcher. No modern transport imports policy from it.
+ */
+
+!function(){try{var e="undefined"!=typeof window?window:"undefined"!=typeof global?global:"undefined"!=typeof globalThis?globalThis:"undefined"!=typeof self?self:{},n=(new e.Error).stack;n&&(e._sentryDebugIds=e._sentryDebugIds||{},e._sentryDebugIds[n]="6a1d9bca-7dac-5537-9930-a12d8049c8b8")}catch(e){}}();
+import { PmCliError } from "../sdk/runtime-primitives.js";
+import { PM_MCP_ERROR_CODES, PM_MCP_LEGACY_PROTOCOL_VERSIONS, PM_MCP_PROTOCOL_VERSION, PmMcpProtocolError, } from "../sdk/mcp/protocol.js";
+/** Explicit compatibility adapter with no cross-process or modern-session role. */
+export class LegacyMcpAdapter {
+    #options;
+    #clientInfo;
+    /** Create one process-local legacy stdio adapter. */
+    constructor(options) {
+        this.#options = options;
+    }
+    /** Read the bounded identity most recently supplied to legacy initialize. */
+    getClientInfo() {
+        return this.#clientInfo ? structuredClone(this.#clientInfo) : undefined;
+    }
+    /** Validate and answer the historical initialize handshake. */
+    initialize(params) {
+        const requestedVersion = params?.protocolVersion;
+        if (typeof requestedVersion === "string" &&
+            !PM_MCP_LEGACY_PROTOCOL_VERSIONS.includes(requestedVersion)) {
+            throw new PmMcpProtocolError("Unsupported legacy MCP protocol version", PM_MCP_ERROR_CODES.unsupportedProtocolVersion, {
+                supported: [...PM_MCP_LEGACY_PROTOCOL_VERSIONS],
+                requested: requestedVersion,
+                modern: PM_MCP_PROTOCOL_VERSION,
+            });
+        }
+        this.#clientInfo = this.#options.parseClientInfo(params?.clientInfo);
+        return {
+            protocolVersion: PM_MCP_LEGACY_PROTOCOL_VERSIONS[0],
+            capabilities: structuredClone(this.#options.capabilities),
+            serverInfo: { ...this.#options.serverInfo },
+            instructions: this.#options.instructions,
+        };
+    }
+    /** Dispatch one unversioned request through the finite legacy method set. */
+    async dispatch(request) {
+        if (request.method === "ping")
+            return {};
+        if (request.method === "tools/list")
+            return this.#options.listTools(request.params);
+        if (request.method === "tools/call") {
+            return this.#options.callTool(request.params, this.#clientInfo);
+        }
+        if (request.method === "resources/list")
+            return this.#options.listResources();
+        if (request.method === "resources/read") {
+            return this.#options.readResource(request.params);
+        }
+        if (request.method === "prompts/list")
+            return this.#options.listPrompts();
+        if (request.method === "prompts/get")
+            return this.#options.getPrompt(request.params);
+        throw new PmCliError(`Unsupported MCP method: ${request.method ?? "(missing)"}`, 64);
+    }
+}
+//# sourceMappingURL=legacy-adapter.js.map
+//# debugId=6a1d9bca-7dac-5537-9930-a12d8049c8b8

package/dist/mcp/server.d.ts

@@ -1,12 +1,22 @@
 #!/usr/bin/env node
+import { type AgentClientInfo } from "../sdk/runtime-primitives.js";
 import { readRequiredString, type PmActionInput } from "../sdk/runtime.js";
-interface JsonRpcRequest {
+import { PmMcpProtocolError, resolveMcpRequestContext, type PmMcpRequestContext } from "../sdk/mcp/protocol.js";
+import { PmMcpInputRequiredError } from "../sdk/mcp/interactions.js";
+import { type PmMcpSubscriptionId, type PmMcpSubscriptionSink } from "../sdk/mcp/subscriptions.js";
+/** JSON-RPC request shape accepted by pm MCP transport adapters. */
+export interface JsonRpcRequest {
+    /** JSON-RPC revision marker when supplied by the transport. */
     jsonrpc?: string;
+    /** Correlation identifier omitted only for notifications. */
     id?: string | number | null;
+    /** Protocol operation selected by the caller. */
     method?: string;
+    /** Operation inputs including request-local MCP metadata. */
     params?: Record<string, unknown>;
 }
 declare function runMcpAction(args: PmActionInput): Promise<unknown>;
+type PmMcpTransportSubscriptionKey = PmMcpSubscriptionId | symbol;
 declare function nearestDeclaredKey(unexpected: string, declared: string[]): string | undefined;
 declare function detectUnexpectedTopLevelKeys(toolName: string, args: Record<string, unknown>, toolDeclaredKeys?: Map<string, string[]>): string[];
 declare function collectMutationGuardWarnings(toolName: string, action: string | undefined, args: Record<string, unknown>): Promise<string[]>;
@@ -15,6 +25,26 @@ declare function resultContent(result: unknown, warnings?: string[], tokenAccoun
 declare function errorContent(error: unknown): Record<string, unknown>;
 /** Retain at most 32 own, valid provenance values without cloning unbounded input. */
 declare function boundMcpClientProvenance(value: unknown): Record<string, string>;
+declare function emitMcpChangeNotifications(action: string | undefined): Promise<void>;
+/** Open one modern subscription through a concrete transport-owned sink. */
+export declare function openMcpSubscription(input: {
+    request: JsonRpcRequest;
+    key?: PmMcpTransportSubscriptionKey;
+    sink: PmMcpSubscriptionSink;
+}): Promise<void>;
+/** Gracefully close one active subscription by its request identifier. */
+export declare function closeMcpSubscription(id: PmMcpSubscriptionId, key?: PmMcpTransportSubscriptionKey): Record<string, unknown> | undefined;
+declare function closeStdioMcpSubscriptions(): Array<{
+    id: PmMcpSubscriptionId;
+    result: Record<string, unknown>;
+}>;
+/** Resolve the current workspace-enriched tool schema for HTTP header checks. */
+export declare function resolveMcpToolSchemaForRequest(request: JsonRpcRequest): Promise<unknown>;
+/** Preserve MCP tool-result error semantics for non-protocol adapter failures. */
+export declare function buildMcpToolCallErrorResult(request: JsonRpcRequest, error: unknown): Record<string, unknown> | undefined;
+declare function mcpTaskPrincipal(requestContext: PmMcpRequestContext): string;
+declare function shouldCreateMcpTask(params: Record<string, unknown> | undefined, requestContext: PmMcpRequestContext): boolean;
+declare function settleMcpTaskExecution(taskId: string, execution: Promise<void>): Promise<void>;
 /** Dispatch one MCP request under supported process-level reproducibility settings. */
 export declare function handleRequest(request: JsonRpcRequest): Promise<Record<string, unknown> | undefined>;
 declare function writeError(id: JsonRpcRequest["id"], error: unknown): void;
@@ -27,24 +57,27 @@ export declare function isInvokedAsMcpMainModule(argvPath: string | undefined, m
 /** Public contract for test only, shared by SDK and presentation-layer consumers. */
 export declare const _testOnly: {
     boundMcpClientProvenance: typeof boundMcpClientProvenance;
+    createMcpInputRequiredError: (input: ConstructorParameters<typeof PmMcpInputRequiredError>[0]) => PmMcpInputRequiredError;
+    createMcpProtocolError: (message: string, code: number, data?: Record<string, unknown> | undefined) => PmMcpProtocolError;
     readonly closeManyOptionsFromFlat: typeof import("../sdk/runtime-input.js").closeManyOptionsFromFlat;
     detectUnexpectedOptionKeys: typeof detectUnexpectedOptionKeys;
     detectUnexpectedTopLevelKeys: typeof detectUnexpectedTopLevelKeys;
     collectMutationGuardWarnings: typeof collectMutationGuardWarnings;
+    closeStdioMcpSubscriptions: typeof closeStdioMcpSubscriptions;
     errorContent: typeof errorContent;
-    getMcpClientInfo: () => {
-        name: string;
-        version?: string;
-        model?: string;
-        session?: string;
-        provenance?: Readonly<Record<string, string | undefined>>;
-        episode?: import("../sdk/runtime-primitives.js").AgentEpisodeIdentity;
-    } | undefined;
+    emitMcpChangeNotifications: typeof emitMcpChangeNotifications;
+    expireMcpSubscriptionRecord: (id: PmMcpSubscriptionId, key?: PmMcpTransportSubscriptionKey) => Record<string, unknown> | undefined;
+    getMcpClientInfo: () => AgentClientInfo | undefined;
     readonly extensionOptionsFromArgs: typeof import("../sdk/runtime-input.js").extensionOptionsFromArgs;
     readonly globalOptions: typeof import("../sdk/runtime-input.js").actionGlobalOptions;
     readonly mutationListOptions: typeof import("../sdk/runtime-input.js").mutationListOptions;
     nearestDeclaredKey: typeof nearestDeclaredKey;
+    mcpTaskPrincipal: typeof mcpTaskPrincipal;
     resultContent: typeof resultContent;
+    resolveMcpRequestContext: typeof resolveMcpRequestContext;
+    shouldCreateMcpTask: typeof shouldCreateMcpTask;
+    settleMcpTaskExecution: typeof settleMcpTaskExecution;
+    subscriptionCount: () => number;
     readonly normalizeActionName: typeof import("../sdk/runtime-input.js").normalizeActionName;
     readonly normalizeCommandPath: typeof import("../sdk/runtime-input.js").normalizeCommandPath;
     readonly normalizeMcpOptionsArrays: typeof import("../sdk/runtime-input.js").normalizeMcpOptionsArrays;