@unbrained/pm-cli 2026.9.6 → 2026.9.8

package/dist/sdk/mcp/discovery.js

@@ -1,495 +1,2 @@
-/**
- * @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;
-}
+!(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]="31eda153-a06e-51ef-a62f-f6dce09064d3")}catch(e2){}})();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";const PM_MCP_PROGRESSIVE_DISCOVERY_EXTENSION="dev.unbrained.pm/progressive-tool-discovery";const PM_MCP_PROGRESSIVE_DISCOVERY_SERVER_CAPABILITY=Object.freeze({version:1,discoveryTool:"pm_discover",canonicalResult:"structuredContent.result",compatibilityText:"pointer"});const PM_MCP_ENTRY_TOOL_NAMES=Object.freeze(["pm_discover","pm_next","pm_context","pm_search","pm_get"]);const DISCOVERY_WEIGHTS=Object.freeze({lexical:.4,semantic:.2,graph:.1,permission:.15,freshness:.05,usage:.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);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>4096){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!==void 0&&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)}}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!==void 0&&typeof candidate.authorized!=="boolean"){throw new PmCliError(`pm tool discovery candidate ${index} authorized must be a boolean.`,64)}}}function parsePmToolDiscoveryOptions(input){validateDiscoveryOptionsContainer(input);if(input.family!==void 0&&(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!==void 0&&(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!==void 0?{query:boundedDiscoveryString(input.query,"query")}:{},...input.family!==void 0?{family:input.family}:{},...input.tier!==void 0?{tier:input.tier}:{},...input.limit!==void 0?{limit:discoveryLimit(input.limit)}:{},...input.cursor!==void 0?{cursor:boundedDiscoveryString(input.cursor,"cursor")}:{},...input.includeSchema!==void 0?{includeSchema:discoveryIncludeSchema(input.includeSchema)}:{},...input.outputBudget!==void 0?{outputBudget:discoveryOutputBudget(input.outputBudget)}:{}}}function normalizedUnitInterval(value){if(value===void 0||!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())?.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())?.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===void 0)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===void 0?"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)}:{}}}function validateDiscoveryFilters(options){if(options.cursorIntegrityKey!==void 0&&(!(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!==void 0&&(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!==void 0&&(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!==void 0&&(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===void 0?"":options.query,"query");const query=rawQuery.trim().replace(/\s+/gu," ");boundedDiscoveryString(options.cursor===void 0?"":options.cursor,"cursor");const limit=discoveryLimit(options.limit===void 0?10:options.limit);const budget=discoveryOutputBudget(options.outputBudget===void 0?1200:options.outputBudget);validateDiscoveryFilters(options);return{query,includeSchema:discoveryIncludeSchema(options.includeSchema),limit,budget,maximumTier:TIER_RANK[options.tier??"full"],profile:options.profile===void 0?"core":options.profile}}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===void 0||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}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:3e4,scope:"private",invalidates_on:DISCOVERY_CACHE_INVALIDATIONS}};const buildResultWithoutCost=(selected2,selectedCount=selected2.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:[...selected2],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=selected2=>{const resultWithoutCost=buildResultWithoutCost(selected2);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}export{PM_MCP_ENTRY_TOOL_NAMES,PM_MCP_PROGRESSIVE_DISCOVERY_EXTENSION,PM_MCP_PROGRESSIVE_DISCOVERY_SERVER_CAPABILITY,discoverPmTools,parsePmToolDiscoveryOptions};
 //# sourceMappingURL=discovery.js.map
-//# debugId=4853ebbf-f28a-55f1-b306-aa75cb9355ae