@unbrained/pm-cli 2026.8.25 → 2026.8.27

package/dist/mcp/server.js

@@ -5,7 +5,7 @@
  * Runs the MCP server adapter that exposes pm actions and contracts to external agents.
  */
 
-!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]="8ce8addc-e47e-5bb9-8a94-0959a1a535e9")}catch(e){}}();
+!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]="77067047-62fc-54e8-9047-ad30580d6125")}catch(e){}}();
 import { realpathSync } from "node:fs";
 import { readFile } from "node:fs/promises";
 import path from "node:path";
@@ -22,7 +22,15 @@ import { isRuntimeRecord, markMcpMutationTransportInput, } from "../sdk/runtime-
 import { attachOutputTokenAccounting } from "../sdk/output-token-accounting.js";
 import { createReproducibleProcessRunner, runWithReproducibleProcessEnvironment, } from "../sdk/reproducibility/process.js";
 import { parseAtomicMutationControls, resolveItemMutationDocument, } from "../sdk/structured-mutations.js";
-import { resolveAuthor, resolvePmRoot } from "../sdk/runtime-primitives.js";
+import { resolveAuthor, resolvePmRoot, resolveWorkspaceRoot, } from "../sdk/runtime-primitives.js";
+import { PM_MCP_ERROR_CODES, PM_MCP_META_KEYS, PM_MCP_PROTOCOL_VERSION, PmMcpProtocolError, attachMcpServerInfo, buildMcpCompleteResult, buildMcpDiscoverResult, hasMcpClientExtension, isMcpRecord, resolveMcpRequestContext, } from "../sdk/mcp/protocol.js";
+import { PmMcpInputRequiredError, buildMcpInputRequiredResult, parseMcpInputResponses, validateMcpJsonSchema, withMcpCachePolicy, } from "../sdk/mcp/interactions.js";
+import { PM_MCP_TASKS_EXTENSION, createMcpTaskStore, } from "../sdk/mcp/tasks.js";
+import { PmMcpSubscriptionRegistry, } from "../sdk/mcp/subscriptions.js";
+import { extractMcpTraceContext, runWithMcpTraceContext, } from "../sdk/mcp/authorization.js";
+import { LegacyMcpAdapter } from "./legacy-adapter.js";
+import { PM_MCP_APP_CONTRACTS, PM_MCP_APP_MIME_TYPE, PM_MCP_APPS_EXTENSION, PM_MCP_APPS_SERVER_CAPABILITY, decoratePmMcpToolsWithApps, findPmMcpAppByUri, hasPmMcpAppsCapability, renderPmMcpAppHtml, } from "../sdk/mcp/apps.js";
+import { PM_MCP_SKILLS_EXTENSION, PM_MCP_SKILLS_SERVER_CAPABILITY, PmMcpSkillRegistry, assertPmMcpSkillsCapability, } from "../sdk/mcp/skills.js";
 function runMcpAction(args) {
     return runAction(markMcpMutationTransportInput(args));
 }
@@ -37,7 +45,68 @@ if (typeof process.env[PM_PACKAGE_ROOT_ENV] !== "string" ||
 // Reflect the real package.json version so agents/telemetry can identify the
 // build serving requests (was hard-coded "1.0.0"; see pm-2nvw).
 const PM_MCP_SERVER_VERSION = resolvePmCliVersion(import.meta.url, ["../.."]) ?? "0.0.0";
-let activeMcpClientInfo;
+const PM_MCP_SERVER_INFO = {
+    name: "pm-mcp",
+    version: PM_MCP_SERVER_VERSION,
+    description: "Stateless project-context management through pm SDK contracts.",
+    websiteUrl: "https://github.com/unbraind/pm-cli",
+};
+const PM_MCP_SERVER_CAPABILITIES = {
+    prompts: { listChanged: true },
+    resources: { listChanged: true, subscribe: true },
+    tools: { listChanged: true },
+    extensions: {
+        [PM_MCP_TASKS_EXTENSION]: {},
+        [PM_MCP_APPS_EXTENSION]: PM_MCP_APPS_SERVER_CAPABILITY,
+        [PM_MCP_SKILLS_EXTENSION]: PM_MCP_SKILLS_SERVER_CAPABILITY,
+    },
+};
+const PM_MCP_SUBSCRIPTIONS = new Map();
+function createMcpSubscriptionRegistry() {
+    return new PmMcpSubscriptionRegistry({
+        capabilities: PM_MCP_SERVER_CAPABILITIES,
+        serverInfo: PM_MCP_SERVER_INFO,
+    });
+}
+function pruneClosedMcpSubscriptionRegistries() {
+    for (const [key, subscription] of PM_MCP_SUBSCRIPTIONS) {
+        if (subscription.registry.size === 0)
+            PM_MCP_SUBSCRIPTIONS.delete(key);
+    }
+}
+const PM_MCP_CACHE_POLICIES = {
+    prompts: { ttlMs: 60_000, cacheScope: "public" },
+    resource: { ttlMs: 0, cacheScope: "private" },
+    resources: { ttlMs: 60_000, cacheScope: "public" },
+    tools: { ttlMs: 30_000, cacheScope: "private" },
+};
+const PM_MCP_DIRECT_TASK_TOOLS = new Set([
+    "pm_graph",
+    "pm_health",
+    "pm_validate",
+]);
+const PM_MCP_RUN_TASK_ACTIONS = new Set([
+    "graph",
+    "health",
+    "import",
+    "reindex",
+    "test-all",
+    "validate",
+]);
+const PM_MCP_SKILL_METHODS = new Set([
+    "skills/list",
+    "skills/get",
+    "resources/directory/read",
+]);
+const PM_MCP_INSTRUCTIONS = "You have access to native pm CLI tools for git-based project management. " +
+    "Use pm_next to pick the next actionable item, or pm_context or pm_search before creating new work. " +
+    "Prefer narrow tools (pm_next, pm_context, pm_list, pm_get, pm_search, pm_events, pm_create, pm_mutate, pm_copy, pm_focus, pm_update, pm_append, pm_claim, pm_release, pm_close, pm_comments, pm_files, pm_docs, pm_notes, pm_learnings, pm_deps, pm_graph, pm_test, pm_validate, pm_health, pm_contracts, pm_schema, pm_profile, pm_config, pm_plan) over pm_run when they cover the operation. " +
+    "Use pm_plan for agent harness Plan workflows: it provides Codex/Claude/Cursor-style planning with durable steps, dependencies, decisions, discoveries, validation, and materialization. " +
+    "Use pm_schema and pm_config for workspace configuration: pm_schema manages custom item types/statuses and pm_config reads or writes settings keys. " +
+    "Use pm_run with an explicit action for active package-owned operations, plus activity, aggregate, history, stats, test-all, and gc. " +
+    "Use history-redact for audited history-stream redaction workflows, history-repair to re-anchor a drifted history chain, and history-compact to checkpoint/prune long history streams while preserving replay integrity. " +
+    "Agent harness and model provenance are detected automatically; pass author only for an intentional identity override. " +
+    "Do not pass path during real repository tracking — only pass path for sandbox or test runs.";
 // Tool definitions (TOOLS) live in ./tool-definitions.ts so the `pm contracts`
 // golden-file snapshot can import the surface without loading the server
 // runtime (pm-4os2). This file owns dispatch, normalization, and transport.
@@ -75,6 +144,7 @@ function nearestDeclaredKey(unexpected, declared) {
 // accept arbitrary top-level keys (see extensionOptionsFromArgs), so unexpected
 // keys there are by-design rather than typos and must not be flagged.
 const UNEXPECTED_KEY_WARNING_EXEMPT_TOOLS = new Set(["pm_run"]);
+const MCP_RETRY_ARGUMENT_KEYS = new Set(["inputResponses", "requestState"]);
 function detectUnexpectedTopLevelKeys(toolName, args, toolDeclaredKeys = declaredToolKeys()) {
     if (typeof args !== "object" || args === null || Array.isArray(args)) {
         return [];
@@ -86,7 +156,7 @@ function detectUnexpectedTopLevelKeys(toolName, args, toolDeclaredKeys = declare
     if (declared === undefined) {
         return [];
     }
-    const declaredSet = new Set(declared);
+    const declaredSet = new Set([...declared, ...MCP_RETRY_ARGUMENT_KEYS]);
     const warnings = [];
     for (const key of Object.keys(args)) {
         if (declaredSet.has(key)) {
@@ -265,10 +335,8 @@ function boundMcpClientProvenance(value) {
     }
     return bounded;
 }
-function readMcpClientInfo(params) {
-    const clientInfo = isRuntimeRecord(params?.clientInfo)
-        ? params.clientInfo
-        : {};
+function readMcpClientInfo(value) {
+    const clientInfo = isRuntimeRecord(value) ? value : {};
     const clientName = typeof clientInfo.name === "string" ? clientInfo.name.trim() : "";
     if (clientName.length === 0)
         return undefined;
@@ -292,11 +360,20 @@ function readMcpClientInfo(params) {
         result.episode = episode;
     return result;
 }
-async function handleToolCall(paramsInput) {
+async function emitMcpChangeNotifications(action) {
+    if (isMutationAction(action ?? "")) {
+        await Promise.all([...PM_MCP_SUBSCRIPTIONS.values()].flatMap(({ registry }) => PM_MCP_RESOURCE_CONTRACTS.map((resource) => registry.emitResourceUpdated(resource.uri))));
+    }
+    if (["extension", "install", "package", "uninstall"].includes(action ?? "")) {
+        await Promise.all([...PM_MCP_SUBSCRIPTIONS.values()].map(({ registry }) => registry.emitListChanged("tools")));
+    }
+    pruneClosedMcpSubscriptionRegistries();
+}
+async function handleToolCall(paramsInput, clientInfo) {
     return runWithHarnessDetectionSignals({
         env: process.env,
         argv: process.argv,
-        ...(activeMcpClientInfo ? { client_info: activeMcpClientInfo } : {}),
+        ...(clientInfo ? { client_info: clientInfo } : {}),
     }, async () => {
         const params = asRecordClone(paramsInput);
         const name = readRequiredString(params, "name");
@@ -306,7 +383,16 @@ async function handleToolCall(paramsInput) {
         if (!handler) {
             throw new PmCliError(`Unknown pm MCP tool: ${name}`, 64);
         }
-        const requestedArgs = decodeHtmlEntitiesInOptions(asRecordClone(params.arguments));
+        const inputResponses = params.inputResponses === undefined
+            ? undefined
+            : parseMcpInputResponses(params.inputResponses);
+        const requestedArgs = {
+            ...decodeHtmlEntitiesInOptions(asRecordClone(params.arguments)),
+            ...(inputResponses ? { inputResponses } : {}),
+            ...(typeof params.requestState === "string"
+                ? { requestState: params.requestState }
+                : {}),
+        };
         const access = await resolveMcpToolAccess(TOOLS, name, requestedArgs);
         if (!access.available) {
             throw new PmCliError(`pm MCP tool "${name}" is unavailable in the ${access.profile} profile.`, 64);
@@ -339,10 +425,70 @@ async function handleToolCall(paramsInput) {
             // cwd is applied inside the serialized activation cycle (see withActiveExtensions),
             // so the chdir/restore is exclusive per request and cannot race a concurrent caller.
             const result = await handler(args);
+            void emitMcpChangeNotifications(action);
             return resultContent(result, warnings, args.tokenAccounting === true);
         }, { probesEnabled: workspaceIdentity?.probes_enabled });
     });
 }
+/** Open one modern subscription through a concrete transport-owned sink. */
+export async function openMcpSubscription(input) {
+    if ((typeof input.request.id !== "string" &&
+        typeof input.request.id !== "number") ||
+        input.request.method !== "subscriptions/listen") {
+        throw new PmMcpProtocolError("Invalid MCP subscriptions/listen request", PM_MCP_ERROR_CODES.invalidParams, { required: ["id", "method", "params.notifications"] });
+    }
+    resolveMcpRequestContext(input.request.params);
+    const key = input.key ?? input.request.id;
+    if (PM_MCP_SUBSCRIPTIONS.has(key)) {
+        throw new PmMcpProtocolError("MCP subscription id is already active", PM_MCP_ERROR_CODES.invalidParams, { subscriptionId: input.request.id });
+    }
+    const registry = createMcpSubscriptionRegistry();
+    await registry.open({
+        id: input.request.id,
+        notifications: input.request.params?.notifications,
+        sink: input.sink,
+    });
+    PM_MCP_SUBSCRIPTIONS.set(key, { id: input.request.id, registry });
+}
+/** Gracefully close one active subscription by its request identifier. */
+export function closeMcpSubscription(id, key = id) {
+    const subscription = PM_MCP_SUBSCRIPTIONS.get(key);
+    if (!subscription || subscription.id !== id)
+        return undefined;
+    PM_MCP_SUBSCRIPTIONS.delete(key);
+    return subscription.registry.close(id);
+}
+function closeStdioMcpSubscriptions() {
+    const closed = [];
+    for (const [key, subscription] of PM_MCP_SUBSCRIPTIONS) {
+        if (key !== subscription.id)
+            continue;
+        const result = closeMcpSubscription(subscription.id, key);
+        if (result)
+            closed.push({ id: subscription.id, result });
+    }
+    return closed;
+}
+/** Resolve the current workspace-enriched tool schema for HTTP header checks. */
+export async function resolveMcpToolSchemaForRequest(request) {
+    if (request.method !== "tools/call")
+        return undefined;
+    const name = request.params?.name;
+    if (typeof name !== "string")
+        return undefined;
+    const surface = await resolveMcpToolSurface(TOOLS, requestWorkspaceArgs(request.params));
+    return surface.tools.find((tool) => tool.name === name)?.inputSchema;
+}
+/** Preserve MCP tool-result error semantics for non-protocol adapter failures. */
+export function buildMcpToolCallErrorResult(request, error) {
+    if (request.method !== "tools/call" || error instanceof PmMcpProtocolError) {
+        return undefined;
+    }
+    const content = errorContent(error);
+    return hasMcpProtocolVersionMetadata(request)
+        ? buildMcpCompleteResult(content, PM_MCP_SERVER_INFO)
+        : content;
+}
 function requestWorkspaceArgs(params) {
     const paramsRecord = asRecordClone(params);
     return asRecordClone(paramsRecord.arguments ?? paramsRecord);
@@ -389,6 +535,16 @@ async function readWorkspaceResource(uri, params) {
         ],
     };
 }
+async function loadRequestSkillRegistry(params) {
+    const args = requestWorkspaceArgs(params);
+    const cwd = typeof args.cwd === "string" ? args.cwd : process.cwd();
+    const workspaceRoot = resolveWorkspaceRoot(resolvePmRoot(cwd, typeof args.path === "string" ? args.path : undefined));
+    return PmMcpSkillRegistry.load({
+        packageRoot: resolvePmPackageRoot(),
+        workspaceRoot,
+        packageVersion: PM_MCP_SERVER_VERSION,
+    });
+}
 function renderWorkflowPrompt(params) {
     const paramsRecord = asRecordClone(params);
     const name = readRequiredString(paramsRecord, "name");
@@ -411,62 +567,367 @@ function renderWorkflowPrompt(params) {
         messages: [{ role: "user", content: { type: "text", text } }],
     };
 }
-/** Implements handle request for the public runtime surface of this module. */
-async function handleRequestInReproducibleContext(request) {
-    if (!request.id && request.method?.startsWith("notifications/")) {
-        return undefined;
+const LEGACY_MCP_ADAPTER = new LegacyMcpAdapter({
+    serverInfo: PM_MCP_SERVER_INFO,
+    capabilities: PM_MCP_SERVER_CAPABILITIES,
+    instructions: PM_MCP_INSTRUCTIONS,
+    parseClientInfo: readMcpClientInfo,
+    listTools: async (params) => ({
+        tools: (await resolveMcpToolSurface(TOOLS, requestWorkspaceArgs(params)))
+            .tools,
+    }),
+    callTool: handleToolCall,
+    listResources: () => ({ resources: PM_MCP_RESOURCE_CONTRACTS }),
+    readResource: (params) => readWorkspaceResource(readRequiredString(asRecordClone(params), "uri"), params),
+    listPrompts: () => ({
+        prompts: PM_MCP_PROMPT_CONTRACTS.map((prompt) => ({
+            name: prompt.name,
+            description: prompt.description,
+            arguments: prompt.arguments,
+        })),
+    }),
+    getPrompt: renderWorkflowPrompt,
+});
+function deterministicMcpTools(tools) {
+    return tools
+        .map((tool) => ({
+        ...tool,
+        inputSchema: validateMcpJsonSchema(tool.inputSchema),
+    }))
+        .sort((left, right) => left.name.localeCompare(right.name));
+}
+function mcpTaskPrincipal(requestContext) {
+    return requestContext.clientInfo
+        ? `${requestContext.clientInfo.name}@${requestContext.clientInfo.version}`
+        : "anonymous-stdio";
+}
+function mcpTaskStore() {
+    return createMcpTaskStore({
+        pmRoot: resolvePmRoot(process.cwd()),
+        owner: "pm-mcp-task-provider",
+    });
+}
+function shouldCreateMcpTask(params, requestContext) {
+    if (!hasMcpClientExtension(requestContext, PM_MCP_TASKS_EXTENSION)) {
+        return false;
     }
-    if (request.method === "ping") {
-        return {};
+    const requestParams = asRecordClone(params);
+    const name = requestParams.name;
+    const args = asRecordClone(requestParams.arguments);
+    if (PM_MCP_DIRECT_TASK_TOOLS.has(name))
+        return true;
+    if (name === "pm_test" &&
+        (args.subcommand === "run" ||
+            (isMcpRecord(args.options) && args.options.subcommand === "run"))) {
+        return true;
     }
-    if (request.method === "initialize") {
-        activeMcpClientInfo = readMcpClientInfo(request.params);
-        return {
-            protocolVersion: "2025-06-18",
-            capabilities: {
-                tools: { listChanged: true },
-                resources: { listChanged: true },
-                prompts: { listChanged: true },
+    if (name !== "pm_run")
+        return false;
+    return (typeof args.action === "string" && PM_MCP_RUN_TASK_ACTIONS.has(args.action));
+}
+const PENDING_MCP_TASKS = new Map();
+async function executeMcpTask(execution, inputResponses) {
+    const params = {
+        ...execution.params,
+        ...(inputResponses ? { inputResponses } : {}),
+        ...(execution.requestState ? { requestState: execution.requestState } : {}),
+    };
+    try {
+        const result = await handleToolCall(params, execution.context.clientInfo);
+        await execution.store.complete(execution.taskId, execution.principal, buildMcpCompleteResult(result, PM_MCP_SERVER_INFO));
+        PENDING_MCP_TASKS.delete(execution.taskId);
+    }
+    catch (error) {
+        if (error instanceof PmMcpInputRequiredError) {
+            execution.requestState = error.requestState;
+            await execution.store.requireInput({
+                taskId: execution.taskId,
+                principal: execution.principal,
+                requestContext: execution.context,
+                inputRequests: error.inputRequests,
+                statusMessage: "Task requires additional client input.",
+            });
+            return;
+        }
+        if (error instanceof PmMcpProtocolError) {
+            await execution.store.fail(execution.taskId, execution.principal, {
+                code: error.code,
+                message: error.message,
+                data: error.data,
+            });
+        }
+        else {
+            await execution.store.complete(execution.taskId, execution.principal, buildMcpCompleteResult(errorContent(error), PM_MCP_SERVER_INFO));
+        }
+        PENDING_MCP_TASKS.delete(execution.taskId);
+    }
+}
+async function settleMcpTaskExecution(taskId, execution) {
+    try {
+        await execution;
+    }
+    catch {
+        // Persistence failures can outlive the request that created the detached
+        // execution. Keep them from becoming process-level unhandled rejections;
+        // the durable task record remains available for TTL-based recovery.
+        PENDING_MCP_TASKS.delete(taskId);
+    }
+}
+function scheduleMcpTaskExecution(execution, inputResponses) {
+    void settleMcpTaskExecution(execution.taskId, executeMcpTask(execution, inputResponses));
+}
+async function createMcpTaskForToolCall(params, requestContext) {
+    const store = mcpTaskStore();
+    const principal = mcpTaskPrincipal(requestContext);
+    const task = await store.create({
+        principal,
+        statusMessage: "pm operation accepted for asynchronous execution.",
+    });
+    const execution = {
+        context: requestContext,
+        params: asRecordClone(params),
+        principal,
+        store,
+        taskId: task.taskId,
+    };
+    PENDING_MCP_TASKS.set(task.taskId, execution);
+    scheduleMcpTaskExecution(execution);
+    return attachMcpServerInfo(task, PM_MCP_SERVER_INFO);
+}
+async function dispatchMcpTaskMethod(request, requestContext) {
+    if (!hasMcpClientExtension(requestContext, PM_MCP_TASKS_EXTENSION)) {
+        throw new PmMcpProtocolError("Missing required client capability", PM_MCP_ERROR_CODES.missingRequiredClientCapability, {
+            requiredCapabilities: {
+                extensions: { [PM_MCP_TASKS_EXTENSION]: {} },
             },
-            serverInfo: { name: "pm-mcp", version: PM_MCP_SERVER_VERSION },
-            instructions: "You have access to native pm CLI tools for git-based project management. " +
-                "Use pm_next to pick the next actionable item, or pm_context or pm_search before creating new work. " +
-                "Prefer narrow tools (pm_next, pm_context, pm_list, pm_get, pm_search, pm_events, pm_create, pm_mutate, pm_copy, pm_focus, pm_update, pm_append, pm_claim, pm_release, pm_close, pm_comments, pm_files, pm_docs, pm_notes, pm_learnings, pm_deps, pm_graph, pm_test, pm_validate, pm_health, pm_contracts, pm_schema, pm_profile, pm_config, pm_plan) over pm_run when they cover the operation. " +
-                "Use pm_plan for agent harness Plan workflows: it provides Codex/Claude/Cursor-style planning with durable steps, dependencies, decisions, discoveries, validation, and materialization. " +
-                "Use pm_schema and pm_config for workspace configuration: pm_schema manages custom item types/statuses and pm_config reads or writes settings keys. " +
-                "Use pm_run with an explicit action for active package-owned operations, plus activity, aggregate, history, stats, test-all, and gc. " +
-                "Use history-redact for audited history-stream redaction workflows, history-repair to re-anchor a drifted history chain, and history-compact to checkpoint/prune long history streams while preserving replay integrity. " +
-                "Agent harness and model provenance are detected automatically; pass author only for an intentional identity override. " +
-                "Do not pass path during real repository tracking — only pass path for sandbox or test runs.",
-        };
+        });
     }
+    const params = asRecordClone(request.params);
+    const taskId = readRequiredString(params, "taskId");
+    const principal = mcpTaskPrincipal(requestContext);
+    const store = mcpTaskStore();
+    if (request.method === "tasks/get") {
+        return buildMcpCompleteResult(await store.get(taskId, principal), PM_MCP_SERVER_INFO);
+    }
+    if (request.method === "tasks/update") {
+        const update = await store.update(taskId, principal, params.inputResponses);
+        const execution = PENDING_MCP_TASKS.get(taskId);
+        if (execution &&
+            update.acceptedKeys.length > 0 &&
+            update.remainingKeys.length === 0) {
+            scheduleMcpTaskExecution(execution, await store.takeInputResponses(taskId, principal));
+        }
+        return buildMcpCompleteResult({}, PM_MCP_SERVER_INFO);
+    }
+    await store.cancel(taskId, principal);
+    PENDING_MCP_TASKS.delete(taskId);
+    return buildMcpCompleteResult({}, PM_MCP_SERVER_INFO);
+}
+async function dispatchModernToolMethod(request, requestContext, clientInfo) {
     if (request.method === "tools/list") {
-        return {
-            tools: (await resolveMcpToolSurface(TOOLS, requestWorkspaceArgs(request.params))).tools,
-        };
+        const surface = await resolveMcpToolSurface(TOOLS, requestWorkspaceArgs(request.params));
+        return buildMcpCompleteResult(withMcpCachePolicy({
+            tools: hasCompatiblePmMcpAppsCapability(requestContext)
+                ? decoratePmMcpToolsWithApps(deterministicMcpTools(surface.tools))
+                : deterministicMcpTools(surface.tools),
+        }, PM_MCP_CACHE_POLICIES.tools), PM_MCP_SERVER_INFO);
+    }
+    if (shouldCreateMcpTask(request.params, requestContext)) {
+        return createMcpTaskForToolCall(request.params, requestContext);
+    }
+    try {
+        return buildMcpCompleteResult(await handleToolCall(request.params, clientInfo), PM_MCP_SERVER_INFO);
     }
-    if (request.method === "tools/call") {
-        return handleToolCall(request.params);
+    catch (error) {
+        if (!(error instanceof PmMcpInputRequiredError))
+            throw error;
+        return buildMcpInputRequiredResult({
+            requestContext,
+            serverInfo: PM_MCP_SERVER_INFO,
+            inputRequests: error.inputRequests,
+            requestState: error.requestState,
+        });
     }
+}
+async function dispatchModernResourceMethod(request, requestContext) {
     if (request.method === "resources/list") {
-        return { resources: PM_MCP_RESOURCE_CONTRACTS };
+        const resources = [
+            ...PM_MCP_RESOURCE_CONTRACTS,
+            ...(hasCompatiblePmMcpAppsCapability(requestContext)
+                ? PM_MCP_APP_CONTRACTS.map((contract) => ({
+                    uri: contract.uri,
+                    name: contract.name,
+                    description: contract.description,
+                    mimeType: PM_MCP_APP_MIME_TYPE,
+                    _meta: { ui: contract.resourceMeta },
+                }))
+                : []),
+        ].sort((left, right) => left.uri.localeCompare(right.uri));
+        return buildMcpCompleteResult(withMcpCachePolicy({ resources }, PM_MCP_CACHE_POLICIES.resources), PM_MCP_SERVER_INFO);
     }
-    if (request.method === "resources/read") {
-        return readWorkspaceResource(readRequiredString(asRecordClone(request.params), "uri"), request.params);
+    if (request.method === "resources/templates/list") {
+        return buildMcpCompleteResult(withMcpCachePolicy({ resourceTemplates: [] }, PM_MCP_CACHE_POLICIES.resources), PM_MCP_SERVER_INFO);
     }
-    if (request.method === "prompts/list") {
-        return {
+    try {
+        const uri = readRequiredString(asRecordClone(request.params), "uri");
+        const app = findPmMcpAppByUri(uri);
+        let resource;
+        if (app) {
+            if (!hasPmMcpAppsCapability(requestContext)) {
+                throw new PmMcpProtocolError("MCP App resource requires negotiated client capability", PM_MCP_ERROR_CODES.missingRequiredClientCapability, {
+                    requiredCapabilities: {
+                        extensions: {
+                            [PM_MCP_APPS_EXTENSION]: PM_MCP_APPS_SERVER_CAPABILITY,
+                        },
+                    },
+                });
+            }
+            resource = {
+                contents: [
+                    {
+                        uri,
+                        mimeType: PM_MCP_APP_MIME_TYPE,
+                        text: renderPmMcpAppHtml(app),
+                        _meta: { ui: app.resourceMeta },
+                    },
+                ],
+            };
+        }
+        else if (uri.startsWith("skill://")) {
+            assertPmMcpSkillsCapability(requestContext);
+            resource = {
+                ...(await loadRequestSkillRegistry(request.params)).read(uri),
+            };
+        }
+        else {
+            resource = await readWorkspaceResource(uri, request.params);
+        }
+        return buildMcpCompleteResult(withMcpCachePolicy(resource, PM_MCP_CACHE_POLICIES.resource), PM_MCP_SERVER_INFO);
+    }
+    catch (error) {
+        if (!(error instanceof PmCliError) ||
+            !error.message.startsWith("Unknown pm MCP resource:")) {
+            throw error;
+        }
+        throw new PmMcpProtocolError(error.message, PM_MCP_ERROR_CODES.invalidParams, { field: "uri" });
+    }
+}
+/** Treat an incompatible optional Apps declaration as absent during discovery. */
+function hasCompatiblePmMcpAppsCapability(requestContext) {
+    try {
+        return hasPmMcpAppsCapability(requestContext);
+    }
+    catch (error) {
+        if (error instanceof PmMcpProtocolError)
+            return false;
+        throw error;
+    }
+}
+/** Validate Skills pagination inputs before handing them to the SDK registry. */
+function readSkillPageOptions(params) {
+    if (params.cursor !== undefined && typeof params.cursor !== "string") {
+        throw new PmMcpProtocolError("Skills cursor must be a string", PM_MCP_ERROR_CODES.invalidParams, { field: "cursor" });
+    }
+    if (params.limit !== undefined && typeof params.limit !== "number") {
+        throw new PmMcpProtocolError("Skills limit must be a number", PM_MCP_ERROR_CODES.invalidParams, { field: "limit" });
+    }
+    return {
+        ...(typeof params.cursor === "string" ? { cursor: params.cursor } : {}),
+        ...(typeof params.limit === "number" ? { limit: params.limit } : {}),
+    };
+}
+async function dispatchModernSkillMethod(request, requestContext) {
+    const directoryRead = request.method === "resources/directory/read";
+    assertPmMcpSkillsCapability(requestContext, directoryRead);
+    const params = asRecordClone(request.params);
+    const registry = await loadRequestSkillRegistry(request.params);
+    let result;
+    if (request.method === "skills/list") {
+        result = { ...registry.list(readSkillPageOptions(params)) };
+    }
+    else if (request.method === "skills/get") {
+        result = { skill: registry.get(readRequiredString(params, "uri")) };
+    }
+    else {
+        result = {
+            ...registry.readDirectory(readRequiredString(params, "uri"), readSkillPageOptions(params)),
+        };
+    }
+    return buildMcpCompleteResult(withMcpCachePolicy(result, PM_MCP_CACHE_POLICIES.resource), PM_MCP_SERVER_INFO);
+}
+function dispatchModernPromptMethod(request) {
+    const result = request.method === "prompts/list"
+        ? withMcpCachePolicy({
             prompts: PM_MCP_PROMPT_CONTRACTS.map((prompt) => ({
                 name: prompt.name,
                 description: prompt.description,
                 arguments: prompt.arguments,
-            })),
-        };
+            })).sort((left, right) => left.name.localeCompare(right.name)),
+        }, PM_MCP_CACHE_POLICIES.prompts)
+        : renderWorkflowPrompt(request.params);
+    return buildMcpCompleteResult(result, PM_MCP_SERVER_INFO);
+}
+/** Dispatch one validated stateless request through the modern surface. */
+async function dispatchModernMcpRequest(request, meta) {
+    const requestContext = resolveMcpRequestContext(request.params);
+    const clientInfo = readMcpClientInfo(meta[PM_MCP_META_KEYS.clientInfo]);
+    if (request.method === "server/discover") {
+        return buildMcpDiscoverResult({
+            serverInfo: PM_MCP_SERVER_INFO,
+            capabilities: PM_MCP_SERVER_CAPABILITIES,
+            instructions: PM_MCP_INSTRUCTIONS,
+        });
+    }
+    if (request.method === "ping") {
+        // The preceding match is an mcp-deprecation-negative-control for modern callers.
+        throw new PmMcpProtocolError("MCP method not found: ping", -32601, {
+            removedIn: PM_MCP_PROTOCOL_VERSION,
+        });
+    }
+    if (PM_MCP_SKILL_METHODS.has(request.method ?? "")) {
+        return dispatchModernSkillMethod(request, requestContext);
+    }
+    if (request.method === "tasks/get" ||
+        request.method === "tasks/update" ||
+        request.method === "tasks/cancel") {
+        return dispatchMcpTaskMethod(request, requestContext);
+    }
+    if (request.method === "tools/list" || request.method === "tools/call") {
+        return dispatchModernToolMethod(request, requestContext, clientInfo);
+    }
+    if (request.method === "resources/list" ||
+        request.method === "resources/templates/list" ||
+        request.method === "resources/read") {
+        return dispatchModernResourceMethod(request, requestContext);
     }
-    if (request.method === "prompts/get") {
-        return renderWorkflowPrompt(request.params);
+    if (request.method === "prompts/list" || request.method === "prompts/get") {
+        return dispatchModernPromptMethod(request);
+    }
+    throw new PmMcpProtocolError(`MCP method not found: ${request.method ?? "(missing)"}`, -32601);
+}
+/** Implements handle request for the public runtime surface of this module. */
+async function handleRequestInReproducibleContext(request) {
+    if (!request.id && request.method?.startsWith("notifications/")) {
+        return undefined;
+    }
+    if (hasMcpProtocolVersionMetadata(request)) {
+        const allowlist = (process.env.PM_MCP_BAGGAGE_ALLOWLIST ?? "")
+            .split(",")
+            .map((entry) => entry.trim())
+            .filter(Boolean);
+        return runWithMcpTraceContext(extractMcpTraceContext(request.params, { baggageAllowlist: allowlist }), () => dispatchModernMcpRequest(request, request.params._meta));
+    }
+    if (request.method === "initialize") {
+        // The preceding match is an mcp-legacy-boundary delegated to the isolated adapter.
+        return LEGACY_MCP_ADAPTER.initialize(request.params);
     }
-    throw new PmCliError(`Unsupported MCP method: ${request.method ?? "(missing)"}`, 64);
+    return LEGACY_MCP_ADAPTER.dispatch(request);
+}
+/** Return whether a request explicitly supplies the modern version metadata key. */
+function hasMcpProtocolVersionMetadata(request) {
+    const meta = isMcpRecord(request.params) ? request.params._meta : undefined;
+    return (isMcpRecord(meta) &&
+        Object.prototype.hasOwnProperty.call(meta, PM_MCP_META_KEYS.protocolVersion));
 }
 /** Dispatch one MCP request under supported process-level reproducibility settings. */
 export async function handleRequest(request) {
@@ -476,11 +937,47 @@ function writeResponse(id, payload) {
     process.stdout.write(`${JSON.stringify({ jsonrpc: "2.0", id, result: payload })}\n`);
 }
 function writeError(id, error) {
-    const code = error instanceof PmCliError ? error.exitCode : -32603;
+    const code = error instanceof PmMcpProtocolError
+        ? error.code
+        : error instanceof PmCliError
+            ? error.exitCode
+            : -32603;
     const message = error instanceof Error ? error.message : String(error);
-    const data = error instanceof PmCliError ? error.context : undefined;
+    const data = error instanceof PmMcpProtocolError
+        ? error.data
+        : error instanceof PmCliError
+            ? error.context
+            : undefined;
     process.stdout.write(`${JSON.stringify({ jsonrpc: "2.0", id, error: { code, message, data } })}\n`);
 }
+/** Write an MCP tool execution failure as a successful tool result envelope. */
+function writeToolCallErrorResponse(request, error) {
+    if (request.method !== "tools/call" || error instanceof PmMcpProtocolError) {
+        return false;
+    }
+    writeResponse(request.id, buildMcpToolCallErrorResult(request, error));
+    return true;
+}
+async function handleStdioTransportControl(request) {
+    if (request.method === "subscriptions/listen") {
+        await openMcpSubscription({
+            request,
+            sink: (notification) => {
+                process.stdout.write(`${JSON.stringify(notification)}\n`);
+            },
+        });
+        return true;
+    }
+    if (request.method !== "notifications/cancelled")
+        return false;
+    const requestId = request.params?.requestId;
+    if (typeof requestId === "string" || typeof requestId === "number") {
+        const result = closeMcpSubscription(requestId);
+        if (result)
+            writeResponse(requestId, result);
+    }
+    return true;
+}
 // pm-3puw: parse one JSON-RPC line, dispatch it, and write the response. Kept
 // as a standalone async unit so the stdio loop can enqueue it onto a serial
 // queue (process lines in arrival order) and tests can drive it directly.
@@ -506,6 +1003,8 @@ async function processRpcLineWithHandler(line, requestHandler) {
     }
     const shouldRespond = Object.prototype.hasOwnProperty.call(request, "id");
     try {
+        if (await handleStdioTransportControl(request))
+            return;
         const result = await requestHandler(request);
         if (shouldRespond && result !== undefined) {
             writeResponse(request.id, result);
@@ -515,10 +1014,7 @@ async function processRpcLineWithHandler(line, requestHandler) {
         if (!shouldRespond) {
             return;
         }
-        if (request.method === "tools/call") {
-            writeResponse(request.id, errorContent(error));
-        }
-        else {
+        if (!writeToolCallErrorResponse(request, error)) {
             writeError(request.id, error);
         }
     }
@@ -551,6 +1047,13 @@ export function startMcpServer() {
     rl.on("line", (line) => {
         void queue.enqueue(() => processLine(line));
     });
+    rl.on("close", () => {
+        void queue.enqueue(() => {
+            for (const closed of closeStdioMcpSubscriptions()) {
+                writeResponse(closed.id, closed.result);
+            }
+        });
+    });
 }
 // npm bin entries are symlinks (node_modules/.bin/pm-mcp -> dist/mcp/server.js),
 // so argv[1] must be realpath-resolved before comparing against this module's
@@ -582,14 +1085,19 @@ function readRuntimeTestHook(key) {
 /** Public contract for test only, shared by SDK and presentation-layer consumers. */
 export const _testOnly = {
     boundMcpClientProvenance,
+    createMcpInputRequiredError: (input) => new PmMcpInputRequiredError(input),
+    createMcpProtocolError: (...input) => new PmMcpProtocolError(...input),
     get closeManyOptionsFromFlat() {
         return readRuntimeTestHook("closeManyOptionsFromFlat");
     },
     detectUnexpectedOptionKeys,
     detectUnexpectedTopLevelKeys,
     collectMutationGuardWarnings,
+    closeStdioMcpSubscriptions,
     errorContent,
-    getMcpClientInfo: () => activeMcpClientInfo ? { ...activeMcpClientInfo } : undefined,
+    emitMcpChangeNotifications,
+    expireMcpSubscriptionRecord: (id, key = id) => PM_MCP_SUBSCRIPTIONS.get(key).registry.close(id),
+    getMcpClientInfo: () => LEGACY_MCP_ADAPTER.getClientInfo(),
     get extensionOptionsFromArgs() {
         return readRuntimeTestHook("extensionOptionsFromArgs");
     },
@@ -600,7 +1108,12 @@ export const _testOnly = {
         return readRuntimeTestHook("mutationListOptions");
     },
     nearestDeclaredKey,
+    mcpTaskPrincipal,
     resultContent,
+    resolveMcpRequestContext,
+    shouldCreateMcpTask,
+    settleMcpTaskExecution,
+    subscriptionCount: () => PM_MCP_SUBSCRIPTIONS.size,
     get normalizeActionName() {
         return readRuntimeTestHook("normalizeActionName");
     },
@@ -649,4 +1162,4 @@ if (isInvokedAsMcpMainModule(process.argv[1], import.meta.url)) {
 }
 /* c8 ignore stop */
 //# sourceMappingURL=server.js.map
-//# debugId=8ce8addc-e47e-5bb9-8a94-0959a1a535e9
+//# debugId=77067047-62fc-54e8-9047-ad30580d6125