@unbrained/pm-cli 2026.8.25 → 2026.8.27

package/dist/sdk/mcp/interactions.js

@@ -0,0 +1,337 @@
+/**
+ * @module sdk/mcp/interactions
+ *
+ * Implements bounded MCP 2026-07-28 multi round-trip request, cache, and JSON
+ * Schema contracts without coupling protocol policy to a transport adapter.
+ */
+
+!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]="469f704b-12eb-524d-bcc8-fb8f9f1775f2")}catch(e){}}();
+import { createHash, createHmac, timingSafeEqual } from "node:crypto";
+import { PM_MCP_ERROR_CODES, PM_MCP_META_KEYS, PmMcpProtocolError, isMcpRecord, } from "./protocol.js";
+/** Methods permitted inside a 2026-07-28 MRTR input request map. */
+export const PM_MCP_INPUT_REQUEST_METHODS = [
+    "elicitation/create",
+    "roots/list",
+    "sampling/createMessage",
+];
+/**
+ * Transport-neutral control signal used by SDK handlers to request an MRTR
+ * response without constructing or serializing JSON-RPC in domain code.
+ */
+export class PmMcpInputRequiredError extends Error {
+    /** Server-authored input requests validated by the adapter. */
+    inputRequests;
+    /** Optional opaque continuation state echoed on retry. */
+    requestState;
+    /** Create an input-required control signal. */
+    constructor(input) {
+        super("MCP operation requires additional input");
+        this.name = "PmMcpInputRequiredError";
+        this.inputRequests = input.inputRequests;
+        this.requestState = input.requestState;
+    }
+}
+const INPUT_KEY_PATTERN = /^[a-zA-Z][a-zA-Z0-9_.-]{0,63}$/u;
+const MAX_INPUT_REQUESTS = 32;
+const MAX_INPUT_PAYLOAD_BYTES = 64 * 1024;
+const MAX_REQUEST_STATE_BYTES = 16 * 1024;
+const DEFAULT_SCHEMA_BOUNDS = {
+    maxBytes: 256 * 1024,
+    maxDepth: 32,
+    maxNodes: 4096,
+};
+function inputCapability(method) {
+    if (method === "elicitation/create")
+        return "elicitation";
+    if (method === "sampling/createMessage")
+        return "sampling";
+    return "roots";
+}
+function assertBoundedJson(value, maximumBytes, field) {
+    let serialized;
+    try {
+        serialized = JSON.stringify(value);
+    }
+    catch {
+        throw new PmMcpProtocolError(`Invalid ${field}: value is not JSON serializable`, PM_MCP_ERROR_CODES.invalidParams, { field });
+    }
+    if (Buffer.byteLength(serialized, "utf8") > maximumBytes) {
+        throw new PmMcpProtocolError(`Invalid ${field}: payload exceeds the protocol bound`, PM_MCP_ERROR_CODES.invalidParams, { field, maximumBytes });
+    }
+}
+/** Validate and clone a server-authored MRTR request map. */
+export function parseMcpInputRequests(value, requestContext) {
+    if (!isMcpRecord(value)) {
+        throw new PmMcpProtocolError("Invalid MCP inputRequests", PM_MCP_ERROR_CODES.invalidParams, { field: "inputRequests", expected: "object" });
+    }
+    const entries = Object.entries(value);
+    if (entries.length === 0 || entries.length > MAX_INPUT_REQUESTS) {
+        throw new PmMcpProtocolError("Invalid MCP inputRequests count", PM_MCP_ERROR_CODES.invalidParams, { minimum: 1, maximum: MAX_INPUT_REQUESTS, observed: entries.length });
+    }
+    const parsed = {};
+    for (const [key, request] of entries) {
+        if (!INPUT_KEY_PATTERN.test(key) || !isMcpRecord(request)) {
+            throw new PmMcpProtocolError("Invalid MCP input request entry", PM_MCP_ERROR_CODES.invalidParams, { field: `inputRequests.${key}` });
+        }
+        const method = request.method;
+        if (typeof method !== "string" ||
+            !PM_MCP_INPUT_REQUEST_METHODS.includes(method)) {
+            throw new PmMcpProtocolError("Unsupported MCP input request method", PM_MCP_ERROR_CODES.invalidParams, { field: `inputRequests.${key}.method`, method: method ?? null });
+        }
+        const capability = inputCapability(method);
+        if (!Object.prototype.hasOwnProperty.call(requestContext.clientCapabilities, capability)) {
+            throw new PmMcpProtocolError("Missing required client capability", PM_MCP_ERROR_CODES.missingRequiredClientCapability, { requiredCapabilities: { [capability]: {} } });
+        }
+        if (!isMcpRecord(request.params)) {
+            throw new PmMcpProtocolError("Invalid MCP input request parameters", PM_MCP_ERROR_CODES.invalidParams, { field: `inputRequests.${key}.params`, expected: "object" });
+        }
+        parsed[key] = {
+            method: method,
+            params: structuredClone(request.params),
+        };
+    }
+    assertBoundedJson(parsed, MAX_INPUT_PAYLOAD_BYTES, "inputRequests");
+    return parsed;
+}
+/** Validate and clone client-supplied input responses from an MRTR retry. */
+export function parseMcpInputResponses(value) {
+    if (!isMcpRecord(value)) {
+        throw new PmMcpProtocolError("Invalid MCP inputResponses", PM_MCP_ERROR_CODES.invalidParams, { field: "inputResponses", expected: "object" });
+    }
+    const entries = Object.entries(value);
+    if (entries.length > MAX_INPUT_REQUESTS) {
+        throw new PmMcpProtocolError("Invalid MCP inputResponses count", PM_MCP_ERROR_CODES.invalidParams, { maximum: MAX_INPUT_REQUESTS, observed: entries.length });
+    }
+    const parsed = {};
+    for (const [key, response] of entries) {
+        if (!INPUT_KEY_PATTERN.test(key) || !isMcpRecord(response)) {
+            throw new PmMcpProtocolError("Invalid MCP input response entry", PM_MCP_ERROR_CODES.invalidParams, { field: `inputResponses.${key}` });
+        }
+        parsed[key] = structuredClone(response);
+    }
+    assertBoundedJson(parsed, MAX_INPUT_PAYLOAD_BYTES, "inputResponses");
+    return parsed;
+}
+/** Build a modern input-required result after validating capability and size bounds. */
+export function buildMcpInputRequiredResult(input) {
+    const requestState = input.requestState?.trim();
+    if (requestState &&
+        Buffer.byteLength(requestState, "utf8") > MAX_REQUEST_STATE_BYTES) {
+        throw new PmMcpProtocolError("Invalid MCP requestState: payload exceeds the protocol bound", PM_MCP_ERROR_CODES.invalidParams, { field: "requestState", maximumBytes: MAX_REQUEST_STATE_BYTES });
+    }
+    const inputRequests = input.inputRequests === undefined
+        ? undefined
+        : parseMcpInputRequests(input.inputRequests, input.requestContext);
+    if (inputRequests === undefined && !requestState) {
+        throw new PmMcpProtocolError("InputRequiredResult requires inputRequests or requestState", PM_MCP_ERROR_CODES.invalidParams, { requiredAnyOf: ["inputRequests", "requestState"] });
+    }
+    return {
+        resultType: "input_required",
+        ...(inputRequests ? { inputRequests } : {}),
+        ...(requestState ? { requestState } : {}),
+        _meta: {
+            [PM_MCP_META_KEYS.serverInfo]: { ...input.serverInfo },
+        },
+    };
+}
+function requestStateSecret(secret) {
+    const bytes = Buffer.from(secret);
+    if (bytes.byteLength < 32) {
+        throw new PmMcpProtocolError("MCP requestState signing key must contain at least 32 bytes", PM_MCP_ERROR_CODES.invalidParams, { minimumBytes: 32 });
+    }
+    return bytes;
+}
+/** Seal integrity-protected continuation state for an MRTR retry. */
+export function sealMcpRequestState(payload, secret) {
+    if (!Number.isSafeInteger(payload.expiresAt) ||
+        payload.expiresAt <= 0 ||
+        payload.method.trim().length === 0 ||
+        payload.parameterDigest.trim().length === 0 ||
+        payload.principal.trim().length === 0) {
+        throw new PmMcpProtocolError("Invalid MCP requestState payload", PM_MCP_ERROR_CODES.invalidParams);
+    }
+    const encoded = Buffer.from(JSON.stringify({ version: 1, ...payload }), "utf8");
+    if (encoded.byteLength > MAX_REQUEST_STATE_BYTES / 2) {
+        throw new PmMcpProtocolError("MCP requestState payload exceeds the protocol bound", PM_MCP_ERROR_CODES.invalidParams, { maximumBytes: MAX_REQUEST_STATE_BYTES / 2 });
+    }
+    const body = encoded.toString("base64url");
+    const signature = createHmac("sha256", requestStateSecret(secret))
+        .update(body)
+        .digest("base64url");
+    return `${body}.${signature}`;
+}
+function parseMcpRequestStatePayload(decoded) {
+    if (!isMcpRecord(decoded) || decoded.version !== 1) {
+        throw new PmMcpProtocolError("Invalid MCP requestState payload", PM_MCP_ERROR_CODES.invalidParams, { field: "requestState" });
+    }
+    const { expiresAt, method, parameterDigest, principal, state } = decoded;
+    if (typeof expiresAt !== "number" || !Number.isSafeInteger(expiresAt)) {
+        throw new PmMcpProtocolError("Invalid MCP requestState payload", PM_MCP_ERROR_CODES.invalidParams, { field: "requestState" });
+    }
+    if (typeof method !== "string" ||
+        typeof parameterDigest !== "string" ||
+        typeof principal !== "string") {
+        throw new PmMcpProtocolError("Invalid MCP requestState payload", PM_MCP_ERROR_CODES.invalidParams, { field: "requestState" });
+    }
+    return { expiresAt, method, parameterDigest, principal, state };
+}
+/** Verify an MRTR requestState value against method, principal, digest, and expiry. */
+export function openMcpRequestState(value, secret, expected) {
+    const [body, signature, extra] = value.split(".");
+    if (!body || !signature || extra !== undefined) {
+        throw new PmMcpProtocolError("Invalid MCP requestState encoding", PM_MCP_ERROR_CODES.invalidParams, { field: "requestState" });
+    }
+    const observed = Buffer.from(signature, "base64url");
+    const calculated = createHmac("sha256", requestStateSecret(secret))
+        .update(body)
+        .digest();
+    if (observed.byteLength !== calculated.byteLength ||
+        !timingSafeEqual(observed, calculated)) {
+        throw new PmMcpProtocolError("Invalid MCP requestState signature", PM_MCP_ERROR_CODES.invalidParams, { field: "requestState" });
+    }
+    let decoded;
+    try {
+        decoded = JSON.parse(Buffer.from(body, "base64url").toString("utf8"));
+    }
+    catch {
+        decoded = null;
+    }
+    const payload = parseMcpRequestStatePayload(decoded);
+    const { expiresAt, method, parameterDigest, principal } = payload;
+    if (expiresAt < (expected.nowMs ?? Date.now())) {
+        throw new PmMcpProtocolError("Expired MCP requestState", PM_MCP_ERROR_CODES.invalidParams, { field: "requestState", expiredAt: expiresAt });
+    }
+    if (method !== expected.method ||
+        parameterDigest !== expected.parameterDigest ||
+        principal !== expected.principal) {
+        throw new PmMcpProtocolError("MCP requestState binding mismatch", PM_MCP_ERROR_CODES.invalidParams, { field: "requestState" });
+    }
+    return payload;
+}
+/** Compute a stable-sized digest for application-selected salient request data. */
+export function digestMcpRequestParameters(value) {
+    assertBoundedJson(value, MAX_INPUT_PAYLOAD_BYTES, "request parameters");
+    return createHash("sha256").update(JSON.stringify(value)).digest("hex");
+}
+/**
+ * Bound single-use MRTR state consumption within one server process. Callers
+ * requiring cross-process one-time semantics should persist the resulting hash.
+ */
+export class PmMcpRequestStateReplayGuard {
+    #consumed = new Set();
+    #maximumEntries;
+    /** Create a bounded in-process replay guard. */
+    constructor(maximumEntries = 4096) {
+        if (!Number.isSafeInteger(maximumEntries) || maximumEntries < 1) {
+            throw new PmMcpProtocolError("Invalid MCP replay guard capacity", PM_MCP_ERROR_CODES.invalidParams, { maximumEntries });
+        }
+        this.#maximumEntries = maximumEntries;
+    }
+    /** Consume one opaque requestState value exactly once in this process. */
+    consume(value) {
+        const digest = createHash("sha256").update(value).digest("hex");
+        if (this.#consumed.has(digest)) {
+            throw new PmMcpProtocolError("MCP requestState replay detected", PM_MCP_ERROR_CODES.invalidParams, { field: "requestState" });
+        }
+        if (this.#consumed.size >= this.#maximumEntries) {
+            const oldest = this.#consumed.values().next().value;
+            this.#consumed.delete(oldest);
+        }
+        this.#consumed.add(digest);
+    }
+}
+/** Validate and clone a required MCP cache policy. */
+export function parseMcpCachePolicy(value) {
+    if (!Number.isSafeInteger(value.ttlMs) ||
+        value.ttlMs < 0 ||
+        (value.cacheScope !== "public" && value.cacheScope !== "private")) {
+        throw new PmMcpProtocolError("Invalid MCP cache policy", PM_MCP_ERROR_CODES.invalidParams, { ttlMs: value.ttlMs, cacheScope: value.cacheScope });
+    }
+    return { ttlMs: value.ttlMs, cacheScope: value.cacheScope };
+}
+/** Attach required cache fields without mutating a method-specific payload. */
+export function withMcpCachePolicy(payload, policy) {
+    return { ...payload, ...parseMcpCachePolicy(policy) };
+}
+function decodeJsonPointerToken(value) {
+    return value.replaceAll("~1", "/").replaceAll("~0", "~");
+}
+function resolveLocalJsonSchemaReference(root, reference) {
+    if (reference === "#")
+        return root;
+    if (!reference.startsWith("#/"))
+        return undefined;
+    let current = root;
+    for (const token of reference
+        .slice(2)
+        .split("/")
+        .map(decodeJsonPointerToken)) {
+        if (!isMcpRecord(current) && !Array.isArray(current))
+            return undefined;
+        if (!Object.prototype.hasOwnProperty.call(current, token))
+            return undefined;
+        current = current[token];
+    }
+    return current;
+}
+function resolveMcpJsonSchemaBounds(bounds) {
+    const maximumBytes = bounds.maxBytes ?? DEFAULT_SCHEMA_BOUNDS.maxBytes;
+    const maximumDepth = bounds.maxDepth ?? DEFAULT_SCHEMA_BOUNDS.maxDepth;
+    const maximumNodes = bounds.maxNodes ?? DEFAULT_SCHEMA_BOUNDS.maxNodes;
+    if (!Number.isSafeInteger(maximumBytes) || maximumBytes < 2) {
+        throw new PmMcpProtocolError("Invalid MCP JSON Schema work bounds", PM_MCP_ERROR_CODES.invalidParams);
+    }
+    if (!Number.isSafeInteger(maximumDepth) || maximumDepth < 1) {
+        throw new PmMcpProtocolError("Invalid MCP JSON Schema work bounds", PM_MCP_ERROR_CODES.invalidParams);
+    }
+    if (!Number.isSafeInteger(maximumNodes) || maximumNodes < 1) {
+        throw new PmMcpProtocolError("Invalid MCP JSON Schema work bounds", PM_MCP_ERROR_CODES.invalidParams);
+    }
+    return { maximumBytes, maximumDepth, maximumNodes };
+}
+function enqueueMcpJsonSchemaChildren(current, pending) {
+    const entries = Array.isArray(current.value)
+        ? current.value
+        : isMcpRecord(current.value)
+            ? Object.values(current.value)
+            : [];
+    for (const entry of entries) {
+        pending.push({ value: entry, depth: current.depth + 1 });
+    }
+}
+function assertMcpJsonSchemaReference(root, value) {
+    if (!isMcpRecord(value) || typeof value.$ref !== "string")
+        return;
+    const reference = value.$ref;
+    if (reference.startsWith("#") &&
+        resolveLocalJsonSchemaReference(root, reference) === undefined) {
+        throw new PmMcpProtocolError("MCP JSON Schema contains an unresolved local reference", PM_MCP_ERROR_CODES.invalidParams, { reference });
+    }
+}
+/**
+ * Validate JSON Schema 2020-12 structure under explicit byte, depth, node, and
+ * local-reference work bounds while allowing the complete keyword vocabulary.
+ */
+export function validateMcpJsonSchema(schema, bounds = {}) {
+    const { maximumBytes, maximumDepth, maximumNodes } = resolveMcpJsonSchemaBounds(bounds);
+    if (typeof schema !== "boolean" && !isMcpRecord(schema)) {
+        throw new PmMcpProtocolError("Invalid MCP JSON Schema root", PM_MCP_ERROR_CODES.invalidParams, { expected: "object or boolean" });
+    }
+    assertBoundedJson(schema, maximumBytes, "JSON Schema");
+    const pending = [
+        { value: schema, depth: 0 },
+    ];
+    let visited = 0;
+    while (pending.length > 0) {
+        const current = pending.pop();
+        visited += 1;
+        if (visited > maximumNodes || current.depth > maximumDepth) {
+            throw new PmMcpProtocolError("MCP JSON Schema exceeds validation work bounds", PM_MCP_ERROR_CODES.invalidParams, { maximumDepth, maximumNodes });
+        }
+        assertMcpJsonSchemaReference(schema, current.value);
+        enqueueMcpJsonSchemaChildren(current, pending);
+    }
+    return structuredClone(schema);
+}
+//# sourceMappingURL=interactions.js.map
+//# debugId=469f704b-12eb-524d-bcc8-fb8f9f1775f2

package/dist/sdk/mcp/protocol.d.ts

@@ -0,0 +1,142 @@
+/**
+ * @module sdk/mcp/protocol
+ *
+ * Defines transport-neutral MCP 2026-07-28 negotiation, request metadata,
+ * discovery, result-envelope, and bounded legacy-compatibility contracts.
+ */
+/** Canonical stateless MCP revision implemented by pm. */
+export declare const PM_MCP_PROTOCOL_VERSION: "2026-07-28";
+/** Legacy initialize-era revisions accepted only by the bounded stdio adapter. */
+export declare const PM_MCP_LEGACY_PROTOCOL_VERSIONS: readonly ["2025-06-18"];
+/** Modern per-request protocol versions accepted by the stateless core. */
+export declare const PM_MCP_SUPPORTED_PROTOCOL_VERSIONS: readonly ["2026-07-28"];
+/** Allocated MCP 2026-07-28 protocol error codes. */
+export declare const PM_MCP_ERROR_CODES: {
+    readonly headerMismatch: -32020;
+    readonly missingRequiredClientCapability: -32021;
+    readonly unsupportedProtocolVersion: -32022;
+    readonly invalidParams: -32602;
+};
+/** Namespaced metadata keys owned by the MCP specification. */
+export declare const PM_MCP_META_KEYS: {
+    readonly clientCapabilities: "io.modelcontextprotocol/clientCapabilities";
+    readonly clientInfo: "io.modelcontextprotocol/clientInfo";
+    readonly protocolVersion: "io.modelcontextprotocol/protocolVersion";
+    readonly serverInfo: "io.modelcontextprotocol/serverInfo";
+};
+/** MCP implementation identity carried in request and result metadata. */
+export interface PmMcpImplementation {
+    /** Stable implementation name. */
+    name: string;
+    /** Implementation version. */
+    version: string;
+    /** Optional human-readable implementation description. */
+    description?: string;
+    /** Optional implementation website. */
+    websiteUrl?: string;
+}
+/** Open MCP client capability map declared independently on every request. */
+export type PmMcpClientCapabilities = Record<string, unknown>;
+/** Server capabilities advertised by pm discovery. */
+export interface PmMcpServerCapabilities {
+    /** Prompt surface and change-notification support. */
+    prompts?: {
+        listChanged?: boolean;
+    };
+    /** Resource surface and change-notification support. */
+    resources?: {
+        listChanged?: boolean;
+        subscribe?: boolean;
+    };
+    /** Tool surface and change-notification support. */
+    tools?: {
+        listChanged?: boolean;
+    };
+    /** Negotiated optional extension settings keyed by extension identifier. */
+    extensions?: Record<string, Record<string, unknown>>;
+    /** Additional capability declarations retained for forward compatibility. */
+    [key: string]: unknown;
+}
+/** Validated request-local metadata for one modern MCP operation. */
+export interface PmMcpRequestContext {
+    /** Exact modern protocol revision used by this request. */
+    protocolVersion: (typeof PM_MCP_SUPPORTED_PROTOCOL_VERSIONS)[number];
+    /** Capabilities declared for this request only. */
+    clientCapabilities: PmMcpClientCapabilities;
+    /** Optional bounded client identity used only for diagnostics/provenance. */
+    clientInfo?: PmMcpImplementation;
+}
+/** Required fields attached to every modern successful result. */
+export interface PmMcpResultEnvelope {
+    /** Ordinary successful results are complete. */
+    resultType: "complete";
+    /** Result-local MCP metadata. */
+    _meta: {
+        /** Server identity is repeated on every modern result. */
+        "io.modelcontextprotocol/serverInfo": PmMcpImplementation;
+    };
+    /** Additional method-specific result fields. */
+    [key: string]: unknown;
+}
+/** Required server identity metadata attached to every modern result shape. */
+export interface PmMcpServerResultMetadata {
+    /** Result-local MCP metadata. */
+    _meta: {
+        /** Server identity is repeated on every modern result. */
+        "io.modelcontextprotocol/serverInfo": PmMcpImplementation;
+        /** Additional namespaced or application metadata. */
+        [key: string]: unknown;
+    };
+}
+/** Modern discovery response contract. */
+export interface PmMcpDiscoverResult extends PmMcpResultEnvelope {
+    /** Modern stateless revisions accepted through per-request metadata. */
+    supportedVersions: string[];
+    /** Deterministic server capability declaration. */
+    capabilities: PmMcpServerCapabilities;
+    /** Cache freshness hint required by the current schema. */
+    ttlMs: number;
+    /** Discovery is public because it contains no caller-specific data. */
+    cacheScope: "public";
+    /** Optional model-facing usage guidance. */
+    instructions?: string;
+}
+/** Protocol-era interpretation used at explicit compatibility boundaries. */
+export type PmMcpProtocolEra = "modern" | "legacy";
+/** Structured MCP protocol error safe for JSON-RPC adapters. */
+export declare class PmMcpProtocolError extends Error {
+    /** JSON-RPC/MCP error code. */
+    readonly code: number;
+    /** Structured recovery or mismatch detail. */
+    readonly data: Record<string, unknown>;
+    /** Create one typed protocol error. */
+    constructor(message: string, code: number, data?: Record<string, unknown>);
+}
+/** Return whether an unknown value is a non-array object. */
+export declare function isMcpRecord(value: unknown): value is Record<string, unknown>;
+/** Parse an optional MCP implementation identity without guessing missing fields. */
+export declare function parseMcpImplementation(value: unknown): PmMcpImplementation | undefined;
+/** Validate the stateless metadata required on every modern MCP request. */
+export declare function resolveMcpRequestContext(params: unknown): PmMcpRequestContext;
+/** Validate the HTTP protocol-version header against request-local metadata. */
+export declare function assertMcpProtocolHeader(requestContext: PmMcpRequestContext, headerValue: string | undefined): void;
+/** Require named client capabilities without consulting prior requests. */
+export declare function assertMcpClientCapabilities(requestContext: PmMcpRequestContext, requiredCapabilities: readonly string[]): void;
+/** Return whether this request independently negotiated one named extension. */
+export declare function hasMcpClientExtension(requestContext: PmMcpRequestContext, extension: string): boolean;
+/** Attach required server identity while preserving a non-complete result discriminator. */
+export declare function attachMcpServerInfo<Payload extends Record<string, unknown>>(payload: Payload, serverInfo: PmMcpImplementation): Payload & PmMcpServerResultMetadata;
+/** Attach required modern result fields without mutating the caller payload. */
+export declare function buildMcpCompleteResult<Payload extends Record<string, unknown>>(payload: Payload, serverInfo: PmMcpImplementation): Payload & PmMcpResultEnvelope;
+/** Build deterministic current-revision server discovery. */
+export declare function buildMcpDiscoverResult(input: {
+    serverInfo: PmMcpImplementation;
+    capabilities: PmMcpServerCapabilities;
+    instructions?: string;
+    ttlMs?: number;
+}): PmMcpDiscoverResult;
+/**
+ * Interpret resultType only at an explicit protocol-era boundary. Legacy
+ * results may omit it; modern results fail closed when it is absent.
+ */
+export declare function interpretMcpResultType(result: unknown, era: PmMcpProtocolEra): string;

package/dist/sdk/mcp/protocol.js

@@ -0,0 +1,174 @@
+/**
+ * @module sdk/mcp/protocol
+ *
+ * Defines transport-neutral MCP 2026-07-28 negotiation, request metadata,
+ * discovery, result-envelope, and bounded legacy-compatibility contracts.
+ */
+/** Canonical stateless MCP revision implemented by pm. */
+
+!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]="9cb05a78-f95d-5211-a35a-03756f66c812")}catch(e){}}();
+export const PM_MCP_PROTOCOL_VERSION = "2026-07-28";
+/** Legacy initialize-era revisions accepted only by the bounded stdio adapter. */
+export const PM_MCP_LEGACY_PROTOCOL_VERSIONS = ["2025-06-18"];
+/** Modern per-request protocol versions accepted by the stateless core. */
+export const PM_MCP_SUPPORTED_PROTOCOL_VERSIONS = [
+    PM_MCP_PROTOCOL_VERSION,
+];
+/** Allocated MCP 2026-07-28 protocol error codes. */
+export const PM_MCP_ERROR_CODES = {
+    headerMismatch: -32020,
+    missingRequiredClientCapability: -32021,
+    unsupportedProtocolVersion: -32022,
+    invalidParams: -32602,
+};
+/** Namespaced metadata keys owned by the MCP specification. */
+export const PM_MCP_META_KEYS = {
+    clientCapabilities: "io.modelcontextprotocol/clientCapabilities",
+    clientInfo: "io.modelcontextprotocol/clientInfo",
+    protocolVersion: "io.modelcontextprotocol/protocolVersion",
+    serverInfo: "io.modelcontextprotocol/serverInfo",
+};
+/** Structured MCP protocol error safe for JSON-RPC adapters. */
+export class PmMcpProtocolError extends Error {
+    /** JSON-RPC/MCP error code. */
+    code;
+    /** Structured recovery or mismatch detail. */
+    data;
+    /** Create one typed protocol error. */
+    constructor(message, code, data = {}) {
+        super(message);
+        this.name = "PmMcpProtocolError";
+        this.code = code;
+        this.data = data;
+    }
+}
+/** Return whether an unknown value is a non-array object. */
+export function isMcpRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+/** Parse an optional MCP implementation identity without guessing missing fields. */
+export function parseMcpImplementation(value) {
+    if (value === undefined)
+        return undefined;
+    if (!isMcpRecord(value)) {
+        throw new PmMcpProtocolError("Invalid MCP clientInfo metadata", PM_MCP_ERROR_CODES.invalidParams, { field: PM_MCP_META_KEYS.clientInfo, expected: "object" });
+    }
+    const name = typeof value.name === "string" ? value.name.trim() : "";
+    const version = typeof value.version === "string" ? value.version.trim() : "";
+    if (name.length === 0 || version.length === 0) {
+        throw new PmMcpProtocolError("Invalid MCP clientInfo metadata", PM_MCP_ERROR_CODES.invalidParams, {
+            field: PM_MCP_META_KEYS.clientInfo,
+            required: ["name", "version"],
+        });
+    }
+    const parsed = {
+        name: name.slice(0, 128),
+        version: version.slice(0, 128),
+    };
+    if (typeof value.description === "string" && value.description.trim()) {
+        parsed.description = value.description.trim().slice(0, 1024);
+    }
+    if (typeof value.websiteUrl === "string" && value.websiteUrl.trim()) {
+        parsed.websiteUrl = value.websiteUrl.trim().slice(0, 2048);
+    }
+    return parsed;
+}
+/** Validate the stateless metadata required on every modern MCP request. */
+export function resolveMcpRequestContext(params) {
+    const meta = isMcpRecord(params) ? params._meta : undefined;
+    if (!isMcpRecord(meta)) {
+        throw new PmMcpProtocolError("Missing required MCP request metadata", PM_MCP_ERROR_CODES.invalidParams, {
+            required: [
+                PM_MCP_META_KEYS.protocolVersion,
+                PM_MCP_META_KEYS.clientCapabilities,
+            ],
+        });
+    }
+    const requested = meta[PM_MCP_META_KEYS.protocolVersion];
+    if (typeof requested !== "string" ||
+        !PM_MCP_SUPPORTED_PROTOCOL_VERSIONS.includes(requested)) {
+        throw new PmMcpProtocolError("Unsupported protocol version", PM_MCP_ERROR_CODES.unsupportedProtocolVersion, {
+            supported: [...PM_MCP_SUPPORTED_PROTOCOL_VERSIONS],
+            requested: typeof requested === "string" ? requested : null,
+        });
+    }
+    const clientCapabilities = meta[PM_MCP_META_KEYS.clientCapabilities];
+    if (!isMcpRecord(clientCapabilities)) {
+        throw new PmMcpProtocolError("Invalid MCP client capabilities metadata", PM_MCP_ERROR_CODES.invalidParams, {
+            field: PM_MCP_META_KEYS.clientCapabilities,
+            expected: "object",
+        });
+    }
+    const clientInfo = parseMcpImplementation(meta[PM_MCP_META_KEYS.clientInfo]);
+    return {
+        protocolVersion: PM_MCP_PROTOCOL_VERSION,
+        clientCapabilities,
+        ...(clientInfo ? { clientInfo } : {}),
+    };
+}
+/** Validate the HTTP protocol-version header against request-local metadata. */
+export function assertMcpProtocolHeader(requestContext, headerValue) {
+    if (headerValue !== requestContext.protocolVersion) {
+        throw new PmMcpProtocolError("MCP protocol header does not match request metadata", PM_MCP_ERROR_CODES.headerMismatch, {
+            header: headerValue ?? null,
+            metadata: requestContext.protocolVersion,
+        });
+    }
+}
+/** Require named client capabilities without consulting prior requests. */
+export function assertMcpClientCapabilities(requestContext, requiredCapabilities) {
+    const missing = requiredCapabilities.filter((capability) => !Object.prototype.hasOwnProperty.call(requestContext.clientCapabilities, capability));
+    if (missing.length > 0) {
+        throw new PmMcpProtocolError("Missing required client capability", PM_MCP_ERROR_CODES.missingRequiredClientCapability, {
+            requiredCapabilities: Object.fromEntries(missing.map((capability) => [capability, {}])),
+        });
+    }
+}
+/** Return whether this request independently negotiated one named extension. */
+export function hasMcpClientExtension(requestContext, extension) {
+    const extensions = requestContext.clientCapabilities.extensions;
+    return isMcpRecord(extensions) && isMcpRecord(extensions[extension]);
+}
+/** Attach required server identity while preserving a non-complete result discriminator. */
+export function attachMcpServerInfo(payload, serverInfo) {
+    const payloadMeta = isMcpRecord(payload._meta) ? payload._meta : {};
+    return {
+        ...payload,
+        _meta: {
+            ...payloadMeta,
+            [PM_MCP_META_KEYS.serverInfo]: { ...serverInfo },
+        },
+    };
+}
+/** Attach required modern result fields without mutating the caller payload. */
+export function buildMcpCompleteResult(payload, serverInfo) {
+    return attachMcpServerInfo({ ...payload, resultType: "complete" }, serverInfo);
+}
+/** Build deterministic current-revision server discovery. */
+export function buildMcpDiscoverResult(input) {
+    const ttlMs = input.ttlMs ?? 60_000;
+    if (!Number.isFinite(ttlMs) || ttlMs < 0) {
+        throw new PmMcpProtocolError("Invalid MCP discovery cache TTL", PM_MCP_ERROR_CODES.invalidParams, { ttlMs });
+    }
+    return buildMcpCompleteResult({
+        supportedVersions: [...PM_MCP_SUPPORTED_PROTOCOL_VERSIONS],
+        capabilities: structuredClone(input.capabilities),
+        ttlMs,
+        cacheScope: "public",
+        ...(input.instructions ? { instructions: input.instructions } : {}),
+    }, input.serverInfo);
+}
+/**
+ * Interpret resultType only at an explicit protocol-era boundary. Legacy
+ * results may omit it; modern results fail closed when it is absent.
+ */
+export function interpretMcpResultType(result, era) {
+    if (isMcpRecord(result) && typeof result.resultType === "string") {
+        return result.resultType;
+    }
+    if (era === "legacy")
+        return "complete";
+    throw new PmMcpProtocolError("Modern MCP result is missing resultType", PM_MCP_ERROR_CODES.invalidParams, { required: "resultType" });
+}
+//# sourceMappingURL=protocol.js.map
+//# debugId=9cb05a78-f95d-5211-a35a-03756f66c812