@unbrained/pm-cli 2026.8.30 → 2026.9.1

package/dist/sdk/mcp/discovery.js

@@ -0,0 +1,495 @@
+/**
+ * @module sdk/mcp/discovery
+ *
+ * Provides the deterministic, token-bounded progressive tool discovery
+ * contract shared by MCP servers, embedded hosts, and agent integrations.
+ */
+
+!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]="4853ebbf-f28a-55f1-b306-aa75cb9355ae")}catch(e){}}();
+import { createHash, createHmac, randomBytes, timingSafeEqual, } from "node:crypto";
+import { PM_COMMAND_CAPABILITY_CONTRACTS, PM_MCP_TOOL_COMMAND_CONTRACTS, resolvePmCommandCapabilityFamily, resolvePmCommandVisibilityTier, } from "../agent-capability-contracts.js";
+import { PmCliError } from "../runtime-primitives.js";
+/** Namespaced MCP extension that opts a client into progressive tool discovery. */
+export const PM_MCP_PROGRESSIVE_DISCOVERY_EXTENSION = "dev.unbrained.pm/progressive-tool-discovery";
+/** Versioned server capability advertised for progressive tool discovery. */
+export const PM_MCP_PROGRESSIVE_DISCOVERY_SERVER_CAPABILITY = Object.freeze({
+    version: 1,
+    discoveryTool: "pm_discover",
+    canonicalResult: "structuredContent.result",
+    compatibilityText: "pointer",
+});
+/** Small stable tool catalog returned to clients that negotiate the extension. */
+export const PM_MCP_ENTRY_TOOL_NAMES = Object.freeze([
+    "pm_discover",
+    "pm_next",
+    "pm_context",
+    "pm_search",
+    "pm_get",
+]);
+const DISCOVERY_WEIGHTS = Object.freeze({
+    lexical: 0.4,
+    semantic: 0.2,
+    graph: 0.1,
+    permission: 0.15,
+    freshness: 0.05,
+    usage: 0.1,
+});
+const DISCOVERY_CACHE_INVALIDATIONS = Object.freeze([
+    "profile_changed",
+    "tool_contract_changed",
+    "workspace_extension_changed",
+    "authorization_changed",
+    "ranking_signal_changed",
+    "cursor_integrity_key_rotated",
+]);
+const TIER_RANK = {
+    core: 0,
+    standard: 1,
+    full: 2,
+    internal: 3,
+};
+const SELECTABLE_TIERS = Object.freeze([
+    "core",
+    "standard",
+    "full",
+]);
+const MCP_TOOL_PROFILES = new Set([
+    "core",
+    "standard",
+    "full",
+    "custom",
+]);
+const CAPABILITY_FAMILIES = new Set(PM_COMMAND_CAPABILITY_CONTRACTS.map(({ family }) => family));
+const PROCESS_CURSOR_INTEGRITY_KEY = randomBytes(32);
+/** Validate a discovery string with the Unicode code-point semantics used by JSON Schema. */
+function boundedDiscoveryString(value, field) {
+    if (typeof value !== "string") {
+        throw new PmCliError(`pm tool discovery ${field} must be a string of at most 4096 Unicode characters.`, 64);
+    }
+    const iterator = value[Symbol.iterator]();
+    let count = 0;
+    for (let next = iterator.next(); !next.done; next = iterator.next()) {
+        count += 1;
+        if (count > 4_096) {
+            throw new PmCliError(`pm tool discovery ${field} must be a string of at most 4096 Unicode characters.`, 64);
+        }
+    }
+    return value;
+}
+function discoveryLimit(value) {
+    if (!Number.isInteger(value) || Number(value) < 1 || Number(value) > 100) {
+        throw new PmCliError("pm tool discovery limit must be from 1 through 100.", 64);
+    }
+    return Number(value);
+}
+function discoveryOutputBudget(value) {
+    if (value !== "unbounded" &&
+        (!Number.isInteger(value) || Number(value) < 128)) {
+        throw new PmCliError("pm tool discovery outputBudget must be unbounded or an integer of at least 128.", 64);
+    }
+    return value === "unbounded" ? value : Number(value);
+}
+function discoveryIncludeSchema(value) {
+    if (value !== undefined && typeof value !== "boolean") {
+        throw new PmCliError("pm tool discovery includeSchema must be a boolean.", 64);
+    }
+    return value === true;
+}
+function validateDiscoveryOptionsContainer(value) {
+    if (value === null || typeof value !== "object" || Array.isArray(value)) {
+        throw new PmCliError("pm tool discovery options must be an object.", 64);
+    }
+}
+/** Reject malformed candidate catalogs supplied by untyped SDK consumers. */
+function validateDiscoveryCandidates(candidates) {
+    if (!Array.isArray(candidates)) {
+        throw new PmCliError("pm tool discovery candidates must be an array.", 64);
+    }
+    for (const [index, candidate] of candidates.entries()) {
+        if (candidate === null ||
+            typeof candidate !== "object" ||
+            Array.isArray(candidate)) {
+            throw new PmCliError(`pm tool discovery candidate ${index} must be an object.`, 64);
+        }
+        if (typeof candidate.name !== "string" ||
+            candidate.name.trim().length === 0) {
+            throw new PmCliError(`pm tool discovery candidate ${index} name must be a non-empty string.`, 64);
+        }
+        if (typeof candidate.description !== "string" ||
+            candidate.description.trim().length === 0) {
+            throw new PmCliError(`pm tool discovery candidate ${index} description must be a non-empty string.`, 64);
+        }
+        if (candidate.inputSchema === null ||
+            typeof candidate.inputSchema !== "object" ||
+            Array.isArray(candidate.inputSchema)) {
+            throw new PmCliError(`pm tool discovery candidate ${index} inputSchema must be an object.`, 64);
+        }
+        if (candidate.authorized !== undefined &&
+            typeof candidate.authorized !== "boolean") {
+            throw new PmCliError(`pm tool discovery candidate ${index} authorized must be a boolean.`, 64);
+        }
+    }
+}
+/** Parse untrusted adapter input without discarding malformed discovery values. */
+export function parsePmToolDiscoveryOptions(input) {
+    validateDiscoveryOptionsContainer(input);
+    if (input.family !== undefined &&
+        (typeof input.family !== "string" || !CAPABILITY_FAMILIES.has(input.family))) {
+        throw new PmCliError("pm tool discovery family must be a declared capability family.", 64);
+    }
+    if (input.tier !== undefined &&
+        (typeof input.tier !== "string" || !SELECTABLE_TIERS.includes(input.tier))) {
+        throw new PmCliError("pm tool discovery tier must be core, standard, or full.", 64);
+    }
+    return {
+        ...(input.query !== undefined
+            ? { query: boundedDiscoveryString(input.query, "query") }
+            : {}),
+        ...(input.family !== undefined
+            ? { family: input.family }
+            : {}),
+        ...(input.tier !== undefined
+            ? {
+                tier: input.tier,
+            }
+            : {}),
+        ...(input.limit !== undefined
+            ? { limit: discoveryLimit(input.limit) }
+            : {}),
+        ...(input.cursor !== undefined
+            ? { cursor: boundedDiscoveryString(input.cursor, "cursor") }
+            : {}),
+        ...(input.includeSchema !== undefined
+            ? { includeSchema: discoveryIncludeSchema(input.includeSchema) }
+            : {}),
+        ...(input.outputBudget !== undefined
+            ? { outputBudget: discoveryOutputBudget(input.outputBudget) }
+            : {}),
+    };
+}
+function normalizedUnitInterval(value) {
+    if (value === undefined || !Number.isFinite(value))
+        return 0;
+    return Math.min(1, Math.max(0, value));
+}
+function normalizedSearchTokens(value) {
+    return [...new Set(value.toLowerCase().match(/[a-z0-9]+/gu) ?? [])].sort();
+}
+function lexicalRelevance(query, text) {
+    const queryTokens = normalizedSearchTokens(query);
+    if (queryTokens.length === 0)
+        return 0;
+    const targetTokens = new Set(normalizedSearchTokens(text));
+    const matched = queryTokens.filter((token) => targetTokens.has(token)).length;
+    const exactBonus = text.toLowerCase().includes(query.toLowerCase())
+        ? 0.25
+        : 0;
+    return Math.min(1, matched / queryTokens.length + exactBonus);
+}
+function semanticRelevance(query, text) {
+    const queryTokens = normalizedSearchTokens(query);
+    if (queryTokens.length === 0)
+        return 0;
+    const target = text.toLowerCase();
+    const targetTokens = normalizedSearchTokens(text);
+    const related = queryTokens.filter((queryToken) => targetTokens.some((targetToken) => targetToken.startsWith(queryToken) ||
+        queryToken.startsWith(targetToken))).length;
+    const phraseBonus = target.includes(query.toLowerCase()) ? 0.2 : 0;
+    return Math.min(1, related / queryTokens.length + phraseBonus);
+}
+function hashDiscoveryValue(value) {
+    return createHash("sha256")
+        .update(JSON.stringify(value))
+        .digest("hex")
+        .slice(0, 24);
+}
+function cursorSignature(fingerprint, offset, integrityKey) {
+    return createHmac("sha256", integrityKey)
+        .update(JSON.stringify({ version: 1, fingerprint, offset }))
+        .digest("base64url");
+}
+function encodeDiscoveryCursor(fingerprint, offset, integrityKey) {
+    const cursor = {
+        version: 1,
+        offset,
+        signature: cursorSignature(fingerprint, offset, integrityKey),
+    };
+    return Buffer.from(JSON.stringify(cursor), "utf8").toString("base64url");
+}
+function decodeDiscoveryCursor(value, fingerprint, total, integrityKey) {
+    if (value === undefined)
+        return 0;
+    try {
+        const decoded = JSON.parse(Buffer.from(value, "base64url").toString("utf8"));
+        if (decoded.version !== 1 ||
+            !Number.isInteger(decoded.offset) ||
+            (decoded.offset ?? -1) < 0 ||
+            Number(decoded.offset) > total ||
+            typeof decoded.signature !== "string") {
+            throw new Error("cursor fields do not match the request");
+        }
+        const expectedSignature = Buffer.from(cursorSignature(fingerprint, decoded.offset, integrityKey), "base64url");
+        const suppliedSignature = Buffer.from(decoded.signature, "base64url");
+        if (suppliedSignature.length !== expectedSignature.length ||
+            !timingSafeEqual(suppliedSignature, expectedSignature)) {
+            throw new Error("cursor signature does not match the request");
+        }
+        return decoded.offset;
+    }
+    catch (error) {
+        throw new PmCliError("Invalid or stale pm tool discovery cursor; restart discovery without cursor.", 64, { reason: String(error) });
+    }
+}
+function appliedSignal(value, weight, source) {
+    return {
+        value: normalizedUnitInterval(value),
+        weight,
+        available: source !== "unavailable",
+        source,
+    };
+}
+function hostOrComputedSignal(hostValue, computedValue, weight) {
+    return appliedSignal(hostValue ?? computedValue, weight, hostValue === undefined ? "computed" : "host");
+}
+function buildRankedRow(candidate, query, includeSchema) {
+    const command = Object.hasOwn(PM_MCP_TOOL_COMMAND_CONTRACTS, candidate.name)
+        ? PM_MCP_TOOL_COMMAND_CONTRACTS[candidate.name]
+        : "help";
+    const family = resolvePmCommandCapabilityFamily(command);
+    const searchableText = `${candidate.name} ${candidate.description} ${command} ${family}`;
+    const lexical = lexicalRelevance(query, searchableText);
+    const queryTokens = new Set(normalizedSearchTokens(query));
+    const signals = {
+        lexical: appliedSignal(lexical, DISCOVERY_WEIGHTS.lexical, "computed"),
+        semantic: hostOrComputedSignal(candidate.signals?.semantic, semanticRelevance(query, searchableText), DISCOVERY_WEIGHTS.semantic),
+        graph: hostOrComputedSignal(candidate.signals?.graph, queryTokens.has(family) || queryTokens.has(command) ? 1 : 0, DISCOVERY_WEIGHTS.graph),
+        permission: appliedSignal(1, DISCOVERY_WEIGHTS.permission, "authorization"),
+        freshness: hostOrComputedSignal(candidate.signals?.freshness, 1, DISCOVERY_WEIGHTS.freshness),
+        usage: hostOrComputedSignal(candidate.signals?.usage, PM_MCP_ENTRY_TOOL_NAMES.includes(candidate.name) ? 1 : 0, DISCOVERY_WEIGHTS.usage),
+    };
+    const score = Object.values(signals).reduce((total, signal) => total + signal.value * signal.weight, 0);
+    return {
+        name: candidate.name,
+        description: candidate.description,
+        command,
+        tier: resolvePmCommandVisibilityTier(command),
+        family,
+        score: Number(score.toFixed(6)),
+        signals,
+        ...(includeSchema
+            ? { input_schema: structuredClone(candidate.inputSchema) }
+            : {}),
+    };
+}
+/** Reject runtime filter values that bypass the public TypeScript unions. */
+function validateDiscoveryFilters(options) {
+    if (options.cursorIntegrityKey !== undefined &&
+        (!(options.cursorIntegrityKey instanceof Uint8Array) ||
+            options.cursorIntegrityKey.byteLength < 32)) {
+        throw new PmCliError("pm tool discovery cursorIntegrityKey must contain at least 32 bytes.", 64);
+    }
+    if (options.tier !== undefined &&
+        (typeof options.tier !== "string" ||
+            !SELECTABLE_TIERS.includes(options.tier))) {
+        throw new PmCliError("pm tool discovery tier must be core, standard, or full.", 64);
+    }
+    if (options.family !== undefined &&
+        (typeof options.family !== "string" ||
+            !CAPABILITY_FAMILIES.has(options.family))) {
+        throw new PmCliError("pm tool discovery family must be a declared capability family.", 64);
+    }
+    if (options.profile !== undefined &&
+        (typeof options.profile !== "string" ||
+            !MCP_TOOL_PROFILES.has(options.profile))) {
+        throw new PmCliError("pm tool discovery profile must be core, standard, full, or custom.", 64);
+    }
+}
+function resolveDiscoveryRequest(options) {
+    const rawQuery = boundedDiscoveryString(options.query === undefined ? "" : options.query, "query");
+    const query = rawQuery.trim().replace(/\s+/gu, " ");
+    boundedDiscoveryString(options.cursor === undefined ? "" : options.cursor, "cursor");
+    const limit = discoveryLimit(options.limit === undefined ? 10 : options.limit);
+    const budget = discoveryOutputBudget(options.outputBudget === undefined ? 1_200 : options.outputBudget);
+    validateDiscoveryFilters(options);
+    return {
+        query,
+        includeSchema: discoveryIncludeSchema(options.includeSchema),
+        limit,
+        budget,
+        maximumTier: TIER_RANK[options.tier ?? "full"],
+        profile: options.profile === undefined ? "core" : options.profile,
+    };
+}
+/**
+ * Measure one result exactly while allowing callers to supply pre-serialized
+ * array contents, so budget selection stays linear in the returned row bytes.
+ */
+function estimateDiscoveryResultTokens(resultWithoutCost, budget, serializedToolRowsBytes) {
+    const toolRowsBytes = serializedToolRowsBytes ??
+        resultWithoutCost.tools.reduce((total, row, index) => total +
+            (index === 0 ? 0 : 1) +
+            Buffer.byteLength(JSON.stringify(row), "utf8"), 0);
+    const emptyToolsResult = { ...resultWithoutCost, tools: [] };
+    let estimatedTokens = 0;
+    for (let iteration = 0; iteration < 4; iteration += 1) {
+        const envelopeBytes = Buffer.byteLength(JSON.stringify({
+            ...emptyToolsResult,
+            token_cost: {
+                estimated_tokens: estimatedTokens,
+                budget,
+                within_budget: true,
+            },
+        }), "utf8");
+        const nextEstimate = Math.ceil((envelopeBytes + toolRowsBytes) / 4);
+        if (nextEstimate === estimatedTokens)
+            break;
+        estimatedTokens = nextEstimate;
+    }
+    return estimatedTokens;
+}
+function rankedDiscoveryRows(candidates, options, request) {
+    return candidates
+        .filter((candidate) => candidate.authorized !== false)
+        .map((candidate) => buildRankedRow(candidate, request.query, request.includeSchema))
+        .filter((row) => row.tier !== "internal" &&
+        TIER_RANK[row.tier] <= request.maximumTier &&
+        (options.family === undefined || row.family === options.family))
+        .sort((left, right) => right.score - left.score ||
+        (left.name < right.name ? -1 : left.name > right.name ? 1 : 0));
+}
+function rowsWithinDiscoveryBudget(candidates, budget, buildResultWithoutCost) {
+    if (budget === "unbounded")
+        return [...candidates];
+    const selected = [];
+    let serializedToolRowsBytes = 0;
+    for (const [index, row] of candidates.entries()) {
+        const candidateRowsBytes = serializedToolRowsBytes +
+            (index === 0 ? 0 : 1) +
+            Buffer.byteLength(JSON.stringify(row), "utf8");
+        const estimatedTokens = estimateDiscoveryResultTokens(buildResultWithoutCost(index + 1), budget, candidateRowsBytes);
+        if (estimatedTokens > budget)
+            break;
+        selected.push(row);
+        serializedToolRowsBytes = candidateRowsBytes;
+    }
+    return selected;
+}
+/**
+ * Rank and page an authorized MCP tool catalog under an explicit token budget.
+ *
+ * Cursors fail closed when the query, filters, schemas, authorization-filtered
+ * catalog, or ranking inputs change. Host signals override documented local
+ * fallbacks without changing the public formula or hiding signal provenance.
+ */
+export function discoverPmTools(candidates, options = {}) {
+    validateDiscoveryCandidates(candidates);
+    validateDiscoveryOptionsContainer(options);
+    const request = resolveDiscoveryRequest(options);
+    const cursorIntegrityKey = options.cursorIntegrityKey ?? PROCESS_CURSOR_INTEGRITY_KEY;
+    const ranked = rankedDiscoveryRows(candidates, options, request);
+    const fingerprint = hashDiscoveryValue({
+        query: request.query,
+        family: options.family ?? null,
+        tier: options.tier ?? "full",
+        includeSchema: request.includeSchema,
+        profile: request.profile,
+        ranked,
+    });
+    const offset = decodeDiscoveryCursor(options.cursor, fingerprint, ranked.length, cursorIntegrityKey);
+    const pageCandidates = ranked.slice(offset, offset + request.limit);
+    const omitted = [];
+    if (!request.includeSchema) {
+        omitted.push({
+            name: "input_schema",
+            reason: "compact_projection",
+            restore_with: "Set includeSchema=true.",
+        });
+    }
+    if (offset + request.limit < ranked.length) {
+        omitted.push({
+            name: "tools",
+            reason: "limit",
+            restore_with: "Continue with next_cursor or increase limit.",
+        });
+    }
+    const base = {
+        result_type: "pm_tool_discovery",
+        contract_version: 1,
+        query: request.query,
+        profile: request.profile,
+        total: ranked.length,
+        ranking_policy: {
+            version: 1,
+            formula: "weighted_sum_then_name",
+            weights: DISCOVERY_WEIGHTS,
+        },
+        cache: {
+            key: hashDiscoveryValue({
+                fingerprint,
+                cursorIntegrityKey: createHash("sha256")
+                    .update(cursorIntegrityKey)
+                    .digest("hex"),
+                limit: request.limit,
+                offset,
+                budget: request.budget,
+            }),
+            ttl_ms: 30_000,
+            scope: "private",
+            invalidates_on: DISCOVERY_CACHE_INVALIDATIONS,
+        },
+    };
+    const buildResultWithoutCost = (selected, selectedCount = selected.length) => {
+        const endOffset = offset + selectedCount;
+        const hasMore = endOffset < ranked.length;
+        const resultOmissions = [...omitted];
+        if (selectedCount < pageCandidates.length) {
+            resultOmissions.push({
+                name: "tools",
+                reason: "token_budget",
+                restore_with: "Continue with next_cursor or increase outputBudget.",
+            });
+        }
+        const resultWithoutCost = {
+            ...base,
+            tools: [...selected],
+            returned: selectedCount,
+            has_more: hasMore,
+            ...(hasMore
+                ? {
+                    next_cursor: encodeDiscoveryCursor(fingerprint, endOffset, cursorIntegrityKey),
+                }
+                : {}),
+            omission_receipt: {
+                has_omissions: resultOmissions.length > 0,
+                omitted: resultOmissions,
+            },
+        };
+        return resultWithoutCost;
+    };
+    const buildResult = (selected) => {
+        const resultWithoutCost = buildResultWithoutCost(selected);
+        const estimatedTokens = estimateDiscoveryResultTokens(resultWithoutCost, request.budget);
+        return {
+            ...resultWithoutCost,
+            token_cost: {
+                estimated_tokens: estimatedTokens,
+                budget: request.budget,
+                within_budget: request.budget === "unbounded" || estimatedTokens <= request.budget,
+            },
+        };
+    };
+    const selected = rowsWithinDiscoveryBudget(pageCandidates, request.budget, (selectedCount) => buildResultWithoutCost([], selectedCount));
+    const result = buildResult(selected);
+    if (pageCandidates.length > 0 && selected.length === 0) {
+        const oneRowCost = buildResult([pageCandidates[0]]).token_cost
+            .estimated_tokens;
+        throw new PmCliError(`pm tool discovery outputBudget is too small to return a tool; increase it to at least ${oneRowCost}.`, 64, { required: String(oneRowCost) });
+    }
+    if (request.budget !== "unbounded" &&
+        result.token_cost.estimated_tokens > request.budget) {
+        throw new PmCliError(`pm tool discovery outputBudget is too small; at least ${result.token_cost.estimated_tokens} estimated tokens are required for this page.`, 64, { required: String(result.token_cost.estimated_tokens) });
+    }
+    return result;
+}
+//# sourceMappingURL=discovery.js.map
+//# debugId=4853ebbf-f28a-55f1-b306-aa75cb9355ae

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

@@ -6,8 +6,16 @@
  */
 /** 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"];
+/**
+ * Legacy initialize-era revisions accepted only by the bounded stdio adapter.
+ *
+ * The canonical revision defines legacy as every version that establishes a
+ * session with the handshake method, which is `2025-11-25` and earlier, so this
+ * set tracks that boundary rather than a single historical revision.
+ * Ordered newest first: element zero is the revision offered to a client that
+ * omits `protocolVersion`.
+ */
+export declare const PM_MCP_LEGACY_PROTOCOL_VERSIONS: readonly ["2025-11-25", "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. */

package/dist/sdk/mcp/protocol.js

@@ -6,10 +6,21 @@
  */
 /** 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){}}();
+!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]="0ec82581-c626-544c-9deb-ec5e810fd7e9")}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"];
+/**
+ * Legacy initialize-era revisions accepted only by the bounded stdio adapter.
+ *
+ * The canonical revision defines legacy as every version that establishes a
+ * session with the handshake method, which is `2025-11-25` and earlier, so this
+ * set tracks that boundary rather than a single historical revision.
+ * Ordered newest first: element zero is the revision offered to a client that
+ * omits `protocolVersion`.
+ */
+export const PM_MCP_LEGACY_PROTOCOL_VERSIONS = [
+    "2025-11-25",
+    "2025-06-18",
+];
 /** Modern per-request protocol versions accepted by the stateless core. */
 export const PM_MCP_SUPPORTED_PROTOCOL_VERSIONS = [
     PM_MCP_PROTOCOL_VERSION,
@@ -171,4 +182,4 @@ export function interpretMcpResultType(result, era) {
     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
+//# debugId=0ec82581-c626-544c-9deb-ec5e810fd7e9

package/dist/sdk/merge/index.d.ts

@@ -7,7 +7,7 @@
  * this module so packages and hosts can reuse the same merge behavior.
  */
 export { ITEM_LATEST_TIMESTAMP_FIELDS, ITEM_UNION_COLLECTION_FIELDS, mergeHistoryStreams, mergeItemDocuments, mergeJsonDocuments, mergeRelationshipEventStreams, type HistoryMergeResult, type HistoryMergeStrategy, type ItemDocumentMergeResult, type JsonDocumentMergeResult, type ItemMergeConflictDecision, type MergePreferredSide, type RelationshipStreamMergeResult, } from "./three-way.js";
-export { listMergeReceipts, markMergeReceiptReconciled, runMergeReceiptReport, summarizeMergeReceipt, type MergeDecisionReceipt, type MergeDecisionReceiptSummary, type MergeReceiptReport, } from "./receipts.js";
+export { inspectMergeReceiptEvidence, listMergeReceipts, markMergeReceiptReconciled, runMergeReceiptEvidenceReport, runMergeReceiptReport, summarizeMergeReceipt, type MergeDecisionReceipt, type MergeDecisionReceiptSummary, type MergeReceiptEvidenceReport, type MergeReceiptEvidenceScan, type MergeReceiptReport, } from "./receipts.js";
 export { MERGE_DRIVER_ARTIFACT_VALUES, runMergeDriver, type MergeDriverArtifact, type MergeDriverOptions, type MergeDriverResult, } from "./driver.js";
 export { auditMergeAttributeFence, auditMergeDriverConfiguration, buildMergeAttributePatterns, findGitWorkspaceRoot, PM_GITATTRIBUTES_END, PM_GITATTRIBUTES_START, PM_GITATTRIBUTES_V2_END, PM_GITATTRIBUTES_V2_START, refreshMergeAttributeFenceIfInstalled, resolveMergeInstallContext, runMergeInstall, type MergeFenceAuditResult, type MergeDriverConfigurationAuditResult, type MergeFenceRefreshOutcome, type MergeInstallOptions, type MergeInstallContextResolution, type MergeInstallResult, } from "./install.js";
 export { runMergeReconcile, type MergeReconcileOptions, type MergeReconcileResult, } from "./reconcile.js";

package/dist/sdk/merge/index.js

@@ -7,11 +7,11 @@
  * this module so packages and hosts can reuse the same merge behavior.
  */
 
-!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]="687855bf-7432-5691-a809-1f0406b5d8a8")}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]="a26f1126-3c87-5b0d-8712-2846fc9dcbb3")}catch(e){}}();
 export { ITEM_LATEST_TIMESTAMP_FIELDS, ITEM_UNION_COLLECTION_FIELDS, mergeHistoryStreams, mergeItemDocuments, mergeJsonDocuments, mergeRelationshipEventStreams, } from "./three-way.js";
-export { listMergeReceipts, markMergeReceiptReconciled, runMergeReceiptReport, summarizeMergeReceipt, } from "./receipts.js";
+export { inspectMergeReceiptEvidence, listMergeReceipts, markMergeReceiptReconciled, runMergeReceiptEvidenceReport, runMergeReceiptReport, summarizeMergeReceipt, } from "./receipts.js";
 export { MERGE_DRIVER_ARTIFACT_VALUES, runMergeDriver, } from "./driver.js";
 export { auditMergeAttributeFence, auditMergeDriverConfiguration, buildMergeAttributePatterns, findGitWorkspaceRoot, PM_GITATTRIBUTES_END, PM_GITATTRIBUTES_START, PM_GITATTRIBUTES_V2_END, PM_GITATTRIBUTES_V2_START, refreshMergeAttributeFenceIfInstalled, resolveMergeInstallContext, runMergeInstall, } from "./install.js";
 export { runMergeReconcile, } from "./reconcile.js";
 //# sourceMappingURL=index.js.map
-//# debugId=687855bf-7432-5691-a809-1f0406b5d8a8
+//# debugId=a26f1126-3c87-5b0d-8712-2846fc9dcbb3

package/dist/sdk/merge/receipts.d.ts

@@ -70,12 +70,31 @@ export interface MergeReceiptReport {
     /** ISO timestamp for the report. */
     generated_at: string;
 }
-/** Internal integrity scan result used by health without exposing malformed receipt contents. */
+/** Loss-aware merge receipt report for integrity gates and diagnostic adapters. */
+export interface MergeReceiptEvidenceReport {
+    /** Whether clone-local evidence resolved and every candidate was read and validated successfully. */
+    ok: boolean;
+    /** Whether clone-local evidence resolved and every discovered JSON candidate was read and validated successfully. */
+    complete: boolean;
+    /** Number of valid receipts returned. */
+    count: number;
+    /** Number of candidates rejected by bounded-file, schema, identity, or copy-consistency validation. */
+    invalid_evidence_count: number;
+    /** Whether the clone-local Git receipt directory was resolved successfully; always emitted by current implementations and optional for structural compatibility. */
+    clone_local_evidence_resolved?: boolean;
+    /** Receipts including recoverable values from the local clone only. */
+    receipts: MergeDecisionReceipt[];
+    /** ISO timestamp for the report. */
+    generated_at: string;
+}
+/** Loss-aware receipt inspection result that never exposes malformed file contents. */
 export interface MergeReceiptEvidenceScan {
     /** Valid receipts that passed bounded-file, schema, and identity validation. */
     receipts: MergeDecisionReceipt[];
     /** Number of JSON receipt candidates that could not be validated safely. */
     invalid_evidence_count: number;
+    /** Whether the clone-local Git receipt directory was resolved successfully; always emitted by current implementations and optional for structural compatibility. */
+    clone_local_evidence_resolved?: boolean;
 }
 declare function prepareReceiptSettlement(params: {
     receiptPath: string;
@@ -134,6 +153,13 @@ export declare function runMergeReceiptReport(options: {
     /** Repository directory to inspect; defaults to the process working directory. */
     cwd?: string;
 }): Promise<MergeReceiptReport>;
+/** Inspect every receipt candidate and retain completeness diagnostics without exposing rejected file contents. */
+export declare function runMergeReceiptEvidenceReport(options: {
+    /** Include receipts already represented by merge history events. */
+    includeReconciled?: boolean;
+    /** Repository directory to inspect; defaults to the process working directory. */
+    cwd?: string;
+}): Promise<MergeReceiptEvidenceReport>;
 /** Test-only seams for deterministic receipt-boundary fault coverage. */
 export declare const _testOnlyMergeReceipts: {
     prepareReceiptSettlement: typeof prepareReceiptSettlement;