relay-dsh-plugin-manager 0.2.3 → 0.2.5

package/CHANGELOG.md

@@ -2,6 +2,28 @@
 
 All notable changes to this project are documented here.
 
+## [0.2.5] - 2026-09-07
+
+### Added
+
+- Default-on anonymous operational analytics for plugin-manager use and
+  manager-executed install start, success, and failure outcomes, with explicit
+  opt-out through `RELAY_PLUGIN_MANAGER_TELEMETRY=0`.
+- First-party delivery to the Registry's versioned telemetry endpoint; the npm
+  package contains no PostHog host or project key.
+- A locally persisted random anonymous identifier; search text, installed
+  inventory, local paths, command output, error messages, IP geolocation, and
+  account identity are excluded.
+
+## [0.2.4] - 2026-09-05
+
+### Changed
+
+- Expose one-based search ranks, default search pages to twenty candidates, and
+  instruct the DSH Agent to exclude clearly unrelated purposes while presenting
+  every remaining possibly relevant result instead of silently truncating the
+  answer to a fixed top-N.
+
 ## [0.2.3] - 2026-09-04
 
 ### Added

package/README.md

@@ -100,6 +100,32 @@ missing companion peers, waits for one confirmation, and runs the installs in
 sequence. Completed changes that still need restart are reported explicitly as
 restart-required or waiting for a manual restart.
 
+### Anonymous usage analytics
+
+Anonymous operational analytics are enabled by default to measure plugin-manager
+search and installation outcomes. To opt out without disabling plugin management,
+set this when starting DSH Web:
+
+```bash
+RELAY_PLUGIN_MANAGER_TELEMETRY=0 dsh web
+```
+
+The manager sends events only to the first-party
+`https://dsh-plugins.tech/v1/telemetry/events` endpoint. The Registry validates
+the exact event schema and forwards accepted events to its PostHog analytics
+project. The plugin records only the manager action type and plugin
+install start, success, or failure events produced by the manager. Install
+events contain the public package name, activation/restart booleans, and a
+bounded error code. Search terms, conversation content, local paths, command
+output, error text, IP geolocation, and account identity are not sent. A random
+anonymous ID is stored in `.relay-plugin-manager/telemetry.json` inside the
+current Profile to avoid counting one installation as many users; delete the
+file to reset it.
+
+These events measure manager use and manager-executed installs. They do not
+claim that another plugin's feature was actually used merely because it loaded
+or activated.
+
 ### DSH Registry discovery provider
 
 The source-only Registry search provider uses `https://dsh-plugins.tech` by
@@ -112,6 +138,10 @@ This provider sends only the task query, inferred Chinese/English locale, and
 result limit. Returned candidates are
 always inspected locally through the same npm/GitHub flow before any plan can be
 created; Registry descriptions are untrusted text and cannot authorize changes.
+Search returns one relevance-ranked page (twenty candidates by default). The
+Agent is instructed to preserve that order and show every possibly relevant
+candidate instead of silently shortening the page to a fixed top five; results
+whose plugin purpose is clearly unrelated to the request are excluded.
 
 ## Part of Relay
 

package/README.zh.md

@@ -95,6 +95,26 @@ dsh web
 一次确认后依次安装。修改完成但仍需重启时，状态会明确区分“需要另行重启”和
 “等待人工重启”。
 
+### 匿名使用统计
+
+匿名运行统计默认开启，用于衡量插件管理器的搜索和安装结果。如需关闭，可在启动
+DSH Web 时设置以下变量；关闭统计不会影响插件管理功能：
+
+```bash
+RELAY_PLUGIN_MANAGER_TELEMETRY=0 dsh web
+```
+
+管理器只向第一方接口 `https://dsh-plugins.tech/v1/telemetry/events` 发送事件；Registry
+会校验严格的事件结构，再把通过校验的事件转发到自己的 PostHog 项目。统计只记录
+管理器操作类型，以及由管理器执行的插件安装开始、成功或失败；安装
+事件包含公开的插件包名、是否激活、是否需要重启和有限错误代码。不会发送搜索词、
+对话内容、本地路径、命令输出、错误文本、IP 地理位置或登录身份。一个随机匿名 ID
+保存在当前 Profile 的 `.relay-plugin-manager/telemetry.json`，用于避免把同一安装重复
+计算为多个用户；删除该文件即可重置。
+
+这些数据只能说明“插件管理器被使用”和“管理器执行了安装”，不会把插件加载或
+激活推断成其他插件的真实功能使用。
+
 ### DSH Registry 发现数据源
 
 来源级 Registry 搜索 provider 默认使用 `https://dsh-plugins.tech`。可设置插件
@@ -105,6 +125,9 @@ dsh web
 该 provider 只发送任务查询、推断出的中英文语言和结果数量。返回候选仍必须进入同一套本地 npm/GitHub
 检查流程，完成检查后才能生成计划；Registry 描述属于不可信文本，不能授权任何
 变更。
+搜索返回一页按相关性排序的结果（默认二十个）。Agent 必须保持该顺序并展示所有
+可能相关的候选，不能静默截成固定的前五个；插件用途明确与需求完全无关时必须
+省略。
 
 ## 与 Relay 的关系
 

package/SPEC.md

@@ -50,6 +50,8 @@ service.
 | PM-023 | `plugin_manage confirm` owns its DSH question: it validates the token, expiry, and exact Session before asking; supplies a stable plan-specific id, visible plan detail, exact approve/decline options, and `plan-review` intent; and executes in that same tool call only for the exact single approve answer. Declines, malformed or unrelated answers, provider failure/cancellation, and cross-session attempts do not execute or consume a still-valid plan. Generic model-authored question results are never mutation authority. |
 | PM-024 | GitHub owner discovery recognizes `owner:<name>`, owner-only GitHub identities, `<name> DSH plugins`, and conservative bare identifiers containing digits. It sends a typed owner intent to providers, uses GitHub's exact owner qualifier, case-insensitively verifies returned ownership, and ranks verified owner matches first. Owner-only `inspect` fails with an actionable error directing callers to search. Every emitted repository identity is accepted by `inspect`; every recommended immutable source is accepted by `plan`. |
 | PM-025 | Register a read-only DSH Registry provider against `https://dsh-plugins.tech` by default, with an explicit `registryUrl: false` opt-out and HTTPS-only configuration override. Send only the task query, inferred Chinese/English locale and result limit; accept only source-level untrusted DiscoveryEntry records, convert their npm/GitHub descriptors into core-owned source types, and submit them to the same mandatory local inspection used by all providers. Registry responses cannot supply exact versions, approval, plans, installers, or profile state, and provider failure remains isolated. |
+| PM-026 | Return search candidates as one explicit, one-based relevance-ranked result page with a default and maximum size of 20. The model-facing contract requires the Agent to preserve rank order, surface every possibly relevant returned candidate, exclude candidates whose purpose is clearly unrelated, and MUST NOT silently reduce the remaining page to a fixed top-N. Ranking remains distinct from compatibility, security, or installation approval. |
+| PM-027 | Send default-on anonymous operational telemetry only to the Registry's canonical first-party HTTPS endpoint under schema `1.0.0`, with explicit `RELAY_PLUGIN_MANAGER_TELEMETRY=0` or `telemetry.enabled: false` opt-out. Events are limited to manager discovery/planning type and manager-executed install start/success/failure, including per-plugin batch outcomes. Never send raw search text, conversation content, Profile state, installed inventory, paths, credentials, command output, error text, account identity, PostHog configuration, or client timestamps. Store only a stable random anonymous ID locally, create it lazily, and never let storage, validation, network, Registry, or analytics failure affect plugin management. |
 
 ## Command Grammar
 
@@ -72,7 +74,10 @@ Read-only actions: `list`, `search`, `inspect`, `status`.
 `search` accepts capability text or GitHub owner forms such as
 `owner:yangbobo2021`. `inspect` accepts npm sources and all three GitHub
 repository forms from PM-007. An owner without a repository belongs to
-`search`, not `inspect`.
+`search`, not `inspect`. Search defaults to a twenty-candidate ranked page. Each
+candidate carries its explicit display rank; the Agent presents all possibly
+relevant returned candidates in that order instead of silently selecting an
+arbitrary top five.
 
 ### `plugin_manage`
 

package/docs/acceptance.md

@@ -38,6 +38,8 @@ This matrix is the release contract. Tests name the relevant `PM-*` ids.
 | A-030 owner-only inspect forms return actionable search guidance while malformed, unsafe, and non-GitHub inputs remain rejected without weakening source validation | PM-018, PM-024 | source/manager negative unit |
 | A-031 search results feed one immutable multi-install plan through the real DSH tool and user-question registries; no mutation starts before one exact UI approval, then child installs execute serially and approval replay is rejected | PM-002, PM-005, PM-009, PM-010, PM-015, PM-023, PM-024 | combined host/tool/search/question/manager integration |
 | A-032 The default formal Registry searches at least 3,000 source records for Chinese task text, English task text, exact plugin names and an honest empty result; every returned source is locally inspected to an immutable npm version or GitHub commit, while Registry authority remains source-only, untrusted, non-recommending and non-approving | PM-005, PM-006, PM-025 | provider/unit/host integration tests plus `npm run acceptance:live:registry` |
+| A-033 Search defaults to a complete twenty-candidate result page, assigns stable one-based display ranks after merge and deduplication, and tells the Agent to exclude clearly unrelated purposes while surfacing every remaining possibly relevant candidate without silent fixed-count truncation | PM-005, PM-026 | search orchestration and conversation-tool contract unit tests plus Agent answer acceptance |
+| A-034 Default manager actions send only schema-valid anonymous envelopes to the first-party Registry endpoint, reuse a lazily created random ID, record each attempted batch install outcome, and continue normally through storage or delivery failure; explicit opt-out creates no ID and makes no telemetry request | PM-027 | telemetry unit tests + manager integration event assertions + Registry endpoint contract and end-to-end PostHog verification |
 
 ## Test Layers
 

package/lib/index.d.ts

@@ -2,6 +2,18 @@ import { a as PluginSearchRuntime, c as PluginSource, i as PluginSearchRequest,
 import { spawn } from "node:child_process";
 import { Context } from "@deepseek-ai/cordis";
 
+//#region src/telemetry.d.ts
+type TelemetryProperty = string | number | boolean;
+interface Telemetry {
+  capture(event: string, properties?: Readonly<Record<string, TelemetryProperty>>): void;
+}
+interface TelemetryConfig {
+  /** Anonymous operational telemetry is enabled unless this is explicitly false. */
+  enabled?: boolean;
+  /** Registry telemetry endpoint. Only the canonical service or localhost is accepted. */
+  endpoint?: string;
+}
+//#endregion
 //#region src/profile.d.ts
 interface PackageSurface {
   packageName: string;
@@ -238,6 +250,7 @@ interface PluginManagerDependencies {
   operations?: OperationTracker;
   fetchOptions?: Omit<FetchOptions, 'signal'>;
   hmrTimeoutMs?: number;
+  telemetry?: Telemetry;
 }
 interface DiscoverRequest {
   action: 'list' | 'search' | 'inspect' | 'status';
@@ -301,7 +314,9 @@ declare class PluginManager {
   private readonly operations;
   private readonly fetchOptions;
   private readonly hmrTimeoutMs;
+  private readonly telemetry;
   constructor(dependencies: PluginManagerDependencies);
+  private capture;
   private loaderEntries;
   list(): PluginStatus[];
   discover(request: DiscoverRequest, signal?: AbortSignal): Promise<unknown>;
@@ -331,8 +346,9 @@ declare const DEFAULT_REGISTRY_ORIGIN = "https://dsh-plugins.tech";
 interface Config {
   allowRestart?: boolean;
   registryUrl?: string | false;
+  telemetry?: TelemetryConfig;
 }
 declare function apply(ctx: Context, config?: Config): void;
 //#endregion
-export { Config, DEFAULT_REGISTRY_ORIGIN, type DiscoverRequest, type InstallManyItemResult, type InstallManyItemStatus, type InstallManyResult, type MutationResult, type PlanRequest, type PluginInspection, PluginManager, type PluginSearchCandidate, type PluginSearchMatch, type PluginSearchProvider, type PluginSearchRequest, type PluginSource, apply, inject, name };
+export { Config, DEFAULT_REGISTRY_ORIGIN, type DiscoverRequest, type InstallManyItemResult, type InstallManyItemStatus, type InstallManyResult, type MutationResult, type PlanRequest, type PluginInspection, PluginManager, type PluginSearchCandidate, type PluginSearchMatch, type PluginSearchProvider, type PluginSearchRequest, type PluginSource, type TelemetryConfig, apply, inject, name };
 //# sourceMappingURL=index.d.ts.map

package/lib/index.js

@@ -74,7 +74,7 @@ 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 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. 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.",
 		parameters: {
 			action: {
 				type: "string",
@@ -101,7 +101,7 @@ function registerConversationSurface(ctx, manager) {
 			},
 			maxResults: {
 				type: "integer",
-				description: "Maximum merged search results."
+				description: "Ranked result-page size from 1 to 20. Use 20 for ordinary need-based searches unless the user explicitly asks for fewer."
 			}
 		},
 		output: {
@@ -736,7 +736,7 @@ function candidateSources(provider, rows) {
 }
 async function searchPlugins(runtime, rawQuery, options = {}) {
 	const parsed = parseSearchQuery(rawQuery);
-	const maxResults = Math.max(1, Math.min(20, options.maxResults ?? 6));
+	const maxResults = Math.max(1, Math.min(20, options.maxResults ?? 20));
 	const timeoutMs = Math.max(100, options.providerTimeoutMs ?? 1e4);
 	const providers = runtime.entries();
 	const settled = await Promise.allSettled(providers.map(async (provider) => ({
@@ -813,13 +813,22 @@ async function searchPlugins(runtime, rawQuery, options = {}) {
 		existing.recommendedSource = existing.sources.find((source) => source.inspection.sourceType === "npm")?.inspection.installSpec ?? existing.sources[0].inspection.installSpec;
 		projects.set(identity, 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: _rank, matchPriority: _matchPriority, ...candidate }) => ({
+	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,
+		rank: index + 1,
 		providers: candidate.providers.sort()
 	}));
 	return {
 		query: parsed.query,
 		candidates,
+		presentation: {
+			order: "rank_ascending",
+			returnedCandidates: candidates.length,
+			requestedMaximum: maxResults,
+			includeEveryPossiblyRelevant: true,
+			excludeClearlyIrrelevant: true,
+			silentTopNTruncation: false
+		},
 		providerErrors,
 		rejectedCandidates
 	};
@@ -1214,11 +1223,56 @@ const PROTECTED_ENTRY_IDS = /* @__PURE__ */ new Set([
 	"webserver",
 	"web-runtime"
 ]);
+const TELEMETRY_ERROR_CODES = /* @__PURE__ */ new Set([
+	"INVALID_SOURCE",
+	"INVALID_NPM_SPEC",
+	"INVALID_NPM_VERSION",
+	"INVALID_GITHUB_SPEC",
+	"INVALID_GITHUB_REF",
+	"GITHUB_OWNER_REQUIRES_SEARCH",
+	"IMMUTABLE_SOURCE_REQUIRED",
+	"NETWORK_ERROR",
+	"SOURCE_HTTP_ERROR",
+	"INVALID_SOURCE_METADATA",
+	"INVALID_PLUGIN_MANIFEST",
+	"NOT_DSH_PLUGIN",
+	"PACKAGE_NAME_MISMATCH",
+	"NPM_INTEGRITY_MISSING",
+	"INVALID_SEARCH_QUERY",
+	"INVALID_ACTION",
+	"INVALID_BATCH",
+	"DUPLICATE_SEARCH_PROVIDER",
+	"PROFILE_READ_FAILED",
+	"PROFILE_WRITE_FAILED",
+	"PLUGIN_NOT_INSTALLED",
+	"PLUGIN_ALREADY_INSTALLED",
+	"ENABLEMENT_UNSUPPORTED",
+	"ENABLEMENT_CONFLICT",
+	"PROTECTED_PLUGIN",
+	"CONFIRMATION_REQUIRED",
+	"CONFIRMATION_INVALID",
+	"CONFIRMATION_EXPIRED",
+	"CONFIRMATION_REPLAYED",
+	"PLAN_STALE",
+	"OPERATION_NOT_FOUND",
+	"DSH_COMMAND_FAILED",
+	"BATCH_INSTALL_FAILED",
+	"POSTCONDITION_FAILED",
+	"RESTART_UNAVAILABLE"
+]);
 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 queryLengthBucket(value) {
+	const length = value?.trim().length ?? 0;
+	if (length === 0) return "empty";
+	if (length <= 10) return "1-10";
+	if (length <= 30) return "11-30";
+	if (length <= 80) return "31-80";
+	return "81+";
+}
 function commandResult(result) {
 	return {
 		exitCode: result.exitCode,
@@ -1232,6 +1286,10 @@ function operationError(error) {
 		message: error instanceof Error ? error.message : String(error)
 	};
 }
+function telemetryErrorCode(error) {
+	const code = operationError(error).code;
+	return code !== void 0 && TELEMETRY_ERROR_CODES.has(code) ? code : "UNKNOWN";
+}
 function installedPackageManifest(profileDir, packageName) {
 	try {
 		return JSON.parse(readFileSync(join(profileDir, "node_modules", packageName, "package.json"), "utf8"));
@@ -1256,6 +1314,7 @@ var PluginManager = class {
 	operations;
 	fetchOptions;
 	hmrTimeoutMs;
+	telemetry;
 	constructor(dependencies) {
 		this.profileDir = dependencies.profileDir;
 		this.searchRuntime = dependencies.searchRuntime;
@@ -1268,6 +1327,12 @@ var PluginManager = class {
 		this.operations = dependencies.operations ?? new OperationTracker();
 		this.fetchOptions = dependencies.fetchOptions ?? {};
 		this.hmrTimeoutMs = dependencies.hmrTimeoutMs ?? 5e3;
+		this.telemetry = dependencies.telemetry ?? { capture() {} };
+	}
+	capture(event, properties = {}) {
+		try {
+			this.telemetry.capture(event, properties);
+		} catch {}
 	}
 	loaderEntries() {
 		if (this.loader === void 0) return [];
@@ -1288,6 +1353,14 @@ var PluginManager = class {
 		return listPluginStatuses(this.profileDir, this.loaderEntries());
 	}
 	async discover(request, signal) {
+		this.capture("plugin_manager_used", {
+			surface: "discover",
+			action: request.action,
+			...request.action === "search" ? {
+				has_query: (request.query?.trim().length ?? 0) > 0,
+				query_length_bucket: queryLengthBucket(request.query)
+			} : {}
+		});
 		if (request.action === "list") return {
 			profile: "web",
 			plugins: this.list()
@@ -1351,6 +1424,11 @@ var PluginManager = class {
 		});
 	}
 	async plan(request, signal) {
+		this.capture("plugin_manager_used", {
+			surface: "plan",
+			action: request.operation,
+			...request.operation === "install_many" ? { batch_size: request.sources?.length ?? 0 } : {}
+		});
 		if (request.operation === "install_many") return await this.planInstallMany(request.sources, signal);
 		if (request.operation === "restart") {
 			if (!this.restarter.available()) fail("RESTART_UNAVAILABLE", "Automatic restart is unavailable in this deployment.");
@@ -1477,7 +1555,22 @@ var PluginManager = class {
 			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 this.withRestartGuidance(await this.installOrUpdate(plan.action, plan.packageName, plan.installSpec, context), automaticRestartAvailable);
+				if (plan.action === "install") this.capture("plugin_install_started", { plugin_name: plan.packageName });
+				try {
+					const result = this.withRestartGuidance(await this.installOrUpdate(plan.action, plan.packageName, plan.installSpec, context), automaticRestartAvailable);
+					if (plan.action === "install") this.capture("plugin_install_succeeded", {
+						plugin_name: plan.packageName,
+						activated: result.activated === true,
+						restart_required: result.restartRequired
+					});
+					return result;
+				} catch (error) {
+					if (plan.action === "install") this.capture("plugin_install_failed", {
+						plugin_name: plan.packageName,
+						error_code: telemetryErrorCode(error)
+					});
+					throw error;
+				}
 			}
 			if (plan.action === "remove") return this.withRestartGuidance(await this.remove(plan.packageName, context), automaticRestartAvailable);
 			return this.withRestartGuidance(await this.toggle(plan.action, plan.packageName, context), automaticRestartAvailable);
@@ -1525,6 +1618,10 @@ var PluginManager = class {
 				break;
 			}
 			context.progress(`install_many: ${index + 1}/${items.length} installing ${item.packageName}`);
+			this.capture("plugin_install_started", {
+				plugin_name: item.packageName,
+				batch: true
+			});
 			try {
 				const result = this.withRestartGuidance(await this.installOrUpdate("install", item.packageName, item.installSpec, context), automaticRestartAvailable);
 				results.push({
@@ -1533,6 +1630,12 @@ var PluginManager = class {
 					status: this.mutationCompletion(result, automaticRestartAvailable).status,
 					result
 				});
+				this.capture("plugin_install_succeeded", {
+					plugin_name: item.packageName,
+					batch: true,
+					activated: result.activated === true,
+					restart_required: result.restartRequired
+				});
 			} catch (error) {
 				results.push({
 					packageName: item.packageName,
@@ -1540,6 +1643,11 @@ var PluginManager = class {
 					status: context.signal.aborted ? "cancelled" : "failed",
 					error: operationError(error)
 				});
+				this.capture("plugin_install_failed", {
+					plugin_name: item.packageName,
+					batch: true,
+					error_code: telemetryErrorCode(error)
+				});
 				skipRemaining(index + 1);
 				break;
 			}
@@ -1686,7 +1794,7 @@ var PluginManager = class {
 };
 //#endregion
 //#region src/providers.ts
-const MAX_PROVIDER_RESULTS = 12;
+const MAX_PROVIDER_RESULTS = 20;
 const REGISTRY_SNAPSHOT_ID = /^discovery\.[a-z0-9.-]+$/u;
 function query(value) {
 	const normalized = value.trim();
@@ -2069,6 +2177,107 @@ var DshCliRunner = class {
 	}
 };
 //#endregion
+//#region src/telemetry.ts
+const DEFAULT_ENDPOINT = "https://dsh-plugins.tech/v1/telemetry/events";
+const STATE_DIRECTORY = ".relay-plugin-manager";
+const STATE_FILE = "telemetry.json";
+const SCHEMA_VERSION = "1.0.0";
+const EVENTS = /* @__PURE__ */ new Set([
+	"plugin_manager_used",
+	"plugin_install_started",
+	"plugin_install_succeeded",
+	"plugin_install_failed"
+]);
+const noopTelemetry = Object.freeze({ capture() {} });
+function safeEndpoint(value) {
+	try {
+		const parsed = new URL(value ?? DEFAULT_ENDPOINT);
+		const local = [
+			"localhost",
+			"127.0.0.1",
+			"::1"
+		].includes(parsed.hostname);
+		const canonical = parsed.protocol === "https:" && parsed.hostname === "dsh-plugins.tech";
+		if (!local && !canonical || local && !["http:", "https:"].includes(parsed.protocol)) return null;
+		if (parsed.username !== "" || parsed.password !== "" || parsed.pathname !== "/v1/telemetry/events" || parsed.search !== "" || parsed.hash !== "") return null;
+		return parsed.href;
+	} catch {
+		return null;
+	}
+}
+function anonymousId(profileDir, random) {
+	const directory = join(profileDir, STATE_DIRECTORY);
+	const path = join(directory, STATE_FILE);
+	try {
+		const existing = JSON.parse(readFileSync(path, "utf8"));
+		if (typeof existing.anonymousId === "string" && /^[0-9a-f-]{36}$/iu.test(existing.anonymousId)) return existing.anonymousId;
+	} catch {}
+	const id = random();
+	try {
+		mkdirSync(directory, {
+			recursive: true,
+			mode: 448
+		});
+		writeFileSync(path, `${JSON.stringify({ anonymousId: id })}\n`, { mode: 384 });
+	} catch {}
+	return id;
+}
+function allowedProperties(event, properties) {
+	const keys = new Set(Object.keys(properties));
+	const exact = (required, optional = []) => {
+		if (required.some((key) => !keys.has(key))) return false;
+		return [...keys].every((key) => required.includes(key) || optional.includes(key));
+	};
+	if (event === "plugin_manager_used") {
+		if (!exact(["surface", "action"], [
+			"has_query",
+			"query_length_bucket",
+			"batch_size"
+		])) return false;
+		if (!["discover", "plan"].includes(String(properties.surface))) return false;
+		return typeof properties.action === "string";
+	}
+	if (event === "plugin_install_started") return exact(["plugin_name"], ["batch"]);
+	if (event === "plugin_install_succeeded") return exact([
+		"plugin_name",
+		"activated",
+		"restart_required"
+	], ["batch"]);
+	if (event === "plugin_install_failed") return exact(["plugin_name", "error_code"], ["batch"]);
+	return false;
+}
+function createTelemetry(profileDir, config, runtime = {
+	fetch,
+	random: randomUUID
+}) {
+	if (config?.enabled === false) return noopTelemetry;
+	const endpoint = safeEndpoint(config?.endpoint);
+	if (endpoint === null) return noopTelemetry;
+	let distinctId;
+	return Object.freeze({ capture(event, properties = {}) {
+		if (!EVENTS.has(event) || !allowedProperties(event, properties)) return;
+		distinctId ??= anonymousId(profileDir, runtime.random);
+		const controller = new AbortController();
+		const timeout = setTimeout(() => controller.abort(), 5e3);
+		timeout.unref?.();
+		try {
+			runtime.fetch(endpoint, {
+				method: "POST",
+				headers: { "content-type": "application/json" },
+				body: JSON.stringify({
+					schema_version: SCHEMA_VERSION,
+					anonymous_id: distinctId,
+					event,
+					properties
+				}),
+				signal: controller.signal
+			}).catch(() => void 0).finally(() => clearTimeout(timeout));
+		} catch {
+			clearTimeout(timeout);
+		}
+	} });
+}
+//#endregion
 //#region src/index.ts
 const name = "relay-dsh-plugin-manager";
 const inject = [
@@ -2081,6 +2290,10 @@ const inject = [
 const DEFAULT_REGISTRY_ORIGIN = "https://dsh-plugins.tech";
 function apply(ctx, config = {}) {
 	const profileDir = profileDirectory("web");
+	const telemetry = config.telemetry ?? {
+		enabled: process.env.RELAY_PLUGIN_MANAGER_TELEMETRY !== "0",
+		endpoint: process.env.RELAY_PLUGIN_MANAGER_TELEMETRY_ENDPOINT
+	};
 	ctx.pluginSearch.register(npmSearchProvider());
 	ctx.pluginSearch.register(githubSearchProvider());
 	const configuredRegistryUrl = config.registryUrl ?? process.env.DSH_PLUGIN_REGISTRY_URL?.trim();
@@ -2092,7 +2305,8 @@ function apply(ctx, config = {}) {
 		runner: new DshCliRunner(),
 		hot: new HotRuntime(ctx, profileDir),
 		restarter: new DshRestarter({ allowRestart: config.allowRestart }),
-		loader: ctx.loader
+		loader: ctx.loader,
+		telemetry: createTelemetry(profileDir, telemetry)
 	}));
 }
 //#endregion