dsh-windows-mcp 0.2.0 → 0.2.1

package/lib/dependency.js

@@ -355,10 +355,63 @@ export function yamlScalar(value) {
   return `'${String(value).replace(/'/gu, "''")}'`;
 }
 
-/** The complete bridge row, pointing at an installed executable. */
+/**
+ * The bridge row values this package ships. The settings page may change them;
+ * `lib/settings.js` normalises user input against these same defaults.
+ */
+export const BRIDGE_DEFAULTS = Object.freeze({
+  toolCallTimeoutMs: 120000,
+  excludeTools: Object.freeze(["App", "PowerShell", "FileSystem"]),
+  screenshotScale: 0.75,
+  screenshotBackend: "auto",
+  disableFlash: true,
+});
+
+/** Render `args:` — `--exclude-tools` takes one comma-separated argv. */
+function bridgeArgsLine(excludeTools) {
+  const names = Array.from(excludeTools, (name) => String(name).trim()).filter((name) => name !== "");
+  if (names.length === 0) return "    args: [serve]";
+  return `    args: [serve, --exclude-tools, ${JSON.stringify(names.join(","))}]`;
+}
+
+/** Render `env:` — only the keys that are set, in a stable order. */
+function bridgeEnvLine(settings) {
+  const pairs = ['ANONYMIZED_TELEMETRY: "false"'];
+  if (settings.disableFlash !== false) pairs.push('WINDOWS_MCP_DISABLE_FLASH: "1"');
+  pairs.push(`WINDOWS_MCP_SCREENSHOT_SCALE: ${JSON.stringify(String(settings.screenshotScale))}`);
+  if (typeof settings.screenshotBackend === "string" && settings.screenshotBackend !== "auto") {
+    pairs.push(`WINDOWS_MCP_SCREENSHOT_BACKEND: ${JSON.stringify(settings.screenshotBackend)}`);
+  }
+  return `    env: { ${pairs.join(", ")} }`;
+}
+
+/** Fold user settings (or their absence) into one complete bridge value set. */
+function bridgeValues(meta) {
+  const source = meta.settings !== null && typeof meta.settings === "object" ? meta.settings : null;
+  const merged = { ...BRIDGE_DEFAULTS };
+  if (source === null) return merged;
+  if (typeof source.toolCallTimeoutMs === "number" && Number.isFinite(source.toolCallTimeoutMs)) {
+    merged.toolCallTimeoutMs = Math.round(source.toolCallTimeoutMs);
+  }
+  if (Array.isArray(source.excludeTools)) merged.excludeTools = source.excludeTools.slice();
+  if (typeof source.screenshotScale === "number" && Number.isFinite(source.screenshotScale)) {
+    merged.screenshotScale = source.screenshotScale;
+  }
+  if (typeof source.screenshotBackend === "string" && source.screenshotBackend !== "") {
+    merged.screenshotBackend = source.screenshotBackend;
+  }
+  if (typeof source.disableFlash === "boolean") merged.disableFlash = source.disableFlash;
+  return merged;
+}
+
+/**
+ * The complete bridge row, pointing at an installed executable.
+ * `meta.settings` is the optional `bridge` half of the user settings.
+ */
 export function bridgeOverrideBlock(executable, meta = {}) {
   const stamp = typeof meta.stamp === "string" ? meta.stamp : new Date().toISOString();
   const version = typeof meta.version === "string" ? meta.version : "unknown";
+  const values = bridgeValues(meta);
   return [
     PROFILE_BLOCK_BEGIN,
     `# Written by ${PACKAGE_ID} ${version} at ${stamp}.`,
@@ -368,11 +421,11 @@ export function bridgeOverrideBlock(executable, meta = {}) {
     "    serverName: windows",
     "    transport: stdio",
     `    command: ${yamlScalar(executable)}`,
-    '    args: [serve, --exclude-tools, "App,PowerShell,FileSystem"]',
-    "    toolCallTimeoutMs: 120000",
+    bridgeArgsLine(values.excludeTools),
+    `    toolCallTimeoutMs: ${values.toolCallTimeoutMs}`,
     "    failOnStartupError: false",
     "    reconnect: { enabled: true, initialDelayMs: 500, maxDelayMs: 30000, maxAttempts: 10 }",
-    '    env: { ANONYMIZED_TELEMETRY: "false", WINDOWS_MCP_DISABLE_FLASH: "1", WINDOWS_MCP_SCREENSHOT_SCALE: "0.75" }',
+    bridgeEnvLine(values),
     PROFILE_BLOCK_END,
   ].join("\n");
 }
@@ -526,7 +579,15 @@ export function writeBridgeOverride(executable, options = {}) {
         backup = null;
       }
     }
-    writeFileSync(file, withBridgeOverride(current, bridgeOverrideBlock(executable, { stamp: new Date().toISOString(), version }), eol), "utf8");
+    writeFileSync(
+      file,
+      withBridgeOverride(
+        current,
+        bridgeOverrideBlock(executable, { stamp: new Date().toISOString(), version, settings: options.settings }),
+        eol,
+      ),
+      "utf8",
+    );
     return { ok: true, path: file, backup, executable, restartRequired: true };
   } catch (error) {
     warn(`could not point the bridge at the installed Windows-MCP: ${String(error)}`);

package/lib/index.js

@@ -39,6 +39,15 @@ import {
   writeBridgeOverride,
 } from "./dependency.js";
 import { UPDATE_ACTIONS, UPDATE_ROUTE, createUpdater } from "./updater.js";
+import {
+  SETTINGS_ROUTE,
+  bridgeSettingsMatch,
+  bridgeSettingsOf,
+  normalizeSettings,
+  readBridgeSettings,
+  readSettings,
+  writeSettings,
+} from "./settings.js";
 
 const PACKAGE_ID = "dsh-windows-mcp";
 const BRIDGE_ROW_ID = "windows-mcp-bridge";
@@ -62,11 +71,15 @@ const stateDirectory = (() => {
 const statePath = join(stateDirectory, "dsh-windows-mcp.state.json");
 const STATE_ROUTE = "/dsh-windows-mcp/state";
 const MAX_STATE_BODY_BYTES = 1024;
+const MAX_SETTINGS_BODY_BYTES = 8192;
 
 /** Mirrors the persisted flag; read once at boot, updated by the state route.
  *  Desktop control is opt-in: a fresh install starts OFF. */
 const computerUse = { enabled: false };
 
+/** User settings; read once at boot, replaced by the settings route. */
+let settings = null;
+
 /** The Windows-MCP version manager, created in apply() once the logger exists. */
 let updater = null;
 
@@ -525,6 +538,23 @@ function registerStateRoute(ctx, warn) {
           };
         };
 
+        /**
+         * Settings plus what the profile patch actually says: the two only
+         * match after a restart, because the MCP client reads its row at boot.
+         */
+        const settingsView = () => {
+          const current = settings === null ? normalizeSettings(null).settings : settings;
+          const patchText = readText(patchPath);
+          const applied = bridgeSettingsMatch(current, patchText);
+          return {
+            settings: current,
+            bridge: readBridgeSettings(patchText),
+            applied,
+            restartRequired: !applied,
+            pluginVersion: selfVersion(),
+          };
+        };
+
         const snapshot = () => {
           const legacy = dependencySnapshot(which, windowsMcpVersionPin(readText(patchPath)));
           const update = updater === null ? null : updater.view();
@@ -535,6 +565,7 @@ function registerStateRoute(ctx, warn) {
             dependency: updater === null ? legacy : updater.dependencyView(legacy),
             prepare: prepareSnapshot(),
             update,
+            settings: settingsView(),
           };
         };
 
@@ -704,11 +735,83 @@ function registerStateRoute(ctx, warn) {
           request.on("error", () => respond(response, 400, { error: "request failed" }));
         };
 
+        /**
+         * Read and update the user settings. Plugin settings apply at once;
+         * bridge settings are written into the profile patch row and only take
+         * effect after DSH restarts.
+         */
+        const settingsHandler = (request, response) => {
+          if (request.method === "GET") {
+            respond(response, 200, settingsView());
+            return;
+          }
+          if (request.method !== "POST") {
+            respond(response, 405, { error: "method not allowed" });
+            return;
+          }
+          const chunks = [];
+          let size = 0;
+          request.on("data", (chunk) => {
+            size += chunk.length;
+            if (size > MAX_SETTINGS_BODY_BYTES) {
+              request.destroy();
+              return;
+            }
+            chunks.push(chunk);
+          });
+          request.on("end", () => {
+            let body;
+            try {
+              body = JSON.parse(Buffer.concat(chunks).toString("utf8") || "{}");
+            } catch {
+              respond(response, 400, { error: "invalid JSON body" });
+              return;
+            }
+            const incoming = body !== null && typeof body === "object" && body.settings !== null && typeof body.settings === "object" ? body.settings : body;
+            const normalized = normalizeSettings(incoming);
+            const stored = writeSettings(normalized.settings, stateDirectory);
+            settings = stored.settings;
+            const wanted = bridgeSettingsOf(settings);
+            if (bridgeSettingsMatch(settings, readText(patchPath))) {
+              respond(response, 200, {
+                ok: true,
+                saved: stored.written,
+                problems: normalized.problems,
+                write: null,
+                ...settingsView(),
+              });
+              return;
+            }
+            const view = updater === null ? null : updater.view();
+            const executable = view?.versions?.activeExecutable ?? windowsMcpExecutable();
+            if (executable === null) {
+              respond(response, 200, {
+                ok: true,
+                saved: stored.written,
+                problems: normalized.problems,
+                write: { ok: false, error: "Windows-MCP is not installed yet, so the bridge row was left untouched" },
+                ...settingsView(),
+              });
+              return;
+            }
+            const written = writeBridgeOverride(executable, { warn, version: selfVersion(), settings: wanted });
+            respond(response, 200, {
+              ok: written.ok === true,
+              saved: stored.written,
+              problems: normalized.problems,
+              write: written,
+              ...settingsView(),
+            });
+          });
+          request.on("error", () => respond(response, 400, { error: "request failed" }));
+        };
+
         scoped.webServer.register({ kind: "exact", path: STATE_ROUTE, handler });
         scoped.webServer.register({ kind: "exact", path: PREPARE_ROUTE, handler: prepareHandler });
         scoped.webServer.register({ kind: "exact", path: PREPARE_CANCEL_ROUTE, handler: cancelHandler });
         scoped.webServer.register({ kind: "exact", path: BRIDGE_ROUTE, handler: bridgeHandler });
         scoped.webServer.register({ kind: "exact", path: UPDATE_ROUTE, handler: updateHandler });
+        scoped.webServer.register({ kind: "exact", path: SETTINGS_ROUTE, handler: settingsHandler });
       } catch (error) {
         warn(`could not register the Computer Use state route: ${String(error)}`);
       }
@@ -726,11 +829,18 @@ export function apply(ctx) {
   try {
     const warn = makeLogger(ctx);
     computerUse.enabled = readComputerUse().enabled;
+    settings = readSettings(stateDirectory);
     updater = createUpdater({
       warn,
       resolver: which,
       pinned: windowsMcpVersionPin(readText(patchPath)),
-      writeBridge: (executable) => writeBridgeOverride(executable, { warn, version: selfVersion() }),
+      preferredMirror: () => (settings === null ? "auto" : settings.plugin.preferredMirror),
+      writeBridge: (executable) =>
+        writeBridgeOverride(executable, {
+          warn,
+          version: selfVersion(),
+          settings: settings === null ? null : bridgeSettingsOf(settings),
+        }),
     });
     auditStartup(warn);
     registerDoctor(ctx, warn);
@@ -738,11 +848,14 @@ export function apply(ctx) {
     registerToolGate(ctx, warn);
     // Check for a newer Windows-MCP build in the background (cheap: a ranged
     // read per mirror, cached for hours). The page shows the result; the boot
-    // never waits for it, and a failure only costs the last known answer.
-    try {
-      void updater.check({ force: false }).catch(() => {});
-    } catch {
-      /* a failed check is not a boot problem */
+    // never waits for it, and a failure only costs the last known answer. The
+    // settings page can turn this off.
+    if (settings === null || settings.plugin.autoCheckUpdates === true) {
+      try {
+        void updater.check({ force: false }).catch(() => {});
+      } catch {
+        /* a failed check is not a boot problem */
+      }
     }
   } catch {
     /* apply() must not throw, whatever happens */

package/lib/mirrors.js

@@ -205,8 +205,16 @@ export async function fetchProjectIndex(options = {}) {
   return { indexUrl, pageUrl, entries, versions, latest: latestStableVersion(versions) };
 }
 
+/** Candidate mirrors in probe order, honouring a user preference. */
+export function mirrorCandidates(preferred = "auto", candidates = MIRROR_CANDIDATES) {
+  const wanted = mirrorById(preferred, candidates);
+  if (wanted === null) return candidates.slice();
+  return [wanted].concat(candidates.filter((mirror) => mirror.id !== wanted.id));
+}
+
 /** Mirrors in the order an install should try them: ranked first, official last. */
-export function mirrorOrder(probe, candidates = MIRROR_CANDIDATES) {  const seen = new Set();
+export function mirrorOrder(probe, candidates = MIRROR_CANDIDATES) {
+  const seen = new Set();
   const order = [];
   for (const id of Array.isArray(probe?.ranked) ? probe.ranked : []) {
     const mirror = mirrorById(id, candidates);

package/lib/settings.js

@@ -0,0 +1,251 @@
+/**
+ * dsh-windows-mcp — user-adjustable settings (host side).
+ *
+ * The plugin's settings page (Settings → left rail) writes this file. There are
+ * two families, and they differ in when they take effect:
+ *
+ *   - `bridge` values are baked into the machine-written row in the profile
+ *     patch, so they only take effect after DSH restarts — the MCP client reads
+ *     that row once, at boot.
+ *   - `plugin` values belong to this plugin itself and apply immediately.
+ *
+ * Everything is validated and clamped before it is stored or rendered: a
+ * hand-edited, truncated or future-version file must never break the host, and
+ * a bad value must never produce a patch row the client cannot parse.
+ */
+import { existsSync, mkdirSync, readFileSync, renameSync, writeFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { dirname, join } from "node:path";
+import { BRIDGE_DEFAULTS, PROFILE_BLOCK_BEGIN, PROFILE_BLOCK_END } from "./dependency.js";
+import { MIRROR_CANDIDATES } from "./mirrors.js";
+
+export const SETTINGS_ROUTE = "/dsh-windows-mcp/settings";
+export const SETTINGS_VERSION = 1;
+export const SETTINGS_FILE = "dsh-windows-mcp.settings.json";
+
+/** Screenshot downscales the upstream server accepts. */
+export const SCREENSHOT_SCALES = Object.freeze([0.25, 0.5, 0.75, 1]);
+/** Upstream capture backends, `auto` lets the server pick. */
+export const SCREENSHOT_BACKENDS = Object.freeze(["auto", "dxcam", "mss", "pillow"]);
+/** Tools whose registration costs the most context; all on by default. */
+export const EXCLUDABLE_TOOLS = Object.freeze(["App", "PowerShell", "FileSystem"]);
+/** `auto` means "whatever the speed probe ranks first". */
+export const MIRROR_CHOICES = Object.freeze(["auto"].concat(MIRROR_CANDIDATES.map((mirror) => mirror.id)));
+/** `toolCallTimeoutMs` bounds — generous, but not unbounded. */
+export const TIMEOUT_RANGE = Object.freeze({ min: 5000, max: 600000 });
+
+export const DEFAULT_SETTINGS = Object.freeze({
+  version: SETTINGS_VERSION,
+  bridge: Object.freeze({
+    toolCallTimeoutMs: BRIDGE_DEFAULTS.toolCallTimeoutMs,
+    excludeTools: Object.freeze(BRIDGE_DEFAULTS.excludeTools.slice()),
+    screenshotScale: BRIDGE_DEFAULTS.screenshotScale,
+    screenshotBackend: BRIDGE_DEFAULTS.screenshotBackend,
+    disableFlash: BRIDGE_DEFAULTS.disableFlash,
+  }),
+  plugin: Object.freeze({
+    autoCheckUpdates: true,
+    preferredMirror: "auto",
+  }),
+});
+
+/** DSH home: `$DSH_HOME`, else `~/.dsh`. */
+export function dshHome(env = process.env) {
+  const fromEnvironment = String(env?.DSH_HOME ?? "").trim();
+  return fromEnvironment === "" ? join(homedir(), ".dsh") : fromEnvironment;
+}
+
+/** Where the settings file lives for a DSH home. */
+export function settingsPath(home = dshHome()) {
+  return join(home, SETTINGS_FILE);
+}
+
+/** A mutable copy of the defaults. */
+export function defaultSettings() {
+  return {
+    version: SETTINGS_VERSION,
+    bridge: {
+      toolCallTimeoutMs: DEFAULT_SETTINGS.bridge.toolCallTimeoutMs,
+      excludeTools: DEFAULT_SETTINGS.bridge.excludeTools.slice(),
+      screenshotScale: DEFAULT_SETTINGS.bridge.screenshotScale,
+      screenshotBackend: DEFAULT_SETTINGS.bridge.screenshotBackend,
+      disableFlash: DEFAULT_SETTINGS.bridge.disableFlash,
+    },
+    plugin: {
+      autoCheckUpdates: DEFAULT_SETTINGS.plugin.autoCheckUpdates,
+      preferredMirror: DEFAULT_SETTINGS.plugin.preferredMirror,
+    },
+  };
+}
+
+/**
+ * Coerce anything into a complete, valid settings object.
+ * @returns `{ settings, problems }` — `problems` names every value that was
+ *   replaced by its default, so the page can say what it ignored.
+ */
+export function normalizeSettings(input) {
+  const settings = defaultSettings();
+  const problems = [];
+  if (input === null || typeof input !== "object") return { settings, problems };
+  const bridge = input.bridge !== null && typeof input.bridge === "object" ? input.bridge : {};
+  const plugin = input.plugin !== null && typeof input.plugin === "object" ? input.plugin : {};
+
+  const timeout = Number(bridge.toolCallTimeoutMs);
+  if (Number.isFinite(timeout) && timeout >= TIMEOUT_RANGE.min && timeout <= TIMEOUT_RANGE.max) {
+    settings.bridge.toolCallTimeoutMs = Math.round(timeout);
+  } else if (bridge.toolCallTimeoutMs !== undefined) {
+    problems.push("bridge.toolCallTimeoutMs");
+  }
+
+  if (Array.isArray(bridge.excludeTools)) {
+    const wanted = [];
+    for (const value of bridge.excludeTools) {
+      const name = typeof value === "string" ? value.trim() : "";
+      if (EXCLUDABLE_TOOLS.includes(name) && !wanted.includes(name)) wanted.push(name);
+    }
+    const ignored = bridge.excludeTools.length - wanted.length;
+    if (ignored > 0) problems.push("bridge.excludeTools");
+    settings.bridge.excludeTools = wanted;
+  } else if (bridge.excludeTools !== undefined) {
+    problems.push("bridge.excludeTools");
+  }
+
+  const scale = Number(bridge.screenshotScale);
+  if (SCREENSHOT_SCALES.includes(scale)) settings.bridge.screenshotScale = scale;
+  else if (bridge.screenshotScale !== undefined) problems.push("bridge.screenshotScale");
+
+  if (SCREENSHOT_BACKENDS.includes(bridge.screenshotBackend)) settings.bridge.screenshotBackend = bridge.screenshotBackend;
+  else if (bridge.screenshotBackend !== undefined) problems.push("bridge.screenshotBackend");
+
+  if (typeof bridge.disableFlash === "boolean") settings.bridge.disableFlash = bridge.disableFlash;
+  else if (bridge.disableFlash !== undefined) problems.push("bridge.disableFlash");
+
+  if (typeof plugin.autoCheckUpdates === "boolean") settings.plugin.autoCheckUpdates = plugin.autoCheckUpdates;
+  else if (plugin.autoCheckUpdates !== undefined) problems.push("plugin.autoCheckUpdates");
+
+  if (MIRROR_CHOICES.includes(plugin.preferredMirror)) settings.plugin.preferredMirror = plugin.preferredMirror;
+  else if (plugin.preferredMirror !== undefined) problems.push("plugin.preferredMirror");
+
+  return { settings, problems };
+}
+
+/** Read the stored settings; a missing or corrupt file means "defaults". */
+export function readSettings(home = dshHome()) {
+  try {
+    const text = readFileSync(settingsPath(home), "utf8");
+    return normalizeSettings(JSON.parse(text)).settings;
+  } catch {
+    return defaultSettings();
+  }
+}
+
+/** Validate, store (atomically) and return the settings that were kept. */
+export function writeSettings(input, home = dshHome()) {
+  const { settings } = normalizeSettings(input);
+  const file = settingsPath(home);
+  const payload = `${JSON.stringify(settings, null, 2)}\n`;
+  try {
+    mkdirSync(dirname(file), { recursive: true });
+    const temporary = `${file}.${process.pid}.tmp`;
+    writeFileSync(temporary, payload, "utf8");
+    renameSync(temporary, file);
+  } catch (error) {
+    return { settings, written: false, error: String(error), path: file };
+  }
+  return { settings, written: true, error: null, path: file };
+}
+
+/** The five values that end up in the bridge row. */
+export function bridgeSettingsOf(settings) {
+  const source = settings !== null && typeof settings === "object" && settings.bridge !== null && typeof settings.bridge === "object" ? settings.bridge : DEFAULT_SETTINGS.bridge;
+  return {
+    toolCallTimeoutMs: typeof source.toolCallTimeoutMs === "number" ? source.toolCallTimeoutMs : DEFAULT_SETTINGS.bridge.toolCallTimeoutMs,
+    excludeTools: Array.isArray(source.excludeTools) ? source.excludeTools.slice() : DEFAULT_SETTINGS.bridge.excludeTools.slice(),
+    screenshotScale: typeof source.screenshotScale === "number" ? source.screenshotScale : DEFAULT_SETTINGS.bridge.screenshotScale,
+    screenshotBackend: typeof source.screenshotBackend === "string" ? source.screenshotBackend : DEFAULT_SETTINGS.bridge.screenshotBackend,
+    disableFlash: typeof source.disableFlash === "boolean" ? source.disableFlash : DEFAULT_SETTINGS.bridge.disableFlash,
+  };
+}
+
+/** Split the YAML flow sequence in `args: [...]`, keeping quoted commas intact. */
+function splitFlowList(raw) {
+  const parts = [];
+  let current = "";
+  let quoted = false;
+  for (const character of String(raw)) {
+    if (character === '"') quoted = !quoted;
+    if (character === "," && !quoted) {
+      parts.push(current.trim());
+      current = "";
+      continue;
+    }
+    current += character;
+  }
+  if (current.trim() !== "") parts.push(current.trim());
+  return parts.map((part) => part.replace(/^["']|["']$/gu, "").trim()).filter((part) => part !== "");
+}
+
+/**
+ * Read the bridge values back out of a profile patch layer.
+ * @returns `{ toolCallTimeoutMs, excludeTools, screenshotScale,
+ *   screenshotBackend, disableFlash }` — missing fields stay `undefined`.
+ */
+export function readBridgeSettings(patchText) {
+  const text = String(patchText ?? "");
+  const begin = text.indexOf(PROFILE_BLOCK_BEGIN);
+  const end = text.indexOf(PROFILE_BLOCK_END);
+  const block = begin === -1 || end === -1 || end < begin ? "" : text.slice(begin, end);
+  const found = {
+    toolCallTimeoutMs: undefined,
+    excludeTools: undefined,
+    screenshotScale: undefined,
+    screenshotBackend: undefined,
+    disableFlash: undefined,
+  };
+
+  const timeout = /(?:^|\n)\s*toolCallTimeoutMs:\s*(\d+)/u.exec(block);
+  if (timeout !== null) found.toolCallTimeoutMs = Number(timeout[1]);
+
+  const args = /(?:^|\n)\s*args:\s*\[([^\]]*)\]/u.exec(block);
+  if (args !== null) {
+    const tokens = splitFlowList(args[1]);
+    const index = tokens.indexOf("--exclude-tools");
+    if (index === -1) found.excludeTools = [];
+    else if (index + 1 < tokens.length) found.excludeTools = tokens[index + 1].split(",").map((name) => name.trim()).filter((name) => name !== "");
+  }
+
+  const scale = /WINDOWS_MCP_SCREENSHOT_SCALE:\s*"([0-9.]+)"/u.exec(block);
+  if (scale !== null) found.screenshotScale = Number(scale[1]);
+
+  const backend = /WINDOWS_MCP_SCREENSHOT_BACKEND:\s*"([a-z]+)"/u.exec(block);
+  if (backend !== null) found.screenshotBackend = backend[1];
+
+  const flash = /WINDOWS_MCP_DISABLE_FLASH:\s*"([01])"/u.exec(block);
+  if (flash !== null) found.disableFlash = flash[1] === "1";
+  else if (block !== "") found.disableFlash = false;
+
+  return found;
+}
+
+/**
+ * Do the stored settings already match the bridge row in `patchText`? A field the
+ * row does not declare falls back to this package's shipped default, so a patch
+ * layer without a machine-written block still compares equal to the defaults.
+ */
+export function bridgeSettingsMatch(settings, patchText) {
+  const wanted = bridgeSettingsOf(settings);
+  const found = readBridgeSettings(patchText);
+  const actual = {
+    toolCallTimeoutMs: found.toolCallTimeoutMs === undefined ? BRIDGE_DEFAULTS.toolCallTimeoutMs : found.toolCallTimeoutMs,
+    excludeTools: found.excludeTools === undefined ? BRIDGE_DEFAULTS.excludeTools.slice() : found.excludeTools,
+    screenshotScale: found.screenshotScale === undefined ? BRIDGE_DEFAULTS.screenshotScale : found.screenshotScale,
+    screenshotBackend: found.screenshotBackend === undefined ? BRIDGE_DEFAULTS.screenshotBackend : found.screenshotBackend,
+    disableFlash: found.disableFlash === undefined ? BRIDGE_DEFAULTS.disableFlash : found.disableFlash,
+  };
+  if (actual.toolCallTimeoutMs !== wanted.toolCallTimeoutMs) return false;
+  if (actual.screenshotScale !== wanted.screenshotScale) return false;
+  if (actual.disableFlash !== wanted.disableFlash) return false;
+  if (actual.screenshotBackend !== wanted.screenshotBackend) return false;
+  if (actual.excludeTools.length !== wanted.excludeTools.length) return false;
+  return wanted.excludeTools.every((name) => actual.excludeTools.includes(name));
+}

package/lib/updater.js

@@ -32,7 +32,7 @@ import {
   writeManifest,
   writeVersionsState,
 } from "./installs.js";
-import { fetchProjectIndex, describeMirror, formatBytesPerSecond, mirrorOrder, probeMirrors } from "./mirrors.js";
+import { fetchProjectIndex, describeMirror, formatBytesPerSecond, mirrorCandidates, mirrorOrder, probeMirrors } from "./mirrors.js";
 import { latestStableVersion } from "./pypi.js";
 
 /** Route the page posts update actions to. */
@@ -75,6 +75,8 @@ function summarizeProbe(probe) {
  * @param options.readIndex - project index reader (tests inject one).
  * @param options.spawnInstall - `uv tool install` starter (tests inject one).
  * @param options.now - clock (tests inject one).
+ * @param options.preferredMirror - `() => id`; a mirror the user pinned, or
+ *   `"auto"` to keep whatever the speed probe ranks first.
  */
 export function createUpdater(options = {}) {
   const home = options.home ?? dshHome();
@@ -85,6 +87,7 @@ export function createUpdater(options = {}) {
   const readIndex = typeof options.readIndex === "function" ? options.readIndex : fetchProjectIndex;
   const startInstall = typeof options.spawnInstall === "function" ? options.spawnInstall : spawnUvInstall;
   const now = typeof options.now === "function" ? options.now : () => Date.now();
+  const preferredMirrorId = typeof options.preferredMirror === "function" ? options.preferredMirror : () => "auto";
   const pinned = typeof options.pinned === "string" && options.pinned !== "" ? options.pinned : null;
   const root = managedToolchainRoot(home);
 
@@ -194,8 +197,11 @@ export function createUpdater(options = {}) {
     checkState.phase = "checking";
     checkState.error = null;
     let probeResult = null;
+    let candidates = mirrorCandidates("auto");
     try {
-      probeResult = await probe({ project: WINDOWS_MCP_TOOL });
+      const preferred = preferredMirrorId();
+      candidates = mirrorCandidates(typeof preferred === "string" ? preferred : "auto");
+      probeResult = await probe({ project: WINDOWS_MCP_TOOL, candidates });
       lastProbe = probeResult;
     } catch (error) {
       checkState.phase = "failed";
@@ -206,7 +212,7 @@ export function createUpdater(options = {}) {
     let latest = null;
     let best = null;
     let lastError = "no mirror answered";
-    for (const mirror of mirrorOrder(probeResult)) {
+    for (const mirror of mirrorOrder(probeResult, candidates)) {
       try {
         const index = await readIndex({ indexUrl: mirror.indexUrl, project: WINDOWS_MCP_TOOL });
         latest = index.latest ?? latestStableVersion(index.versions ?? []);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dsh-windows-mcp",
-  "version": "0.2.0",
+  "version": "0.2.1",
   "description": "Windows desktop automation for DeepSeek Harness — plugs CursorTouch/Windows-MCP (screenshot, UI automation, input, clipboard, processes, registry) into DSH through the official MCP client bridge.",
   "license": "MIT",
   "author": "dsh-windows-mcp contributors",