relay-dsh-plugin-manager 0.1.0-rc.1

package/lib/index.js

@@ -0,0 +1,1621 @@
+import { t as fail } from "./errors-BGx4K2uq.js";
+import "@deepseek-ai/cordis-plugin-loader";
+import { createUserMessage } from "@deepseek-ai/dsh-llm";
+import { defineTool } from "@deepseek-ai/dsh-tools";
+import { existsSync, mkdirSync, readFileSync, readdirSync, realpathSync, renameSync, rmSync, writeFileSync } from "node:fs";
+import { dirname, join, resolve } from "node:path";
+import { pathToFileURL } from "node:url";
+import { parse, parseDocument } from "yaml";
+import { homedir, tmpdir } from "node:os";
+import { createHash, randomUUID } from "node:crypto";
+import { spawn } from "node:child_process";
+//#region src/conversation.ts
+function jsonValue(value) {
+	return JSON.parse(JSON.stringify(value));
+}
+function renderJson(_args, value) {
+	return [{
+		type: "text",
+		text: JSON.stringify(value, null, 2)
+	}];
+}
+function confirmationCursor(execution) {
+	const session = execution.agent?.session;
+	if (session === void 0) return null;
+	let userMessageSeq = -1;
+	for (const event of session.events) if (event.type === "user/message") userMessageSeq = event.seq;
+	return {
+		sessionId: String(session.id),
+		userMessageSeq
+	};
+}
+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, inspect one npm/GitHub source, or query plugin/operation status. This tool never changes the profile.",
+		parameters: {
+			action: {
+				type: "string",
+				enum: [
+					"list",
+					"search",
+					"inspect",
+					"status"
+				],
+				required: true,
+				description: "The read-only operation."
+			},
+			query: {
+				type: "string",
+				description: "Natural-language search query."
+			},
+			target: {
+				type: "string",
+				description: "npm package, GitHub source, or installed package name."
+			},
+			operationId: {
+				type: "string",
+				description: "Operation id returned by plugin_manage."
+			},
+			maxResults: {
+				type: "integer",
+				description: "Maximum merged search results."
+			}
+		},
+		output: {
+			schema: { type: "json" },
+			render: renderJson
+		},
+		timeoutMs: 35e3,
+		isConcurrencySafe: () => true,
+		execute: async (args, execution) => jsonValue(await manager.discover(args, execution.signal))
+	}));
+	ctx.tools.register(defineTool({
+		name: "plugin_manage",
+		description: "Plan and run DSH plugin mutations. ALWAYS call action=plan first and show its impact. NEVER treat the request that produced a plan as confirmation. Only call action=execute with its confirmationToken after a later, explicit user confirmation. Install sources are npm or GitHub; search providers do not define installers.",
+		parameters: {
+			action: {
+				type: "string",
+				enum: [
+					"plan",
+					"execute",
+					"status",
+					"cancel"
+				],
+				required: true,
+				description: "Lifecycle stage. Mutations require plan followed by execute."
+			},
+			operation: {
+				type: "string",
+				enum: [
+					"install",
+					"remove",
+					"update",
+					"enable",
+					"disable",
+					"restart"
+				],
+				description: "Mutation to plan."
+			},
+			target: {
+				type: "string",
+				description: "Installed package name, or install source when source is omitted."
+			},
+			source: {
+				type: "string",
+				description: "npm package/version or canonical GitHub repository/ref."
+			},
+			confirmationToken: {
+				type: "string",
+				description: "One-use token from a prior plan."
+			},
+			operationId: {
+				type: "string",
+				description: "Tracked operation id."
+			}
+		},
+		output: {
+			schema: { type: "json" },
+			render: renderJson
+		},
+		execute: async (args, execution) => {
+			if (args.action === "plan") {
+				if (args.operation === void 0) fail("INVALID_ACTION", "Planning requires an operation.");
+				const plan = await manager.plan({
+					operation: args.operation,
+					...args.target === void 0 ? {} : { target: args.target },
+					...args.source === void 0 ? {} : { source: args.source }
+				}, execution.signal);
+				const cursor = confirmationCursor(execution);
+				if (cursor === null) fail("CONFIRMATION_REQUIRED", "Planning requires a DSH Agent session.");
+				const now = Date.now();
+				for (const [token, binding] of confirmations) if (binding.expiresAt <= now) confirmations.delete(token);
+				confirmations.set(plan.confirmationToken, {
+					...cursor,
+					expiresAt: Date.parse(plan.expiresAt)
+				});
+				return jsonValue(plan);
+			}
+			if (args.action === "execute") {
+				if (args.confirmationToken === void 0) fail("CONFIRMATION_REQUIRED", "Execution requires a confirmation token.");
+				const binding = confirmations.get(args.confirmationToken);
+				const cursor = confirmationCursor(execution);
+				if (binding === void 0 || cursor === null || cursor.sessionId !== binding.sessionId) fail("CONFIRMATION_REQUIRED", "Confirmation token is not bound to this DSH conversation.");
+				if (cursor.userMessageSeq <= binding.userMessageSeq) fail("CONFIRMATION_REQUIRED", "Wait for a later explicit user confirmation before execution.");
+				confirmations.delete(args.confirmationToken);
+				return jsonValue(manager.execute(args.confirmationToken));
+			}
+			if (args.operationId === void 0) fail("OPERATION_NOT_FOUND", `${args.action} requires an operation id.`);
+			return jsonValue(args.action === "cancel" ? manager.cancel(args.operationId) : manager.operation(args.operationId));
+		}
+	}));
+	ctx.commands.register({
+		name: "plugins",
+		description: "manage DSH plugins through this conversation",
+		input: { hint: "<request>" },
+		handler: ({ agent, rawInput }) => {
+			const request = rawInput.trim() === "" ? "List the installed DSH plugins and summarize their status." : rawInput.trim();
+			agent.steer(createUserMessage({
+				content: [{
+					type: "text",
+					text: request
+				}],
+				source: { kind: "user" }
+			}));
+			return {
+				kind: "success",
+				text: "Plugin request submitted to this conversation."
+			};
+		}
+	});
+}
+//#endregion
+//#region src/hot-runtime.ts
+function parseSimpleHotPatch(text) {
+	let value;
+	try {
+		value = parse(text);
+	} catch {
+		return null;
+	}
+	if (!Array.isArray(value) || value.length === 0) return null;
+	const rows = [];
+	for (const patch of value) {
+		if (typeof patch !== "object" || patch === null || Array.isArray(patch)) return null;
+		if (Object.keys(patch).length !== 1 || !Array.isArray(patch.insert)) return null;
+		for (const raw of patch.insert) {
+			if (typeof raw !== "object" || raw === null || Array.isArray(raw)) return null;
+			const entry = raw;
+			if (Object.keys(entry).some((key) => key !== "id" && key !== "name")) return null;
+			if (typeof entry.id !== "string" || entry.id === "" || typeof entry.name !== "string" || entry.name === "") return null;
+			rows.push({
+				id: entry.id,
+				name: entry.name
+			});
+		}
+	}
+	return rows.length === 0 ? null : rows;
+}
+var HotRuntime = class {
+	handles = /* @__PURE__ */ new Map();
+	sequence = 0;
+	includeClass;
+	ctx;
+	profileDir;
+	timeoutMs;
+	loadInclude;
+	constructor(ctx, profileDir, timeoutMs = 1e4, loadInclude) {
+		this.ctx = ctx;
+		this.profileDir = profileDir;
+		this.timeoutMs = timeoutMs;
+		this.loadInclude = loadInclude;
+		this.clean();
+	}
+	hotDir() {
+		return join(this.profileDir, ".relay-plugin-manager");
+	}
+	clean() {
+		let files;
+		try {
+			files = readdirSync(this.hotDir());
+		} catch {
+			return;
+		}
+		for (const file of files) if (/^hot-\d+\.yml$/u.test(file)) rmSync(join(this.hotDir(), file), { force: true });
+	}
+	async include() {
+		if (this.includeClass !== void 0) return this.includeClass;
+		if (this.loadInclude !== void 0) {
+			this.includeClass = await this.loadInclude();
+			return this.includeClass;
+		}
+		try {
+			const module = await import("@deepseek-ai/cordis-plugin-include");
+			const Include = module.Include ?? module.default;
+			if (Include === void 0) throw new Error("missing Include export");
+			this.includeClass = class RuntimeHotInclude extends Include {
+				write() {}
+			};
+		} catch {
+			this.includeClass = null;
+		}
+		return this.includeClass;
+	}
+	async activate(surface) {
+		if (this.handles.has(surface.packageName)) return {
+			active: true,
+			restartRequired: false,
+			reason: null
+		};
+		const Include = await this.include();
+		if (Include === null) return {
+			active: false,
+			restartRequired: true,
+			reason: "DSH Include runtime is unavailable."
+		};
+		let rows = null;
+		if (surface.bundlePatch !== null) {
+			try {
+				rows = parseSimpleHotPatch(readFileSync(join(this.profileDir, "node_modules", surface.packageName, surface.bundlePatch), "utf8"));
+			} catch {
+				rows = null;
+			}
+			if (rows === null) return {
+				active: false,
+				restartRequired: true,
+				reason: "Bundle patch is not a plain insert-only patch."
+			};
+		} else if (surface.client) rows = [{
+			id: `client-${surface.packageName.replace(/[^A-Za-z0-9_.-]/gu, "-")}`,
+			name: surface.packageName
+		}];
+		else return {
+			active: false,
+			restartRequired: true,
+			reason: "Package has no hot-activatable DSH surface."
+		};
+		mkdirSync(this.hotDir(), {
+			recursive: true,
+			mode: 448
+		});
+		const file = join(this.hotDir(), `hot-${String(++this.sequence)}.yml`);
+		writeFileSync(file, rows.map((row) => ["- id: " + JSON.stringify(`rpm-${row.id}`), "  name: " + JSON.stringify(row.name)].join("\n")).join("\n") + "\n", { mode: 384 });
+		let handle;
+		let timeout;
+		try {
+			handle = this.ctx.plugin(Include, { path: pathToFileURL(file).href });
+			await Promise.race([handle.await(), new Promise((_resolve, reject) => {
+				timeout = setTimeout(() => reject(/* @__PURE__ */ new Error("hot activation timed out")), this.timeoutMs);
+			})]);
+			this.handles.set(surface.packageName, handle);
+			return {
+				active: true,
+				restartRequired: false,
+				reason: null
+			};
+		} catch (error) {
+			try {
+				await handle?.dispose();
+			} catch {}
+			return {
+				active: false,
+				restartRequired: true,
+				reason: error instanceof Error ? error.message : String(error)
+			};
+		} finally {
+			if (timeout !== void 0) clearTimeout(timeout);
+		}
+	}
+	async deactivate(packageName) {
+		const handle = this.handles.get(packageName);
+		if (handle === void 0) return false;
+		this.handles.delete(packageName);
+		try {
+			await handle.dispose();
+			return true;
+		} catch {
+			return false;
+		}
+	}
+	isActive(packageName) {
+		return this.handles.has(packageName);
+	}
+};
+//#endregion
+//#region src/source.ts
+const EXACT_SEMVER = /^(0|[1-9]\d*)\.(0|[1-9]\d*)\.(0|[1-9]\d*)(?:-[0-9A-Za-z-]+(?:\.[0-9A-Za-z-]+)*)?(?:\+[0-9A-Za-z-]+(?:\.[0-9A-Za-z-]+)*)?$/u;
+const NPM_NAME = /^(?:@[a-z0-9][a-z0-9._-]*\/)?[a-z0-9][a-z0-9._-]*$/u;
+const FULL_COMMIT = /^[a-f0-9]{40}$/iu;
+const GITHUB_PART = /^[A-Za-z0-9](?:[A-Za-z0-9_.-]{0,98}[A-Za-z0-9])?$/u;
+const UNSAFE_TOKEN = /[\u0000-\u0020\u007f;&|`$<>]/u;
+function safeToken(value) {
+	const source = String(value ?? "").trim();
+	if (source === "" || source.startsWith("-") || UNSAFE_TOKEN.test(source)) fail("INVALID_SOURCE", "Plugin source must be one safe npm or GitHub token.");
+	return source;
+}
+function parseNpmSpec(value, requireExact = false) {
+	const spec = safeToken(value);
+	let packageName = spec;
+	let version;
+	const separator = spec.lastIndexOf("@");
+	const scopedBoundary = spec.startsWith("@") ? spec.indexOf("/") : -1;
+	if (separator > Math.max(0, scopedBoundary)) {
+		packageName = spec.slice(0, separator);
+		version = spec.slice(separator + 1);
+	}
+	if (!NPM_NAME.test(packageName)) fail("INVALID_NPM_SPEC", "Plugin source is not a valid npm package name.");
+	if (version !== void 0 && !EXACT_SEMVER.test(version)) fail("INVALID_NPM_VERSION", "npm plugin versions must be exact semantic versions.");
+	if (requireExact && version === void 0) fail("IMMUTABLE_SOURCE_REQUIRED", "Installation requires an exact npm version.");
+	return {
+		kind: "npm",
+		package: packageName,
+		...version === void 0 ? {} : { version }
+	};
+}
+function validGithubPart(value) {
+	return GITHUB_PART.test(value) && value !== "." && value !== ".." && !value.endsWith(".git");
+}
+function parseGithubSpec(value, requireCommit = false) {
+	const spec = safeToken(value);
+	let owner;
+	let repo;
+	let ref;
+	if (spec.startsWith("github:")) {
+		const match = /^github:([^/]+)\/([^#]+?)(?:#(.+))?$/u.exec(spec);
+		if (match === null) fail("INVALID_GITHUB_SPEC", "GitHub source must use github:owner/repo[#ref].");
+		owner = match[1];
+		repo = match[2];
+		ref = match[3];
+	} else if (spec.startsWith("https://github.com/")) {
+		let url;
+		try {
+			url = new URL(spec);
+		} catch {
+			fail("INVALID_GITHUB_SPEC", "GitHub URL is invalid.");
+		}
+		if (url.protocol !== "https:" || url.hostname !== "github.com" || url.search !== "") fail("INVALID_GITHUB_SPEC", "Only canonical HTTPS github.com repository URLs are supported.");
+		const parts = url.pathname.split("/").filter(Boolean);
+		owner = parts[0];
+		repo = parts[1]?.replace(/\.git$/u, "");
+		if (parts.length > 2) {
+			if (parts[2] !== "tree" && parts[2] !== "commit" || parts.length < 4) fail("INVALID_GITHUB_SPEC", "GitHub URL must identify a repository, tree, or commit.");
+			ref = decodeURIComponent(parts.slice(3).join("/"));
+		} else if (url.hash !== "") fail("INVALID_GITHUB_SPEC", "Use a tree/commit URL or github:owner/repo#ref for GitHub refs.");
+	} else if (/^[A-Za-z][A-Za-z0-9+.-]*:\/\//u.test(spec)) fail("INVALID_GITHUB_SPEC", "Only canonical HTTPS github.com repository URLs are supported.");
+	else return null;
+	if (!validGithubPart(owner ?? "") || !validGithubPart(repo ?? "")) fail("INVALID_GITHUB_SPEC", "GitHub owner or repository name is invalid.");
+	if (ref !== void 0 && (ref === "" || ref.length > 200 || UNSAFE_TOKEN.test(ref))) fail("INVALID_GITHUB_REF", "GitHub ref is invalid.");
+	if (requireCommit && !FULL_COMMIT.test(ref ?? "")) fail("IMMUTABLE_SOURCE_REQUIRED", "Installation requires a full GitHub commit.");
+	return {
+		kind: "github",
+		owner,
+		repo,
+		...ref === void 0 ? {} : { ref }
+	};
+}
+function parsePluginSource(value) {
+	if (typeof value === "string") return parseGithubSpec(value) ?? parseNpmSpec(value);
+	if (value.kind === "npm") return parseNpmSpec(`${value.package}${value.version === void 0 ? "" : `@${value.version}`}`);
+	return parseGithubSpec(`github:${value.owner}/${value.repo}${value.ref === void 0 ? "" : `#${value.ref}`}`);
+}
+function renderSource(source) {
+	if (source.kind === "npm") return `${source.package}${source.version === void 0 ? "" : `@${source.version}`}`;
+	return `github:${source.owner}/${source.repo}${source.ref === void 0 ? "" : `#${source.ref}`}`;
+}
+function manifestDsh(value) {
+	if (typeof value !== "object" || value === null || Array.isArray(value)) return {
+		bundlePatch: null,
+		client: false
+	};
+	const dsh = value.dsh;
+	if (typeof dsh !== "object" || dsh === null || Array.isArray(dsh)) return {
+		bundlePatch: null,
+		client: false
+	};
+	const bundle = dsh.bundle;
+	const patch = typeof bundle === "object" && bundle !== null && !Array.isArray(bundle) ? bundle.patch : void 0;
+	return {
+		bundlePatch: typeof patch === "string" && patch.trim() !== "" ? patch : null,
+		client: dsh.client !== void 0
+	};
+}
+function validatePluginManifest(manifest, expectedName) {
+	if (typeof manifest !== "object" || manifest === null || Array.isArray(manifest)) fail("INVALID_PLUGIN_MANIFEST", "Plugin package manifest must be an object.");
+	const packageName = String(manifest.name ?? "");
+	if (!NPM_NAME.test(packageName)) fail("INVALID_PLUGIN_MANIFEST", "Plugin manifest has no valid package name.");
+	if (expectedName !== void 0 && packageName !== expectedName) fail("PACKAGE_NAME_MISMATCH", "Resolved package name does not match the requested npm package.");
+	const surface = manifestDsh(manifest);
+	if (surface.bundlePatch === null && !surface.client) fail("NOT_DSH_PLUGIN", `${packageName} declares neither dsh.bundle.patch nor dsh.client.`);
+	return {
+		packageName,
+		...surface
+	};
+}
+async function fetchJson(url, options, headers = {}) {
+	const fetchImpl = options.fetch ?? globalThis.fetch;
+	let response;
+	try {
+		response = await fetchImpl(url, {
+			headers: {
+				accept: "application/json",
+				...headers
+			},
+			redirect: "follow",
+			signal: options.signal
+		});
+	} catch (error) {
+		fail("NETWORK_ERROR", `Could not reach plugin source: ${error instanceof Error ? error.message : String(error)}`);
+	}
+	if (!response.ok) fail("SOURCE_HTTP_ERROR", `Plugin source returned HTTP ${response.status}.`, {
+		url,
+		status: response.status
+	});
+	try {
+		return await response.json();
+	} catch {
+		fail("INVALID_SOURCE_METADATA", "Plugin source returned invalid JSON metadata.", { url });
+	}
+}
+function repositoryIdentity(value) {
+	const raw = typeof value === "string" ? value : typeof value === "object" && value !== null ? value.url : void 0;
+	if (typeof raw !== "string" || raw.trim() === "") return null;
+	const normalized = raw.trim().replace(/^git\+/u, "").replace(/^git@github\.com:/u, "https://github.com/").replace(/^github:/u, "https://github.com/").replace(/\.git(?:#.*)?$/u, "").replace(/\/$/u, "");
+	const match = /^https:\/\/github\.com\/([^/]+)\/([^/]+)$/iu.exec(normalized);
+	return match === null ? normalized.toLowerCase() : `github.com/${match[1].toLowerCase()}/${match[2].toLowerCase()}`;
+}
+function npmMetadataUrl(name, version) {
+	return `https://registry.npmjs.org/${encodeURIComponent(name).replace(/^%40/u, "@")}/${encodeURIComponent(version ?? "latest")}`;
+}
+async function inspectNpm(source, options = {}) {
+	const manifest = await fetchJson(npmMetadataUrl(source.package, source.version), options);
+	const plugin = validatePluginManifest(manifest, source.package);
+	const version = String(manifest.version ?? "");
+	if (!EXACT_SEMVER.test(version)) fail("INVALID_NPM_VERSION", "Registry metadata has no exact semantic version.");
+	const integrity = manifest.dist?.integrity;
+	if (typeof integrity !== "string" || !/^sha512-[A-Za-z0-9+/=]+$/u.test(integrity)) fail("NPM_INTEGRITY_MISSING", "Registry metadata has no SHA-512 package integrity.");
+	const exact = {
+		kind: "npm",
+		package: plugin.packageName,
+		version
+	};
+	return {
+		source: exact,
+		sourceType: "npm",
+		requestedSpec: renderSource(source),
+		installSpec: renderSource(exact),
+		packageName: plugin.packageName,
+		version,
+		integrity,
+		repository: repositoryIdentity(manifest.repository),
+		description: typeof manifest.description === "string" ? manifest.description : null,
+		bundlePatch: plugin.bundlePatch,
+		client: plugin.client
+	};
+}
+function githubHeaders(env = process.env) {
+	const token = env.GITHUB_TOKEN ?? env.GH_TOKEN;
+	return {
+		"user-agent": "relay-dsh-plugin-manager",
+		"x-github-api-version": "2022-11-28",
+		...token === void 0 || token === "" ? {} : { authorization: `Bearer ${token}` }
+	};
+}
+async function inspectGithub(source, options = {}) {
+	const headers = githubHeaders(options.env);
+	let ref = source.ref;
+	if (ref === void 0) {
+		const repository = await fetchJson(`https://api.github.com/repos/${source.owner}/${source.repo}`, options, headers);
+		ref = typeof repository.default_branch === "string" ? repository.default_branch : void 0;
+		if (ref === void 0 || ref === "") fail("INVALID_SOURCE_METADATA", "GitHub repository has no default branch.");
+	}
+	const commit = await fetchJson(`https://api.github.com/repos/${source.owner}/${source.repo}/commits/${encodeURIComponent(ref)}`, options, headers);
+	const sha = String(commit.sha ?? "").toLowerCase();
+	if (!FULL_COMMIT.test(sha)) fail("INVALID_SOURCE_METADATA", "GitHub did not resolve the source to a full commit.");
+	const manifest = await fetchJson(`https://raw.githubusercontent.com/${source.owner}/${source.repo}/${sha}/package.json`, options);
+	const plugin = validatePluginManifest(manifest);
+	const exact = {
+		kind: "github",
+		owner: source.owner,
+		repo: source.repo,
+		ref: sha
+	};
+	return {
+		source: exact,
+		sourceType: "github",
+		requestedSpec: renderSource(source),
+		installSpec: renderSource(exact),
+		packageName: plugin.packageName,
+		commit: sha,
+		repository: `github.com/${source.owner.toLowerCase()}/${source.repo.toLowerCase()}`,
+		description: typeof manifest.description === "string" ? manifest.description : null,
+		bundlePatch: plugin.bundlePatch,
+		client: plugin.client
+	};
+}
+async function inspectPluginSource(value, options = {}) {
+	const source = parsePluginSource(value);
+	return source.kind === "npm" ? inspectNpm(source, options) : inspectGithub(source, options);
+}
+function inspectionIdentity(inspection) {
+	return inspection.repository ?? `${inspection.sourceType}:${inspection.packageName.toLowerCase()}`;
+}
+//#endregion
+//#region src/search.ts
+function searchQuery(value) {
+	const query = value.trim();
+	if (query === "" || query.length > 120 || /[\u0000-\u001f\u007f]/u.test(query)) fail("INVALID_SEARCH_QUERY", "Search query must contain 1 to 120 printable characters.");
+	return query;
+}
+function abortReason(signal) {
+	return signal.reason instanceof Error ? signal.reason : /* @__PURE__ */ new Error("search cancelled");
+}
+async function searchProvider(provider, query, maxResults, parent, timeoutMs) {
+	const controller = new AbortController();
+	const onAbort = () => controller.abort(parent?.reason);
+	if (parent?.aborted === true) throw abortReason(parent);
+	parent?.addEventListener("abort", onAbort, { once: true });
+	const timeout = setTimeout(() => controller.abort(/* @__PURE__ */ new Error(`provider timed out after ${timeoutMs}ms`)), timeoutMs);
+	try {
+		const result = await provider.search({
+			query,
+			maxResults,
+			signal: controller.signal
+		});
+		if (!Array.isArray(result)) throw new TypeError("provider result must be an array");
+		return result.slice(0, maxResults);
+	} finally {
+		clearTimeout(timeout);
+		parent?.removeEventListener("abort", onAbort);
+	}
+}
+function candidateSources(provider, rows) {
+	const output = [];
+	const ranked = [...rows].sort((left, right) => (right.score ?? 0) - (left.score ?? 0) || left.id.localeCompare(right.id));
+	for (const [rank, candidate] of ranked.entries()) {
+		if (typeof candidate.id !== "string" || candidate.id.trim() === "" || !Array.isArray(candidate.sources)) continue;
+		for (const raw of candidate.sources.slice(0, 3)) try {
+			output.push({
+				source: parsePluginSource(raw),
+				provider,
+				evidence: [...candidate.evidence ?? []].filter((value) => typeof value === "string").slice(0, 5),
+				rank
+			});
+		} catch {}
+	}
+	return output;
+}
+async function searchPlugins(runtime, rawQuery, options = {}) {
+	const query = searchQuery(rawQuery);
+	const maxResults = Math.max(1, Math.min(20, options.maxResults ?? 6));
+	const timeoutMs = Math.max(100, options.providerTimeoutMs ?? 1e4);
+	const providers = runtime.entries();
+	const settled = await Promise.allSettled(providers.map(async (provider) => ({
+		provider: provider.id,
+		rows: await searchProvider(provider, query, maxResults, options.signal, timeoutMs)
+	})));
+	if (options.signal?.aborted === true) throw abortReason(options.signal);
+	const providerErrors = [];
+	const discovered = [];
+	for (let index = 0; index < settled.length; index += 1) {
+		const result = settled[index];
+		const provider = providers[index].id;
+		if (result.status === "rejected") {
+			providerErrors.push({
+				provider,
+				error: result.reason instanceof Error ? result.reason.message : String(result.reason)
+			});
+			continue;
+		}
+		discovered.push(...candidateSources(result.value.provider, result.value.rows));
+	}
+	const inspect = options.inspect ?? inspectPluginSource;
+	const inspected = await Promise.all(discovered.map(async (item) => {
+		try {
+			return {
+				ok: true,
+				item,
+				inspection: await inspect(item.source, options)
+			};
+		} catch {
+			return { ok: false };
+		}
+	}));
+	const projects = /* @__PURE__ */ new Map();
+	let rejectedCandidates = 0;
+	for (const result of inspected) {
+		if (!result.ok) {
+			rejectedCandidates += 1;
+			continue;
+		}
+		const identity = inspectionIdentity(result.inspection);
+		const existing = projects.get(identity) ?? {
+			identity,
+			packageName: result.inspection.packageName,
+			description: result.inspection.description,
+			repository: result.inspection.repository,
+			sources: [],
+			recommendedSource: result.inspection.installSpec,
+			rank: result.item.rank
+		};
+		const sameSource = existing.sources.find((source) => source.inspection.installSpec === result.inspection.installSpec);
+		if (sameSource === void 0) existing.sources.push({
+			inspection: result.inspection,
+			providers: [result.item.provider],
+			evidence: [...result.item.evidence]
+		});
+		else {
+			if (!sameSource.providers.includes(result.item.provider)) sameSource.providers.push(result.item.provider);
+			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.recommendedSource = existing.sources.find((source) => source.inspection.sourceType === "npm")?.inspection.installSpec ?? existing.sources[0].inspection.installSpec;
+		projects.set(identity, existing);
+	}
+	return {
+		query,
+		candidates: [...projects.values()].sort((left, right) => left.rank - right.rank || left.packageName.localeCompare(right.packageName)).slice(0, maxResults).map(({ rank: _rank, ...candidate }) => candidate),
+		providerErrors,
+		rejectedCandidates
+	};
+}
+const STATE_VERSION = 1;
+const STATE_DIR = ".relay-plugin-manager";
+function readJsonObject(file, missing) {
+	try {
+		const parsed = JSON.parse(readFileSync(file, "utf8"));
+		if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed)) return missing;
+		return parsed;
+	} catch (error) {
+		if (error.code === "ENOENT") return missing;
+		fail("PROFILE_READ_FAILED", `Could not read ${file}: ${error instanceof Error ? error.message : String(error)}`);
+	}
+}
+function atomicWrite(file, text) {
+	try {
+		mkdirSync(dirname(file), {
+			recursive: true,
+			mode: 448
+		});
+		const temporary = `${file}.tmp-${process.pid}-${Date.now()}`;
+		writeFileSync(temporary, text, { mode: 384 });
+		renameSync(temporary, file);
+	} catch (error) {
+		fail("PROFILE_WRITE_FAILED", `Could not write ${file}: ${error instanceof Error ? error.message : String(error)}`);
+	}
+}
+function writeProfileManifest(dir, manifest) {
+	atomicWrite(join(dir, "package.json"), `${JSON.stringify(manifest, null, 2)}\n`);
+}
+function reconcileRemovedPackage(dir, packageName) {
+	const manifest = readProfileManifest(dir);
+	if (manifest.dependencies !== void 0) delete manifest.dependencies[packageName];
+	const bundles = manifest.dsh?.profile?.bundles;
+	if (bundles !== void 0) manifest.dsh.profile.bundles = bundles.filter((name) => name !== packageName);
+	writeProfileManifest(dir, manifest);
+}
+function dshHome(env = process.env) {
+	const configured = env.DSH_HOME?.trim();
+	return resolve(configured === void 0 || configured === "" ? join(homedir(), ".dsh") : configured);
+}
+function profileDirectory(profile = "web", env = process.env) {
+	return join(dshHome(env), "profiles", profile);
+}
+function readProfileManifest(dir) {
+	return readJsonObject(join(dir, "package.json"), {});
+}
+function profileManifestText(dir) {
+	try {
+		return readFileSync(join(dir, "package.json"), "utf8");
+	} catch (error) {
+		if (error.code === "ENOENT") return null;
+		fail("PROFILE_READ_FAILED", `Could not read profile manifest: ${error instanceof Error ? error.message : String(error)}`);
+	}
+}
+function restoreProfileManifest(dir, text) {
+	if (text === null) return;
+	atomicWrite(join(dir, "package.json"), text);
+}
+function packageManifest(dir, packageName) {
+	const file = join(dir, "node_modules", packageName, "package.json");
+	if (!existsSync(file)) return null;
+	return readJsonObject(file, {});
+}
+function bundleEntryIds(dir, packageName, patch) {
+	try {
+		const document = parseDocument(readFileSync(join(dir, "node_modules", packageName, patch), "utf8"));
+		if (document.errors.length > 0 || !Array.isArray(document.toJS())) return null;
+		const ids = [];
+		for (const row of document.toJS()) {
+			if (typeof row !== "object" || row === null || Array.isArray(row)) continue;
+			const inserted = row.insert;
+			if (!Array.isArray(inserted)) continue;
+			for (const entry of inserted) {
+				if (typeof entry !== "object" || entry === null || Array.isArray(entry)) return null;
+				const id = entry.id;
+				if (typeof id !== "string" || id.trim() === "") return null;
+				if (!ids.includes(id)) ids.push(id);
+			}
+		}
+		return ids.length === 0 ? null : ids;
+	} catch {
+		return null;
+	}
+}
+function packageSurface(dir, packageName, source) {
+	const manifest = packageManifest(dir, packageName);
+	const dsh = typeof manifest?.dsh === "object" && manifest.dsh !== null && !Array.isArray(manifest.dsh) ? manifest.dsh : {};
+	const bundle = typeof dsh.bundle === "object" && dsh.bundle !== null && !Array.isArray(dsh.bundle) ? dsh.bundle : {};
+	const patch = typeof bundle.patch === "string" && bundle.patch.trim() !== "" ? bundle.patch : null;
+	return {
+		packageName,
+		source,
+		bundle: patch !== null,
+		bundlePatch: patch,
+		client: dsh.client !== void 0,
+		entryIds: patch === null ? null : bundleEntryIds(dir, packageName, patch)
+	};
+}
+function statePath(dir) {
+	return join(dir, STATE_DIR, "state.json");
+}
+function readManagerState(dir) {
+	const state = readJsonObject(statePath(dir), {});
+	const disabled = {};
+	if (state.version === STATE_VERSION && typeof state.disabled === "object" && state.disabled !== null) {
+		for (const [name, ids] of Object.entries(state.disabled)) if (Array.isArray(ids) && ids.every((id) => typeof id === "string")) disabled[name] = [...new Set(ids)];
+	}
+	return {
+		version: STATE_VERSION,
+		disabled
+	};
+}
+function writeManagerState(dir, state) {
+	atomicWrite(statePath(dir), `${JSON.stringify(state, null, 2)}\n`);
+}
+function patchDocument(file) {
+	let source = "[]\n";
+	try {
+		source = readFileSync(file, "utf8");
+	} catch (error) {
+		if (error.code !== "ENOENT") fail("PROFILE_READ_FAILED", `Could not read profile patch: ${error instanceof Error ? error.message : String(error)}`);
+	}
+	const document = parseDocument(source);
+	if (document.errors.length > 0) fail("ENABLEMENT_CONFLICT", "Profile cordis.patch.yml is not valid YAML.");
+	const value = document.toJS();
+	if (value === null) document.contents = document.createNode([]);
+	else if (!Array.isArray(value)) fail("ENABLEMENT_CONFLICT", "Profile cordis.patch.yml must contain a patch list.");
+	return document;
+}
+function exactDisabledRow(value, id) {
+	if (typeof value !== "object" || value === null || Array.isArray(value)) return false;
+	return Object.keys(value).length === 2 && value.id === id && value.disabled === true;
+}
+function disablePackage(dir, surface) {
+	if (surface.packageName === "relay-dsh-plugin-manager") fail("PROTECTED_PLUGIN", "The plugin manager cannot disable itself.");
+	if (surface.entryIds === null || surface.entryIds.length === 0) fail("ENABLEMENT_UNSUPPORTED", `${surface.packageName} has no safely attributable Loader entry ids.`);
+	const file = join(dir, "cordis.patch.yml");
+	const state = readManagerState(dir);
+	const document = patchDocument(file);
+	const rows = document.toJS();
+	const alreadyOwned = new Set(state.disabled[surface.packageName] ?? []);
+	for (const id of surface.entryIds) {
+		const existing = rows.find((row) => typeof row === "object" && row !== null && !Array.isArray(row) && row.id === id);
+		if (existing !== void 0 && !(alreadyOwned.has(id) && exactDisabledRow(existing, id))) fail("ENABLEMENT_CONFLICT", `Profile patch already owns Loader entry "${id}"; it will not be overwritten.`);
+		if (existing === void 0) document.add({
+			id,
+			disabled: true
+		});
+	}
+	state.disabled[surface.packageName] = [...surface.entryIds];
+	atomicWrite(file, document.toString());
+	writeManagerState(dir, state);
+	return [...surface.entryIds];
+}
+function enablePackage(dir, surface) {
+	if (surface.packageName === "relay-dsh-plugin-manager") fail("PROTECTED_PLUGIN", "The plugin manager cannot change its own enablement.");
+	const state = readManagerState(dir);
+	const owned = state.disabled[surface.packageName];
+	if (owned === void 0 || owned.length === 0) return [];
+	const file = join(dir, "cordis.patch.yml");
+	const document = patchDocument(file);
+	const rows = document.toJS();
+	for (const id of owned) if (rows.filter((row) => typeof row === "object" && row !== null && !Array.isArray(row) && row.id === id).some((row) => !exactDisabledRow(row, id))) fail("ENABLEMENT_CONFLICT", `Manager-owned Loader entry "${id}" was modified and will not be removed.`);
+	const keep = rows.filter((row) => !owned.some((id) => exactDisabledRow(row, id)));
+	document.contents = document.createNode(keep);
+	delete state.disabled[surface.packageName];
+	atomicWrite(file, document.toString());
+	writeManagerState(dir, state);
+	return [...owned];
+}
+function runtimeState(entries) {
+	const phases = entries.map((entry) => entry.phase);
+	if (phases.includes("failed")) return "failed";
+	if (phases.includes("active")) return "active";
+	if (phases.some((phase) => phase === "loading" || phase === "pending")) return "loading";
+	if (entries.length > 0) return "inactive";
+	return "unknown";
+}
+function listPluginStatuses(dir, loaderEntries = []) {
+	const manifest = readProfileManifest(dir);
+	const bundles = new Set(manifest.dsh?.profile?.bundles ?? []);
+	const state = readManagerState(dir);
+	return Object.entries(manifest.dependencies ?? {}).sort(([left], [right]) => left.localeCompare(right)).map(([packageName, source]) => {
+		const surface = packageSurface(dir, packageName, source);
+		const ids = surface.entryIds;
+		const entries = ids === null ? [] : loaderEntries.filter((entry) => ids.includes(entry.id));
+		let enablement = "unknown";
+		if (ids !== null) {
+			const disabledIds = new Set(state.disabled[packageName] ?? []);
+			const disabled = ids.filter((id) => disabledIds.has(id) || entries.some((entry) => entry.id === id && entry.disabled)).length;
+			enablement = disabled === 0 ? "enabled" : disabled === ids.length ? "disabled" : "mixed";
+		}
+		const runtime = runtimeState(entries);
+		return {
+			packageName,
+			source,
+			bundle: bundles.has(packageName) || surface.bundle,
+			enablement,
+			runtime,
+			restartRequired: surface.bundle && runtime === "unknown" && !state.disabled[packageName],
+			entryIds: ids
+		};
+	});
+}
+//#endregion
+//#region src/plans.ts
+var PlanStore = class {
+	plans = /* @__PURE__ */ new Map();
+	used = /* @__PURE__ */ new Set();
+	now;
+	random;
+	ttlMs;
+	constructor(options = {}) {
+		this.now = options.now ?? Date.now;
+		this.random = options.random ?? randomUUID;
+		this.ttlMs = options.ttlMs ?? 10 * 6e4;
+	}
+	create(input) {
+		const created = this.now();
+		const id = this.random();
+		const confirmationToken = this.random();
+		const digest = createHash("sha256").update(JSON.stringify({
+			id,
+			...input
+		})).digest("hex");
+		const plan = Object.freeze({
+			...input,
+			id,
+			digest,
+			confirmationToken,
+			createdAt: new Date(created).toISOString(),
+			expiresAt: new Date(created + this.ttlMs).toISOString()
+		});
+		this.plans.set(confirmationToken, plan);
+		return plan;
+	}
+	consume(token) {
+		if (this.used.has(token)) fail("CONFIRMATION_REPLAYED", "Confirmation token has already been used.");
+		const plan = this.plans.get(token);
+		if (plan === void 0) fail("CONFIRMATION_REQUIRED", "A valid confirmation token is required.");
+		this.plans.delete(token);
+		this.used.add(token);
+		if (this.now() >= Date.parse(plan.expiresAt)) fail("CONFIRMATION_EXPIRED", "Confirmation token has expired.");
+		return plan;
+	}
+};
+//#endregion
+//#region src/operations.ts
+var OperationTracker = class {
+	records = /* @__PURE__ */ new Map();
+	active = null;
+	random;
+	now;
+	constructor(options = {}) {
+		this.random = options.random ?? randomUUID;
+		this.now = options.now ?? Date.now;
+	}
+	start(action, target, execute) {
+		if (this.active !== null) fail("OPERATION_BUSY", `Plugin operation ${this.active} is still running.`);
+		const id = this.random();
+		const controller = new AbortController();
+		const snapshot = {
+			id,
+			action,
+			target,
+			status: "queued",
+			progress: "queued",
+			startedAt: new Date(this.now()).toISOString()
+		};
+		const record = {
+			snapshot,
+			controller,
+			done: Promise.resolve()
+		};
+		this.records.set(id, record);
+		this.active = id;
+		record.done = Promise.resolve().then(async () => {
+			snapshot.status = "running";
+			snapshot.progress = "running";
+			try {
+				const result = await execute({
+					signal: controller.signal,
+					progress: (message) => {
+						snapshot.progress = message.slice(0, 500);
+					}
+				});
+				if (controller.signal.aborted) {
+					snapshot.status = "cancelled";
+					snapshot.progress = "cancelled";
+				} else {
+					snapshot.status = "succeeded";
+					snapshot.progress = "completed";
+					snapshot.result = result;
+				}
+			} catch (error) {
+				if (controller.signal.aborted) {
+					snapshot.status = "cancelled";
+					snapshot.progress = "cancelled";
+				} else {
+					snapshot.status = "failed";
+					snapshot.progress = "failed";
+					snapshot.error = {
+						...typeof error === "object" && error !== null && "code" in error && typeof error.code === "string" ? { code: error.code } : {},
+						message: error instanceof Error ? error.message : String(error)
+					};
+				}
+			} finally {
+				snapshot.finishedAt = new Date(this.now()).toISOString();
+				if (this.active === id) this.active = null;
+			}
+		});
+		return structuredClone(snapshot);
+	}
+	get(id) {
+		const record = this.records.get(id);
+		if (record === void 0) fail("OPERATION_NOT_FOUND", `Plugin operation ${id} was not found.`);
+		return structuredClone(record.snapshot);
+	}
+	cancel(id) {
+		const record = this.records.get(id);
+		if (record === void 0) fail("OPERATION_NOT_FOUND", `Plugin operation ${id} was not found.`);
+		if (record.snapshot.status === "queued" || record.snapshot.status === "running") {
+			record.snapshot.progress = "cancelling";
+			record.controller.abort(/* @__PURE__ */ new Error("Plugin operation cancelled by user."));
+		}
+		return structuredClone(record.snapshot);
+	}
+	async wait(id) {
+		const record = this.records.get(id);
+		if (record === void 0) fail("OPERATION_NOT_FOUND", `Plugin operation ${id} was not found.`);
+		await record.done;
+		return this.get(id);
+	}
+};
+//#endregion
+//#region src/manager.ts
+const FIBER_PHASE = {
+	0: "pending",
+	1: "loading",
+	2: "active",
+	3: "failed",
+	4: null,
+	5: "unloading"
+};
+const PROTECTED_ENTRY_IDS = /* @__PURE__ */ new Set([
+	"relay-plugin-search-runtime",
+	"relay-plugin-manager-host",
+	"commands",
+	"tools",
+	"webserver",
+	"web-runtime"
+]);
+function safePackageName(value) {
+	const name = value?.trim() ?? "";
+	if (!NPM_NAME.test(name)) fail("INVALID_NPM_SPEC", "A valid installed package name is required.");
+	return name;
+}
+function commandResult(result) {
+	return {
+		exitCode: result.exitCode,
+		stdout: result.stdout,
+		stderr: result.stderr
+	};
+}
+function installedPackageManifest(profileDir, packageName) {
+	try {
+		return JSON.parse(readFileSync(join(profileDir, "node_modules", packageName, "package.json"), "utf8"));
+	} catch {
+		return null;
+	}
+}
+function installedSourceMatches(packageName, dependency, installSpec) {
+	if (parseGithubSpec(installSpec, true) !== null) return dependency === installSpec;
+	const npm = parseNpmSpec(installSpec, true);
+	return npm.package === packageName && dependency === npm.version;
+}
+var PluginManager = class {
+	profileDir;
+	searchRuntime;
+	runner;
+	hot;
+	restarter;
+	loader;
+	inspect;
+	plans;
+	operations;
+	fetchOptions;
+	hmrTimeoutMs;
+	constructor(dependencies) {
+		this.profileDir = dependencies.profileDir;
+		this.searchRuntime = dependencies.searchRuntime;
+		this.runner = dependencies.runner;
+		this.hot = dependencies.hot;
+		this.restarter = dependencies.restarter;
+		this.loader = dependencies.loader;
+		this.inspect = dependencies.inspect ?? inspectPluginSource;
+		this.plans = dependencies.plans ?? new PlanStore();
+		this.operations = dependencies.operations ?? new OperationTracker();
+		this.fetchOptions = dependencies.fetchOptions ?? {};
+		this.hmrTimeoutMs = dependencies.hmrTimeoutMs ?? 5e3;
+	}
+	loaderEntries() {
+		if (this.loader === void 0) return [];
+		return [...this.loader.entries()].flatMap((entry) => {
+			const id = entry.options?.id ?? entry.id;
+			if (id === void 0 || id === "") return [];
+			const rawPhase = entry.fiber?.state;
+			const phase = typeof rawPhase === "number" ? FIBER_PHASE[rawPhase] ?? "unknown" : rawPhase ?? null;
+			return [{
+				id,
+				...entry.options?.name === void 0 ? {} : { name: entry.options.name },
+				disabled: entry.disabled === true,
+				phase
+			}];
+		});
+	}
+	list() {
+		return listPluginStatuses(this.profileDir, this.loaderEntries());
+	}
+	async discover(request, signal) {
+		if (request.action === "list") return {
+			profile: "web",
+			plugins: this.list()
+		};
+		if (request.action === "search") {
+			const options = {
+				...this.fetchOptions,
+				signal,
+				maxResults: request.maxResults,
+				inspect: this.inspect
+			};
+			return await searchPlugins(this.searchRuntime, request.query ?? "", options);
+		}
+		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, {
+				...this.fetchOptions,
+				signal
+			});
+		}
+		if (request.operationId !== void 0) return this.operations.get(request.operationId);
+		if (request.target === void 0) return {
+			profile: "web",
+			plugins: this.list()
+		};
+		const name = safePackageName(request.target);
+		const status = this.list().find((plugin) => plugin.packageName === name);
+		if (status === void 0) fail("PLUGIN_NOT_INSTALLED", `${name} is not installed in the web profile.`);
+		return status;
+	}
+	installed(name) {
+		const source = readProfileManifest(this.profileDir).dependencies?.[name];
+		if (source === void 0) fail("PLUGIN_NOT_INSTALLED", `${name} is not installed in the web profile.`);
+		return {
+			source,
+			surface: packageSurface(this.profileDir, name, source)
+		};
+	}
+	assertEnablementAllowed(surface) {
+		if (surface.entryIds?.some((id) => PROTECTED_ENTRY_IDS.has(id)) === true) fail("PROTECTED_PLUGIN", `${surface.packageName} owns protected DSH infrastructure and cannot be toggled.`);
+	}
+	async updateInspection(name, sourceOverride, signal) {
+		if (sourceOverride !== void 0) {
+			const inspection = await this.inspect(sourceOverride, {
+				...this.fetchOptions,
+				signal
+			});
+			if (inspection.packageName !== name) fail("PACKAGE_NAME_MISMATCH", "Update source resolves to a different package name.");
+			return inspection;
+		}
+		const current = this.installed(name).source;
+		const github = parseGithubSpec(current);
+		const source = github === null ? name : renderSource({
+			kind: "github",
+			owner: github.owner,
+			repo: github.repo
+		});
+		return await this.inspect(source, {
+			...this.fetchOptions,
+			signal
+		});
+	}
+	async plan(request, signal) {
+		if (request.operation === "restart") {
+			if (!this.restarter.available()) fail("RESTART_UNAVAILABLE", "Automatic restart is unavailable in this deployment.");
+			return this.plans.create({
+				action: "restart",
+				profile: "web",
+				impact: "Restart the running DSH process.",
+				restartExpected: true
+			});
+		}
+		if (request.operation === "install") {
+			const source = request.source ?? request.target;
+			if (source === void 0) fail("INVALID_SOURCE", "Install requires an npm or GitHub source.");
+			const inspection = await this.inspect(source, {
+				...this.fetchOptions,
+				signal
+			});
+			if (readProfileManifest(this.profileDir).dependencies?.[inspection.packageName] !== void 0) fail("PLUGIN_ALREADY_INSTALLED", `${inspection.packageName} is already installed; use update.`);
+			return this.plans.create({
+				action: "install",
+				profile: "web",
+				packageName: inspection.packageName,
+				installSpec: inspection.installSpec,
+				impact: `Install ${inspection.packageName} from ${inspection.installSpec}.`,
+				restartExpected: inspection.bundlePatch !== null
+			});
+		}
+		const name = safePackageName(request.target);
+		const installed = this.installed(name);
+		if (request.operation === "update") {
+			const inspection = await this.updateInspection(name, request.source, signal);
+			return this.plans.create({
+				action: "update",
+				profile: "web",
+				packageName: name,
+				currentSource: installed.source,
+				installSpec: inspection.installSpec,
+				impact: `Update ${name} from ${installed.source} to ${inspection.installSpec}.`,
+				restartExpected: true
+			});
+		}
+		if (request.operation === "enable" || request.operation === "disable") {
+			this.assertEnablementAllowed(installed.surface);
+			if (installed.surface.entryIds === null) fail("ENABLEMENT_UNSUPPORTED", `${name} has no safely attributable Loader entries.`);
+		}
+		return this.plans.create({
+			action: request.operation,
+			profile: "web",
+			packageName: name,
+			currentSource: installed.source,
+			impact: request.operation === "disable" ? `Disable ${name}. Conversations currently using capabilities from this plugin may be interrupted; confirm from another backend or session when continuity matters.` : `${request.operation[0].toUpperCase()}${request.operation.slice(1)} ${name}.`,
+			restartExpected: request.operation === "remove"
+		});
+	}
+	execute(confirmationToken) {
+		const plan = this.plans.consume(confirmationToken);
+		const dependencies = readProfileManifest(this.profileDir).dependencies ?? {};
+		if (plan.action === "install" && plan.packageName !== void 0 && dependencies[plan.packageName] !== void 0) fail("PLAN_STALE", `${plan.packageName} was installed after this plan was created; create a new plan.`);
+		if (plan.action !== "install" && plan.action !== "restart" && plan.packageName !== void 0 && dependencies[plan.packageName] !== plan.currentSource) fail("PLAN_STALE", `${plan.packageName} changed after this plan was created; create a new plan.`);
+		const target = plan.packageName ?? "dsh";
+		return this.operations.start(plan.action, target, async (context) => {
+			if (plan.action === "restart") {
+				context.progress("scheduling restart");
+				return {
+					action: "restart",
+					changed: true,
+					restartRequired: false,
+					restart: this.restarter.schedule()
+				};
+			}
+			if (plan.packageName === void 0) fail("POSTCONDITION_FAILED", "Mutation plan has no package name.");
+			if (plan.action === "install" || plan.action === "update") {
+				if (plan.installSpec === void 0) fail("POSTCONDITION_FAILED", "Install/update plan has no immutable source.");
+				return await this.installOrUpdate(plan.action, plan.packageName, plan.installSpec, context);
+			}
+			if (plan.action === "remove") return await this.remove(plan.packageName, context);
+			return await this.toggle(plan.action, plan.packageName, context);
+		});
+	}
+	operation(id) {
+		return this.operations.get(id);
+	}
+	cancel(id) {
+		return this.operations.cancel(id);
+	}
+	wait(id) {
+		return this.operations.wait(id);
+	}
+	async installOrUpdate(action, packageName, installSpec, context) {
+		const before = profileManifestText(this.profileDir);
+		context.progress(`${action}: running official DSH plugin command`);
+		const result = await this.runner.runPlugin("web", [
+			"add",
+			"--save-exact",
+			installSpec
+		], context.signal, context.progress);
+		if (result.exitCode !== 0 || result.timedOut || result.cancelled) {
+			restoreProfileManifest(this.profileDir, before);
+			fail("DSH_COMMAND_FAILED", `Official DSH plugin command failed with exit code ${result.exitCode}.`, commandResult(result));
+		}
+		const manifest = readProfileManifest(this.profileDir);
+		const dependency = manifest.dependencies?.[packageName];
+		const surface = dependency === void 0 ? null : packageSurface(this.profileDir, packageName, dependency);
+		const installedManifest = installedPackageManifest(this.profileDir, packageName);
+		const bundleCount = manifest.dsh?.profile?.bundles?.filter((name) => name === packageName).length ?? 0;
+		const validSurface = surface !== null && (surface.bundle || surface.client);
+		const validBundleMembership = surface !== null && (surface.bundle ? bundleCount === 1 : bundleCount === 0);
+		const validIdentity = installedManifest?.name === packageName;
+		const validSource = dependency !== void 0 && installedSourceMatches(packageName, dependency, installSpec);
+		const npmSource = parseGithubSpec(installSpec, true) === null ? parseNpmSpec(installSpec, true) : null;
+		const validVersion = npmSource === null || installedManifest?.version === npmSource.version;
+		if (!validSource || !validSurface || !validBundleMembership || !validIdentity || !validVersion) {
+			restoreProfileManifest(this.profileDir, before);
+			fail("POSTCONDITION_FAILED", `Official command completed but ${packageName} did not satisfy profile postconditions.`);
+		}
+		let activation;
+		if (action === "update") activation = {
+			active: false,
+			restartRequired: true,
+			reason: "Updated bundles activate after DSH restart."
+		};
+		else {
+			context.progress("install: attempting restart-free activation");
+			activation = await this.hot.activate(surface);
+		}
+		return {
+			action,
+			packageName,
+			installSpec,
+			changed: true,
+			activated: activation.active,
+			restartRequired: activation.restartRequired,
+			...activation.reason === null ? {} : { reason: activation.reason },
+			command: commandResult(result)
+		};
+	}
+	async remove(packageName, context) {
+		this.installed(packageName);
+		const before = profileManifestText(this.profileDir);
+		const wasHot = this.hot.isActive(packageName);
+		context.progress("remove: running official DSH plugin command");
+		const result = await this.runner.runPlugin("web", ["remove", packageName], context.signal, context.progress);
+		const packageExists = existsSync(join(this.profileDir, "node_modules", packageName, "package.json"));
+		if (result.exitCode !== 0 || result.timedOut || result.cancelled) {
+			if (!result.cancelled && !packageExists) reconcileRemovedPackage(this.profileDir, packageName);
+			else restoreProfileManifest(this.profileDir, before);
+			if (packageExists || result.cancelled) fail("DSH_COMMAND_FAILED", `Official DSH plugin remove failed with exit code ${result.exitCode}.`, commandResult(result));
+		}
+		const manifest = readProfileManifest(this.profileDir);
+		if (manifest.dependencies?.[packageName] !== void 0 || manifest.dsh?.profile?.bundles?.includes(packageName) === true) fail("POSTCONDITION_FAILED", `${packageName} remains in the profile after removal.`);
+		const deactivated = wasHot ? await this.hot.deactivate(packageName) : false;
+		return {
+			action: "remove",
+			packageName,
+			changed: true,
+			activated: false,
+			restartRequired: !deactivated,
+			...deactivated ? {} : { reason: "A boot-loaded plugin remains in the current process until DSH restarts." },
+			command: commandResult(result)
+		};
+	}
+	async toggle(action, packageName, context) {
+		const { surface } = this.installed(packageName);
+		this.assertEnablementAllowed(surface);
+		context.progress(`${action}: updating profile patch`);
+		const ids = action === "disable" ? disablePackage(this.profileDir, surface) : enablePackage(this.profileDir, surface);
+		if (action === "disable" && this.hot.isActive(packageName)) await this.hot.deactivate(packageName);
+		if (action === "enable" && !this.loaderEntries().some((entry) => surface.entryIds?.includes(entry.id))) {
+			const activation = await this.hot.activate(surface);
+			return {
+				action,
+				packageName,
+				changed: ids.length > 0,
+				activated: activation.active,
+				restartRequired: activation.restartRequired,
+				...activation.reason === null ? {} : { reason: activation.reason }
+			};
+		}
+		const expectedDisabled = action === "disable";
+		const deadline = Date.now() + this.hmrTimeoutMs;
+		let verified = false;
+		while (Date.now() < deadline && !context.signal.aborted) {
+			const relevant = this.loaderEntries().filter((entry) => surface.entryIds?.includes(entry.id));
+			if (relevant.length > 0 && relevant.every((entry) => entry.disabled === expectedDisabled)) {
+				verified = true;
+				break;
+			}
+			await new Promise((resolve) => setTimeout(resolve, 50));
+		}
+		return {
+			action,
+			packageName,
+			changed: ids.length > 0,
+			activated: action === "enable" && verified,
+			restartRequired: !verified,
+			...verified ? {} : { reason: "Loader HMR state could not be verified; restart is required." }
+		};
+	}
+};
+//#endregion
+//#region src/providers.ts
+const MAX_PROVIDER_RESULTS = 12;
+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.");
+	return normalized;
+}
+function npmSearchProvider(fetchImpl = globalThis.fetch) {
+	return {
+		id: "npm",
+		async search(request) {
+			const text = query(request.query);
+			const response = await fetchImpl(`https://registry.npmjs.org/-/v1/search?text=${encodeURIComponent(`${text} keywords:dsh-plugin`)}&size=${Math.min(request.maxResults, MAX_PROVIDER_RESULTS)}`, {
+				signal: request.signal,
+				headers: { accept: "application/json" }
+			});
+			if (!response.ok) throw new Error(`npm search returned HTTP ${response.status}`);
+			const searched = ((await response.json()).objects ?? []).flatMap((entry) => {
+				const name = entry.package?.name;
+				if (typeof name !== "string" || !NPM_NAME.test(name)) return [];
+				return [{
+					id: `npm:${name}`,
+					title: name,
+					...typeof entry.package?.description === "string" ? { description: entry.package.description } : {},
+					...typeof entry.package?.links?.homepage === "string" ? { homepage: entry.package.links.homepage } : {},
+					...typeof entry.package?.links?.repository === "string" ? { repository: entry.package.links.repository } : {},
+					sources: [{
+						kind: "npm",
+						package: name
+					}],
+					...typeof entry.score?.final === "number" ? { score: entry.score.final } : {}
+				}];
+			});
+			if (!NPM_NAME.test(text) || searched.some((candidate) => candidate.sources.some((source) => source.kind === "npm" && source.package === text))) return searched;
+			return [{
+				id: `npm:${text}`,
+				title: text,
+				sources: [{
+					kind: "npm",
+					package: text
+				}],
+				score: Number.MAX_SAFE_INTEGER,
+				evidence: ["Exact npm package-name query"]
+			}, ...searched];
+		}
+	};
+}
+function githubSearchProvider(fetchImpl = globalThis.fetch, env = process.env) {
+	return {
+		id: "github",
+		async search(request) {
+			const text = query(request.query);
+			const token = env.GITHUB_TOKEN ?? env.GH_TOKEN;
+			const response = await fetchImpl(`https://api.github.com/search/repositories?q=${encodeURIComponent(`${text} topic:dsh-plugin`)}&per_page=${Math.min(request.maxResults, MAX_PROVIDER_RESULTS)}`, {
+				signal: request.signal,
+				headers: {
+					accept: "application/vnd.github+json",
+					"user-agent": "relay-dsh-plugin-manager",
+					"x-github-api-version": "2022-11-28",
+					...token === void 0 || token === "" ? {} : { authorization: `Bearer ${token}` }
+				}
+			});
+			if (!response.ok) throw new Error(`GitHub search returned HTTP ${response.status}`);
+			return ((await response.json()).items ?? []).flatMap((entry) => {
+				if (typeof entry.full_name !== "string") return [];
+				const [owner, repo, ...extra] = entry.full_name.split("/");
+				if (owner === void 0 || repo === void 0 || extra.length > 0) return [];
+				return [{
+					id: `github:${entry.id ?? entry.full_name}`,
+					title: entry.full_name,
+					...typeof entry.description === "string" ? { description: entry.description } : {},
+					...typeof entry.html_url === "string" ? {
+						homepage: entry.html_url,
+						repository: entry.html_url
+					} : {},
+					sources: [{
+						kind: "github",
+						owner,
+						repo
+					}],
+					...typeof entry.stargazers_count === "number" ? { score: entry.stargazers_count } : {},
+					evidence: [`GitHub stars: ${String(entry.stargazers_count ?? 0)}`]
+				}];
+			});
+		}
+	};
+}
+//#endregion
+//#region src/restart.ts
+function detectedSupervisor(env = process.env, ppid = process.ppid) {
+	return ((env.INVOCATION_ID ?? "") !== "" || (env.JOURNAL_STREAM ?? "") !== "") && ppid === 1 ? "systemd" : null;
+}
+function restartAllowed(allowRestart, env = process.env, ppid = process.ppid) {
+	if (allowRestart !== void 0) return allowRestart;
+	return detectedSupervisor(env, ppid) === null;
+}
+var DshRestarter = class {
+	options;
+	constructor(options = {}) {
+		this.options = options;
+	}
+	available() {
+		return restartAllowed(this.options.allowRestart, this.options.env, this.options.ppid);
+	}
+	schedule() {
+		if (!this.available()) fail("RESTART_UNAVAILABLE", "Automatic restart is disabled or owned by the process supervisor.");
+		const argv = this.options.argv ?? process.argv;
+		if (argv[1] === void 0) fail("RESTART_UNAVAILABLE", "The current DSH entry point cannot be identified.");
+		const execPath = this.options.execPath ?? process.execPath;
+		const cwd = this.options.cwd ?? process.cwd();
+		const env = this.options.env ?? process.env;
+		const logFile = join(tmpdir(), `relay-dsh-plugin-manager-restart-${Date.now()}.log`);
+		const source = [
+			"const { spawn } = require('node:child_process')",
+			"const fs = require('node:fs')",
+			"setTimeout(() => {",
+			`  const out = fs.openSync(${JSON.stringify(logFile)}, 'a')`,
+			`  const child = spawn(${JSON.stringify(execPath)}, ${JSON.stringify(argv.slice(1))}, {`,
+			`    cwd: ${JSON.stringify(cwd)}, env: process.env, detached: true, stdio: ['ignore', out, out]`,
+			"  })",
+			"  child.on('error', error => fs.appendFileSync(" + JSON.stringify(logFile) + ", String(error) + '\\n'))",
+			"  child.unref()",
+			"}, 1200)"
+		].join("\n");
+		writeFileSync(logFile, "", {
+			flag: "a",
+			mode: 384
+		});
+		const helper = (this.options.spawn ?? spawn)(execPath, ["-e", source], {
+			detached: true,
+			stdio: "ignore",
+			env
+		});
+		helper.unref();
+		setTimeout(this.options.terminate ?? (() => process.kill(process.pid, "SIGTERM")), 500).unref();
+		return {
+			helperPid: helper.pid,
+			logFile
+		};
+	}
+};
+//#endregion
+//#region src/runner.ts
+function resolveDshLaunch(options = {}) {
+	const env = options.env ?? process.env;
+	const argv = options.argv ?? process.argv;
+	const execPath = options.execPath ?? process.execPath;
+	const cwd = options.cwd ?? process.cwd();
+	const platform = options.platform ?? process.platform;
+	const configured = env.DSH_EXECUTABLE?.trim();
+	let file;
+	let prefix;
+	if (configured !== void 0 && configured !== "") {
+		file = configured;
+		prefix = [];
+	} else if (argv[1] !== void 0 && existsSync(argv[1])) {
+		file = execPath;
+		prefix = [realpathSync(argv[1])];
+	} else {
+		file = "dsh";
+		prefix = [];
+	}
+	return {
+		file,
+		prefix,
+		cwd,
+		shell: platform === "win32" && /\.(?:cmd|bat)$/iu.test(file)
+	};
+}
+function boundedAppend(current, chunk, maxBytes) {
+	const combined = current + chunk.toString();
+	return Buffer.byteLength(combined) <= maxBytes ? combined : combined.slice(-maxBytes);
+}
+var DshCliRunner = class {
+	options;
+	constructor(options = {}) {
+		this.options = options;
+	}
+	runPlugin(profile, args, signal, progress = () => void 0) {
+		const launch = resolveDshLaunch(this.options);
+		const spawnImpl = this.options.spawn ?? spawn;
+		const timeoutMs = this.options.timeoutMs ?? 5 * 6e4;
+		const maxOutput = this.options.maxOutputBytes ?? 64 * 1024;
+		return new Promise((resolve, reject) => {
+			let child;
+			try {
+				child = spawnImpl(launch.file, [
+					...launch.prefix,
+					"plugin",
+					"--profile",
+					profile,
+					...args
+				], {
+					cwd: launch.cwd,
+					env: this.options.env ?? process.env,
+					shell: launch.shell,
+					stdio: [
+						"ignore",
+						"pipe",
+						"pipe"
+					]
+				});
+			} catch (error) {
+				reject(error);
+				return;
+			}
+			let stdout = "";
+			let stderr = "";
+			let timedOut = false;
+			let cancelled = false;
+			let settled = false;
+			const terminate = (reason) => {
+				if (reason === "timeout") timedOut = true;
+				else cancelled = true;
+				child.kill("SIGTERM");
+				setTimeout(() => {
+					if (!settled) child.kill("SIGKILL");
+				}, 2e3).unref();
+			};
+			const timer = setTimeout(() => terminate("timeout"), timeoutMs);
+			const onAbort = () => terminate("cancel");
+			if (signal.aborted) onAbort();
+			else signal.addEventListener("abort", onAbort, { once: true });
+			child.stdout?.on("data", (chunk) => {
+				stdout = boundedAppend(stdout, chunk, maxOutput);
+				progress(chunk.toString().trim().slice(-500));
+			});
+			child.stderr?.on("data", (chunk) => {
+				stderr = boundedAppend(stderr, chunk, maxOutput);
+				progress(chunk.toString().trim().slice(-500));
+			});
+			child.once("error", (error) => {
+				clearTimeout(timer);
+				signal.removeEventListener("abort", onAbort);
+				settled = true;
+				reject(error);
+			});
+			child.once("close", (code, closeSignal) => {
+				clearTimeout(timer);
+				signal.removeEventListener("abort", onAbort);
+				settled = true;
+				resolve({
+					exitCode: code ?? 1,
+					signal: closeSignal,
+					stdout,
+					stderr,
+					cancelled,
+					timedOut
+				});
+			});
+		});
+	}
+};
+//#endregion
+//#region src/index.ts
+const name = "relay-dsh-plugin-manager";
+const inject = [
+	"pluginSearch",
+	"tools",
+	"commands",
+	"loader"
+];
+function apply(ctx, config = {}) {
+	const profileDir = profileDirectory("web");
+	ctx.pluginSearch.register(npmSearchProvider());
+	ctx.pluginSearch.register(githubSearchProvider());
+	registerConversationSurface(ctx, new PluginManager({
+		profileDir,
+		searchRuntime: ctx.pluginSearch,
+		runner: new DshCliRunner(),
+		hot: new HotRuntime(ctx, profileDir),
+		restarter: new DshRestarter({ allowRestart: config.allowRestart }),
+		loader: ctx.loader
+	}));
+}
+//#endregion
+export { PluginManager, apply, inject, name };
+
+//# sourceMappingURL=index.js.map