relay-dsh-plugin-manager 0.2.6 → 0.3.0

package/lib/index.js

@@ -74,13 +74,15 @@ function registerConversationSurface(ctx, manager) {
 	const confirmations = /* @__PURE__ */ new Map();
 	ctx.tools.register(defineTool({
 		name: "plugin_discover",
-		description: "Read-only DSH plugin discovery. List installed plugins, search registered sources (including GitHub owner:NAME), inspect one npm/GitHub repository source, or query plugin/operation status. Search candidates form one relevance-ranked result page: present every possibly relevant candidate in ascending rank, exclude candidates whose purpose is clearly unrelated, and NEVER silently truncate the remaining page to a fixed top-N. Ranking is not a compatibility, security, or installation approval. Search result repository and recommendedSource values can be passed directly to inspect and plan. This tool never changes the profile.",
+		description: "Read-only DSH plugin discovery. Use search for one capability, exact identity, or GitHub owner:NAME. For a task needing multiple responsibilities, use search_roles: decompose the task into the smallest set of mutually distinct required/optional coverage roles, even when one plugin may ultimately cover several roles. Keep coherent operations on the same resource together: browsing, filtering, and previewing files are one file-browser responsibility. Every ongoing observation that finishes later is the deliberate exception and needs separate roles for source-specific state/event reading and for durable waiting/scheduling that resumes the original session; never merge those coverage responsibilities. Give each role a focused capability query and declare unresolved user choices as ambiguities. It returns inspected candidates grouped by role but does not claim they are relevant until reviewed. Exclude unrelated candidates, retain materially different alternatives, then call assess_solution with only reviewed candidate identities from each role. Assessment verifies role membership, merges one solution used by multiple roles, and reports the smallest complete answer only when every required role is selected and no ambiguity remains; never repeat npm/GitHub aliases, pad results, or silently impose a fixed top count. Ranking and directory placement are relevance evidence, not compatibility, security, or installation approval. Search result repository and recommendedSource values can be passed directly to inspect and plan. This tool never changes the profile.",
 		parameters: {
 			action: {
 				type: "string",
 				enum: [
 					"list",
 					"search",
+					"search_roles",
+					"assess_solution",
 					"inspect",
 					"status"
 				],
@@ -89,7 +91,7 @@ function registerConversationSurface(ctx, manager) {
 			},
 			query: {
 				type: "string",
-				description: "Natural-language query or GitHub owner:NAME search."
+				description: "Natural-language query or GitHub owner:NAME search. Required for search and search_roles; for search_roles this is the complete user task and must contain 1 to 1000 printable characters."
 			},
 			target: {
 				type: "string",
@@ -102,6 +104,85 @@ function registerConversationSurface(ctx, manager) {
 			maxResults: {
 				type: "integer",
 				description: "Ranked result-page size from 1 to 20. Use 20 for ordinary need-based searches unless the user explicitly asks for fewer."
+			},
+			maxResultsPerRole: {
+				type: "integer",
+				description: "Candidate-pool size from 1 to 20 for each search_roles role. Defaults to 20."
+			},
+			roles: {
+				type: "array",
+				items: {
+					type: "object",
+					additionalProperties: false,
+					properties: {
+						id: {
+							type: "string",
+							required: true,
+							description: "Stable lowercase role id."
+						},
+						label: {
+							type: "string",
+							required: true,
+							description: "Short user-facing responsibility label containing 1 to 80 printable characters."
+						},
+						query: {
+							type: "string",
+							required: true,
+							description: "Focused capability query for this role, without unrelated responsibilities; must contain 1 to 120 printable characters."
+						},
+						required: {
+							type: "boolean",
+							description: "False only when the user explicitly made this role optional."
+						}
+					}
+				},
+				description: "For search_roles, the smallest mutually distinct coverage responsibilities needed to complete the task; keep roles distinct even if one plugin may cover several."
+			},
+			ambiguities: {
+				type: "array",
+				items: {
+					type: "object",
+					additionalProperties: false,
+					properties: {
+						id: {
+							type: "string",
+							required: true
+						},
+						question: {
+							type: "string",
+							required: true
+						},
+						options: {
+							type: "array",
+							items: { type: "string" },
+							required: true
+						}
+					}
+				},
+				description: "Material unresolved user choices. Any ambiguity prevents a complete assessment."
+			},
+			solutionId: {
+				type: "string",
+				description: "Short-lived id returned by search_roles."
+			},
+			selections: {
+				type: "array",
+				items: {
+					type: "object",
+					additionalProperties: false,
+					properties: {
+						roleId: {
+							type: "string",
+							required: true
+						},
+						candidateIdentities: {
+							type: "array",
+							items: { type: "string" },
+							required: true
+						}
+					}
+				},
+				description: "For assess_solution, reviewed candidates grouped by role; first is primary and remaining entries are materially different alternatives."
 			}
 		},
 		output: {
@@ -734,6 +815,30 @@ function candidateSources(provider, rows) {
 	}
 	return output;
 }
+function candidateMatchReasons(match) {
+	if (match?.kind === "github-owner") return [];
+	if (match?.kind === "exact-identifier") return [`Exact identifier: ${match.value}`];
+	if (match?.kind !== "registry") return [];
+	return [
+		...match.exactIdentifier ? ["Exact Registry identifier"] : [],
+		...match.canonicalPath.length === 0 ? [] : [`Semantic directory: ${match.canonicalPath.join(" / ")}`],
+		...match.matchedCapabilities.length === 0 ? [] : [`Matched capabilities: ${match.matchedCapabilities.join(", ")}`]
+	];
+}
+function matchPriority(match, exactOwner) {
+	if (exactOwner || match?.kind === "exact-identifier" || match?.kind === "registry" && match.exactIdentifier) return 0;
+	return 1;
+}
+function semanticMatch(match) {
+	if (match?.kind !== "registry" || match.canonicalPath.length === 0 && match.matchedCapabilities.length === 0) return null;
+	return {
+		directoryVersion: match.directoryVersion ?? null,
+		canonicalPathKey: match.canonicalPathKey ?? null,
+		canonicalPath: [...match.canonicalPath],
+		matchedCapabilities: [...match.matchedCapabilities],
+		retrievalSources: [...match.retrievalSources]
+	};
+}
 async function searchPlugins(runtime, rawQuery, options = {}) {
 	const parsed = parseSearchQuery(rawQuery);
 	const maxResults = Math.max(1, Math.min(20, options.maxResults ?? 20));
@@ -770,17 +875,44 @@ async function searchPlugins(runtime, rawQuery, options = {}) {
 			return { ok: false };
 		}
 	}));
-	const projects = /* @__PURE__ */ new Map();
-	let rejectedCandidates = 0;
-	for (const result of inspected) {
-		if (!result.ok) {
-			rejectedCandidates += 1;
-			continue;
+	const accepted = inspected.flatMap((result) => result.ok ? [result] : []);
+	const parent = accepted.map((_, index) => index);
+	const root = (index) => {
+		let current = index;
+		while (parent[current] !== current) current = parent[current];
+		while (parent[index] !== index) {
+			const next = parent[index];
+			parent[index] = current;
+			index = next;
+		}
+		return current;
+	};
+	const join = (left, right) => {
+		const leftRoot = root(left);
+		const rightRoot = root(right);
+		if (leftRoot === rightRoot) return;
+		parent[Math.max(leftRoot, rightRoot)] = Math.min(leftRoot, rightRoot);
+	};
+	const aliasOwner = /* @__PURE__ */ new Map();
+	for (const [index, result] of accepted.entries()) {
+		const aliases = [`package:${result.inspection.packageName.toLowerCase()}`, ...result.inspection.repository === null ? [] : [`repository:${result.inspection.repository.toLowerCase()}`]];
+		for (const alias of aliases) {
+			const owner = aliasOwner.get(alias);
+			if (owner === void 0) aliasOwner.set(alias, index);
+			else join(index, owner);
 		}
+	}
+	const projects = /* @__PURE__ */ new Map();
+	const rejectedCandidates = inspected.length - accepted.length;
+	for (const [acceptedIndex, result] of accepted.entries()) {
+		const project = root(acceptedIndex);
 		const identity = inspectionIdentity(result.inspection);
 		const repositoryOwner = /^github\.com\/([^/]+)\//iu.exec(result.inspection.repository ?? "")?.[1]?.toLowerCase() ?? null;
-		const exactOwner = result.item.match?.kind === "github-owner" && repositoryOwner === result.item.match.value.toLowerCase();
-		const existing = projects.get(identity) ?? {
+		const exactOwnerValue = result.item.match?.kind === "github-owner" ? result.item.match.value : null;
+		const exactOwner = exactOwnerValue !== null && repositoryOwner === exactOwnerValue.toLowerCase();
+		const reasons = candidateMatchReasons(result.item.match);
+		const semantic = semanticMatch(result.item.match);
+		const existing = projects.get(project) ?? {
 			identity,
 			packageName: result.inspection.packageName,
 			description: result.inspection.description,
@@ -788,16 +920,19 @@ async function searchPlugins(runtime, rawQuery, options = {}) {
 			repositoryOwner,
 			providers: [],
 			matchReasons: [],
+			semanticMatches: [],
 			sources: [],
 			recommendedSource: result.inspection.installSpec,
 			rank: result.item.rank,
-			matchPriority: exactOwner ? 0 : 1
+			matchPriority: matchPriority(result.item.match, exactOwner)
 		};
 		if (!existing.providers.includes(result.item.provider)) existing.providers.push(result.item.provider);
 		if (exactOwner) {
-			const reason = `Exact GitHub owner: ${result.item.match.value}`;
+			const reason = `Exact GitHub owner: ${exactOwnerValue}`;
 			if (!existing.matchReasons.includes(reason)) existing.matchReasons.push(reason);
 		}
+		for (const reason of reasons) if (!existing.matchReasons.includes(reason)) existing.matchReasons.push(reason);
+		if (semantic !== null && !existing.semanticMatches.some((item) => item.directoryVersion === semantic.directoryVersion && item.canonicalPathKey === semantic.canonicalPathKey)) existing.semanticMatches.push(semantic);
 		const sameSource = existing.sources.find((source) => source.inspection.installSpec === result.inspection.installSpec);
 		if (sameSource === void 0) existing.sources.push({
 			inspection: result.inspection,
@@ -809,9 +944,9 @@ async function searchPlugins(runtime, rawQuery, options = {}) {
 			for (const evidence of result.item.evidence) if (!sameSource.evidence.includes(evidence)) sameSource.evidence.push(evidence);
 		}
 		existing.rank = Math.min(existing.rank, result.item.rank);
-		existing.matchPriority = Math.min(existing.matchPriority, exactOwner ? 0 : 1);
+		existing.matchPriority = Math.min(existing.matchPriority, matchPriority(result.item.match, exactOwner));
 		existing.recommendedSource = existing.sources.find((source) => source.inspection.sourceType === "npm")?.inspection.installSpec ?? existing.sources[0].inspection.installSpec;
-		projects.set(identity, existing);
+		projects.set(project, existing);
 	}
 	const candidates = [...projects.values()].sort((left, right) => left.matchPriority - right.matchPriority || left.rank - right.rank || left.packageName.localeCompare(right.packageName)).slice(0, maxResults).map(({ rank: _providerRank, matchPriority: _matchPriority, ...candidate }, index) => ({
 		...candidate,
@@ -825,8 +960,10 @@ async function searchPlugins(runtime, rawQuery, options = {}) {
 			order: "rank_ascending",
 			returnedCandidates: candidates.length,
 			requestedMaximum: maxResults,
-			includeEveryPossiblyRelevant: true,
+			includeEveryDistinctRelevantSolution: true,
 			excludeClearlyIrrelevant: true,
+			deduplicateEquivalentSources: true,
+			padToRequestedMaximum: false,
 			silentTopNTruncation: false
 		},
 		providerErrors,
@@ -1205,6 +1342,177 @@ var OperationTracker = class {
 	}
 };
 //#endregion
+//#region src/task-solutions.ts
+const DEFAULT_TTL_MS = 600 * 1e3;
+const MAX_ROLES = 8;
+const MAX_AMBIGUITIES = 4;
+const MAX_OPTIONS = 8;
+const MAX_DRAFTS = 32;
+const ROLE_ID = /^[a-z][a-z0-9_]{0,63}$/u;
+function bounded(value, name, maximum) {
+	const text = typeof value === "string" ? value.trim() : "";
+	if (text === "" || text.length > maximum || /[\u0000-\u001f\u007f]/u.test(text)) fail("INVALID_TASK_SOLUTION", `${name} must contain 1 to ${String(maximum)} printable characters.`);
+	return text;
+}
+function validateTaskSolutionPlan(taskValue, roleValues, ambiguityValues = []) {
+	const task = bounded(taskValue, "Task", 1e3);
+	if (!Array.isArray(roleValues) || roleValues.length < 1 || roleValues.length > MAX_ROLES) fail("INVALID_TASK_SOLUTION", `A task solution requires 1 to ${String(MAX_ROLES)} roles.`);
+	const roleIds = /* @__PURE__ */ new Set();
+	const roleLabels = /* @__PURE__ */ new Set();
+	const roleQueries = /* @__PURE__ */ new Set();
+	const roles = roleValues.map((value) => {
+		const id = typeof value?.id === "string" ? value.id.trim() : "";
+		if (!ROLE_ID.test(id)) fail("INVALID_TASK_SOLUTION", "Role ids must be lowercase stable identifiers.");
+		if (roleIds.has(id)) fail("INVALID_TASK_SOLUTION", "Role ids must be unique.");
+		roleIds.add(id);
+		const label = bounded(value.label, "Role label", 80);
+		const query = bounded(value.query, "Role query", 120);
+		const labelKey = label.toLocaleLowerCase();
+		const queryKey = query.toLocaleLowerCase().replace(/\s+/gu, " ");
+		if (roleLabels.has(labelKey) || roleQueries.has(queryKey)) fail("INVALID_TASK_SOLUTION", "Role labels and focused queries must be unique.");
+		roleLabels.add(labelKey);
+		roleQueries.add(queryKey);
+		return {
+			id,
+			label,
+			query,
+			required: value.required !== false
+		};
+	});
+	if (!Array.isArray(ambiguityValues) || ambiguityValues.length > MAX_AMBIGUITIES) fail("INVALID_TASK_SOLUTION", `A task solution supports at most ${String(MAX_AMBIGUITIES)} unresolved ambiguities.`);
+	const ambiguityIds = /* @__PURE__ */ new Set();
+	return {
+		task,
+		roles,
+		ambiguities: ambiguityValues.map((value) => {
+			const id = typeof value?.id === "string" ? value.id.trim() : "";
+			if (!ROLE_ID.test(id) || ambiguityIds.has(id) || roleIds.has(id)) fail("INVALID_TASK_SOLUTION", "Ambiguity ids must be unique lowercase stable identifiers and cannot reuse a role id.");
+			ambiguityIds.add(id);
+			if (!Array.isArray(value.options) || value.options.length < 2 || value.options.length > MAX_OPTIONS) fail("INVALID_TASK_SOLUTION", `Each ambiguity requires 2 to ${String(MAX_OPTIONS)} options.`);
+			const options = value.options.map((option) => bounded(option, "Ambiguity option", 80));
+			if (new Set(options).size !== options.length) fail("INVALID_TASK_SOLUTION", "Ambiguity options must be unique.");
+			return {
+				id,
+				question: bounded(value.question, "Ambiguity question", 200),
+				options
+			};
+		})
+	};
+}
+function candidateSummary(candidate) {
+	const { sources: _sources, ...summary } = candidate;
+	return structuredClone(summary);
+}
+var TaskSolutionStore = class {
+	now;
+	id;
+	ttlMs;
+	drafts = /* @__PURE__ */ new Map();
+	constructor(options = {}) {
+		this.now = options.now ?? Date.now;
+		this.id = options.id ?? (() => `task-solution:${randomUUID()}`);
+		this.ttlMs = options.ttlMs ?? DEFAULT_TTL_MS;
+		if (!Number.isSafeInteger(this.ttlMs) || this.ttlMs < 1e3 || this.ttlMs > 3600 * 1e3) throw new RangeError("Task solution ttlMs must be from 1 second to 1 hour.");
+	}
+	create(input) {
+		const plan = validateTaskSolutionPlan(input.task, input.roles, input.ambiguities);
+		const now = this.now();
+		for (const [id, draft] of this.drafts) if (draft.expiresAt <= now) this.drafts.delete(id);
+		while (this.drafts.size >= MAX_DRAFTS) this.drafts.delete(this.drafts.keys().next().value);
+		const roles = plan.roles.map((role) => {
+			const search = input.searches[role.id];
+			if (search === void 0) fail("INVALID_TASK_SOLUTION", `Search results are missing for role ${role.id}.`);
+			return {
+				...role,
+				candidates: search.candidates.map(candidateSummary),
+				providerErrors: structuredClone(search.providerErrors),
+				rejectedCandidates: search.rejectedCandidates
+			};
+		});
+		const requiredCandidateMissing = roles.some((role) => role.required && role.candidates.length === 0);
+		const draft = {
+			schemaVersion: "1.0.0",
+			solutionId: bounded(this.id(), "Task solution id", 200),
+			task: plan.task,
+			status: plan.ambiguities.length > 0 ? "ambiguous" : requiredCandidateMissing ? "incomplete" : "needs_review",
+			createdAt: now,
+			expiresAt: now + this.ttlMs,
+			roles,
+			ambiguities: plan.ambiguities
+		};
+		if (this.drafts.has(draft.solutionId)) fail("INVALID_TASK_SOLUTION", "Task solution id must be unique.");
+		this.drafts.set(draft.solutionId, draft);
+		return structuredClone(draft);
+	}
+	assess(solutionIdValue, selectionValues) {
+		const solutionId = bounded(solutionIdValue, "Task solution id", 200);
+		const draft = this.drafts.get(solutionId);
+		if (draft === void 0) fail("TASK_SOLUTION_NOT_FOUND", "Task solution draft was not found.");
+		if (draft.expiresAt <= this.now()) {
+			this.drafts.delete(solutionId);
+			fail("TASK_SOLUTION_EXPIRED", "Task solution draft has expired; search the roles again.");
+		}
+		if (!Array.isArray(selectionValues) || selectionValues.length > draft.roles.length) fail("INVALID_TASK_SOLUTION", "Task solution selections must contain at most one row per role.");
+		const roleById = new Map(draft.roles.map((role) => [role.id, role]));
+		const selections = /* @__PURE__ */ new Map();
+		for (const value of selectionValues) {
+			const roleId = typeof value?.roleId === "string" ? value.roleId.trim() : "";
+			const role = roleById.get(roleId);
+			if (role === void 0) fail("INVALID_TASK_SOLUTION", `Unknown task solution role ${roleId}.`);
+			if (selections.has(roleId)) fail("INVALID_TASK_SOLUTION", `Role ${roleId} has duplicate selection rows.`);
+			if (!Array.isArray(value.candidateIdentities) || value.candidateIdentities.length > 20) fail("INVALID_TASK_SOLUTION", `Role ${roleId} has too many candidate identities.`);
+			const identities = value.candidateIdentities.map((identity) => bounded(identity, "Candidate identity", 500));
+			if (new Set(identities).size !== identities.length) fail("INVALID_TASK_SOLUTION", `Role ${roleId} contains a duplicate candidate.`);
+			const available = new Set(role.candidates.map((candidate) => candidate.identity));
+			for (const identity of identities) if (!available.has(identity)) fail("INVALID_TASK_SOLUTION", `${identity} is not a candidate for role ${roleId}.`);
+			selections.set(roleId, identities);
+		}
+		const solutions = /* @__PURE__ */ new Map();
+		const roles = draft.roles.map((role) => {
+			const identities = selections.get(role.id) ?? [];
+			for (const identity of identities) {
+				const candidate = role.candidates.find((item) => item.identity === identity);
+				const existing = solutions.get(identity);
+				if (existing === void 0) solutions.set(identity, {
+					...structuredClone(candidate),
+					roleIds: [role.id]
+				});
+				else if (!existing.roleIds.includes(role.id)) existing.roleIds.push(role.id);
+			}
+			return {
+				id: role.id,
+				label: role.label,
+				query: role.query,
+				required: role.required,
+				status: identities.length > 0 ? "covered" : role.required ? "missing_required" : "missing_optional",
+				primaryCandidateIdentity: identities[0] ?? null,
+				alternativeCandidateIdentities: identities.slice(1)
+			};
+		});
+		const required = roles.filter((role) => role.required);
+		const optional = roles.filter((role) => !role.required);
+		const missingRequiredRoleIds = required.filter((role) => role.status !== "covered").map((role) => role.id);
+		const complete = missingRequiredRoleIds.length === 0 && draft.ambiguities.length === 0;
+		return {
+			schemaVersion: "1.0.0",
+			solutionId,
+			task: draft.task,
+			status: draft.ambiguities.length > 0 ? "ambiguous" : complete ? "complete" : "incomplete",
+			roles,
+			ambiguities: structuredClone(draft.ambiguities),
+			solutions: [...solutions.values()],
+			coverage: {
+				requiredRoles: required.length,
+				coveredRequiredRoles: required.filter((role) => role.status === "covered").length,
+				optionalRoles: optional.length,
+				coveredOptionalRoles: optional.filter((role) => role.status === "covered").length,
+				missingRequiredRoleIds,
+				complete
+			}
+		};
+	}
+};
+//#endregion
 //#region src/manager.ts
 const MAX_INSTALL_MANY_SOURCES = 20;
 const FIBER_PHASE = {
@@ -1258,7 +1566,10 @@ const TELEMETRY_ERROR_CODES = /* @__PURE__ */ new Set([
 	"DSH_COMMAND_FAILED",
 	"BATCH_INSTALL_FAILED",
 	"POSTCONDITION_FAILED",
-	"RESTART_UNAVAILABLE"
+	"RESTART_UNAVAILABLE",
+	"INVALID_TASK_SOLUTION",
+	"TASK_SOLUTION_NOT_FOUND",
+	"TASK_SOLUTION_EXPIRED"
 ]);
 function safePackageName(value) {
 	const name = value?.trim() ?? "";
@@ -1315,6 +1626,7 @@ var PluginManager = class {
 	fetchOptions;
 	hmrTimeoutMs;
 	telemetry;
+	taskSolutions;
 	constructor(dependencies) {
 		this.profileDir = dependencies.profileDir;
 		this.searchRuntime = dependencies.searchRuntime;
@@ -1328,6 +1640,7 @@ var PluginManager = class {
 		this.fetchOptions = dependencies.fetchOptions ?? {};
 		this.hmrTimeoutMs = dependencies.hmrTimeoutMs ?? 5e3;
 		this.telemetry = dependencies.telemetry ?? { capture() {} };
+		this.taskSolutions = dependencies.taskSolutions ?? new TaskSolutionStore();
 	}
 	capture(event, properties = {}) {
 		try {
@@ -1356,7 +1669,7 @@ var PluginManager = class {
 		this.capture("plugin_manager_used", {
 			surface: "discover",
 			action: request.action,
-			...request.action === "search" ? {
+			...request.action === "search" || request.action === "search_roles" ? {
 				has_query: (request.query?.trim().length ?? 0) > 0,
 				query_length_bucket: queryLengthBucket(request.query)
 			} : {}
@@ -1374,6 +1687,27 @@ var PluginManager = class {
 			};
 			return await searchPlugins(this.searchRuntime, request.query ?? "", options);
 		}
+		if (request.action === "search_roles") {
+			const plan = validateTaskSolutionPlan(request.query ?? "", request.roles ?? [], request.ambiguities ?? []);
+			const maxResultsPerRole = request.maxResultsPerRole ?? 20;
+			if (!Number.isInteger(maxResultsPerRole) || maxResultsPerRole < 1 || maxResultsPerRole > 20) fail("INVALID_TASK_SOLUTION", "maxResultsPerRole must be an integer from 1 to 20.");
+			const searches = await Promise.all(plan.roles.map(async (role) => [role.id, await searchPlugins(this.searchRuntime, role.query, {
+				...this.fetchOptions,
+				signal,
+				maxResults: maxResultsPerRole,
+				inspect: this.inspect
+			})]));
+			return this.taskSolutions.create({
+				task: plan.task,
+				roles: plan.roles,
+				ambiguities: plan.ambiguities,
+				searches: Object.fromEntries(searches)
+			});
+		}
+		if (request.action === "assess_solution") {
+			if (request.solutionId === void 0) fail("INVALID_TASK_SOLUTION", "A task solution id is required for assessment.");
+			return this.taskSolutions.assess(request.solutionId, request.selections ?? []);
+		}
 		if (request.action === "inspect") {
 			if (request.target === void 0) fail("INVALID_SOURCE", "A plugin source is required for inspection.");
 			return await this.inspect(request.target, {
@@ -1795,7 +2129,14 @@ var PluginManager = class {
 //#endregion
 //#region src/providers.ts
 const MAX_PROVIDER_RESULTS = 20;
+const REGISTRY_KEYWORD_CHALLENGER_POOL = 21;
+const REGISTRY_DIRECTORY_POOL = 50;
+const RECIPROCAL_RANK_OFFSET = 20;
+const KEYWORD_RANK_WEIGHT = .1;
+const DIRECTORY_RANK_WEIGHT = .2;
+const IDENTITY_TERM_BOOST = .01;
 const REGISTRY_SNAPSHOT_ID = /^discovery\.[a-z0-9.-]+$/u;
+const REGISTRY_DIRECTORY_VERSION = /^[a-z0-9][a-z0-9._-]{0,127}$/u;
 function query(value) {
 	const normalized = value.trim();
 	if (normalized === "" || normalized.length > 120 || /[\u0000-\u001f\u007f]/u.test(normalized)) throw new Error("Search query must contain 1 to 120 printable characters.");
@@ -1836,7 +2177,11 @@ function npmSearchProvider(fetchImpl = globalThis.fetch) {
 					package: text
 				}],
 				score: Number.MAX_SAFE_INTEGER,
-				evidence: ["Exact npm package-name query"]
+				evidence: ["Exact npm package-name query"],
+				match: {
+					kind: "exact-identifier",
+					value: text
+				}
 			}, ...searched];
 		}
 	};
@@ -1911,7 +2256,7 @@ function githubSearchProvider(fetchImpl = globalThis.fetch, env = process.env) {
 		}
 	};
 }
-function registryEndpoint(value) {
+function registryEndpoint(value, operation) {
 	let url;
 	try {
 		url = new URL(value);
@@ -1921,7 +2266,7 @@ function registryEndpoint(value) {
 	const local = url.hostname === "127.0.0.1" || url.hostname === "localhost" || url.hostname === "::1";
 	if (url.protocol !== "https:" && !(local && url.protocol === "http:")) throw new Error("Registry URL must use HTTPS, except for an explicit local development endpoint.");
 	if (url.username !== "" || url.password !== "" || url.search !== "" || url.hash !== "") throw new Error("Registry URL cannot contain credentials, query parameters, or a fragment.");
-	url.pathname = `${url.pathname.replace(/\/$/u, "")}/v1/plugins:search`;
+	url.pathname = `${url.pathname.replace(/\/$/u, "")}/v1/plugins:${operation}`;
 	return url.href;
 }
 function boundedText(value, maximum = 4e3) {
@@ -1930,7 +2275,19 @@ function boundedText(value, maximum = 4e3) {
 function queryLocale(value) {
 	return /\p{Script=Han}/u.test(value) ? "zh-CN" : "en";
 }
-function registryCandidate(value, snapshotId) {
+function safeCodes(value, maximum = 20) {
+	return Array.isArray(value) ? value.filter((item) => typeof item === "string" && /^[a-z0-9._-]+$/u.test(item)).slice(0, maximum) : [];
+}
+function safePath(value, locale) {
+	if (!Array.isArray(value)) return [];
+	return value.flatMap((item) => {
+		if (typeof item !== "object" || item === null || Array.isArray(item)) return [];
+		const path = item;
+		const label = locale === "en" ? boundedText(path.en, 200) ?? boundedText(path.zh_CN, 200) : boundedText(path.zh_CN, 200) ?? boundedText(path.en, 200);
+		return label === void 0 ? [] : [label];
+	}).slice(0, 8);
+}
+function registryCandidate(value, metadata) {
 	if (typeof value !== "object" || value === null || Array.isArray(value)) return null;
 	const candidate = value;
 	const entry = candidate.entry;
@@ -1961,7 +2318,12 @@ function registryCandidate(value, snapshotId) {
 	const zh = boundedText(entry.imported_content?.description?.["zh-CN"]);
 	const en = boundedText(entry.imported_content?.description?.en);
 	const repository = boundedText(entry.identity?.repository_url, 500);
-	const reasonCodes = Array.isArray(candidate.match?.reason_codes) ? candidate.match.reason_codes.filter((item) => typeof item === "string" && /^[a-z0-9_]+$/u.test(item)).slice(0, 8) : [];
+	const reasonCodes = safeCodes(candidate.match?.reason_codes ?? candidate.match?.keyword_reason_codes, 8);
+	const retrievalSources = safeCodes(candidate.match?.retrieval_sources, 8);
+	const canonicalPathKey = boundedText(candidate.match?.canonical_path_key, 500);
+	const canonicalPath = safePath(candidate.match?.canonical_primary_path, metadata.locale);
+	const matchedCapabilities = safeCodes(candidate.match?.matched_capabilities, 8);
+	const exactIdentifier = reasonCodes.includes("exact_identifier");
 	const score = typeof candidate.match?.score === "number" && Number.isFinite(candidate.match.score) && candidate.match.score >= 0 ? candidate.match.score : void 0;
 	return {
 		id: `registry:${entry.entry_id}`,
@@ -1974,19 +2336,123 @@ function registryCandidate(value, snapshotId) {
 		sources,
 		...score === void 0 ? {} : { score },
 		evidence: [
-			`DSH Registry source snapshot: ${snapshotId}`,
+			`DSH Registry source snapshot: ${metadata.snapshotId}`,
+			...metadata.directoryVersion === void 0 ? [] : [`DSH Registry directory version: ${metadata.directoryVersion}`],
+			...canonicalPath.length === 0 ? [] : [`Semantic directory: ${canonicalPath.join(" / ")}`],
+			...matchedCapabilities.length === 0 ? [] : [`Matched capabilities: ${matchedCapabilities.join(", ")}`],
 			"Registry discovery record only; compatibility and security not tested",
 			...reasonCodes.map((code) => `Registry match: ${code}`)
-		]
+		],
+		match: {
+			kind: "registry",
+			strategy: metadata.strategy,
+			snapshotId: metadata.snapshotId,
+			...metadata.directoryVersion === void 0 ? {} : { directoryVersion: metadata.directoryVersion },
+			retrievalSources,
+			keywordReasonCodes: reasonCodes,
+			...canonicalPathKey === void 0 ? {} : { canonicalPathKey },
+			canonicalPath,
+			matchedCapabilities,
+			exactIdentifier
+		}
+	};
+}
+async function parseRegistryResponse(response, strategy, locale) {
+	if (!response.ok) throw new Error(`DSH Registry ${strategy === "keyword" ? "search" : "directory route"} returned HTTP ${response.status}`);
+	const data = await response.json();
+	const directoryVersion = strategy === "keyword-plus-semantic-directory-v1" && typeof data.directory_version === "string" && REGISTRY_DIRECTORY_VERSION.test(data.directory_version) ? data.directory_version : void 0;
+	if (typeof data.snapshot_id !== "string" || !REGISTRY_SNAPSHOT_ID.test(data.snapshot_id) || !Array.isArray(data.candidates) || data.is_final_recommendation === true || data.grants_install_approval === true || strategy === "keyword-plus-semantic-directory-v1" && directoryVersion === void 0) throw new Error("DSH Registry search returned an invalid discovery response.");
+	const metadata = {
+		snapshotId: data.snapshot_id,
+		strategy,
+		locale,
+		...directoryVersion === void 0 ? {} : { directoryVersion }
+	};
+	return {
+		metadata,
+		candidates: data.candidates.flatMap((candidate) => {
+			const normalized = registryCandidate(candidate, metadata);
+			return normalized === null ? [] : [normalized];
+		})
 	};
 }
-function registrySearchProvider(baseUrl, fetchImpl = globalThis.fetch) {
-	const endpoint = registryEndpoint(baseUrl);
+const IDENTITY_STOP_TERMS = /* @__PURE__ */ new Set([
+	"and",
+	"dsh",
+	"for",
+	"from",
+	"inside",
+	"into",
+	"plugin",
+	"plugins",
+	"the",
+	"use",
+	"using",
+	"with"
+]);
+function identityTermCoverage(searchText, candidate) {
+	const terms = [...new Set(searchText.toLowerCase().match(/[a-z0-9@]+/gu) ?? [])].filter((term) => term.length >= 3 && !IDENTITY_STOP_TERMS.has(term));
+	if (terms.length === 0) return 0;
+	const identityTerms = new Set(`${candidate.title} ${candidate.repository ?? ""}`.toLowerCase().split(/[^a-z0-9@]+/gu).filter(Boolean));
+	return terms.filter((term) => identityTerms.has(term)).length / terms.length;
+}
+function mergeRegistryRankings(searchText, keyword, directory, limit) {
+	const combined = /* @__PURE__ */ new Map();
+	for (const [source, response, weight] of [[
+		"keyword",
+		keyword,
+		KEYWORD_RANK_WEIGHT
+	], [
+		"directory",
+		directory,
+		DIRECTORY_RANK_WEIGHT
+	]]) {
+		if (response === null) continue;
+		response.candidates.forEach((candidate, index) => {
+			if (source === "directory" && keyword !== null && !combined.has(candidate.id)) return;
+			const current = combined.get(candidate.id) ?? {
+				candidate,
+				score: 0
+			};
+			current.score += weight / (RECIPROCAL_RANK_OFFSET + index + 1);
+			if (source === "keyword") current.keywordRank = index + 1;
+			else {
+				current.directoryRank = index + 1;
+				current.candidate = candidate;
+			}
+			combined.set(candidate.id, current);
+		});
+	}
+	return [...combined.values()].map((item) => {
+		const keywordMatch = keyword?.candidates.find((candidate) => candidate.id === item.candidate.id)?.match;
+		const directoryMatch = directory?.candidates.find((candidate) => candidate.id === item.candidate.id)?.match;
+		const exactIdentifier = keywordMatch?.kind === "registry" && keywordMatch.exactIdentifier || directoryMatch?.kind === "registry" && directoryMatch.exactIdentifier;
+		const registryMatch = directoryMatch?.kind === "registry" ? directoryMatch : keywordMatch?.kind === "registry" ? keywordMatch : null;
+		const score = item.score + IDENTITY_TERM_BOOST * identityTermCoverage(searchText, item.candidate) + (exactIdentifier ? 1 : 0);
+		return {
+			...item.candidate,
+			score,
+			...registryMatch === null ? {} : { match: {
+				...registryMatch,
+				strategy: directory === null ? "keyword" : "keyword-plus-semantic-directory-v1",
+				keywordReasonCodes: keywordMatch?.kind === "registry" ? keywordMatch.keywordReasonCodes : registryMatch.keywordReasonCodes,
+				exactIdentifier
+			} },
+			evidence: [...item.candidate.evidence ?? [], `Registry rank fusion: keyword=${String(item.keywordRank ?? "none")}, directory=${String(item.directoryRank ?? "none")}`]
+		};
+	}).sort((left, right) => (right.score ?? 0) - (left.score ?? 0) || left.id.localeCompare(right.id)).slice(0, limit);
+}
+function registrySearchProvider(baseUrl, fetchImpl = globalThis.fetch, options = {}) {
+	const keywordEndpoint = registryEndpoint(baseUrl, "search");
+	const directoryEndpoint = registryEndpoint(baseUrl, "route");
+	const strategy = options.strategy ?? "hybrid";
 	return {
 		id: "dsh-registry",
 		async search(request) {
 			const text = query(request.query);
-			const response = await fetchImpl(endpoint, {
+			const locale = queryLocale(text);
+			const outputLimit = Math.min(request.maxResults, MAX_PROVIDER_RESULTS);
+			const requestEndpoint = async (endpoint, responseStrategy, limit) => parseRegistryResponse(await fetchImpl(endpoint, {
 				method: "POST",
 				signal: request.signal,
 				headers: {
@@ -1996,17 +2462,20 @@ function registrySearchProvider(baseUrl, fetchImpl = globalThis.fetch) {
 				body: JSON.stringify({
 					schema_version: "1.0.0",
 					query: text,
-					locale: queryLocale(text),
-					limit: Math.min(request.maxResults, MAX_PROVIDER_RESULTS)
+					locale,
+					limit
 				})
-			});
-			if (!response.ok) throw new Error(`DSH Registry search returned HTTP ${response.status}`);
-			const data = await response.json();
-			if (typeof data.snapshot_id !== "string" || !REGISTRY_SNAPSHOT_ID.test(data.snapshot_id) || !Array.isArray(data.candidates)) throw new Error("DSH Registry search returned an invalid discovery response.");
-			return data.candidates.flatMap((candidate) => {
-				const normalized = registryCandidate(candidate, data.snapshot_id);
-				return normalized === null ? [] : [normalized];
-			}).slice(0, Math.min(request.maxResults, MAX_PROVIDER_RESULTS));
+			}), responseStrategy, locale);
+			if (strategy === "keyword") return (await requestEndpoint(keywordEndpoint, "keyword", outputLimit)).candidates.slice(0, outputLimit);
+			const [keywordResult, directoryResult] = await Promise.allSettled([requestEndpoint(keywordEndpoint, "keyword", REGISTRY_KEYWORD_CHALLENGER_POOL), requestEndpoint(directoryEndpoint, "keyword-plus-semantic-directory-v1", REGISTRY_DIRECTORY_POOL)]);
+			const keyword = keywordResult.status === "fulfilled" ? keywordResult.value : null;
+			const directory = directoryResult.status === "fulfilled" ? directoryResult.value : null;
+			if (keyword === null && directory === null) {
+				const reasons = [keywordResult, directoryResult].map((result) => result.status === "rejected" ? result.reason instanceof Error ? result.reason.message : String(result.reason) : "").filter(Boolean);
+				throw new Error(`DSH Registry search failed: ${reasons.join("; ")}`);
+			}
+			if (keyword !== null && directory !== null && keyword.metadata.snapshotId !== directory.metadata.snapshotId) throw new Error("DSH Registry keyword and directory responses reference different snapshots.");
+			return mergeRegistryRankings(text, keyword, directory, outputLimit);
 		}
 	};
 }