@xnng/browser-relay 1.6.0

package/server/sdk.js

@@ -0,0 +1,307 @@
+import {
+  DEFAULT_REMOTE_HOST,
+  parseRemoteDeviceId,
+  remoteHttpBase,
+} from "./remote-protocol.js";
+import { randomUUID } from "node:crypto";
+import { isAutomationPath, isTaskRequest } from "../extension/protocol.js";
+
+export class BrowserRelayError extends Error {
+  constructor(payload) {
+    super(payload.message || payload.error || "Browser action failed");
+    this.code = payload.code;
+    this.payload = payload;
+  }
+}
+export function createTransport({
+  url = process.env.BROWSER_RELAY_URL || "http://127.0.0.1:18795",
+  remoteDeviceId = process.env.BROWSER_RELAY_REMOTE_DEVICE_ID,
+  remoteHost = process.env.BROWSER_RELAY_REMOTE_HOST || DEFAULT_REMOTE_HOST,
+} = {}) {
+  const remote = remoteDeviceId ? parseRemoteDeviceId(remoteDeviceId) : null;
+  const request = async (method, path, body, { signal, timeoutMs = 35000 } = {}) => {
+    const query = new URL(path, "http://relay.local");
+    const taskRequest = isTaskRequest(method, query.pathname);
+    let taskId, sessionId;
+    if (taskRequest) {
+      taskId = (method === "GET" ? query.searchParams.get("taskId") : body?.taskId) || `job_${randomUUID()}`;
+      sessionId = (method === "GET" ? query.searchParams.get("sessionId") : body?.sessionId) || undefined;
+      if (method === "GET") {
+        query.searchParams.set("taskId", taskId);
+        path = query.pathname + query.search;
+      } else body = { ...body, taskId };
+    }
+    const controller = new AbortController();
+    const abort = () => controller.abort(signal.reason);
+    if (signal?.aborted) abort();
+    else signal?.addEventListener("abort", abort, { once: true });
+    const timer = setTimeout(
+      () => controller.abort(new Error("Browser Relay request timed out")),
+      timeoutMs,
+    );
+    try {
+      const response = await fetch(
+        remote
+          ? `${remoteHttpBase(remoteHost)}/v1/rpc`
+          : `${url.replace(/\/$/, "")}${path}`,
+        {
+          method: remote ? "POST" : method,
+          headers: {
+            "Content-Type": "application/json",
+            ...(remote ? { Authorization: `Bearer ${remote.secret}` } : {}),
+          },
+          ...(remote
+            ? {
+                body: JSON.stringify({
+                  routeId: remote.routeId,
+                  id: randomUUID(),
+                  method,
+                  path,
+                  body: body ?? null,
+                  headers: {},
+                }),
+              }
+            : body === undefined
+              ? {}
+              : { body: JSON.stringify(body) }),
+          signal: controller.signal,
+        },
+      );
+      const result = await response.json();
+      if (!response.ok || result.ok === false)
+        throw new BrowserRelayError(result);
+      return result;
+    } catch (error) {
+      if (error instanceof BrowserRelayError &&
+          !["cdp_timeout", "rpc_timeout", "request_timeout", "remote_request_timeout", "extension_not_connected"].includes(error.code)) throw error;
+      const code = signal?.aborted ? "request_cancelled" : controller.signal.aborted ? "request_timeout" : error.code || "transport_error";
+      clearTimeout(timer);
+      // An aborted fetch does not stop Chrome (especially behind a remote hub).
+      // Cancel through a fresh request and retain the task identity/progress.
+      let task, cancellationError;
+      if (taskId) {
+        try {
+          ({ task } = await request("POST", `/api/tasks/${encodeURIComponent(taskId)}/cancel`,
+            { sessionId }, { timeoutMs: 2500 }));
+        } catch (cancelError) {
+          cancellationError = cancelError.code || "transport_error";
+        }
+      }
+      throw new BrowserRelayError({
+        ok: false,
+        code,
+        message: error.message,
+        retryable: !taskId && !signal?.aborted && method === "GET",
+        ...(taskId ? { taskId, sessionId, task, cancellationRequested: !!task, cancellationError } : {}),
+      });
+    } finally {
+      clearTimeout(timer);
+      signal?.removeEventListener("abort", abort);
+    }
+  };
+  return request;
+}
+export function createBrowser({
+  request: transportRequest = createTransport(),
+  sessionId = randomUUID(),
+} = {}) {
+  let timer,
+    disposed = false,
+    sessionError;
+  const request = async (method, path, body, options) => {
+    const history = method === "GET" && path.startsWith("/api/tasks/");
+    if (disposed && !history)
+      throw new BrowserRelayError({
+        code: "session_stopped",
+        message: "Browser session disposed; create a new browser session",
+      });
+    if (sessionError && !history) throw sessionError;
+    const modern = isAutomationPath(path.split("?")[0]);
+    if (modern && !path.startsWith("/api/capabilities")) {
+      if (method === "GET")
+        path += `${path.includes("?") ? "&" : "?"}sessionId=${encodeURIComponent(sessionId)}`;
+      else body = { ...body, sessionId };
+      if (!timer && !history) {
+        timer = setInterval(
+          () =>
+            transportRequest(
+              "POST",
+              "/api/sessions",
+              { sessionId, action: "heartbeat" },
+              { timeoutMs: 5000 },
+            ).catch((error) => {
+              sessionError = error;
+              clearInterval(timer);
+            }),
+          40000,
+        );
+        timer.unref?.();
+      }
+    }
+    return transportRequest(method, path, body, options);
+  };
+  async function waitTask(id, { timeoutMs = 125000 } = {}) {
+    const deadline = Date.now() + timeoutMs;
+    while (true) {
+      const { task } = await request(
+        "GET",
+        `/api/tasks/${encodeURIComponent(id)}`,
+      );
+      if (task.status === "completed") return task;
+      if (task.status === "failed" || task.status === "cancelled")
+        throw new BrowserRelayError({ ...task.error, task });
+      if (Date.now() >= deadline) {
+        await request(
+          "POST",
+          `/api/tasks/${encodeURIComponent(id)}/cancel`,
+          {},
+        );
+        throw new BrowserRelayError({
+          code: "task_timeout",
+          message: "Task wait timed out",
+        });
+      }
+      await new Promise((r) => setTimeout(r, 40));
+    }
+  }
+  function tab(tabId) {
+    if (typeof tabId !== "string" || !/^t_[\w-]{10}$/.test(tabId))
+      throw new Error("Use a tab id from browser.tabs() or browser.open()");
+    const run = async (actions, options = {}) => {
+      const { signal, requestTimeoutMs, ...actionOptions } = options;
+      const result = await request("POST", "/api/actions", {
+        tabId,
+        sessionId,
+        taskId: `job_${randomUUID()}`,
+        actions,
+        observe: "snapshot",
+        ...actionOptions,
+      }, { signal, timeoutMs: requestTimeoutMs });
+      return result.task;
+    };
+    const locator = (target) => ({
+      click: (options = {}) => run([{ type: "click", target, ...options }]),
+      doubleClick: (options = {}) =>
+        run([{ type: "double_click", target, ...options }]),
+      fill: (text, options = {}) =>
+        run([{ type: "fill", target, text, ...options }]),
+      type: (text, options = {}) =>
+        run([{ type: "type", target, text, ...options }]),
+      hover: (options = {}) => run([{ type: "hover", target, ...options }]),
+      select: (value, options = {}) =>
+        run([{ type: "select", target, value, ...options }]),
+      check: (checked = true, options = {}) =>
+        run([{ type: "check", target, checked, ...options }]),
+      waitFor: (options = {}) => run([{ type: "wait", target, ...options }]),
+      getByRole: (role, options = {}) =>
+        locator({ role, ...options, scope: target }),
+      read: (options = {}) =>
+        request("POST", "/api/read", { tabId, target, ...options }),
+      target,
+    });
+    return {
+      id: tabId,
+      act: run,
+      ref: (ref) => locator({ ref }),
+      locator: (selector, options = {}) => locator({ selector, ...options }),
+      getByRole: (role, options = {}) => locator({ role, ...options }),
+      read: (options = {}) =>
+        request("POST", "/api/read", { tabId, ...options }),
+      observe: (options = {}) =>
+        request("POST", "/api/observe", { tabId, ...options }),
+      focus: () => run([{ type: "focus" }]),
+      claim: (options = {}) =>
+        request("POST", "/api/tabs/claim", { tabId, ...options }),
+      release: () => request("POST", "/api/tabs/release", { tabId }),
+      handoff: (toSessionId) =>
+        request("POST", "/api/tabs/handoff", { tabId, toSessionId }),
+      snapshot: (options = {}) =>
+        request("POST", "/api/observe", {
+          tabId,
+          sessionId,
+          diff: true,
+          ...options,
+        }),
+      screenshot: (options = {}) =>
+        request("POST", "/api/observe", {
+          tabId,
+          mode: "screenshot",
+          ...options,
+        }),
+      goto: (url, options = {}) =>
+        run([
+          { type: "navigate", url, ...options },
+          ...(options.waitFor
+            ? [
+                {
+                  type: "wait",
+                  target: options.waitFor,
+                  timeoutMs: options.timeoutMs || 10000,
+                },
+              ]
+            : []),
+        ]),
+      close: () => request("POST", "/api/tabs/close", { tabId }),
+      click: (target, options = {}) =>
+        run([{ type: "click", target, ...options }]),
+      clickAt: (x, y, options = {}) =>
+        run([{ type: "click", x, y, ...options }]),
+      key: (key) => run([{ type: "key", key }]),
+      scroll: (deltaY, options = {}) =>
+        run([{ type: "scroll", x: 400, y: 300, deltaY, ...options }]),
+      hover: (target) => run([{ type: "hover", target }]),
+      drag: (from, to, options = {}) =>
+        run([{ type: "drag", ...from, to, ...options }]),
+      eval: async (expression) => {
+        const result = await request("POST", "/api/evaluate", {
+          tabId,
+          expression,
+        });
+        if (result.exceptionDetails)
+          throw new BrowserRelayError({
+            code: "evaluation_failed",
+            message:
+              result.exceptionDetails.exception?.description ||
+              result.exceptionDetails.text,
+          });
+        return result.value;
+      },
+    };
+  }
+  return {
+    sessionId,
+    start: (label) => request('POST', '/api/sessions', { action: 'start', label }),
+    complete: async () => {
+      // complete 是任务结束，dispose 只是控制器退出；后者继续保留页面。
+      const result = await transportRequest('POST', '/api/sessions', { sessionId, action: 'complete' });
+      disposed = true;
+      clearInterval(timer);
+      return result;
+    },
+    heartbeat: () => request("POST", "/api/sessions", { action: "heartbeat" }),
+    claims: () => request("GET", "/api/sessions"),
+    dispose: async () => {
+      if (disposed) return;
+      disposed = true;
+      clearInterval(timer);
+      await transportRequest(
+        "POST",
+        "/api/sessions",
+        { sessionId, action: "stop" },
+        { timeoutMs: 5000 },
+      );
+    },
+    tabs: async () => (await request("GET", "/api/tabs")).tabs,
+    tab,
+    open: async (url) =>
+      tab((await request("POST", "/api/tabs/create", { url })).tabId),
+    capabilities: () => request("GET", "/api/capabilities"),
+    tasks: {
+      get: async (id) =>
+        (await request("GET", `/api/tasks/${encodeURIComponent(id)}`)).task,
+      wait: waitTask,
+      cancel: (id) =>
+        request("POST", `/api/tasks/${encodeURIComponent(id)}/cancel`, {}),
+    },
+  };
+}

package/server/service-state.js

@@ -0,0 +1,103 @@
+import { spawnSync as defaultSpawnSync } from "node:child_process";
+import { existsSync as defaultExistsSync } from "node:fs";
+
+function outputText(value) {
+  if (typeof value === "string") return value;
+  if (Buffer.isBuffer(value)) return value.toString("utf-8");
+  return "";
+}
+
+function firstLine(value) {
+  return outputText(value).split(/\r?\n/, 1)[0].trim().slice(0, 240);
+}
+
+function probeError(command, label, result) {
+  if (result?.error?.code === "ENOENT") return `${command} is unavailable (command not found)`;
+  if (result?.error?.code === "ETIMEDOUT") return `${label} timed out`;
+  const detail = firstLine(result?.stderr) || firstLine(result?.error?.message);
+  return detail ? `${label} is unavailable: ${detail}` : `${label} is unavailable`;
+}
+
+function runProbe(spawnSyncFn, command, args) {
+  try {
+    return spawnSyncFn(command, args, { encoding: "utf-8", timeout: 1500 });
+  } catch (error) {
+    return { error, status: null, stdout: "", stderr: "" };
+  }
+}
+
+export function inspectPosixServiceState({
+  sys,
+  plistPath,
+  systemdPath,
+  launchdLabel,
+  systemdUnit,
+  spawnSyncFn = defaultSpawnSync,
+  existsSyncFn = defaultExistsSync,
+}) {
+  const supported = sys === "darwin" || sys === "linux";
+  const registered = sys === "darwin"
+    ? existsSyncFn(plistPath)
+    : sys === "linux"
+      ? existsSyncFn(systemdPath)
+      : false;
+  const state = {
+    loaded: false,
+    pid: null,
+    supported,
+    registered,
+    checked: false,
+    error: null,
+    conflict: false,
+  };
+
+  if (sys === "darwin") {
+    const result = runProbe(spawnSyncFn, "launchctl", ["list"]);
+    const hasOutput = typeof result?.stdout === "string" || Buffer.isBuffer(result?.stdout);
+    if (!result?.error && result?.status === 0 && hasOutput) {
+      state.checked = true;
+      const line = outputText(result.stdout)
+        .split("\n")
+        .find((item) => item.trim().split(/\s+/).at(-1) === launchdLabel);
+      if (line) {
+        state.loaded = true;
+        const [pid] = line.trim().split(/\s+/);
+        if (pid && pid !== "-") state.pid = pid;
+      }
+    } else if (!result?.error && result?.status === 0) {
+      state.error = "launchctl status is unavailable: command returned no output";
+    } else {
+      state.error = probeError("launchctl", "launchctl status", result);
+    }
+    return state;
+  }
+
+  if (sys === "linux") {
+    const result = runProbe(spawnSyncFn, "systemctl", ["--user", "is-active", systemdUnit]);
+    const serviceStatus = outputText(result?.stdout).trim();
+    const knownStates = new Set([
+      "active",
+      "activating",
+      "deactivating",
+      "failed",
+      "inactive",
+      "maintenance",
+      "reloading",
+      "unknown",
+    ]);
+    if (!result?.error && knownStates.has(serviceStatus)) {
+      state.checked = true;
+      state.loaded = serviceStatus === "active";
+    } else {
+      state.error = probeError("systemctl", "systemd user status", result);
+    }
+  }
+
+  return state;
+}
+
+export function relayStartRemediation(service) {
+  return service?.checked && service.registered
+    ? "Run: browser-relay status, then browser-relay logs"
+    : "Start the relay in a terminal with: browser-relay";
+}

package/server/snapshot.js

@@ -0,0 +1,161 @@
+/**
+ * DOM-to-text extraction function.
+ * This JS string is sent to the browser via Runtime.evaluate and returns
+ * a text representation of the visible page suitable for an LLM.
+ */
+export const SNAPSHOT_JS = `
+(function() {
+  const INTERACTIVE_TAGS = new Set([
+    'A', 'BUTTON', 'INPUT', 'SELECT', 'TEXTAREA', 'DETAILS', 'SUMMARY',
+  ]);
+  const SKIP_TAGS = new Set([
+    'SCRIPT', 'STYLE', 'NOSCRIPT', 'SVG', 'PATH', 'TEMPLATE',
+    'IFRAME', 'OBJECT', 'EMBED',
+  ]);
+  const BLOCK_TAGS = new Set([
+    'DIV', 'P', 'H1', 'H2', 'H3', 'H4', 'H5', 'H6',
+    'UL', 'OL', 'LI', 'TABLE', 'TR', 'SECTION', 'ARTICLE',
+    'NAV', 'HEADER', 'FOOTER', 'MAIN', 'ASIDE', 'FORM',
+    'BLOCKQUOTE', 'PRE', 'HR', 'BR', 'DL', 'DT', 'DD',
+    'FIGURE', 'FIGCAPTION', 'ADDRESS',
+  ]);
+
+  function isVisible(el) {
+    if (!el.offsetParent && el.tagName !== 'BODY' && el.tagName !== 'HTML') {
+      var style = getComputedStyle(el);
+      if (style.display === 'none' || style.visibility === 'hidden') return false;
+      if (style.display !== 'contents' && style.position !== 'fixed' && style.position !== 'sticky') return false;
+    }
+    if (el.getAttribute('aria-hidden') === 'true') return false;
+    if (el.hasAttribute('hidden')) return false;
+    return true;
+  }
+
+  function describeElement(el) {
+    var tag = el.tagName;
+    if (tag === 'A') {
+      var href = el.getAttribute('href') || '';
+      var text = (el.innerText || el.getAttribute('aria-label') || '').trim();
+      return '[link' + (text ? ' "' + text + '"' : '') + (href ? ' href="' + href + '"' : '') + ']';
+    }
+    if (tag === 'BUTTON' || (el.getAttribute('role') === 'button')) {
+      var text = (el.getAttribute('aria-label') || el.innerText || '').trim();
+      return '[button' + (text ? ' "' + text + '"' : '') + ']';
+    }
+    if (tag === 'INPUT') {
+      var type = el.getAttribute('type') || 'text';
+      var name = el.getAttribute('name') || '';
+      var placeholder = el.getAttribute('placeholder') || '';
+      var label = el.getAttribute('aria-label') || '';
+      var val = type === 'password' ? '[redacted]' : (el.value || '').slice(0, 80);
+      var desc = '[input type=' + type;
+      if (name) desc += ' name="' + name + '"';
+      if (placeholder) desc += ' placeholder="' + placeholder + '"';
+      if (label) desc += ' label="' + label + '"';
+      if (val) desc += ' value="' + val + '"';
+      desc += ']';
+      return desc;
+    }
+    if (tag === 'TEXTAREA') {
+      var name = el.getAttribute('name') || '';
+      var placeholder = el.getAttribute('placeholder') || '';
+      var val = (el.value || '').slice(0, 200);
+      var desc = '[textarea';
+      if (name) desc += ' name="' + name + '"';
+      if (placeholder) desc += ' placeholder="' + placeholder + '"';
+      if (val) desc += ' value="' + val + '"';
+      desc += ']';
+      return desc;
+    }
+    if (tag === 'SELECT') {
+      var name = el.getAttribute('name') || '';
+      var selected = el.options && el.selectedIndex >= 0 ? (el.options[el.selectedIndex].text || '').slice(0, 60) : '';
+      var desc = '[select';
+      if (name) desc += ' name="' + name + '"';
+      if (selected) desc += ' selected="' + selected + '"';
+      desc += ']';
+      return desc;
+    }
+    if (tag === 'IMG') {
+      var alt = el.getAttribute('alt') || '';
+      return alt ? '[image "' + alt.slice(0, 100) + '"]' : '[image]';
+    }
+    return null;
+  }
+
+  var lines = [];
+  var maxLen = (typeof __maxLength !== 'undefined') ? __maxLength : 100000;
+  var totalLen = 0;
+  var truncated = false;
+
+  function addLine(text, indent) {
+    if (truncated) return;
+    var line = '  '.repeat(indent) + text;
+    totalLen += line.length + 1;
+    if (totalLen > maxLen) { truncated = true; return; }
+    lines.push(line);
+  }
+
+  function walk(node, depth) {
+    if (truncated) return;
+    if (node.nodeType === 3) {
+      var text = node.textContent.trim();
+      if (text) addLine(text, depth);
+      return;
+    }
+    if (node.nodeType !== 1) return;
+    var el = node;
+    var tag = el.tagName;
+    if (SKIP_TAGS.has(tag)) return;
+    if (!isVisible(el)) return;
+
+    var headingMatch = tag.match(/^H([1-6])$/);
+    if (headingMatch) {
+      var text = (el.innerText || '').trim();
+      if (text) addLine('#'.repeat(parseInt(headingMatch[1])) + ' ' + text, depth);
+      return;
+    }
+
+    var desc = describeElement(el);
+    if (desc) {
+      addLine(desc, depth);
+      if (tag === 'A' || tag === 'BUTTON') return;
+    }
+
+    var isBlock = BLOCK_TAGS.has(tag);
+    var childDepth = desc ? depth + 1 : (isBlock ? depth : depth);
+
+    if (tag === 'LI') {
+      var text = '';
+      for (var i = 0; i < el.childNodes.length; i++) {
+        var child = el.childNodes[i];
+        if (child.nodeType === 3) text += child.textContent;
+      }
+      text = text.trim();
+      if (text) addLine('- ' + text, depth);
+      for (var i = 0; i < el.children.length; i++) {
+        walk(el.children[i], depth + 1);
+      }
+      return;
+    }
+
+    if (tag === 'TR') {
+      var cells = [];
+      for (var i = 0; i < el.children.length; i++) {
+        cells.push((el.children[i].innerText || '').trim());
+      }
+      if (cells.some(function(c) { return c; })) {
+        addLine('| ' + cells.join(' | ') + ' |', depth);
+      }
+      return;
+    }
+
+    for (var i = 0; i < el.childNodes.length; i++) {
+      walk(el.childNodes[i], childDepth);
+    }
+  }
+
+  walk(document.body, 0);
+  return JSON.stringify({ snapshot: lines.join('\\n'), truncated: truncated });
+})()
+`;

package/server/uninstall.js

@@ -0,0 +1,61 @@
+#!/usr/bin/env node
+import { existsSync, unlinkSync } from "node:fs";
+import { join, resolve } from "node:path";
+import { homedir, platform } from "node:os";
+import { execSync } from "node:child_process";
+import { fileURLToPath } from "node:url";
+import { uninstallWindowsTask } from "./windows-service.js";
+
+function log(msg) {
+  console.log(`[browser-relay] ${msg}`);
+}
+
+const LAUNCHD_LABEL = "org.browser-relay.service";
+
+export function uninstallService(options = {}) {
+  const explicit = options.explicit === true;
+  const strict = options.strict === true;
+  const isGlobal = process.env.npm_config_global === "true";
+  if (!explicit && !isGlobal) {
+    log("Local uninstall — leaving any global background service unchanged.");
+    return { removed: false, skipped: true };
+  }
+
+  const sys = platform();
+  try {
+    if (sys === "darwin") {
+      const plistDst = join(homedir(), `Library/LaunchAgents/${LAUNCHD_LABEL}.plist`);
+      if (existsSync(plistDst)) {
+        try { execSync(`launchctl bootout gui/${process.getuid()} "${plistDst}" 2>/dev/null`); } catch {}
+        unlinkSync(plistDst);
+        log("Removed launchd service.");
+      }
+    } else if (sys === "linux") {
+      try {
+        execSync("systemctl --user stop browser-relay 2>/dev/null");
+        execSync("systemctl --user disable browser-relay 2>/dev/null");
+      } catch {}
+      const serviceDst = join(homedir(), ".config/systemd/user/browser-relay.service");
+      if (existsSync(serviceDst)) {
+        unlinkSync(serviceDst);
+        execSync("systemctl --user daemon-reload 2>/dev/null");
+        log("Removed systemd service.");
+      }
+    } else if (sys === "win32") {
+      const result = uninstallWindowsTask();
+      log(result.removedTask ? "Removed Windows Task Scheduler service." : "Windows service was not registered.");
+      log(`Logs were preserved at ${result.paths.logs}`);
+    } else if (strict) {
+      throw new Error(`Background service is not supported on ${sys}`);
+    }
+  } catch (error) {
+    if (strict) throw error;
+    log(`postuninstall warning: ${error instanceof Error ? error.message : String(error)}`);
+  }
+  return { removed: true, skipped: false };
+}
+
+const isDirect = process.argv[1] && resolve(process.argv[1]) === resolve(fileURLToPath(import.meta.url));
+if (isDirect) {
+  uninstallService();
+}

package/server/windows-service-entry.js

@@ -0,0 +1,58 @@
+#!/usr/bin/env node
+import { closeSync, mkdirSync, openSync, writeSync } from "node:fs";
+import { dirname } from "node:path";
+import { pathToFileURL } from "node:url";
+
+function option(name) {
+  const index = process.argv.indexOf(name);
+  return index === -1 ? null : process.argv[index + 1] || null;
+}
+
+function redirect(stream, file) {
+  mkdirSync(dirname(file), { recursive: true });
+  const fd = openSync(file, "a");
+  const original = stream.write.bind(stream);
+  stream.write = (chunk, encoding, callback) => {
+    let done = callback;
+    let charset = encoding;
+    if (typeof encoding === "function") {
+      done = encoding;
+      charset = undefined;
+    }
+    try {
+      if (typeof chunk === "string") writeSync(fd, chunk, null, typeof charset === "string" ? charset : "utf8");
+      else writeSync(fd, chunk);
+      if (typeof done === "function") queueMicrotask(done);
+      return true;
+    } catch (error) {
+      return original(chunk, encoding, callback) && !error;
+    }
+  };
+  process.on("exit", () => {
+    try { closeSync(fd); } catch {}
+  });
+}
+
+const entry = option("--entry");
+const stdoutLog = option("--stdout-log");
+const stderrLog = option("--stderr-log");
+
+if (!entry || !stdoutLog || !stderrLog) {
+  console.error("Usage: windows-service-entry --entry <file> --stdout-log <file> --stderr-log <file>");
+  process.exit(2);
+}
+
+redirect(process.stdout, stdoutLog);
+redirect(process.stderr, stderrLog);
+// Match the launchd/systemd service definitions: the managed local service is
+// always loopback-only on the standard port. Remote control remains outbound.
+process.env.BROWSER_RELAY_HOST = "127.0.0.1";
+process.env.BROWSER_RELAY_PORT = "18795";
+process.argv = [process.execPath, entry];
+
+try {
+  await import(pathToFileURL(entry).href);
+} catch (error) {
+  console.error(error?.stack || error?.message || String(error));
+  process.exitCode = 1;
+}